上下文

用户书写的 UI 代码需要一个”当前正在构建什么”的隐式环境:当前身份、当前子节点列表、当前缩放、当前主题色。KotlinMCUI 用 Kotlin 上下文参数(context parameters) 表达这件事,而不是自定义接收者加 @DslMarker,也不用编译器插件。

为什么不直接用一个接收者

如果所有 DSL 函数都写成 DslContext.() -> Unit,那么任何拿到上下文的函数都能读写全部状态,无法在类型上区分”这个函数只读缩放”与”这个函数会注册子节点”。

因此上下文被拆成一组最小能力接口:

接口 提供 典型使用者
DslScaleContext scale scaled 单位换算、子组件继承缩放
DslIdContext identity 身份派生、属性作用域寻址
DslChildrenContext children collect / remove
DslDataStoreContext dataStore backend、translate 等派生属性
DslColorContext color Color.mixed 主题混色
DslPreventContext 阻止聚合 Modifier.align 的参数
DslExecuteContext dataStore 属性/动画初始化块、事件回调
DslTextBuilderContext 文本构建 emit 等

每个接口都带 companion object { operator fun invoke(...) } 工厂,返回匿名实现,因此可以凭空构造一个只含单一能力的上下文(例如 DslIdContext(id))临时满足某个函数的签名要求。

用 context(...) 声明的函数在调用点自动取得所需能力,调用者只需要身处一个提供了这些能力的词法范围内。

单一可变上下文对象

DslContext 是 open class,实现上面若干能力接口。它不是不可变的值对象,而是一个被反复复用的可变槽位容器:

槽位 初值 含义
_identity 未设置 当前节点身份
_children 未设置 当前可注册子节点的集合
_scale Double.NaN 当前缩放
_color Color.WHITE 当前主题色
_overlays 未设置 当前 Overlay 收集槽

进入一个作用域时保存旧值、写入新值;离开时在 finally 中恢复。这一保存/恢复对由 withField 统一实现,对外暴露成 withIdentity / withChildren / withScale / withColor / withOverlays。

这样做是出于性能:整棵树每帧都会重建,如果每进入一层容器都新建一个上下文对象,逐帧分配量会与树的深度成正比。复用同一个对象之后,进入/离开作用域只付出两次字段读写。

未设置的槽位必须报错

“没有当前缩放”和”缩放是 0”是完全不同的两件事。_scale 用 NaN 初始化,读取时校验:

  • 未设置的身份 → undefined identity
  • 未设置的子节点集合 → undefined children
  • 未设置或为 NaN 的缩放 → undefined scale
  • 未设置的 Overlay 槽 → undefined overlays

宗旨是让误用立刻炸掉,而不是产生一个看起来合理但错误的尺寸。判据是 isNaN,因为”未初始化”与”合法的非零尺度”是两件事;DslScaleContext 不接受 0、负数、NaN 或无穷大,屏在输出准备好之前只推迟读取根的尺度,不会把 0 当成合法占位值。

线程约束

UI 构建状态只在创建它的那个线程上有效。DslContext 在构造时记录 Thread.currentThread(),所有槽位的读写都先经过 checkThread(),不匹配时报出当前线程与期望线程。

这不是可选优化,而是设计前提:上下文对象是共享可变的,一旦多个线程同时构建 UI,保存/恢复对会互相踩踏。跨线程的数据准备必须先在后台线程算好,再回到主线程渲染——见 协程。

单位

scale 是”用户界面缩放”,与 Minecraft 的 GUI Scale 同源。DSL 里的尺寸有两种写法:

  • N.px:输出目标坐标单位,不随 DSL 缩放变化;不保证等于显示器物理像素
  • N.scaled:等于 px * ctx.scale,随缩放变化

scaled 是对 Double / Float / Int 的扩展属性,需要 DslScaleContext。反向换算由 Measure.unscaled 提供。

推荐尺寸是 9.px 的整数倍(9.px 相当于缩放 1 下的一个字宽),这样在不同缩放与不同字体下都能对齐。

DslFunction

typealias DslFunction = context(DslContext) () -> Unit

所有”构建一段 UI”的位置都用这个类型。它是普通函数类型,不是带接收者的 lambda,因此不能通过 this 访问上下文——只能通过 context(...) 参数声明,或者使用 dsl 包里的扩展属性(identity、children、backend、local、stable、static 等)。

dsl/DslFunctions.kt 提供常用动作:

函数 作用
newChildId(id) 以当前身份为前缀派生一个子身份
withId(obj) { } 在当前身份下追加一段并执行
withScale(scale) { } 以有限正数替换局部 DSL 尺度;退出时恢复,不自动乘父尺度,也不变换已有坐标
withColor(color) { } 局部改变主题色
Iterable.forEachWithId { } 遍历并给每个元素一个基于元素本身的身份
collect(component) / remove(child) 手动增删子节点
translate(string, vararg args) 取翻译文本,缺失时回退为原文
showScreen(title, function) 新建并展示一个 Screen
localImage(file) / remoteImage(url) / imageResource(location, w, h) 构造图像引用

颜色作用域

主题色是构建期概念。组件在自己的构造表达式里读取 Color.WHITE.mixed 把它立刻求解成一个普通 Color 值并保存;渲染阶段不再做任何颜色运算。所以颜色不是响应式的——withColor 换色只影响当帧新建的组件树,而树本来就每帧重建,因此实际表现仍然是即时生效。

mixedWith 是逐通道相乘(a*b/255),所以:

  • Color.WHITE.mixed 等于当前主题色本身(白色是乘法单位元);
  • withColor(Color.RED.mixed) { } 是把红色混入当前主题色,得到偏红的色调;
  • withColor(Color.RED) { } 则是绝对设色,与之前的作用域无关。

混色刻意放在调用点完成,框架不做隐式的事后处理。作用域在离开 withColor 的那一行就被恢复,不会污染后续代码。

作用域如何穿过延迟构建的容器

容器是延迟构建的:Box{} 在被书写时只创建组件,它的 body 要等到自己的 build() 阶段才执行,Overlay 的 body 更是排在单独的构建阶段。此时调用者的颜色作用域早已离开。

因此容器在创建时记下当时的主题色,在执行 body 时重新应用。这与身份、缩放的处理完全一致(组件在创建时记下身份与缩放,执行 body 时再放回去),于是

withColor(Color.RED) {
    Box { Button {} }   // Button 同样在红色作用域里构建
}

符合直觉。


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