面向 Schema 编程,Vue 3 页面级渲染引擎!强大的第三方 UI 适配与扩展(一)

0 阅读3分钟

目前市面上支持 Vue 3 的 schema 渲染引擎,多数在第三方 UI 控件的适配与扩展上,难以满足较为苛刻的定制需求。即便能够实现,也往往需要层层包装,增加了维护成本与扩展难度。对 vue-juan-form 这种页面级渲染引擎而言,这类需求可以放在用户扩展层完成。底层与 Vue 3 的数据驱动、链路监听对齐之后,第三方 UI 的适配成本较低,用户层也保留了足够的扩展空间。

下面以具体例子说明。

配置案例

需求如下:提供一个控件,分别编辑「名」(givenName)与「姓」(familyName),对外输出以空格拼接后的 fullName。

test39.gif

在 vue-juan-form 中使用该自定义类型时,页面源码如下:

<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

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 与上一节相同,此处省略。

component: {
  render(inner) {
    return h('div', { style: { padding: '8px', background: '#ecf5ff' } }, [
      inner,
      h('div', { style: { marginTop: '8px' } }, '名和姓会拼成一个值,中间加一个空格'),
    ])
  },
},

render 的第一个参数是 schema 解析得到的 vnode,可通过 h 继续组装最终内容:

20261116091056.png

要满足本节开头的动态需求,只需在 render 中读取当前控件绑定的值,并据此切换样式与提示。schema 与 dependsOn 仍与「自定义 schema 类型」一节相同,此处省略。

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,
      ])
    },
  },
},

test40.gif

这里同时说明了工具模块的注入。读取当前字段值,除了 schema.getValue(),也可以直接访问实例上的 state:

const name = this.state.$parent!.fullName as string

// 或者
const name = this.state.$root!.fullName as string

后一种写法更直接,与底层的层、作用域链路一致,可以读取页面任意层的数据。

schema 扩展

这里会遇到另一个问题:上述动态效果能否只写 schema 配置,而不使用 render?

可以。schema 的扩展方式与 Vue 单文件组件的写法对齐,内部机制也保持一致:

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 拼接后写入当前字段,此处省略。

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,可以具备如下动态能力:

test42.gif

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