文本

文本是唯一一类”构建期无法确定尺寸”的内容:需要字体度量才能算出宽度,而字体来自后端。因此文本系统被切成两半——构建期只收集字符,渲染期才用字体计算宽高。

这条分界决定了整个文本包的结构。

构建期:收集字符

DslTextBuilderContext 包装当前上下文并转发缩放、数据存储、颜色三种能力,内部只维护”行 → 字符列表”这一个结构。

fun String.emit(color: Color? = null, size: Measure = 9.scaled, style: DslCharStyle = DslCharStyle())
fun enter()
fun toChars(): List<List<DslRenderableChar>>

emit 把字符串按 码点(而非 UTF-16 char)切分,逐个生成”字符 + 样式 + 颜色 + 字号”的记录。遇到换行符就开启新的一行。

两个默认值值得注意:

  • 字号默认是 9.scaled,与”9.px 是缩放 1 下的一个字宽”这一约定一致;
  • 颜色默认取当前主题色(ctx.color),不是 Color.WHITE.mixed。因为 withColor 已经把最终颜色写进了上下文槽位,这里直接取用即可。

enter() 显式开启新行,等价于在字符串里写换行符。

构建期完全不接触字体:字号、样式、颜色都被记录成数据,等渲染期再解析。

三个入口

| 入口 | 行结构 | 宽度 | | — | — | — | | TextFlatten | 把所有内容压成一行(换行符被忽略) | 内容总宽 | | TextFoldable | 保留 emit / enter 产生的行 | 内容总宽 | | TextAutoFold | 在保留的行基础上按可用宽度折行 | 最小宽度为 0,由父容器决定 |

三者的对齐参数都默认 close(Align.MID)(水平与垂直都居中)。

TextAutoFold 的关键在于覆写了最小宽度:它上报的最小宽度直接取 modifier 里声明的宽度,因此内容不参与最小宽度计算——这正是”可以被压缩到任意窄并折行”的前提。这也意味着它不会把父容器撑宽。

仓库中不存在 TextAutoScale,正式文档若提及该名称则是错误的。

折行算法

折行发生在文本处理阶段(渲染前),做法非常直接:逐字符累加字宽,一旦超过可用宽度就换行并把该字符放到新行。

因此:

  • 没有单词边界处理,也不区分 CJK 与拉丁文字。英文单词会被从中间断开,中文与英文的行为一致。
  • 单个字符本身超过可用宽度时仍会被放到新行(不会被丢弃),可能产生一个空行。
  • 可用宽度取的是组件当前矩形的宽度,因此折行依赖横向布局已经完成——这正是”先横后纵”这一全局约定的直接动因。
  • 折行结果按当前宽度缓存:宽度不变时,重复查询 lines() / contentMinHeight 复用结果;同一帧内矩形宽度变化后,下一次查询 lines()、processedChars 或 contentMinHeight / contentMinWidth 都会先重新处理,再更新对应的最小尺寸缓存。字体实例和度量仍由后端按名称提供,不受这层缓存影响。

渲染期的度量

文本组件作为 Alignable 参与布局,它的最小尺寸由各行累加得出。渲染单个字符时:

  • 横向位置 = 分配区间内居中((low + high - 最小尺寸) / 2,再按行内偏移推进);
  • 纵向位置 = 行矩形顶部;
  • 字符实际步进 = 字体给出的步进 × 字符字号 / 字体行高。

最后一条是”同一段文本里混排不同字号”的实现方式:字号通过缩放步进体现,而不是通过逐字垂直居中。

由于纵向位置统一取行顶,同一行里混排不同字号时基线不对齐。

字形由后端提供(字宽、粗体偏移、阴影偏移)。样式是若干开关(粗体、斜体、下划线、删除线、阴影),渲染时按开关切换字形查询。

对齐使用 close 策略,它不做边界钳制——当文本框比内容窄时,文字会同时向两侧溢出。

翻译

翻译键就是点分路径字符串,语言文件(assets/kotlinmcui/lang/*.json)是唯一真源:

TextFlatten { translate("kotlinmcui.page.title").emit() }

这里刻意没有编译期的键表,也不做缺键检查:查不到就把键名原样显示。

早先的版本用 Kotlin 属性委托搭过一棵与语言文件同构的键树(KeyNode + by name),本意是获得 IDE 补全与拼写检查,但它要求把同一份键在代码里再维护一遍,而且没有任何机制保证两边不漂移——加一个键要改三处(键树、en_us、zh_cn),漏改不会有任何提示;框架自己的键树当时就已经缺了一个键而无人察觉。字符串键只有一个真源,代价仅仅是拼错时界面上会显示键名,这个代价比维护两份键表低得多,所以键树被整体删除了。

不在 DSL 上下文里取值(例如入口的元数据、组件实现的属性)用 translateGlobal,它不走上下文而是直接用全局后端。

可编辑文本

可编辑字符串在”码点序列 + 光标 + 选区”之上提供编辑操作,是文本编辑框的状态载体。

两个实现特征:

  • 撤销粒度是按帧的:编辑框每帧渲染时记录一次状态,因此一帧内的连续输入会被合并为一步撤销;撤销深度有上限。这意味着撤销的语义是”回到上一帧”,而不是”回到上一次按键”。
  • 光标闪烁由帧时间驱动:以固定周期(默认半秒)取整求奇偶,不依赖平台计时器,因此与游戏暂停/掉帧的关系是确定的。
  • 选区与光标都以码点计数:复制、剪切这类取子串的操作必须走码点切片,直接用字符串下标会在代理对上错位。

撤销栈维持一条不变式:栈顶始终是当前状态。撤销就是丢掉栈顶、恢复到下一项,因此”没有可撤销的内容”与”没有历史”是同一件事。

EditableText 需要显式身份,惯例是调用点写一个空 lambda 充当键。

输入法组合文本有两条路径:组件自绘时它把组合串直接插入真实字符串并保存/恢复光标;否则由框架的浮层显示,组件本身不变。细节见 事件与焦点。

测试现状

文本模型(码点切片、撤销/重做)已有单元测试;文本布局算法现在有回归覆盖:宽高测量、按宽度折行、宽度变化后的重新折行,以及文本在 LateBox 和惰性列表中的实际布局路径。

测试用的假后端提供固定度量(行高与字宽都是 9.px、粗体偏移 0、阴影偏移 1.px、缩放 1.0),并对同一名称返回同一字体实例,因此”布局期与渲染期字体必须是同一实例”这条契约在测试中是被真正走到的。


This site uses Just the Docs, a documentation theme for Jekyll.