Chendi Wu
Chendi WuMediaPhotographyProjectsBlog
Back to blog

一套设计器同时跑 Vue 2.7 和 Vue 3:lowcode-engine-vue 重构记录

把 Vue 2.7 和 Vue 3 两个低代码渲染器、八个仓库重建成一个:为什么重建、三条路里选了哪条、留下了什么;一个渲染器内核加两个适配层,去掉包装组件,渲染器与出码共用 schema 读法,物料从文档生成,以及结果和教训。

Published2026-11-15Updated2026-11-16
NotesLow-CodeVue

在画布里拖一个原生的 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,用法见使用指南。

Vue 3 下的设计器:左侧组件库,中间画布,右侧属性面板

这篇文章讲为什么要重建、当时有哪几条路、留下了什么、新的结构是什么样,以及结果。最后是几条教训和还没解决的问题。

一点历史

阿里的 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 2.7:同一个设计器外壳,画布里是 Vue 2.7 和 Vant 2

一个内核,两个适配层

两个 Vue 版本的差异不多,而且很集中:

差异Vue 2.7Vue 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-modelmodel 选项,默认 value + inputmodelValue + 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 没有 Fragment

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 MB32 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)现在
挂载时编译表达式的次数30014只有第一次挂载编译,之后是 0
一次更新编译表达式的次数30000
组件实例数30062004少三分之一
挂载耗时(中位数)149 ms84 ms1.8 倍
更新耗时(中位数)95 ms47 ms2 倍

前三行是数出来的,不依赖机器。旧渲染器每求值一次就 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 和它的官方插件提供了设计器本身。谢谢。

Copyright (c) 2023-PRESENT All Rights Reserved. Powered by wudi