目前市面上支持 Vue 3 的 schema 渲染引擎,多数在第三方 UI 控件的适配与扩展上,难以满足较为苛刻的定制需求。即便能够实现,也往往需要层层包装,增加了维护成本与扩展难度。对 vue-juan-form 这种页面级渲染引擎而言,这类需求可以放在用户扩展层完成。底层与 Vue 3 的数据驱动、链路监听对齐之后,第三方 UI 的适配成本较低,用户层也保留了足够的扩展空间。
下面以具体例子说明。
配置案例
需求如下:提供一个控件,分别编辑「名」(givenName)与「姓」(familyName),对外输出以空格拼接后的 fullName。

在 vue-juan-form 中使用该自定义类型时,页面源码如下:
ts
<script setup lang="ts">
import JuanForm from 'vue-juan-form'
import './fullName.ts'
import type { FieldConfig, FormSchema } from 'vue-juan-form'
const schema: FormSchema = {
preview: true,
children: [
{
items: [
{
prop: 'fullName',
label: '姓名拆分',
type: 'FullName',
col: 16,
} as unknown as FieldConfig,
],
},
],
}
</script>
<template>
<JuanForm :schema="schema" />
</template>
preview 用于在调试模式下向页面输出可实时预览的数据模型。type 定义为自定义的 FullName,数据模型中绑定的字段名为 fullName,效果见上图。
自定义 schema 类型
针对这一需求,下面说明 vue-juan-form 如何包装自定义控件类型。
fullName.ts
ts
import { createInput, type SchemaApi } from 'vue-juan-form'
createInput('FullName', {
schema: {
$el: 'div',
attrs: { class: 'w-full' },
children: [
[
{ prop: 'givenName', label: '名', type: 'Input', col: 8 },
{ prop: 'familyName', label: '姓', type: 'Input', col: 8 },
],
],
},
dependsOn: {
inject: ['schema'],
handle: (scope, schema: SchemaApi) => {
schema.setValue(`${scope.givenName ?? ''} ${scope.familyName ?? ''}`.trim())
},
},
})
通过 createInput 包装扩展的 schema 控件类型:第一个参数为类型名,第二个参数为配置选项。schema 用于组装界面,可以配置 HTML 元素与属性,也可以嵌入任意已有 type 的控件,并结合栅格布局组成新的控件类型。
内部输入通过 dependsOn 做联动:相关字段变化后执行 handle,再通过注入的 schema 工具,把拼接结果写回当前自定义节点。
由此可见,用 schema 组装自定义控件接近于组合现有积木;再配合 dependsOn,即可处理页面任意层之间的数据联动,也包括控件自身的内部层。
render 扩展
接下来会遇到一个问题:如果还要在现有界面上增加动态能力,例如姓名中出现敏感关键字时高亮整个控件并给出提示,能否实现?
可以。这正是 vue-juan-form 的扩展方式所覆盖的范围。
schema 解析之后会得到渲染用的 vnode。与 schema 并列的 component.render 可以继续包装这份节点。先看静态包装:在已解析的节点外包一层容器,并附带说明文字。schema 与 dependsOn 与上一节相同,此处省略。
ts
component: {
render(inner) {
return h('div', { style: { padding: '8px', background: '#ecf5ff' } }, [
inner,
h('div', { style: { marginTop: '8px' } }, '名和姓会拼成一个值,中间加一个空格'),
])
},
},
render 的第一个参数是 schema 解析得到的 vnode,可通过 h 继续组装最终内容:

要满足本节开头的动态需求,只需在 render 中读取当前控件绑定的值,并据此切换样式与提示。schema 与 dependsOn 仍与「自定义 schema 类型」一节相同,此处省略。
ts
component: {
render: {
inject: ['schema'],
handle(inner, schema: SchemaApi) {
const name = schema.getValue() as string
const hit = ['java', 'vue'].some((word) => name.toLowerCase().includes(word))
return h('div', { style: hit ? { padding: '8px', background: '#fef0f0' } : undefined }, [
inner,
hit ? h('div', { style: { marginTop: '8px', color: '#f56c6c' } }, `姓名 ${name} 包含敏感关键字`) : null,
])
},
},
},

这里同时说明了工具模块的注入。读取当前字段值,除了 schema.getValue(),也可以直接访问实例上的 state:
ts
const name = this.state.$parent!.fullName as string
// 或者
const name = this.state.$root!.fullName as string
后一种写法更直接,与底层的层、作用域链路一致,可以读取页面任意层的数据。
schema 扩展
这里会遇到另一个问题:上述动态效果能否只写 schema 配置,而不使用 render?
可以。schema 的扩展方式与 Vue 单文件组件的写法对齐,内部机制也保持一致:
ts
createInput('FullName', {
computed: {
hit() {
const name = String(this.state.$parent?.fullName ?? '')
return ['java', 'vue'].some((word) => name.toLowerCase().includes(word))
},
},
schema: {
$el: 'div',
attrs: {
class: 'w-full',
style() {
return this.hit ? { padding: '8px', background: '#fef0f0' } : undefined
},
},
children: [
[
{ prop: 'givenName', label: '名', type: 'Input', col: 8 },
{ prop: 'familyName', label: '姓', type: 'Input', col: 8 },
],
{
$el: 'div',
attrs: { style: { marginTop: '8px', color: '#f56c6c' } },
if() {
return this.hit
},
text: '姓名包含敏感关键字',
},
],
},
// dependsOn 与「自定义 schema 类型」一节相同:inject schema,将 givenName 与 familyName 拼接后写入当前字段
dependsOn: { ... },
})
对习惯 Vue 单文件写法的开发者来说,这一结构并不陌生。vue-juan-form 把它提升到 schema 配置这一层:判断逻辑抽成可复用的计算属性;style、if 用于 HTML 元素的动态样式与条件渲染,并且支持模块注入。
效果与上一节的动态需求相同,截图省略。
用户层配置
用 schema 封装自定义控件时,还需要区分哪些能力留给页面配置,而不是写进扩展层。以敏感关键字为例,更合适的做法是写在用户层 schema 上:createInput 中的计算属性从用户层读取定义,不再写死。schema 树与上一节相同:根节点 div 的 style、提示节点的 if 都读取 this.hit;dependsOn 仍将 givenName 与 familyName 拼接后写入当前字段,此处省略。
ts
import { createInput, type FieldConfig, type FormSchema, type SchemaApi } from 'vue-juan-form'
createInput('FullName', {
computed: {
hit: {
inject: ['schema'],
handle(scope, schema: SchemaApi) {
const name = String(scope.$parent?.fullName ?? '')
const raw = schema.current().props?.keywords
const words = Array.isArray(raw) ? raw.map(String) : []
return words.some((word) => name.toLowerCase().includes(word.toLowerCase()))
},
},
},
// schema 树与「schema 扩展」一节相同:根节点 style、提示节点 if 都读取 this.hit
schema: { ... },
// dependsOn 与「自定义 schema 类型」一节相同:inject schema,将 givenName 与 familyName 拼接后写入当前字段
dependsOn: { ... },
})
export const schema: FormSchema = {
preview: true,
children: [
{
items: [
{
prop: 'fullName',
label: '姓名拆分',
type: 'FullName',
col: 16,
props: { keywords: ['java', 'vue'] },
} as unknown as FieldConfig,
],
},
],
}
这里通过注入的 SchemaApi 读取用户层字段上的 props,再据此判断。
本篇只是入门示例。下一篇会说明 vue-juan-form 如何与目前主流的 Vue 3 UI 框架整合、适配与扩展:把原本需要在 Vue 单文件中引入并开发的过程,改成由使用者按需把第三方 UI 扩展为可复用的 schema 类型,并具备渲染引擎的动态能力。
例如整合 Element Plus Tabs,可以具备如下动态能力:

第三方 UI 本身也提供新增、删除页签的能力。借助 vue-juan-form 的配置,只需使用组件的外观,而不必接入它自身的 API。这正是 schema 动态渲染能力的体现。下篇见。