KMP 实战:用 XML 描述界面,写一个 Compose 动态表单引擎
服务端下发一段 XML,客户端把它渲染成原生界面 —— 同一份 XML 在 Android、iOS、Desktop 上跑出同一个页面。 这不是 WebView,也不是自绘,每一个标签最终都编译成对 Compose 组件的一次调用。
0. 先看它长什么样
左边是 XML,右边是它在三端渲染出来的样子。注意几件事:
value="{{username}}"是双向绑定:输入框改了,data.username就变了,别处读它的文本立刻跟着变。onClick="@{ action.login() }"是事件,action是宿主注册的函数表。@{ data.contacts.append(new()) }直接改了数据 —— 没有注册任何 action。Foreach里的item/i是行上下文,{{item.phone}}和@{ data.contacts.remove(i) }都指向这一行。
而渲染它的宿主代码只有两行:
val data = rememberData(mapOf("username" to "张三", /* … */))
DynamicLayout(xml = PLAYGROUND_XML, data = data)
这篇文章讲三件事:为什么做、怎么用、内部怎么实现的。第三部分是重点,也会讲我踩过的几个 Compose 的坑。
1. 为什么要造这个轮子
先说场景,再说取舍。
1.1 场景:表单要频繁变,但客户端发版不自由
典型的后台/中台 App 里,表单是最"重"也最"碎"的部分:
- 一个审批流有十几张表单,每张字段不同;
- 运营改一版字段顺序、加一个必填项,客户端就要跟着发版;
- Android 和 iOS 各写一遍,两边的校验规则还常常对不上。
常见的三个解法,各有各的痛:
| 方案 | 痛在哪 |
|---|---|
| WebView 嵌 H5 | 首屏白屏、键盘与滚动体验割裂、拿不到原生能力、和宿主视觉不一致 |
| 服务端下发 JSON Schema,客户端自己映射 | "映射层"会越长越像一门 DSL,"这个字段配了这个属性会怎样"永远说不清 |
| 每个表单手写 Compose | 三端三份代码,改一版表单要动三处 |
我想试第四条:让 XML 直接描述界面结构,由一个引擎把它变成原生的 Compose 调用。XML 是服务端最熟悉的格式(配置、模板、老系统都能产出),而 Compose 本身就是声明式的 —— 这两者的转换是天然的。
1.2 三条设计红线
做这类"别人下发的东西由我来渲染"的引擎,最容易出的问题不是渲染不出来,而是出错时说不清。所以一开始就定了三条红线:
-
能在解析期报的错,绝不留给运行期。 标签名拼错、属性名拼错、把字面量写进可写槽位、
{{dta.x}}里的全局对象名拼错 —— 这些都在拿到 XML 的那一刻全部报出来,一次报完,而不是"改一个跑一次"。 -
引擎本身不认识任何具体组件。 内置的
Text、Button和宿主自己写的RatingBar走完全同一条注册路径。没有任何if (tag == "Text")之类的特权分支。 -
XML 只描述"长什么样 + 绑哪份数据",不描述业务。 校验规则、网络请求、跳转逻辑都在宿主代码里。XML 里能写的表达式只有"取个值、算个三元"这个量级。
2. 五分钟上手
2.1 引入
// settings.gradle.kts
include(":composexmlform")
// 依赖方
dependencies {
implementation(project(":composexmlform"))
}
2.2 最小可跑
@Composable
fun ProfileForm() {
// 一份可观察的数据源
val data = rememberData(
mapOf(
"username" to "张三",
"region" to "BJ",
"isLogin" to false,
),
)
// 服务端下发的只读资源(字典、选项、文案),整棵子树冻结
val config = mapOf(
"regions" to listOf(
mapOf("label" to "北京", "value" to "BJ"),
mapOf("label" to "上海", "value" to "SH"),
),
)
DynamicLayout(xml = FORM_XML, data = data, config = config)
}
<Column scroll="true" padding="20" spacing="12" width="fill">
<Text value="用户信息" fontSize="22" fontWeight="bold"/>
<TextField label="姓名" value="{{username}}"/>
<Select label="城市" options="{{config.regions}}" value="{{region}}"/>
<If test="{{isLogin}}">
<Then><Text value="已登录" color="#1B7F3B"/></Then>
<Else><Text value="未登录" color="#C0392B"/></Else>
</If>
</Column>
到这里就有一个能输入、能联动、能切分支的表单了。
2.3 三个全局对象
引擎只认三个保留名字:
| 名字 | 是什么 | 能不能写 |
|---|---|---|
data | 业务数据根 | 可写(DataObject.frozen == false) |
config | 服务端下发的只读资源 | 整棵子树冻结,写就抛 FrozenWriteException |
action | 宿主动作表 | 只读,成员全是函数 |
除此之外宿主还能注册自己的全局对象(http / storage / pv …),语义完全同级:
val globals = globals {
object_("http") {
const("baseUrl", "https://api.example.com")
suspendFn("get") { _, args -> /* … */ }
}
}
2.4 属性值只有三种形态
这是整个 XML 语法的全部:
| 写法 | 含义 | 用在哪 |
|---|---|---|
"字面量" | 常量 | 所有只读属性 |
{{path}} | 路径绑定,读即订阅 | 只读属性 + 可写属性 |
@{ 语句 } | 脚本,事件用;{ expr } 是只读表达式 | onClick 等事件槽位,或算显示值 |
{{}} 里只能写路径(data.user.name、item.phone),不能写运算。要算就在 {} 里算:
<Text value="{ item.name ?: '(未命名)' }"/>
2.5 脚本能力有三档,默认最保守
模板能改数据,是个产品决策,不该由引擎替使用者决定。所以有个显式的档位:
| 档位 | {{}} | {} | @{} | 赋值 | await |
|---|---|---|---|---|---|
NoScript | ✅ | 报错 | 报错 | — | — |
ExpressionsOnly(默认) | ✅ | ✅ 只读 | ✅ 只读 | 报错 | 报错 |
Full | ✅ | ✅ | ✅ | ✅ | ✅ |
默认档位下,@{ data.x = 1 } 会在解析期报错,而不是运行期悄悄改掉数据。要写就显式升档:
DynamicLayout(xml = xml, data = data, scriptMode = ScriptMode.Full)
2.6 表达式里能写什么
{} / @{} 的能力是刻意收窄的,清单如下:
// ✅ 能写
{ a + b * 2 } // 四则、比较、逻辑、空合并 ?:
{ item.name ?: '(未命名)' } // 三元
{ list.size() } // 内置方法
{ data.contacts.append(new()) } // 有副作用的方法调用
{ '第 ' + (i + 1) + ' 行' } // 字符串拼接
// ❌ 不能写(解析期报错)
{ fun f() = 1 } // 函数定义 —— 这是 <Script> 那一版的事
{ val x = 1 } // 变量声明(ExpressionsOnly 档位下)
{ await http.get(u) } // 挂起调用(要 Full 档位,且只在语句层)
内置方法按值类型分三组,名字与内置冲突时宿主注册会当场报错:
| 类型 | 方法(共 14 个,全部列出) |
|---|---|
| 数组 | append insert remove indexOf size |
| 字符串 | upper lower trim length split contains |
| 对象 | keys has remove |
需要"现有最大值 + 1"这种逻辑?脚本里没有 maxOf,也声明不了变量 —— 这类计算应该由宿主提供函数,而不是把模板变成一门编程语言。
3. 整体架构
依赖是严格单向的:androidApp / iosApp / desktopApp → shared(示例)→ composexmlform(库)。库内再分三段:
3.1 声明面:api.decl
宿主写组件要用到的一切:Props / Prop / PropsNode / PropsContainer。
这一段单独抽出来,是为了让 AttrSlot、AttrDef、NodeType 这些引擎内部类型可以全部 internal。宿主看得见的东西只有 7 个类型(下一节细说)。
3.2 组件层:components
7 个内置组件(Text / Button / TextField / Select / Column / Row / Box)+ 样式解析。这一层没有任何特权:它调用的 registry.component(...) 和宿主调的是同一个。
3.3 引擎内核:engine,8 个包
| 包 | 行数 | 职责 |
|---|---|---|
diag | 273 | 诊断码、严重级别、Diagnostic 本身 |
value | 1081 | Value(= Any? 的规范形态)、DataObject、DataArray、normalize |
syntax | 1109 | 词法 + 语法:XML → AST,表达式 → AST |
env | 401 | Env 作用域链、EnvSchema(解析期能看见的"能力表") |
eval | 1291 | 求值器、内置方法表、宿主扩展链 |
node | 747 | Node / AttrSlot / NodeType / 结构节点 |
parse | 1107 | AST + 能力表 + 白名单 → 节点树 + 诊断 |
render | 720 | 节点 → 渲染器 → Composable;属性求值、事件绑定 |
有意思的是 engine 完全不认识 tag。parse 只查 NodeTypes(一张 tag → NodeType 的表),render 只查 Renderers(KClass → Renderer)。这两张表都由注册表提供,而注册表里有什么,取决于宿主装了什么。
唯一的反向禁令:
engine.node不 importapi.decl。所以If/Foreach这两个结构节点至今仍用裸的AttrSlot,而不是props.bool("test")—— 让它们用Props就会形成node → api.decl → node的环。收益只是内部 4 个类少写几个泛型,而宿主永远不会写结构节点,不值得为它破一层依赖。
4. 实现原理
4.1 一次渲染过四道关
阶段 ① syntax:XML 文本 → AST
自写的解析器(不引 XML 库,因为 KMP 上没有合适的、能同时给你源码位置的库)。属性值在这一步就被分成三种形态:字面量、{{path}}、@{script}。
这一阶段是唯一可能"整页无树"的地方 —— 标签没闭合时,没有"继续解析"这回事。
阶段 ② parse:AST + 能力表 + 白名单 → 节点树
这一步做三件校验:
- 全局对象名:
{{dta.user}}里的dta不在能力表里 → 报错。但不校验成员存在 ——data.user有没有user、action注册了哪些函数,都是运行期的事。 - 属性白名单:
<Text valu="x"/>这种拼写错误,由NodeType.attributes拦住。 - 可写性:可写槽位收到字面量 → 报错。
阶段 ③ node:节点树只是声明
class TextNode(props: Props) : PropsNode(props) {
val text by props.string("value", "")
val fontSize by props.float("fontSize")
// …
}
节点不 import env,不 import Compose,手里没有任何值 —— 它只声明"我需要哪几个属性"。值是在渲染期才算出来的。
阶段 ④ render:查表 + 求值 + 订阅
@NonSkippableComposable
@Composable
fun RenderNode(node: Node, env: Env = LocalEnv.current) {
val renderer = LocalRenderers.current.rendererFor(node) ?: /* 报缺渲染器 */ return
// …每行绑一份现场
renderer.Render(node)
}
属性读到值的同时就订阅了那个 MutableState,数据一变只重组用到它的那一小片。
为什么不是 fail-fast
一个标签上写错三个属性、另一个标签拼错名字,引擎一次全报。用户改一遍就全改对,不用"改一个 → 跑一次 → 发现下一个"。
代价说清楚:ParseResult.root != null 不代表没有问题,宿主必须用 hasErrors 判断要不要渲染。
4.2 两条求值路径
{{}} 和 @{} 看着像同一种东西,其实走的是两条完全不同的路:
{{path}} | @{ script } / { expr } | |
|---|---|---|
| 类型 | AttrRef.Bind | AttrRef.Code |
| 求值 | 沿 Env 链读路径,读即订阅 | 交给求值器跑 AST |
| 可写 | 是(env.assign 写回路径) | 不作为槽位写回;但脚本可以调用有副作用的函数改数据 |
| 能算 | 不能 | 能 |
事件槽位比较特别:它需要"点击那一刻"的现场,但局部变量(item)又必须是"渲染那一刻"的。所以绑定时会做一次快照:
val eventEnv = ctx.env.root().child() // 全局对象要执行那一刻的
for ((k, v) in captured) eventEnv.define(k, v) // 局部变量要渲染那一刻的
根 env 用"现在"的(否则请求延迟期间用户改的值会被旧快照覆盖),局部变量用"渲染时"的(否则点击拿到的是循环结束后的最后一个元素)。
4.3 「这个属性能不能写」是三件事分别回答的
这是被问得最多的一个问题:options="{{config.regions}}" 和 value="{{region}}" 都写双括号,为什么前者只读、后者可写?
因为括号只说明值的形态,不说明能不能写。三道闸门是"与"的关系:
- 形态:可写槽位只收
{{path}}。写死一个字面量进去 = "用户改了也存不回去",解析期直接报错。 - 访问器:
props.varString(...)有 setter,props.string(...)没有。所以SelectNode里options是string(...)、value是varValue(...)—— 同一个组件里两个属性,可写性不同。 - 数据:目标容器必须是可写的。
config整棵子树冻结,写就抛FrozenWriteException。
第三条有个容易忽略的细节:冻结要传给所有后代。否则"把一个只读对象塞进可写位置"就绕过了。
反过来看,只要页面里出现 node.value = x 却没生效,一定是这三条里的某一条 —— 按顺序查就行。
4.4 数据层:一条链,不是两张表
data / config / action / http 都是同一张 DataObject 的实现,差别只有 frozen 和成员内容。
每个 key 一个 MutableState。 这一条是强制的:读 a 只订阅 a,Foreach 的元素级更新全靠它。退化成"整表一个 state",列表里任何一格变化都会重建全部行。
Env 本身是一条链,不是"全局表 + 局部表"两块:
Env(store, parent) ← 子层:Foreach 的行变量、组件局部量
└── Env(store, parent) ← 根层:data / config / action / http …
读一个名字走五个分支,顺序固定:
绝对路径(data.x) → 全局对象
frame → 脚本函数局部变量
链 → 内层到外层
命名全局 → http / pv 等
兜底 → 按槽位期望类型:Data → data,Function → action
最后那个兜底是"省略 data. 前缀"的实现:{{username}} 等于 {{data.username}}。它必须排在最后 —— 否则 {{config.x}} 会被解释成 data.config.x。
写入只有一个出口:env.assign → DataObject.assign → setMember → 发 DataChange。全系统只有这里发变更事件,因为只有根容器知道"从根走下来的完整路径",嵌套容器没有父指针。
4.5 Foreach 的行身份:整个项目最难查的 bug
现象:删掉列表中间一行,数据确实删了,日志也打了,界面就是不动。
根因不在"删除",在"行身份"。如果拿下标当 key:
- 删掉第 0 行后,剩下的元素前移;
- 但 Compose 只看到"下标 0 还在",于是复用第 0 组的 slot;
- 而这个 slot 记着的是已经被删掉的那个元素的状态;
- 这一组没有重组,界面停在旧值。
试过的错方案:给行加 revision 参数、用 key(element) 再包一层子节点、在 SideEffect 里写槽位 —— 都不稳。
最后是两条规则一起用才解决:
- 行 key 三级退化:
key="id"→ 元素本身 → 下标。没写key时默认用元素对象本身,绝不用下标。下标会随增删错位,那就是上面这个 bug 的源头。 RenderNode标@NonSkippableComposable。
第 2 条容易被忽略:Foreach 每帧用 Env.define("item", …) 原地改行变量(这是为了不重建整行)。而"组合期写 MutableState"有个前提 —— 下游没被跳过。如果这一组恰好被 Compose 跳过,写进去也唤不醒它。关掉跳过是唯一可靠的办法。
4.6 组件扩展 API:一个属性名只写一遍
早期的写法里,value 这个属性名要在 4 个地方各写一遍:属性声明表、节点构造参数、工厂里的 attrs.attr(...)、渲染器里的读值。改个类型要同步改 4 处,漏一处编译器不一定报错。
现在的全部代码是三块:
// ① 一个类:声明即读取
class RatingBarNode(props: Props) : PropsNode(props) {
var value by props.varLong("value", 0L) // 名字 / 类型 / 默认值 / 可写性,一行
val max by props.long("max", 5L)
val label by props.string("label")
val color by props.string("color")
val style = props.style() // 六个样式属性一次拿全
}
// ② 一个普通 Composable:node.value 就是 Long,不是槽位
@Composable
fun RatingBar(node: RatingBarNode) {
Row(node.style.modifier()) {
repeat(node.max.toInt()) { i ->
Text(
text = "★",
color = node.color.toColor(),
modifier = Modifier.clickable { node.value = (i + 1).toLong() },
)
}
}
}
// ③ 一行注册
registry.component("RatingBar", create = ::RatingBarNode, render = ::RatingBar)
属性表不用另外声明:注册时引擎会用一份空 Props 把这个类构造一次,构造函数里调过的每个 props.xxx(...) 就是白名单。所以属性名只有一处来源,不可能"声明了却没读"或"读了却没声明"。
带 default 的访问器返回非空类型(Long),不带的返回可空类型(Long?)—— "要不要兜底"直接写在类型上,不需要另一个 present 标志。
覆盖内置组件也是同一个方法:
val themed = ComposeXmlForm.createRegistry {
component("Text", replace = true, create = ::FancyTextNode, render = ::FancyText)
}
replace = true 才会替换;不写就是重名失败。两个 Text 同时存在时"谁生效"取决于注册顺序,那是最难查的一类 bug。
5. 六个踩过的坑
这一节可能是最有用的部分 —— 都是真实撞出来的,不是推演。
坑 1:Compose 不允许 composable 的 setValue
最开始的设想是"在渲染器里也像原生状态一样用":
@Composable fun Render(node: X) {
var v by node.value // 想要这个
}
编译器直接拒绝:
COMPOSE_INVALID_DELEGATE: Composable setValue operator is not currently supported
var 委托要求 getValue 和 setValue 都是 composable,而 setValue 不支持。这条路整条不通。
所以委托只能放在节点类里(非 composable,事件回调里也能赋值),现场由 Props 持有。渲染器里拿到的是 node.value,一个普通值。
坑 2:组合期写槽位,唤不醒被跳过的下游
上面 4.5 讲过。教训:"写状态"不等于"会重组"。Compose 的跳过逻辑会拦住它,只有关掉跳过才可靠。
坑 3:Foreach 用下标当 key
同上。教训:列表的行身份必须稳定,而"稳定"的唯一来源是元素本身或它的主键,不是它在数组里的位置。
坑 4:冻结对象在构造期写入会崩
FrozenWriteException
现象很有意思:窗口能开,预览区一片空白,日志就一行。
根因:DataArray.ofValues 在构造期走了 append,而 append 里有 frozen 检查。但冻结是给外部写入用的,不该拦"我自己的初始内容"。所以构造期必须走 appendRaw / setRaw。
这条后来变成一条规则:frozen 只拦外部写入,不拦构造期装载。
坑 5:首帧的诊断汇总是空的
preview 想把渲染期诊断汇总报给宿主,用的是 SideEffect。第一版写在 CompositionLocalProvider 之前,结果首帧收集不到任何东西。
原因很简单:CompositionLocalProvider 里的子组合还没执行完,而诊断是在子组合里产生的。
顺序必须是:CompositionLocalProvider { … } → SideEffect { 汇总 }。
坑 6:少写一个参数,声明出一个空名字的属性
props.varString("") // 想写 varString("value", "")
编译期不报错,运行期白名单里多一条谁也写不出来的空键。现在 Schema.resolve 加了两条护栏:属性名不能为空、同一属性的默认值前后必须一致。
教训:API 的形状要能挡住手滑。varString(name, default) 这种两个位置参数的重载,天然容易被少传。
6. 现在到哪一步了
| 维度 | 状态 |
|---|---|
| 测试 | ./gradlew :composexmlform:jvmTest → 293 例全过(JVM 上跑,含 Compose UI 测试) |
| 平台 | Android / iOS(arm64) / Desktop 编译通过,示例三端可跑 |
| 规模 | 库约 9100 行(engine 6729 / api 1519 / components 761,其余是门面与预览) |
| 内置组件 | 7 个 + 4 个结构标签(If / Then / Else / Foreach) |
| 调试 | Desktop 端有调试台:左 XML 编辑 / 右实时渲染 / 底部数据快照与诊断 |
还没做的,也说清楚:
- 字段校验规则(
required/minLength/pattern)。这是目前唯一的功能回退 —— 校验需要独立的FormState与"规则从哪儿来"的设计,不想在 api 里临时补一个口径。 <Script>标签:让 XML 里能写多行脚本、定义函数,元素文本承载代码。前置改动是让解析器保留元素文本,还要裁定"缩进空白算不算代码"。- 增量更新:现在换 XML 会整棵重建,没有 diff。
- 列表上移 / 下移 / 排序:需要行上下文(
RowStore)才能做干净。
7. 什么样的场景适合它
适合:
- ✅ 中后台、审批流、配置面板这类表单多、改得勤的页面
- ✅ 需要服务端/运营侧下发界面,但又要保持原生体验和原生能力
- ✅ 已经在用 Compose Multiplatform,想三端共用一套界面描述
- ✅ 需要"解析期就把错误报全"——比如让非开发的同事也能改 XML
不适合:
- ❌ 复杂动画、自定义手势、重度自绘的界面(这些直接写 Compose)
- ❌ 需要极致首帧性能的场景(多一层解析)
- ❌ 指望用 XML 写业务逻辑 —— 它的表达式只有"取个值、算个三元"这个量级,这是刻意的
8. 小结
这个项目最核心的三个判断,回头看都是对的:
- 把"解析"和"渲染"彻底分开。 解析期不碰 Compose,所以它能在 CI 里跑、能被单测覆盖(293 个用例里绝大多数不用起 UI),也能给 IDE 做实时校验。
- 引擎不认识组件。 内置组件和宿主组件走同一条注册路径,于是"扩展引擎"和"使用引擎"是同一件事 —— 没有需要修改内核才能加功能的时刻。
- 诊断收集而不是 fail-fast。 一次报全所有错误,是把"改配置"这件事从"调试"降级成"改错别字"的关键。
项目内部还有三份文档:DESIGN.md(分层与语义契约)、IMPLEMENTATION.md(逐文件职责与实现细节)、API_USAGE.md(可复制的用法),比这篇文章细得多 —— 尤其是每个决策为什么这么定、哪些方案被明确否决过。
如果这篇对你有用,或者你也在做"服务端下发 UI"这类的事,欢迎在评论区聊聊你们的方案 —— 尤其是校验规则该从哪儿来这个我还没想好的问题。