组件模型
一个组件要同时回答四类问题:它长什么样(尺寸与修饰)、它怎么排布子节点、它怎么响应输入、它在无障碍与 IME 里扮演什么角色。KotlinMCUI 把这四类问题拆成若干接口,全部有默认实现,再由一个总接口聚合起来。
契约分解
| 接口 | 回答的问题 | 关键成员 | | — | — | — | | DslComponentMetadata | 元数据与无障碍 | modifier、transform、instance、focusable、tooltip、narration、narratable、highlightable、preeditArea、selfRenderPreedit | | DslComponentAlign | 测量与对齐适配 | rect、contentMinWidth/Height、alignableHorizontal/Vertical | | DslComponentNavigator | 焦点导航 | viewHorizontal、viewVertical、viewSequential | | DslComponentEvent | 输入事件 | render、keyDown/Up、onPointer、preedit、mouseScroll*、charTyped、dropFiles、testHit | | DslComponentGlobalEvent | 全局状态变更 | globalFocusChanged、globalHoverChanged | | DslComponent | 之上全部 + 构建、布局、输入遍历 | build、layoutHorizontal/Vertical、visitInput |
DslComponent 同时继承 DslIdContext 与 DslScaleContext,所以任何组件天然知道自己是谁、自己的缩放是多少。
默认值的取舍值得留意:highlightable 的默认实现读的是 instance.focusable 而不是 this.focusable。原因是装饰器链——外层装饰器希望”内层声明了可获得焦点,我就能高亮”,而 this 只是链上的一层。同理 testHit 用 instance.rect、contentMinWidth 用 instance.modifier。整套默认实现都锚定 instance,这是布局、命中、高亮三者能保持一致的前提。
装饰器:用接口委托组合行为
框架没有”属性插槽”或”效果列表”,行为通过替换子节点槽位里的实例来叠加:
fun DslChild.background(color: Color? = null) = change {
val c = color ?: Color.WHITE.mixed
object : DslComponent by it { /* 覆写若干成员 */ }
}
change 不插入新节点,只是把当前组件换成它的一个包装。因此 children.size 不变,身份、索引、rect 全部沿用——装饰是”隐身”的。
instance 自引用
所有层都委托到同一个 instance 字段(委托到最内层实现里的那个字段)。attachInstance() 只在最外层调用一次,写入的就是最外层装饰器。于是链上任何一层读 instance 都得到最外层对象。
最外层装饰器 ← instance 指向这里
└─ 内层装饰器
└─ 原始组件(持有 instance 字段)
这解决了一个具体问题:外层装饰器想知道”最终这个组件能不能获得焦点”,但它看不到更内层装饰器的覆写;读 instance.focusable 就能拿到最终答案。
硬性规则
- 不要覆写
instance、identity、scale。它们描述的是整条链,不是当前层。 - 要读内层尺寸时必须显式写
it.contentMinWidth,不能读contentMinWidth(那会经由instance回到最外层,形成自引用)。 - 装饰器每帧重建。任何跨帧状态都必须走
local/stable/static,不能在装饰器对象里放普通字段。 - 需要协程作用域时,在对象体里提前取
val coroutineScope = local.coroutineScope。放在回调里取只在回调触发的那一帧被访问,会被当成过期项回收。 - 覆写带上下文参数的成员时,必须逐字复制 receiver 列表与泛型参数(
context(...)与<RP>),否则不构成有效覆写。 instance只能写入一次;在组件已经挂载之后再追加装饰器会报错。
装饰器目录
效果类(绘制在内容下层或上层):
| 装饰器 | 作用 | 绘制位置 |
|---|---|---|
background / backgroundImage | 纯色 / 图片底 | 内层之下 |
outline / highlightBox | 边框 / 高亮框 | 内层之下 |
containerBackground / slotBackground / tooltipBackground | 原版风格的容器、槽位、提示底纹 | 内层之下 |
mask / hoverMask | 整体遮罩 / 悬停高亮 | 内层之上 |
shrink | 上报尺寸为 0,配合外层容器决定实际大小 | 改测量 |
widthRate / heightRate | 按比例缩放上报尺寸 | 改测量 |
animateHeight / animateWidth | 尺寸变化走动画 | 改测量 |
renderScissor | 绘制裁剪 | 裁剪 |
reverseChildren | 子节点逆序绘制 | 改顺序 |
rotate / scale / move / shear / perspective | 视觉变换 | 变换 |
带参数为”单位值”的变换装饰器(rotate(0.0)、scale(1.0)、move(0.px) 等)会直接返回自身,不产生包装对象。
事件类:
| 装饰器 | 作用 |
|---|---|
clickable | 鼠标点击与回车激活,触发按钮音效 |
onHovered / onHoverChanged | 悬停回调 |
onFocused / onFocusChanged | 焦点回调 |
narrate | 提供无障碍朗读文本 |
tooltip | 提供提示内容 |
onFilesDropped | 文件拖放 |
scissor | 裁绘制并裁输入;输入上只筛按下/拖放/滚轮,移动与松开透传 |
clickable 的两个细节:enabled = false 时它整体短路返回内层,而不是产生一个”禁用态装饰器”;它只响应左键,命中后无条件消费左键按下——同一个矩形里如果叠了两个可点组件,靠后者会被挡住。按下即激活,没有释放生命周期,因此不参与指针捕获。
生命周期
每帧对每个组件按固定顺序调用:
build():执行 body,产出子节点,然后递归build()子节点;layoutHorizontal():父节点在自己可用区间内摆放子节点,然后递归;layoutVertical();render()。
构建阶段先在临时的子节点集合里执行。body、子节点构建、横向/纵向布局、Overlay 或 Tooltip 物化任一环节抛错,Screen 会恢复上一张成功构建的完整树(首次构建失败则保持空树),后续事件和查询继续对旧树有效,异常本身原样抛出。已提交的绘制像素不回滚,用户代码产生的普通副作用也不做事务回滚;重建失败只承诺组件树和 local 扫描边界的有限一致性。若 DSL 在构建中关闭了 Screen 或其 Root,终态优先:失败处理不会恢复旧树,也不会发布失败帧的候选节点。
全树先做完横向布局,再做纵向布局。这不是实现顺序上的偶然,而是语义约定:纵向测量可能依赖横向结果,最典型的是文本换行——必须先知道可用宽度,才能算出会折成几行、进而算出所需高度。个别组件(如 LateBox)会刻意打破这条约定见长,属于受控例外。
事件路由
Root 依据 visitInput 提供的物化树统一选择目标、转换坐标并管理指针生命周期。容器不递归输入;装饰链仍只是一项逻辑节点,变换和裁剪按装饰顺序报告。默认实现报告 instance 及其子节点,Lazy 改报可见物化节点。完整状态表见多点输入。
渲染顺序与命中顺序的一致
render() 用 children.asReversed() 遍历,而 testHit 与事件用正序遍历。两条看似矛盾的规则合起来给出一个不变式:
声明靠前 = 绘制在更上层 = 命中优先。
asReversed() 是因为绘制是按顺序覆盖的,先画的在下层;命中从前往后探测,先声明的先被命中,正好对应”最上层优先”。用户不需要记住这两套遍历方向,只需要记住”写在前面就在上面”。
testHit 的谓词语义
testHit(mouse) { it.takeIf { ... } } 里的 get 是可失败的谓词:返回 null 表示”这个组件不满足条件”,探测会继续找兄弟节点;返回非 null 则选中。因此它的语义是”最上层满足条件的组件”,可以一次查询焦点组件、悬停组件、可朗读组件等。
无坐标重载 testHit { } 用于按身份定位组件(例如找当前焦点组件),不需要鼠标位置。
裁剪与变换装饰器通过 visitInput 按作用域贡献几何;testHit 复用按需遍历及完整 clip,不再由装饰器各自递归或重复逆变换。
全局状态
焦点、悬停、朗读、IME 预编辑状态不放在组件上,而放在根(DslRoot)上:它们属于那个根的树,在同一个根内切换 Screen 时随根保留,不同根互不影响。同一进程里的多个后端各有各的根,因此这些状态是每根的,不是进程级的。设焦点由鼠标与键盘导航驱动,走的是根内部同一个入口;它不筛选 focusable,所以”根记录了焦点”和”组件报告 isFocused“是两件事。由代码主动设焦点的唯一入口是 root.setFocus(identity)(source 默认 FocusSource.CODE,null 表示清除)——”开屏就把光标放进输入框”用的就是它;DslRootState 保持 internal,所以 setHovered/setPreedit/帧计数都不在公开面上。
全局事件从根节点向下派发,顺序是后序的(先子后父):子组件先知道自己失去了焦点,父容器最后才看到变化,便于父容器在子组件已更新后再做整体反应。
preedit 始终定向组合开始时的文本目标。组合结束、切焦点、隐藏或移除目标时,先向原目标发送空 preedit 并清组合状态;提交/取消边界暂留旧路径,保证回调内切焦点仍能结束已移除的原目标。
编写一个新组件
- 用
Spacer(modifier, id).change { object : DslComponent by it { ... } }起手,只覆写需要的成员(Spacer内部就是DslComponentImpl,但它是internal,用户侧只能走这个工厂); - 需要一个容器就用
Scope(modifier, id, 横向 aligner, 纵向 aligner, function),再change { object : DslScope by it as DslScope { ... } }; - 想暴露自定义尺寸,覆写
contentMinWidth/contentMinHeight;需要让子节点参与测量,遍历instance.children,用outerMinWidth/outerMinHeight自行求和或取最大值; - 需要在同一个组件上继续叠加行为,返回
DslChild(而不是Unit),这样调用者能链式调用装饰器; - 必须在构造期读取的东西(尺寸、颜色、主题)直接读;必须每帧保持的东西(状态、协程)走属性作用域。
如果组件需要在布局完成后才知道自己要构建什么(典型是自适应宽度的延后布局),可以覆写 layoutVertical(),在那里执行 buildThis 并自行调用 aligner——LateBox 就是这么做的,代价是它无法再被子节点撑大。