KMP 实战:用 XML 描述界面,写一个 Compose 动态表单引擎

15 阅读17分钟

KMP 实战:用 XML 描述界面,写一个 Compose 动态表单引擎

服务端下发一段 XML,客户端把它渲染成原生界面 —— 同一份 XML 在 Android、iOS、Desktop 上跑出同一个页面。 这不是 WebView,也不是自绘,每一个标签最终都编译成对 Compose 组件的一次调用。


0. 先看它长什么样

01-xml-to-ui.png

左边是 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 三条设计红线

做这类"别人下发的东西由我来渲染"的引擎,最容易出的问题不是渲染不出来,而是出错时说不清。所以一开始就定了三条红线:

  1. 能在解析期报的错,绝不留给运行期。 标签名拼错、属性名拼错、把字面量写进可写槽位、{{dta.x}} 里的全局对象名拼错 —— 这些都在拿到 XML 的那一刻全部报出来,一次报完,而不是"改一个跑一次"。

  2. 引擎本身不认识任何具体组件。 内置的 Text、Button 和宿主自己写的 RatingBar 走完全同一条注册路径。没有任何 if (tag == "Text") 之类的特权分支。

  3. 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. 整体架构

02-architecture.png

依赖是严格单向的: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 个包

包行数职责
diag273诊断码、严重级别、Diagnostic 本身
value1081Value(= Any? 的规范形态)、DataObject、DataArray、normalize
syntax1109词法 + 语法:XML → AST,表达式 → AST
env401Env 作用域链、EnvSchema(解析期能看见的"能力表")
eval1291求值器、内置方法表、宿主扩展链
node747Node / AttrSlot / NodeType / 结构节点
parse1107AST + 能力表 + 白名单 → 节点树 + 诊断
render720节点 → 渲染器 → Composable;属性求值、事件绑定

有意思的是 engine 完全不认识 tag。parse 只查 NodeTypes(一张 tag → NodeType 的表),render 只查 Renderers(KClass → Renderer)。这两张表都由注册表提供,而注册表里有什么,取决于宿主装了什么。

唯一的反向禁令:engine.node 不 import api.decl。所以 If / Foreach 这两个结构节点至今仍用裸的 AttrSlot,而不是 props.bool("test") —— 让它们用 Props 就会形成 node → api.decl → node 的环。收益只是内部 4 个类少写几个泛型,而宿主永远不会写结构节点,不值得为它破一层依赖。


4. 实现原理

4.1 一次渲染过四道关

03-pipeline.png

阶段 ① syntax:XML 文本 → AST

自写的解析器(不引 XML 库,因为 KMP 上没有合适的、能同时给你源码位置的库)。属性值在这一步就被分成三种形态:字面量、{{path}}、@{script}。

这一阶段是唯一可能"整页无树"的地方 —— 标签没闭合时,没有"继续解析"这回事。

阶段 ② parse:AST + 能力表 + 白名单 → 节点树

这一步做三件校验:

  1. 全局对象名:{{dta.user}} 里的 dta 不在能力表里 → 报错。但不校验成员存在 —— data.user 有没有 user、action 注册了哪些函数,都是运行期的事。
  2. 属性白名单:<Text valu="x"/> 这种拼写错误,由 NodeType.attributes 拦住。
  3. 可写性:可写槽位收到字面量 → 报错。

阶段 ③ 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.BindAttrRef.Code
求值沿 Env 链读路径,读即订阅交给求值器跑 AST
可写是(env.assign 写回路径)不作为槽位写回;但脚本可以调用有副作用的函数改数据
能算不能能

事件槽位比较特别:它需要"点击那一刻"的现场,但局部变量(item)又必须是"渲染那一刻"的。所以绑定时会做一次快照:

val eventEnv = ctx.env.root().child()          // 全局对象要执行那一刻的
for ((k, v) in captured) eventEnv.define(k, v) // 局部变量要渲染那一刻的

根 env 用"现在"的(否则请求延迟期间用户改的值会被旧快照覆盖),局部变量用"渲染时"的(否则点击拿到的是循环结束后的最后一个元素)。

4.3 「这个属性能不能写」是三件事分别回答的

04-writability.png

这是被问得最多的一个问题:options="{{config.regions}}" 和 value="{{region}}" 都写双括号,为什么前者只读、后者可写?

因为括号只说明值的形态,不说明能不能写。三道闸门是"与"的关系:

  1. 形态:可写槽位只收 {{path}}。写死一个字面量进去 = "用户改了也存不回去",解析期直接报错。
  2. 访问器:props.varString(...) 有 setter,props.string(...) 没有。所以 SelectNode 里 options 是 string(...)、value 是 varValue(...) —— 同一个组件里两个属性,可写性不同。
  3. 数据:目标容器必须是可写的。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

05-foreach-identity.png

现象:删掉列表中间一行,数据确实删了,日志也打了,界面就是不动。

根因不在"删除",在"行身份"。如果拿下标当 key:

  • 删掉第 0 行后,剩下的元素前移;
  • 但 Compose 只看到"下标 0 还在",于是复用第 0 组的 slot;
  • 而这个 slot 记着的是已经被删掉的那个元素的状态;
  • 这一组没有重组,界面停在旧值。

试过的错方案:给行加 revision 参数、用 key(element) 再包一层子节点、在 SideEffect 里写槽位 —— 都不稳。

最后是两条规则一起用才解决:

  1. 行 key 三级退化:key="id" → 元素本身 → 下标。没写 key 时默认用元素对象本身,绝不用下标。下标会随增删错位,那就是上面这个 bug 的源头。
  2. RenderNode 标 @NonSkippableComposable。

第 2 条容易被忽略:Foreach 每帧用 Env.define("item", …) 原地改行变量(这是为了不重建整行)。而"组合期写 MutableState"有个前提 —— 下游没被跳过。如果这一组恰好被 Compose 跳过,写进去也唤不醒它。关掉跳过是唯一可靠的办法。

4.6 组件扩展 API:一个属性名只写一遍

06-declarative-api.png

早期的写法里,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. 小结

这个项目最核心的三个判断,回头看都是对的:

  1. 把"解析"和"渲染"彻底分开。 解析期不碰 Compose,所以它能在 CI 里跑、能被单测覆盖(293 个用例里绝大多数不用起 UI),也能给 IDE 做实时校验。
  2. 引擎不认识组件。 内置组件和宿主组件走同一条注册路径,于是"扩展引擎"和"使用引擎"是同一件事 —— 没有需要修改内核才能加功能的时刻。
  3. 诊断收集而不是 fail-fast。 一次报全所有错误,是把"改配置"这件事从"调试"降级成"改错别字"的关键。

项目内部还有三份文档:DESIGN.md(分层与语义契约)、IMPLEMENTATION.md(逐文件职责与实现细节)、API_USAGE.md(可复制的用法),比这篇文章细得多 —— 尤其是每个决策为什么这么定、哪些方案被明确否决过。

如果这篇对你有用,或者你也在做"服务端下发 UI"这类的事,欢迎在评论区聊聊你们的方案 —— 尤其是校验规则该从哪儿来这个我还没想好的问题。