一套设计器同时跑 Vue 2.7 和 Vue 3:lowcode-engine-vue 重构记录
把 Vue 2.7 和 Vue 3 两个低代码渲染器、八个仓库重建成一个:为什么重建、三条路里选了哪条、留下了什么;一个渲染器内核加两个适配层,去掉包装组件,渲染器与出码共用 schema 读法,物料从文档生成,以及结果和教训。
在画布里拖一个原生的 button,给它绑一个 onClick,点一下。在旧的 Vue 2.7 渲染器里,什么都不会发生。计数器停在 0,事件从头到尾就没有绑到那个按钮上。
这个渲染器 2023 年 7 月发布了 1.0.0,之后三年没有动过。它不是唯一的一个:旁边还有一个 Vue 3 的渲染器,以及分散在另外几个仓库里的设置器、插件、物料和工具。
现在它们是一个仓库,lowcode-engine-vue。一套设计器,用 ?vue=2 / ?vue=3 切换 Vue 版本;两个版本背后是同一个渲染器内核,同一批测试各跑一遍。线上地址是 lowcode-vue.pages.dev,用法见使用指南。

这篇文章讲为什么要重建、当时有哪几条路、留下了什么、新的结构是什么样,以及结果。最后是几条教训和还没解决的问题。
一点历史
阿里的 LowCode Engine 是 React 写的,官方只有 React 的渲染器。社区的 KNXCloud/lowcode-engine-vue 给它做了 Vue 3 的渲染器和画布,下面所有的东西都是从它来的。
2023 年 3 月,我 fork 了它,把渲染器移植到 Vue 2.7,给还停在 Vue 2 的项目用。低代码平台搭出来的页面要嵌进已有的系统,而很多内部系统连同它们用的 Element UI、Vant 2 都停在 Vue 2,短期内不会整体升级。Vue 2.7 是这些项目能升到的最后一站。
之后的做法是缺什么就再开一个仓库:设置器一个,设计器插件一个,物料工具两个,物料按 Vue 版本各一个,再加一个 demo 设计器。Vue 3 的 demo 直接用 @knxcloud 的渲染器包,Vue 2.7 的用自己移植的那套。
每个仓库各管一件事,单看都说得过去。麻烦在于它们有八个。
flowchart LR
subgraph old["2023:八个仓库"]
direction TB
r27["lowcode-engine-vue2.7<br/>Vue 2.7 渲染器(4 个包)"]
knx["@knxcloud 的包<br/>Vue 3 渲染器"]
ext["lowcode-engine-ext-vue<br/>设置器"]
plg["lowcode-engine-plugins<br/>设计器插件"]
tools["lowcode-engine-tools2.7<br/>vite-plugin-lib-types2.7"]
mat["lowcode-engine-materials-vue<br/>lowcode-engine-materials-vue2.7"]
demo["lowcode-engine-demo-vue<br/>设计器"]
end
subgraph now["现在:一个仓库"]
direction TB
renderer["packages/renderer<br/>内核 + 两个适配层"]
plugins["packages/plugins"]
ptools["packages/tools"]
materials["packages/materials"]
designer["apps/designer"]
end
r27 --> renderer
knx --> renderer
ext --> plugins
plg --> plugins
tools --> ptools
mat --> materials
demo --> designer
旧仓库各自去了哪里。
问题
低代码页面是一份 schema,一段描述页面的 JSON。同一份 schema 有三个读者。
画布里的 Vue 3 渲染器要把它渲染出来,还要告诉设计器每个节点对应哪个组件实例,这样才能选中、拖拽。
画布里的 Vue 2.7 渲染器做同样的事,但它脚下的 Vue 不一样:vnode 的数据结构不同,没有 Fragment,事件和属性的透传规则不同。
出码器不渲染,它把 schema 翻译成 .vue 文件,交给用户带走。
三个读者各读各的,同一份 schema 就可能有三种解释。
有些问题不会出现在设计文档里,要等系统跑了几年才看得见。2026 年 11 月,我对着 Vue 2.7 的源码把那个渲染器审了一遍,记下 31 条问题,其中 11 条在 jsdom 里复现了。开头那个点不动的按钮是第一条。
它其实是一个 Vue 3 的渲染器。 移植的时候保留了 Vue 3 的语义,而 Vue 2 没有这些语义:
- 原生标签上的事件不触发。
onClick被放进了组件事件里,Vue 2 不会把它透传给原生元素。 - 循环会多包一层
div。Vue 2 没有 Fragment,这层div让el-col、tr、option这类依赖父子结构的布局全部错位。 - 默认插槽拿不到作用域参数,
el-table-column的单元格渲染出undefined。 v-model写死成value+input,组件自己声明的model选项被忽略。- Vue 2 的生命周期名(
created、beforeDestroy、destroyed)被悄悄忽略。 - 表达式里的
this是按文本替换的。绑定一个字符串"click this now",渲染出来是click __self now。 - 每次渲染都用
new Function重新编译每一个表达式,没有缓存。
而且没有测试。一条都没有。
两个渲染器在漂移。 每个功能、每个修复、每条测试都要做两遍,实际上总有一边没做。把两边摆在一起看:Vue 2.7 那套不支持源码面板里的 props、emits、computed、watch、provide、inject、setup,也不能渲染区块和低代码组件;Vue 3 那套没有后来写的表达式编译器,没有数据源上的几处修复,测试也大多没有。
每个节点外面都套着一层包装组件。 这是从上游沿用下来的结构:设计模式下每个节点能单独订阅自己的变化。代价是父组件看到的子节点全是包装层。Ant Design Vue 的 Select 读子节点的 vnode 来找 Option,看到的是包装组件,认不出来;Element UI 的 Tabs 顺着 $parent 找父组件,中间多一层就断了。
物料是手写的,写错了很多。 Vue 3 的事件写成了 kebab-case,Vant 4 的物料里用的是 Vant 2 的事件,Ant Design Vue 1.x 的元数据是照着 React 版的 API 写的。
八个仓库之间没有连接。 改一行渲染器的代码,要用浏览器插件把线上的画布脚本代理到本地才能看效果。跨渲染器、插件、物料的一个改动,要发三次版。
单独看,每一条都不大。合起来,就是任何一处都不敢放心改。
决定
当时有三条路。
第一条,原地修。这条路我先走了:在旧仓库里把 31 条里的 30 条修掉,并补上了回归测试。Vue 2.7 的渲染器因此变好了,但修复只落在一边。Vue 3 那套没有得到这些修复,Vue 2.7 这套也没有得到 Vue 3 那边有的功能。修得越多,两边差得越远。
第二条,保留两个渲染器,把仓库合到一起,共享工具函数。调试和发版会轻松很多,但造成问题的结构还在:两份渲染逻辑,两份测试,同一个 bug 修两次。
第三条,只留一个渲染器内核。内核只用 Vue 2.7 和 Vue 3 共有的那部分 API,两边不一样的地方收进一个适配层,测试写一份、跑两遍。然后把插件、物料、工具和设计器都搬到它旁边。选的是这一条。
它能成立,靠的是一个事实:Vue 2.7 把 Composition API 搬了回来。defineComponent、ref、reactive、computed、watch、provide / inject、getCurrentInstance 和生命周期钩子,两边都有,而且都是 import from 'vue'。
对这种重建,有两个合理的质疑。
“不要从头重写。” 没有从头。内核是把两边各自有的东西合到一起:Vue 2.7 这边审计之后修过的代码和测试,Vue 3 那边的区块、低代码组件和源码面板的钩子。审计里复现过的问题已经是测试,合并之后它们在两个 Vue 版本上各跑一遍,旧的行为就是规格。
“为什么不用 vue-demi,或者 Vue 3 的兼容构建?” vue-demi 解决的是“从哪里导入 Composition API”,Vue 2.7 内置这套 API 之后,这一层已经不需要了;渲染器真正的差异在它不管的地方,vnode 的结构、h 的参数、挂载方式、实例的内部字段。@vue/compat 方向是反的:它让 Vue 2 写法的代码跑在 Vue 3 的运行时上,而这里要的是 Element UI、Vant 2 这些 Vue 2 组件库原样工作,它们需要真正的 Vue 2 运行时。
留下了什么
重写很容易把旧代码说得比实际更差。旧实现里对的东西不少,都留下来了。
上游把 schema 的约定定对了。 从 React 版引擎过来的 schema 可以直接用:this.state.xxx 和 this.props.xxx 都读成 this.xxx,React 的生命周期名映射到 Vue 的钩子,onUpdateXxx 可以代替 onUpdate:xxx。这些一条没动。
“用 Vue 3 的写法写渲染器,再转换给 Vue 2”这个思路是对的。 旧代码里有一个叫 Vue3Adapter 的文件做这件事,问题出在它转换得不完整,而且被复制成了两份、互相对不上。思路本身留了下来,变成了适配器接口上的 h。
渲染器的骨架。 一个 Renderer 挑选容器渲染器,一个根作用域负责组装 this,一个画布模块负责把组件实例对应到节点。现在还是这三块。
审计的复现用例,作为回归测试。
浏览器里的全局变量名,window.LCVueRenderer。
新做了什么
留下来的是约定和骨架。代码这一层,仓库里的包大部分是这次新写的:
| 包 | 来历 | 是什么 |
|---|---|---|
lowcode-vue-core | 新写 | 渲染器和画布的内核,两边合并后重新组织;外加一个不依赖 Vue 的 schema 读法模块 |
lowcode-vue2、lowcode-vue3 | 新写 | 两个适配层,各几百行 |
lowcode-code-generator | 新写 | 出码器:schema 变成 Vite + Vue 项目,带命令行 |
lowcode-plugin-code-generator | 新写 | 设计器里的“出码”按钮:预览文件,下载 zip |
lowcode-material-builder | 新写 | 基于 Vite 的物料构建器,替换原来的 Vue CLI 插件 |
create-lowcode | 重写 | 物料项目脚手架,Vue 2.7 和 Vue 3 两套模板 |
lowcode-materials-*(6 个) | 重新生成 | 565 个组件的元数据、片段和缩略图 |
lowcode-plugin-vue-code-editor | 沿用,大改 | 源码面板:setup() 写法、两个版本的类型提示 |
lowcode-engine-ext-vue | 沿用 | 设置器和绑定弹窗,补了多语言和测试 |
directive-loading、manual、set-doc-url | 沿用 | 三个小插件,补了多语言 |
表里看不到的还有两块:生成物料元数据的那套脚本,和设计器应用里新加的几个面板。
按“以前做不到、现在能做”来数,是这些。
把页面带走。 以前搭出来的页面只能活在渲染器里。现在可以出码:在设计器里点一下,或者在命令行里跑 lowcode-codegen,得到一个对应 Vue 版本的 Vite 项目,页面是普通的 .vue 文件,多页面带路由,数据源和多语言有一小段运行时代码。导不出去的东西(找不到来源的组件、要自己注册的指令)会列成警告,而不是悄悄丢掉。
用 Vue 的写法写逻辑。 源码面板以前在 Vue 2.7 下不可用。现在两个版本都能用,新页面默认是 setup(),编辑器里有对应版本的 Vue 和 vue-router 类型提示;setup() 返回的状态和方法会出现在属性面板的变量绑定和事件绑定里。
在设计器里做组件。 低代码组件以前在 Vue 2.7 下渲染不了。现在可以新建一个“组件”,像编辑页面一样编辑它,声明真的 props 和 emits,然后在别的页面里当普通组件用;预览和出码都认它。
一个项目,多个页面。 页面带路由路径,可以新建、切换、删除;选中的节点可以存成区块再插入;整个项目可以导出成一个 JSON 文件,在另一个浏览器里导入,或者重置回示例。
不改设计器就能加物料。 在面板里填一个 assets.json 的地址,物料运行时加载进来,并随项目一起保存。写物料也有了完整的一条线:脚手架建项目,构建器开发和打包,产物直接能被设计器加载、被出码器识别。
项目自己的多语言。 画布可以单独切换语言来看项目里的多语言文案,和设计器界面的语言互不影响,预览沿用同一个设置。
JSONP 数据源,画布和出码后的项目里都能用。
物料不再手写。 一套脚本从组件库对应版本的文档生成元数据,另一套测试拿它去核对安装的组件。
有东西守着。 491 个单测,渲染器和出码之间的对照测试,把每个物料渲染一遍的 E2E,检查包清单的 publint。以前这些一样都没有。
下面先讲它们放在什么样的结构里,再挑其中最费周折的几件展开。
新的结构
先看全貌。整个系统分四层,上层只依赖下层:
flowchart TB
subgraph L1["设计器应用(React)"]
direction LR
app["apps/designer"]
eng["LowCode Engine + 官方插件"]
own["自己的插件:页面、区块、物料、源码面板、出码"]
ext["engine-ext-vue 设置器"]
end
subgraph L2["画布与预览(Vue)"]
direction LR
sim["simulator:文档、路由、实例与节点的对应"]
ren["renderer:容器渲染器、根作用域、节点渲染、数据源"]
end
subgraph L3["内核里不依赖 Vue 的部分"]
direction LR
sch["schema 读法"]
exp["表达式编译"]
ast["资源加载、i18n"]
end
subgraph L4["适配层"]
direction LR
a2["lowcode-vue2 → Vue 2.7"]
a3["lowcode-vue3 → Vue 3"]
end
L1 -- "画布脚本地址、assets.json、节点模型" --> L2
L2 -- "纯函数" --> L3
L2 -- "VueAdapter" --> L4
设计器、画布、内核里的纯函数、适配层。出码器和物料是两条旁路,后面单独讲:出码器只用第三层里的 schema 读法,物料同时供给设计器、渲染器和出码器。
- 设计器应用是 React 的,负责编辑。它不认识 Vue,只知道三件事:画布脚本的地址、物料的
assets.json、引擎自己的节点模型。 - 画布与预览是 Vue 的,负责把 schema 变成界面。画布比预览多一个 simulator,用来和设计器对话。
- 内核里不依赖 Vue 的部分是纯函数:schema 怎么读、表达式怎么编译、资源怎么加载。出码器在 Node 里也能用其中的 schema 读法。
- 适配层是唯一知道自己跑在哪个 Vue 版本上的代码。
下面按这个顺序往下走。
一个设计器,两种画布
LowCode Engine 的顶栏、面板、设置器都是 React 组件,但画布是一个 iframe。引擎往里面加载一个渲染器脚本,用什么框架渲染 schema 完全由这个脚本决定。所以支持两个 Vue 版本不需要两套设计器,只要让 iframe 加载不同的东西。
flowchart TB
subgraph shell["设计器页面:React,不区分 Vue 版本"]
direction LR
engine["LowCode Engine"]
plugins["插件:页面、区块、源码面板、出码……"]
setters["属性设置器"]
end
shell -- "?vue=2" --> c2
shell -- "?vue=3" --> c3
subgraph c2["画布 iframe"]
direction TB
v2["Vue 2.7 运行时"]
s2["lowcode-vue2 simulator"]
m2["element-ui / vant2 / antd-vue1 物料"]
end
subgraph c3["画布 iframe"]
direction TB
v3["Vue 3 运行时"]
s3["lowcode-vue3 simulator"]
m3["element-plus / vant4 / antd-vue4 物料"]
end
同一个设计器外壳,按参数决定画布里加载什么。
设计器里读这个参数的代码只有几行,其余地方都从这里取:
// apps/designer/src/version.ts
export const vueVersion: VueVersion =
new URLSearchParams(window.location.search).get('vue') === '2' ? 2 : 3
export const runtime = {
vue: `/runtime/vue${vueVersion}/vue.js`,
renderer: `/runtime/vue${vueVersion}/renderer.js`,
simulator: `/runtime/vue${vueVersion}/simulator.js`,
simulatorCss: `/runtime/vue${vueVersion}/simulator.css`,
}
/** localStorage 的 key 也按版本分开,两个版本的项目互不影响 */
export const storageKey = (name: string) => `${name}:vue${vueVersion}`参数影响五样东西:Vue 运行时、渲染器和画布脚本、物料、示例项目、本地存储的 key。少数插件需要知道版本(源码面板要加载对应的类型声明,出码要生成对应版本的项目),都是注册时传一个 { vue: 2 | 3 },插件自己不依赖 Vue。

一个内核,两个适配层
两个 Vue 版本的差异不多,而且很集中:
| 差异 | Vue 2.7 | Vue 3 |
|---|---|---|
| vnode 数据 | VNodeData(props / attrs / on / scopedSlots 分开放) | 扁平的 props,有 Fragment |
| 实例内部字段 | _uid、_isDestroyed | $.uid、$.isUnmounted |
| 挂载 | new Vue(...) | createApp(...) |
| 路由 | vue-router 3(没有 removeRoute) | vue-router 4 / 5 |
v-model | model 选项,默认 value + input | modelValue + update:modelValue |
它们全部收进一个 162 行的 VueAdapter 接口。节选:
// packages/renderer/core/src/adapter.ts(节选)
export interface VueAdapter {
readonly version: 2 | 3
/** 创建 vnode。props 统一用 Vue 3 的扁平写法(onClick、class、v-xxx……) */
h(type: string | VueComponent, props?: object | null, slots?: Slots): VNode
/** 没有根元素时的容器 */
readonly Fragment: VueComponent
/** 增删属性并让响应式对象感知到 */
set(target: object, key: string, value: unknown): void
del(target: object, key: string): void
/** 不带参数的 v-model 对应哪个 prop 和事件 */
modelOf(component: unknown): { prop: string; event: string }
/** 给组件 vnode 加上“卸载后回调”的 props */
unmountedHook(callback: () => void): Record<string, unknown>
instanceId(instance: ComponentInstance): number
isAlive(instance: ComponentInstance): boolean
}@cdlab996/lowcode-vue2 和 @cdlab996/lowcode-vue3 各实现一份,168 行和 214 行。同一个方法,两边大概是这个量级:
// Vue 2.7
modelOf(component) {
const model = getComponentOption(component, 'model')
return { prop: model?.prop ?? 'value', event: model?.event ?? 'input' }
},
unmountedHook: (callback) => ({ 'onHook:destroyed': callback }),
// Vue 3
modelOf: () => ({ prop: 'modelValue', event: 'update:modelValue' }),
unmountedHook: (callback) => ({ onVnodeUnmounted: callback }),真正有分量的是 h。内核里所有节点都按 Vue 3 的扁平写法给 props,Vue 3 那边几乎原样传下去;Vue 2 那边要按组件声明的 props 把它们拆回 VNodeData:声明过的进 props,onXxx 进 on,v-xxx 进 directives,剩下的进 attrs。开头那个点不动的按钮,就是旧代码在这一步漏了原生标签的事件。
对比一下审计清单:那些“Vue 3 的语义没有适配 Vue 2”的问题,现在各自落在接口的某个方法上。新发现一处差异时,接口会逼着两边都给出实现。
这条路也有成本。Vue 2 这边每创建一个 vnode 都要多做一次转换;凡是内核想用、但只有一边有的能力,都得先变成接口上的方法,写起来比直接调用绕一点。
Vue 2 的组件只能有一个根节点,所以适配层里 Vue 2 的 Fragment 实际渲染成一个 div。schema 没有根元素时,两个版本的 DOM 会差这一层。循环不受影响:循环项是作为兄弟节点渲染的,不再多包一层。
内核内部怎么分
内核的目录就是上面那张图的中间两层:
packages/renderer/core/src/
adapter.ts VueAdapter 接口,setAdapter / getAdapter
shared/ 不导入 vue:schema 读法、表达式编译、改写 this、
资源加载、i18n、类型判断
context/ 渲染器上下文(设计模式、组件表、getNode)
renderer/
renderer.ts <Renderer>:按 schema 的根类型挑容器渲染器
renderers/ Page、Block、Component 三种容器
root-scope/ 组装 this:状态、方法、生命周期、setup、数据源、css
use.ts 节点渲染:属性、插槽、循环、条件、ref
leaf.ts 节点状态:拆分属性和插槽,设计模式下订阅节点
data-source/ 数据源引擎,内置 fetch 和 jsonp
simulator/ 画布:文档实例、内存路由、实例与节点的对应、选区和光标对外是三个入口,按“需要多少”切开:
| 入口 | 包含 | 谁用 |
|---|---|---|
./schema | 只有 schema 读法,不导入 Vue | 出码器 |
./runtime | 渲染器,不含画布,不依赖 vue-router | 预览页、线上页面 |
. | ./runtime 加上画布 | 设计器的画布 |
切成三个不是为了好看。预览页不该为了一个用不到的画布去加载 vue-router;出码器跑在 Node 里,不该为了读一条规则去装 Vue。所以内核把 vue 声明成可选的 peer,路由相关的能力单独放在一个 RouterAdapter 里,只有完整入口才装它。
适配器是内核模块里的一个变量,@cdlab996/lowcode-vue2 / lowcode-vue3 被导入时调用 setAdapter() 把自己装进去。这带来一个硬约束:一个应用里内核只能有一份。最早内核是私有包,构建时内联进两个适配包和出码器,同一段逻辑于是出现在三个产物里;应用里一旦同时存在两份内核,适配器只会装到其中一份上,另一份调 getAdapter() 时直接抛错。后来内核改成单独发布的包,其他包依赖它;只有给浏览器直接用的 UMD 包还内联内核,因为那里没有包管理器。
画布:设计器和渲染器怎么对话
画布里除了渲染,还要回答设计器的问题:这个 DOM 元素属于哪个节点,这个节点的组件实例在哪,它占了页面上哪块区域。这部分是 simulator。
sequenceDiagram
participant H as 设计器(引擎的 host)
participant S as simulator
participant R as Renderer
participant C as 组件实例
H->>S: 连接:物料库、组件表、设备、语言、设计模式
H->>S: 文档列表(autorun)
S->>S: 每个文档一条内存路由
S->>R: 当前文档导出的 schema
R->>C: 渲染节点
C-->>S: ref 回调:节点 id + 实例
S-->>H: setInstance(文档, 节点, 实例记录)
H->>S: 用户改了属性:节点的 onPropChange
S->>R: 节点状态更新,容器重新渲染
H->>S: 点击画布:这个元素是哪个节点?
S-->>H: 最近的节点和实例
一次编辑往返:设计器改节点,渲染器更新界面,实例再报回设计器。
几个设计点:
- 每个文档是一条路由。 项目里的页面和低代码组件都是引擎的“文档”。simulator 建一个内存路由,每个文档一条,路径就是页面的路由路径;切换页面是一次
router.replace。这样页面里的$route、路由守卫在画布里也是真的。文档删掉时路由也要删,vue-router 3 没有removeRoute,这是适配器要补的一处。 - schema 从引擎的文档导出,不自己存。 渲染用的 schema 是
document.export()的计算属性,simulator 不保留副本。需要整页重来时,改一个时间戳让它重新导出。 - 属性变化不走整页导出。 设计模式下,每个节点的状态订阅引擎节点的
onPropChange/onChildrenChange,改一个属性只更新那个节点的状态,再由 Vue 重新渲染它所在的容器。 - 实例和节点的对应是双向的。 往上报:节点渲染出组件后,
ref回调把实例交给 simulator,它记下“文档 id、节点 id、实例 id”三元组并通知引擎;卸载时回调一个null,simulator 用适配器的isAlive把死掉的实例清掉。往下查:simulator 在组件的根 DOM 元素上记了节点 id,设计器问“这个元素属于谁”时,顺着 DOM 往上找到第一个带记录的元素。 - 没有导入时的副作用。 画布模块被导入时什么都不做,
createSimulatorRenderer(host)才创建,UMD 包里再调一次installSimulatorRenderer()挂到window.SimulatorRenderer。所以它能在 jsdom 里被测试,旧实现做不到这一点。
schema 里的 this
schema 里的逻辑是 state、methods、生命周期,加上属性上绑定的表达式。渲染器要回答两个问题:这些东西合起来的 this 是什么,表达式怎么求值。合并之前,两套渲染器在这里差得最多。
this 就是渲染器组件的公开实例。做法是让 setup() 返回要暴露的东西,交给 Vue 自己挂到实例上:
// packages/renderer/core/src/renderer/root-scope/state.ts
export function useRootState(stateSchema, initData) {
const states = parseSchema(stateSchema) ?? {}
return toRefs(reactive({ ...states, ...initData }))
}状态、计算属性、inject 进来的 ref、数据源的结果都这样返回,于是在两个版本里都是实例上的响应式属性。这里有一条约束:不写任何私有字段(Vue 3 的 setupState、accessCache,Vue 2 的 _data)。直接改内部字段最省事,但两个版本的内部结构完全不同,也都不保证稳定。
初始化顺序照着选项式 API 来。唯一要适配器帮忙的是 “created 阶段”:注册 watch、数据源首次加载、调用 created,必须在 setup 返回、属性已经挂到实例上之后执行。Vue 2 里放进实例自己的 created 钩子列表,Vue 3 里用第一个 onBeforeMount。
表达式只有一个编译器:
// packages/renderer/core/src/shared/expression.ts
const body = `var ${SELF} = arguments[0];
with (arguments[0] || {}) { return ${rewriteThis(source, SELF)}
}`
fn = new Function(body)with 让不带 this. 的标识符也从作用域上找。rewriteThis 把代码里的 this 换成一个指向作用域的局部变量,否则表达式里嵌一个普通函数时,里面的 this 就不是页面了。它是一个小的扫描器,字符串、模板字符串里的文本、注释和正则字面量里的 this 不动,"click this now" 现在还是 click this now。编译结果按源码缓存,同一个表达式在循环里渲染一千行,只编译一次。
这个设计有一条边界要说清楚:schema 就是代码。表达式和方法是用 new Function 执行的,渲染一份 schema 等于运行它里面的 JavaScript。所以渲染器只该渲染你信任的 schema,不能拿来渲染用户随手提交的内容;页面的 CSP 也不能禁掉 unsafe-eval。这是所有“运行时解释 schema”的低代码渲染器共有的性质,不是这个实现特有的。绕开它的办法是下面要讲的出码:生成的项目里表达式已经写进模板,由 Vue 的编译器在构建时处理,运行时没有 new Function。
一份 schema,三个出口
同一份项目 schema,最后会从三个地方出去:
flowchart LR
schema["项目 schema<br/>页面、低代码组件、i18n、数据源"]
subgraph canvas["画布"]
direction TB
c1["simulator.umd.js"] --> c2["Renderer(design 模式)"]
end
subgraph preview["预览 / 线上"]
direction TB
p1["renderer.umd.js 或 /runtime 入口"] --> p2["Renderer(live 模式)"]
end
subgraph codegen["出码"]
direction TB
g1["模板生成 + 脚本生成"] --> g2["Vite + Vue 项目"]
end
schema --> canvas
schema --> preview
schema --> codegen
画布和预览是同一个 Renderer,只差设计模式;出码是另一个实现,靠对照测试和它们对齐。
画布和预览用的是同一个 Renderer 组件。预览页的全部逻辑是:从存储里读出项目,用资源加载器把物料脚本加载进来,把 schema 里的组件表和物料的全局变量对上,然后挂载 Renderer。没有路由,没有 simulator。线上页面走的是同一条路,只是从打包工具导入而不是从 window 读。
出码不经过渲染器。它把每个页面拆成两半:模板一半由节点树生成,脚本一半优先用源码面板里写的那份源码,没有的话从 state、methods、生命周期拼一个选项式组件。数据源、utils、constants、i18n 这些运行时的东西,写成一小段普通 JavaScript 放进生成项目的 src/lowcode/,通过 mixin 给到每个页面。生成的项目不依赖渲染器,是一个可以直接接手维护的 Vite 工程。
两条路共用的只有 schema 读法那一个模块,下一节讲它们怎么保持一致。
物料:一个包,三方消费
一套物料构建出三个文件,分别给三方:
| 产物 | 内容 | 谁用 |
|---|---|---|
index.js | 组件库本身,挂在 window[library] 上 | 画布和预览里的渲染器 |
meta.js | 每个组件的描述:属性、事件、插槽、默认片段 | 设计器的组件面板和属性面板 |
assets.json | 上面两个文件的地址,外加一份导出清单 | 设计器加载物料;出码器生成 import |
导出清单是这次加的。物料入口通常是从组件库重新导出(export { Button as VanButton } from 'vant'),构建时把“VanButton 是 vant 的 Button”、需要引入的样式和依赖版本记进 assets.json。出码器靠它把画布里的组件名还原成真实的 import,不用自己维护一张对照表。
低代码组件走的是同一个入口。项目里每个“组件”文档会注册成一个 devMode: 'lowCode' 的物料;渲染器遇到它时,用它的 schema 现场生成一个 Vue 组件,声明 schema 里写的 props,再把属性和事件转交给内部的 Renderer。对使用它的页面来说,它和 Element 的按钮没有区别。
第三方物料也是这条路:同一个构建器产出同样三个文件,在设计器的“物料”面板里填 assets.json 的地址,运行时加载进来。
设计器应用
apps/designer 是最薄的一层。它做三件事:把上面这些东西接起来,补几个官方引擎没有的面板,保存项目。
- 接线:读版本参数,注册插件,把画布脚本和物料交给引擎。
- 面板:页面管理(带路由路径)、低代码组件、区块、运行时物料、画布语言切换、出码。它们都是引擎的普通插件,放在应用里是因为和这个设计器的项目结构绑定。
- 保存:项目是一条记录,包含 schema、用到的物料包、运行时添加的物料地址。读写走一个三个方法的接口(
load/save/clear),默认实现是按 Vue 版本分开的localStorage。预览页读的是同一份记录。
它是一个纯静态站点,没有服务端。
包怎么依赖
把上面这些落到包上,依赖只有一条链:
@cdlab996/lowcode-vue-core 内核:渲染器、画布、schema 读法(peer:vue,可选)
├─ @cdlab996/lowcode-vue2 Vue 2.7 适配层(peer:vue 2.7、vue-router 3)
├─ @cdlab996/lowcode-vue3 Vue 3 适配层(peer:vue 3.5、vue-router 4 / 5)
└─ @cdlab996/lowcode-code-generator 出码器,只用到 core/schema
└─ @cdlab996/lowcode-plugin-code-generator 设计器里的“出码”按钮其余的插件、6 套物料、物料构建器和脚手架互不依赖,也不依赖这条链。所有公开的包用同一个版本号,一个 tag 一次发布:lowcode-vue3@2.0.0 依赖的一定是 lowcode-vue-core@2.0.0,看版本号就知道哪些包是一起的。以前按组分别发版,组之间有依赖时还要专门写脚本检查先后顺序。
去掉包装组件
每个节点外面那层包装组件(代码里后来叫 Leaf),是这次改动里风险最大的一处。
之前 现在
ASelect ASelect
└─ Leaf └─ ASelectOption
└─ ASelectOption它在的时候,为了绕开它做过两件事:把 10 个 Ant Design 的子组件从组件面板里藏起来(antd-vue1 藏了 6 个,antd-vue4 藏了 4 个),让主组件改用 options、columns 这类数据属性;在 Vue 2 的适配层里用一个 mixin 改写 $parent,让 Element UI 的 Steps、Carousel、Tabs 能找到真正的父组件。即使这样,手写同样结构的 schema,在画布、预览和线上都渲染不对。
现在每个节点直接渲染成组件自己的 vnode。包装组件原来承担的事情(拆分属性和插槽、设计模式下订阅节点变化)还在,只是从一个组件变成了一段普通的状态逻辑。做的过程里有四个坑:
- 节点状态要在“创建它的 vnode 的地方”读取。插槽函数在渲染该插槽的组件里执行,所以一个节点变了,重新渲染的是它所在的容器,Vue 再按 diff 只更新变了的部分。
- vnode 上带一个新函数,或者带一个 slots 对象(哪怕是
{}),子组件就会在父组件每次渲染时被强制更新。 所以给画布上报实例用的ref和卸载钩子要按 key 缓存,没有插槽的节点干脆不传 slots。 - 在同一个组件的
setup里,inject拿不到自己provide的值。原来由包装组件 inject 的上下文要显式传进去。 - Vue 2 下,不带参数的默认插槽要像模板编译那样作为 children 传,否则
$slots.default每读一次都是一批新 vnode。
最后一条的后果很有意思。Element UI 的 Tabs 会在每次更新后读面板实例,而它现在终于能看到自己的面板了,于是开始无限重渲染。以前隔着一层包装组件,它找不到面板,也就不会去反复读它们。修好一个问题,露出了一个一直被它挡着的问题。
考虑过两个折中,都没采用。只在预览和线上去掉包装、画布里保留:画布和预览就不一致了。针对具体组件库把包装层“拆开”:等于每个库打一个补丁。
代价要说清楚。以前一个节点变化只重新渲染它自己,现在重新渲染的是它的容器。有一条测试守着底线:改一个节点的属性,没变的兄弟节点不会跟着重新渲染。但设计模式下,大容器里改一个属性的开销理论上比以前大,这一点没有量过。量过的是另一头:去掉包装之后组件实例少了多少,数字在后面的“结果”里。
一份读法,两个读者
渲染器的问题解决之后,还剩第三个读者,出码器。它是这次新写的,写完和渲染器对照着读了一遍,已经在五处对不上:
| schema 特性 | 渲染器 | 出码器(修复前) |
|---|---|---|
children 属性和节点 children 同时存在 | 属性优先 | 节点 children 优先 |
onUpdateXxx 事件 | 归一成 onUpdate:xxx | 写成 @updateXxx,Vue 3 下永远不触发 |
v-model 绑定字面量 | 当普通属性传 | 生成 v-model="'x'",模板编译报错 |
没有内容的 JSSlot | 不传插槽 | 生成空的 <template #x /> |
全局 dataSource.dataHandler | 生效 | 被忽略 |
这是“两个渲染器在漂移”的同一个故事,只是换了一对主角,而且更隐蔽:用户在画布里看到的是对的,下载下来的项目是错的。
做法分两步。先把这些判断抽成一个纯函数模块 @cdlab996/lowcode-vue-core/schema,不导入 Vue,渲染器和出码器都用它,规则只写一处。
再写一套对照测试。每个用例是一小段 schema,加初始状态和要点击的元素:
{
name: 'v-model with an expression and a literal',
node: {
componentName: 'div',
children: [
{ componentName: 'XField', props: { 'v-model': expr('this.text') } },
{ componentName: 'XField', props: { 'v-model': 'literal' } },
{ componentName: 'span', children: [expr('this.text')] },
],
},
state: { text: 'initial' },
click: ['.x-field'],
}同一份 schema 走两条路。一边交给渲染器渲染;一边用出码器生成模板,用当前 Vue 版本的 vue/compiler-sfc 编译后挂载。然后对两边做同样的点击,比较 HTML 和记录下来的方法调用,必须完全一致。数据源则直接执行出码器写进项目里的运行时代码,和渲染器在同一个 mock 的 fetch 下比较请求和结果。两个 Vue 版本各跑一遍。
这套测试一上来又抓出四个问题。出码把相邻文本各放一行,Vue 编译时换行变成了空格。Vue 2 不支持带参数的 v-model,应该生成 .sync。渲染器的数据源没写 method 时没有默认 GET,参数被当成请求体发了出去。出码的运行时遇到 204 响应会报错。后两条不算“不一致”,是两边各自的 bug,但也是对着跑才发现的。
出码的结果长这样。输入是一个按钮、一个弹出层和一个循环:
{
"componentName": "Page",
"fileName": "index",
"state": { "open": false, "list": ["a", "b"] },
"methods": {
"toggle": { "type": "JSFunction", "value": "function () { this.open = !this.open }" }
},
"children": [
{
"componentName": "VanButton",
"props": {
"type": "primary",
"onClick": { "type": "JSFunction", "value": "function () { this.toggle() }" }
},
"children": "切换"
},
{
"componentName": "VanPopup",
"props": {
"v-model:show": { "type": "JSExpression", "value": "this.open" },
"position": "bottom"
},
"children": [
{
"componentName": "VanCell",
"loop": { "type": "JSExpression", "value": "this.list" },
"props": { "title": { "type": "JSExpression", "value": "this.item" } }
}
]
}
]
}用命令行的出码器(lowcode-codegen page.json --vue 3 --assets <vant4 的 assets.json>)生成的 src/pages/index.vue,原样贴出:
<template>
<div class="lc-page" style="height: 100%">
<VanButton
type="primary"
@click="
() => {
toggle();
}
"
>切换</VanButton
>
<VanPopup v-model:show="open" position="bottom">
<VanCell v-for="(item, index) in list" :key="index" :title="item" />
</VanPopup>
</div>
</template>
<script>
import { defineComponent } from 'vue';
import { Button as VanButton, Popup as VanPopup, Cell as VanCell } from 'vant';
export default defineComponent({
components: { VanButton, VanPopup, VanCell },
data() {
return { open: false, list: ['a', 'b'] };
},
methods: {
toggle: function () {
this.open = !this.open;
},
},
});
</script>组件的 import 来自物料 assets.json 里的一份清单,VanButton 对应 vant 的 Button。同一份 schema 加 --vue 2,弹出层那一行会生成 :show.sync="open",正是上面对照测试抓出来的那条。
物料从文档生成
6 套物料,565 个组件。下面两段摘自生成之前的手写元数据:
// antd-vue1 的 button:分组的标题写进了 name(应该放在 title 里)
props: [
{
name: '功能',
display: 'block',
type: 'group',
items: [/* ... */],
},
]
// element-plus 的 cascader:Vue 3 的事件处理器要写成驼峰。
// 组件发的事件是 expand-change,对应的处理器是 onExpandChange;
// 下面这个名字永远不会被调用(模板里的方法名倒是写对了)
{
name: 'onExpand-change',
description: '当展开节点发生变化时触发',
template: 'onExpandChange(value, ${extParams}){ /* ... */ }',
}565 个组件靠人逐个核对不现实,核对完也会再次过期。现在元数据从组件库对应版本的官方文档生成:按物料实际安装的版本下载文档,解析其中的 API 表格,结合组件运行时声明的 props 生成;片段(拖进画布时的默认结构)由手写的配方补充;缩略图由脚本在设计器里逐个渲染截取。生成是确定的,重新跑一遍,结果和已提交的逐字节一致。
生成之后有两道检查。每套物料有一个测试,拿元数据去对安装的那个版本的组件:属性是不是真的声明过,事件名是不是合法的处理器名,文档链接、出码用的导出、缩略图是否齐全。然后 E2E 把每个组件的片段插进画布渲染一遍。
第二道检查抓到过生成器自己的错。Element Plus 的 ElTable 是从 config-provider 那一页的 “Table Attribute” 生成的,属性全错。Ant Design Vue 4 的 tree-select 里,TreeNode 被对应到了 Tree 的导出上,ATreeSelect 无限递归。后一个是那 10 个子组件放回面板之后才暴露的。
设计器不再依赖 CDN
原来的 demo 从 alicdn 加载引擎、React、Fusion、lodash、moment 和 Monaco。现在全部从 npm 包提供;样式和插件里引用的 alicdn 字体、图片、图标脚本存到本地,构建时按文件名改写地址。E2E 里有一条用例:打开设计器、组件面板和源码面板之后,不能有任何第三方请求。以后哪个依赖偷偷加了一个外链,这条用例直接失败。
这一步顺带解决了类型提示的问题。CDN 上的 Monaco 是 0.31,内置 TypeScript 4.4,读不懂 Vue 3.5 的类型。现在固定在 Monaco 0.52.2。
然后是体积。部署包从 43 MB 降到 32 MB,首屏下载从 gzip 3.5–3.9 MB 降到 2.6–3.0 MB。首屏的收益主要来自一处:Monaco 从启动时预加载,改成第一次打开编辑器时才加载。
改完之后,E2E 偶尔会失败一次。
官方 base-monaco-editor 锁定的 @monaco-editor/loader@1.3.0 没有“正在加载中”的判断:Monaco 还没加载完时如果又有编辑器挂载,它会再注入一遍 AMD 加载器,控制台报 Identifier '_amdLoaderGlobal' has already been declared。以前启动时就预加载了,编辑器挂载时 Monaco 早就在了,所以一直没暴露;改成按需加载后,只要有编辑器在加载期间挂载(比如出码弹窗里连续点开几个文件)就会撞上。用 pnpm overrides 升到 1.7 解决。
为了不再靠运气复现,出码的 E2E 现在会人为把 Monaco 的加载拖慢 1.5 秒,期间连续点开多个文件。
同一轮还发现一个只在生产构建里出现的问题:渲染器包的 dist/simulator.css 被构建成了一个目录。开发模式下设计器读的是源码里的那份 css,一切正常;只有生产构建的画布没有样式。
结果
最直接的变化在开头那个按钮上。这是内核里的一条测试,在 vue2 和 vue3 两个 project 里各跑一遍:
it('onClick on a native button tag fires on click', async () => {
globalThis.__r01Clicks = 0
mounted = await mountRenderer({
schema: {
componentName: 'Page',
children: [
{
componentName: 'button',
props: {
onClick: {
type: 'JSFunction',
value: 'function () { window.__r01Clicks += 1; }',
},
},
children: 'click',
},
],
},
components: { button: 'button' },
})
const button = mounted.el.querySelector('button')
button.dispatchEvent(new MouseEvent('click', { bubbles: true }))
await mounted.flush()
expect(globalThis.__r01Clicks).toBe(1)
})我把 2023 年发布的 1.0.0 的源码重新打了一个包,用同一份 schema 跑了一遍:点击之后计数是 0。新内核是 1。
其余的结果是结构性的。
| 之前 | 现在 | |
|---|---|---|
| 仓库 | 8 个 | 1 个 |
| 渲染器实现 | 2 套,各 4 个包 | 1 个内核 + 2 个适配层 |
| 测试 | 2023 年发布时没有 | 491 个单测,35 个 E2E 用例 |
| 审计的 31 条问题 | — | 全部关闭 |
| 源码面板在 Vue 2.7 下 | 不支持 props、emits、computed、watch、provide、inject、setup | 两个版本都支持 |
| 区块和低代码组件在 Vue 2.7 下 | 不能渲染 | 能 |
| 被隐藏的 Ant Design 子组件 | 10 个 | 0 个 |
| 物料元数据 | 手写 | 565 个,从文档生成并逐个核对 |
| 出码 | 没有 | 两个 Vue 版本的 Vite 项目 |
| 设计器的第三方请求 | alicdn | 没有 |
| 部署包 / 首屏(gzip) | 43 MB / 3.5–3.9 MB | 32 MB / 2.6–3.0 MB |
| 发版 | 每个仓库各发各的 | 一个版本号,一个 tag |
一个修复现在只落一次。改渲染器的时候,vue2 和 vue3 两个测试 project 都过才算改完;改 schema 的读法,渲染器和出码器一起变,对照测试会说两边是不是还一致。
本地调试也变了。以前要用浏览器插件把线上的画布脚本代理到本地;现在 pnpm dev 之后改代码、等构建完成,打开的页面自己刷新。
量出来的部分
性能也量了一次。同一份 schema 分别交给 2023 年的 1.0.0 和现在的内核,都跑在 Vue 2.7.16 上:一个循环渲染 1000 行,每行一个 div 套一个 span,带两个属性表达式和一个文本表达式,也就是 2000 个节点、每次渲染 3000 次表达式求值。先挂载,再改一个所有行都依赖的状态。
| 1.0.0(2023) | 现在 | ||
|---|---|---|---|
| 挂载时编译表达式的次数 | 3001 | 4 | 只有第一次挂载编译,之后是 0 |
| 一次更新编译表达式的次数 | 3000 | 0 | |
| 组件实例数 | 3006 | 2004 | 少三分之一 |
| 挂载耗时(中位数) | 149 ms | 84 ms | 1.8 倍 |
| 更新耗时(中位数) | 95 ms | 47 ms | 2 倍 |
前三行是数出来的,不依赖机器。旧渲染器每求值一次就 new Function 一次,3000 次求值就是 3000 次编译,更新时再来一遍;现在按源码缓存,四个不同的表达式编译四次。实例数每行少一个。
后两行是计时,要打折看。它们是在 Node 24 的 jsdom 里量的,没有真实浏览器的布局和绘制;每种情况跑 11 次,去掉前 2 次取中位数,重复三轮的结果在 147–151 ms 对 77–84 ms、93–96 ms 对 46–47 ms 之间。把它当作差距的大致形状,不要当成你的页面会快多少。
有两件事没有量:设计模式下改一个属性的开销(去掉包装组件之后,重新渲染的是容器而不是节点自己,这一头可能变慢),以及 Vue 3 一侧的对比(旧的 Vue 3 渲染器是上游的包,不是同一份代码的前后版本)。
学到的
回头看,有四条。
旧实现是最好的规格。 审计里复现过的问题变成了测试,合并两个渲染器的时候,这些测试说明了“对”是什么意思。没有它们,合并就是凭感觉。
两个实现一定会漂移,不管它们是谁。 两个渲染器漂移了三年。出码器是新写的,写完当天就和渲染器在五处对不上。共用判断逻辑解决“现在一致”,对照测试解决“以后也一致”,两样都要有。
把每个东西都真的渲染一遍。 Tabs 的死循环、ATreeSelect 的无限递归,都是组件库的实现细节和我们的改动叠在一起才出事。565 个组件逐个放进画布的那条 E2E,是抓这类问题最有效的手段。同样的道理,simulator.css 变成目录这种事,只有跑生产构建的测试才看得见。
偶发的失败是真的失败。 “偶尔失败一次”的 E2E 追到底,是用户手快一点就能碰到的竞态。追到之后把触发条件写进测试,比加重试有用。
还没解决的
- 项目只存在浏览器里。 保存走的是一个存储接口,默认实现是按 Vue 版本分开的
localStorage。接口留了替换的位置,但没有后端实现,跨设备只能靠导出和导入 JSON。 - 两个 Vue 版本的项目不能互转。 组件库不同,组件名和属性都对不上,导入时会拒绝另一个版本的项目。
- 出码不是什么都能导出。 物料清单里找不到的组件没有
import,不认识的指令要自己注册,写成相对地址的数据源会相对于生成的应用。这些会逐条列在警告里,但需要人来处理。 - 绑定列表是静态分析出来的。 源码面板只认
setup()末尾返回的对象字面量,换一种写法代码能跑,变量却不会出现在绑定弹窗里。 - Vue 2 侧的组件库不会再更新。 element-ui 2.15.14、vant 2.13.9、ant-design-vue 1.7.8 都是各自最后的 Vue 2 版本。
- 物料的标题没有翻译。 设计器界面可以切英文,组件和属性的标题来自组件库的中文文档。
接下来
旧的包和仓库会保留。已经在用 @cdlab996/*2.7 那几个包的项目不会因为这次重建坏掉,它们停在原来的版本上,各自的说明里会指向新的包。新的功能和修复只进这个仓库。
要换过来的话,从旧包迁移要改什么写在仓库的 docs/migration.md 里:包名怎么对应,导入和产物名哪里变了,哪些渲染行为和以前不一样。旧仓库的来龙去脉和那份问题清单在 docs/history.md,该装哪个包见 README。
上面“还没解决的”那几条,目前都没有排期。
2023 年做 Vue 2.7 这个移植,是想让停在 Vue 2 的项目也能用上低代码。三年后目标没有变,只是现在它和 Vue 3 用的是同一份代码。
致谢
KNXCloud/lowcode-engine-vue 提供了这一切的起点:渲染器、画布,以及把 React 版的 schema 约定搬到 Vue 上的那套设计。LowCode Engine 和它的官方插件提供了设计器本身。谢谢。