跪拜 Guibai
← Back to the summary

Schema-Driven Vue 3 Forms: Extending Controls Without Touching the Engine


theme: channing-cyan

Most schema rendering engines that support Vue 3 struggle with adapting and extending third-party UI controls, especially when customization demands are strict. Even when they can, it often requires layer upon layer of wrapping, adding maintenance cost and making extension harder. For a page-level rendering engine like vue-juan-form, such needs can be handled at the user extension layer. Once the underlying data-driven behavior and link listening align with Vue 3, adapting third-party UI becomes cheap, and the user layer retains enough room for extension.

The following example illustrates this.

Configuration example

The requirement: provide a control that edits "given name" (givenName) and "family name" (familyName) separately, and outputs fullName as the space-joined result.

test39.gif

When this custom type is used in vue-juan-form, the page source looks like this:

<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 enables debug mode, outputting a live-preview data model to the page. type is the custom FullName type, and the bound field in the data model is fullName. The effect is shown in the image above.

Custom schema type

Now let's explain how vue-juan-form wraps a custom control type for this need.

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 wraps the extended schema control type: the first argument is the type name, the second is the configuration. schema assembles the UI; it can define HTML elements and attributes, embed any existing type control, and combine with grid layout to build a new control type.

Internal inputs are linked through dependsOn: when relevant fields change, handle runs, and via the injected schema utility, writes the concatenated result back to the current custom node.

So composing a custom control in schema is close to assembling existing building blocks; with dependsOn, you can handle data linking between any layers in the page, including the control's own internal layers.

render extension

Next, a question: what if you also need dynamic behavior on the existing UI, such as highlighting the entire control and showing a warning when the name contains a sensitive keyword? Can you do it?

Yes. This is exactly the territory covered by vue-juan-form's extension approach.

After parsing, schema yields a vnode for rendering. The component.render option, parallel to schema, can wrap that node. Let's look at static wrapping first: wrap the parsed node in a container and attach explanatory text. schema and dependsOn are the same as in the previous section, so they are omitted here.

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

The first parameter of render is the vnode parsed from schema, and h can further assemble the final content:

20261116091056.png

To meet the dynamic requirement from the start of this section, just read the current bound value inside render and switch styles and messages accordingly. schema and dependsOn remain the same as in the "Custom schema type" section, so they are omitted.

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

This also demonstrates module injection. To read the current field value, besides schema.getValue(), you can also access the state on the instance directly:

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

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

The latter approach is more direct and aligns with the underlying layer and scope chain, allowing you to read data from any page layer.

schema extension

Here's another question: can the dynamic effect above be expressed purely in schema config without using render?

Yes. The schema extension approach aligns with Vue single-file component syntax, and the internal mechanism is consistent:

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: { ... },
})

For developers used to Vue SFC, this structure isn't unfamiliar. vue-juan-form lifts it to the schema configuration layer: the conditional logic becomes a reusable computed property; style and if handle dynamic styles and conditional rendering for HTML elements, and they support module injection.

The effect matches the dynamic requirement in the previous section; the screenshot is omitted.

User-layer configuration

When wrapping a custom control in schema, you also need to decide which capabilities stay at the page-config level rather than being hardcoded into the extension layer. With sensitive keywords as an example, the better practice is to write them on the user-layer schema: the computed property in createInput reads definitions from the user layer instead of hardcoding. The schema tree is the same as in the previous section: the root div's style and the warning node's if both read this.hit; dependsOn still joins givenName and familyName and writes to the current field, so it's omitted here.

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

Here, the injected SchemaApi reads props from the user-layer field and judges based on that.

This post is just an entry-level example. The next post will explain how vue-juan-form integrates, adapts, and extends mainstream Vue 3 UI frameworks: turning what would normally require importing and developing in a Vue single-file component into an approach where users extend third-party UI into reusable schema types on demand, with the dynamic capabilities of the rendering engine.

For example, integrating Element Plus Tabs can give you the following dynamic capabilities:

test42.gif

Third-party UI itself also provides the ability to add and delete tabs. With vue-juan-form's configuration, you use the component's appearance without plugging into its own API. That's the value of schema's dynamic rendering capability. See you in the next post.