视图协议
JS 逻辑层(@weft-ui/runtime/remote 和生成的 remote 模式逻辑模块)与视图层(小程序 WXML、原生平台、无头渲染器)之间的约定,实现以本文为准。
参考实现是 @weft-ui/runtime/testing 的无头渲染器:它把每批 ops 编码、解码、按布局校验后应用到内存树上。tests/conformance/golden/ 的黄金文件就是它记录的 ops 文本。
ViewLayout(crates/transformer/src/view.rs)从整个应用的 Program 推导,JSON 形式由 WASM 的 compileApp(...).layout 给出,例子见 crates/transformer/tests/snapshots/TodoList/layout.json。
{ "hash": "a6bb96edf9a9ad2d", "templates": [ { "label": "TodoList", "kind": "component", "roots": [0], "nodes": [{"element": "Column", "props": {}, "children": [1, 2]}, {"point": 0}], "values": [{"node": 1, "prop": "value", "type": "String"}], "events": [{"node": 1, "event": "onChange", "payload": "String", "controls": 0}], "points": [{"node": 2, "kind": "branch", "templates": [1]}] } ]}- 模板编号:先是每个组件体,按 Program 中组件的顺序,所以模板
i就是组件i的组件体;之后按出现顺序是各组件内的if分支(每个分支一个)、for行体和插槽内容。label只用于调试:TodoList、TodoList:if8.0(节点 8 的第 0 个分支)、TodoList:for7、Board:slot12。 - 节点:
nodes是模板内的局部节点表,roots是顶层节点。元素节点带静态属性props(没有绑定的字面量,平台直接内联进模板,不占槽位)和子节点;{"point": n}是挂载点n在树中的位置。 - 值槽
values[i]:节点的一个动态属性,type是元素属性声明的类型:Int/Bool/String/Color。Color槽的值是字符串,由平台解析(规则见语法的内置元素与布局);静态颜色已在编译期校验,props里写成规范化的#rrggbb或#rrggbbaa。受控属性(Input.value、Checkbox.checked)即使是常量也总是值槽。 - 事件槽
events[i]:节点的一个事件属性,payload是载荷类型(null表示无载荷)。Input/Checkbox总有onChange事件槽,controls是它控制的值槽下标,其余事件为null。生命周期属性(onMount/onUnmount)由 JS 处理,不进入布局。 - 挂载点
points[i]:branch(templates依次是各分支的模板)、list(template是行体)、instance(template是被实例化组件的组件体)或slot(插槽内容由使用方提供,可以是任意slot种类的模板)。 - 哈希:去掉
hash字段后的 JSON 的 FNV-1a 64 位哈希,16 位十六进制。它同时写进 JS 逻辑(App构造参数)和平台视图,sink 在open时比对,不一致直接报错。
运行时每个模板实例是一个 scope。id 由 JS 按 app 分配,从 1 开始递增,不复用。scope 0 是虚拟的根,它只有挂载点 0:根组件实例用 attach 0 0 <id> 挂上去。
scope 在 create 时创建,此时还没挂上树。它被 branch 换掉、不再出现在 rows 里、或者祖先被销毁时隐式销毁,后代一起销毁。unmount 时 sink 收到 close,所有 scope 一起作废。
| op | 参数 | 含义 |
|---|---|---|
create |
scope, template | 创建实例 |
set |
scope, slot, value | 写值槽,值的类型与槽的类型一致 |
branch |
scope, point, child | 0 | branch 挂载点切换到 child(0 表示没有分支),旧的子 scope 销毁 |
rows |
scope, point, [child…] | list 挂载点的完整新顺序,不在新列表里的行销毁 |
attach |
scope, point, child | instance / slot 挂载点挂上 child,每个挂载点只发一次 |
保证:
- 一批 ops 对应一次 flush,sink 在
commit时整批应用。 - 新 scope 的
create和它所有值槽的set都在同一批里,且先于挂载它的 op。平台总是先建好子树再插入。 - 新 scope 的
branch挂载点为空、list挂载点没有行;状态不变时不发 op(空列表不发rows,顺序不变的列表不重发,值没变不发set)。 - 同一个挂载点上的 child 只能是该挂载点允许的模板的实例,一个 scope 最多挂载一次。
反方向只有一种消息:Session.dispatch(scope, slot, payload) → boolean,slot 是事件槽下标,payload 的类型由事件槽决定。JS 同步执行处理函数并 flush,所以返回前 sink 已经收到这次事件引起的 ops。返回值表示受控编辑是否被接受:事件槽没有 controls、scope 已销毁、或者被控值槽的当前值等于载荷时为 true。返回 false 时视图把控件恢复成被控值槽的当前值(宿主改写过的值已经通过 set 到达)。已销毁或未知 scope 的事件被忽略并返回 true。
二进制编码(版本 1)
Section titled “二进制编码(版本 1)”一批 ops 是一段字节:第一个字节是版本号 1,之后是连续的 op。整数都是 u32 小端。
| opcode | op | 字段 |
|---|---|---|
| 1 | create |
scope, template |
| 2 | set |
scope, slot, value |
| 3 | branch |
scope, point, child |
| 4 | rows |
scope, point, count, child × count |
| 5 | attach |
scope, point, child |
值以一个 u8 标签开头:0 false、1 true、2 数字(f64 小端,Int 槽的值也按 f64 传)、3 字符串(u32 字节长度 + UTF-8)。JS 侧的 OpWriter(@weft-ui/runtime 的 src/ops.ts)复用同一块缓冲,每批的字节只在下一次写入前有效。
调试 dump 和黄金文件使用的一行一个 op 的形式,字符串和布尔值按 JSON 书写:
create 3 2set 3 0 "milk"rows 2 0 [3 4 5]branch 1 0 0attach 0 0 1无头渲染器在 # 后附上模板 label 或槽位说明,例如 create 1 0 # TodoList、set 1 0 "" # Input.value。
Sink 是平台一侧的接口(src/remote.ts):
open(session):mount 时调用一次,session带hash、dispatch和detach(平台视图先于 app 消失时调用)。create/set/branch/rows/attach:记录本批 ops。commit():一次 flush 结束,应用整批。close():unmount,丢弃所有 scope。
小程序 sink(./wechat)不编码,直接把 ops 翻译成 setData 路径,数据形状见下文;无头渲染器经过二进制编码;原生 sink(./native)把缓冲交给 __weft.commit,见下一节。
小程序数据布局
Section titled “小程序数据布局”WXML 只渲染 {{key}},setData 的路径就是块数据树中的路径(N 是 IR 中的节点编号):
| key | 内容 |
|---|---|
n{N}_{i} |
属性值、文本 |
e{N} |
事件处理器 id(sink 分配),WXML 中写成 data-h,由视图组件的 $e 分发 |
i{N} / b{N} |
if 当前分支下标 / 分支数据 |
l{N} |
for 的行数组,每行带 k(行的 scope id,用作 wx:key) |
c{N} |
组件实例数据 |
y{N} |
插槽数据,t 是插槽模板名({组件}-s{N}) |
setData 规则:
- 每次 flush 每个视图只调用一次
setData。块的set用===比较新旧值,只发送变化的叶子,路径如r.b8.l7[2].n3_0。 - 列表只在末尾追加时发送新行的下标路径(
l7[3]);删除、移动、插入时整体发送行数组,复用的行保留原有处理器 id;顺序没变时不发送。 - 同一次 flush 中被其他路径覆盖的路径(祖先已整体发送)会被丢弃。
原生平台的 JS bundle 跑在 native/core 的内核里:内核嵌入 Hermes,执行 bundle.hbc,通过 C ABI(native/core/include/weft/runtime.h)和平台壳通信。iOS / macOS 的平台壳是 native/apple 的 WeftKit,Android 的是 native/android 的 Kotlin 模块(通过 JNI 加载 libweft.so),Windows 的是 native/windows 的 Weft.WinUI(通过 P/Invoke 加载 weft_core.dll),Linux 的是 native/linux 的 C++ 库(链接 libweft_core.so)。内核不开线程,所有函数都在 UI 线程上调用,且不能在 weft_host 回调里重入。
__weft 全局
Section titled “__weft 全局”内核在 bundle 运行前安装,@weft-ui/runtime/native 和 @weft-ui/platform 的原生实现通过它工作:
| 成员 | 含义 |
|---|---|
open(hash, dispatch) |
sink 的 open。hash 与平台壳传给 weft_runtime_new 的布局哈希不同就抛错,已有 app 打开时也抛错 |
commit(buffer, offset, length) |
一批 ops。内核把这段字节直接交给 weft_host.commit,不复制 |
close() |
sink 的 close;之后的事件被忽略 |
supports(module) |
平台壳是否实现平台模块 module |
call(module, method, args?) |
平台调用,返回 Promise<ArrayBuffer>。args 是字符串(按 UTF-8 发送)、ArrayBuffer 或其视图。模块不受支持时立即以 Error 拒绝 |
version |
平台壳报告的系统版本(weft_host.version) |
内核还注入 setTimeout / setInterval / clearTimeout / clearInterval、queueMicrotask 和 console(debug / log / info / warn / error 对应 weft_host.log 的 0–3 级;非字符串参数按 JSON 输出,错误对象输出 stack)。TextEncoder / TextDecoder 由 Hermes 自带。
weft_runtime_new执行 bundle(bundle 在其中挂载 app),之后每个会执行 JS 的入口(new、tick、dispatch、resolve)返回前都清空微任务队列。所以weft_runtime_new返回时第一批 ops 已经提交。- 定时器按到期时间、同一时间按设置顺序执行,每个定时器之后清空一次微任务;在一次
tick里新设的定时器留到下一次。内核用weft_host.schedule(delay)请求下一次tick,平台壳可以合并请求,提前或多余的tick无害。 - 未捕获的异常(bundle、定时器、微任务、事件处理函数里)以
WEFT_LOG_ERROR报告,不终止运行时。bundle 本身抛错(包括布局哈希不一致)时weft_runtime_new返回NULL。
weft_runtime_dispatch(rt, scope, slot, payload, len) 的 payload 是一个按二进制编码的值(标签字节加数据),无载荷的事件传空。返回值即 Session.dispatch 的返回值。
__weft.call 分配调用 id 并调用 weft_host.call(id, module, method, args);平台壳异步完成后在 UI 线程调用 weft_runtime_resolve(id, ok, result),每个 id 恰好一次。ok 时 Promise 以 result 的 ArrayBuffer 副本兑现,否则以消息为 result(UTF-8)的 Error 拒绝。字节的含义由各模块约定:
| 模块 | 方法 | 参数 | 结果 |
|---|---|---|---|
fetch |
request |
帧:u32 头长度(小端) | 头(UTF-8 JSON)| 请求体,头是 {"url", "method", "headers"} |
同样的帧,头是 {"status"},之后是响应体 |
storage |
get / set / remove |
JSON 数组:[key] 或 [key, value] |
get:JSON 字符串或 null;其余为空 |
@weft-ui/platform 在 supports(api) 为假时直接抛 PlatformError,不发起调用。
自己移动原生行的平台壳(WinUI、GTK)可以用 weft_stable_rows(old, new, stable):它标出新顺序里保持原位的行(旧位置的最长递增子序列),其余行需要移动或插入。C++ 平台壳可以用 weft/ops.hpp 解码 ops,解码不分配内存,字符串和行列表直接指向这批字节。