文本
文本是唯一一类”构建期无法确定尺寸”的内容:需要字体度量才能算出宽度,而字体来自后端。因此文本系统被切成两半——构建期只收集字符,渲染期才用字体计算宽高。
这条分界决定了整个文本包的结构。
构建期:收集字符
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),并对同一名称返回同一字体实例,因此”布局期与渲染期字体必须是同一实例”这条契约在测试中是被真正走到的。