JSONSchema动态表单生成总结

做过几个后台系统后，我有个直觉：手写表单是个“有手就行”的活儿，但越写越想哭。字段多、校验多、场景多，重复代码像打地鼠，打一只冒三只。直到我拉上 JSON Schema，当了次“架构上嫁妆”，整个表单系统就顺了：既省心又省时，扩展起来还带劲。

这篇就聊聊我在 Vue 3 + ant-design-vue 上，怎么用 JSON Schema 动态生成 form 表单的，附上核心思路和示例代码，保准下饭。

背景与目标：别再重复造按钮了#

我们的问题
- 表单字段重复：增改查共用一套字段，却要写三遍
- 校验逻辑分散：某个正则换了，三个地方都要改
- 维护困难：需求一变，页面上“万里长城”一样的表单就得挨个修
我们的目标
- 用 JSON Schema 描述数据结构、类型、校验
- 自动渲染对应的输入控件
- 支持自定义组件、联动逻辑、异步校验
- “配置化而非硬编码”，减少重复劳动

一句话总结：让“写页面”变“写配置”。

基本思路：Schema → 中间层 → 渲染#

JSON Schema 只描述“数据结构和约束”
UI 决策（组件类型、props、placeholder 等）用一层 uiSchema 或者简化过的表单 schema 补齐
解析器把两者融合，生成“可直接渲染的节点描述”
dynamic-form.vue 读取节点描述，循环渲染 <a-form-item + 动态组件>

你可以把它想象成“翻译官”：把“数据的语言”翻译成“组件的语言”。

我们的 Schema 长什么样（简化示例）#

这里我用“数据 schema + UI schema 合体”的方式，生产可读性更高：

{
  "title": "用户信息",
  "type": "object",
  "required": ["name", "gender", "birthday"],
  "properties": {
    "name": {
      "type": "string",
      "title": "姓名",
      "minLength": 2,
      "ui:widget": "input",
      "ui:props": { "placeholder": "请输入姓名", "allowClear": true }
    },
    "gender": {
      "type": "string",
      "title": "性别",
      "enum": ["male", "female"],
      "ui:widget": "select",
      "ui:options": [
        { "label": "男", "value": "male" },
        { "label": "女", "value": "female" }
      ]
    },
    "age": {
      "type": "number",
      "title": "年龄",
      "minimum": 0,
      "maximum": 150,
      "ui:widget": "input-number",
      "ui:props": { "min": 0, "max": 150, "style": "width: 100%" }
    },
    "isMarried": {
      "type": "boolean",
      "title": "已婚",
      "ui:widget": "switch"
    },
    "birthday": {
      "type": "string",
      "format": "date",
      "title": "生日",
      "ui:widget": "date-picker"
    }
  }
}

约定俗成的映射（可按需拓展）：

string → input / textarea / password / date-picker / select
number → input-number / slider
boolean → switch / checkbox
enum → select / radio-group
array → select(multiple) / dynamic-list
object → 分组 / 子表单

基于 ant-design-vue 的封装要点#

外层用承载表单状态及校验
内层每个字段一条，name 对应字段路径（支持 a.b.c）
表单控件用动态渲染
不同控件的 v-model 指令不同（多数是 v-model，Switch/Checkbox 用 v-model）
统一一层“组件注册表”与“绑定适配”，避免写 if-else 丛林

组件注册表示例（极简）：

const widgetMap = {
  input: 'a-input',
  'input-number': 'a-input-number',
  select: 'a-select',
  'radio-group': 'a-radio-group',
  switch: 'a-switch',
  'date-picker': 'a-date-picker',
  textarea: 'a-textarea'
}

dynamic-form.vue 的核心实现（精简版）#

下面是一个可以跑通的思路示例，细节可按项目打磨：

<script setup lang="ts">
import { computed, reactive, watch, toRaw } from 'vue'
import { Form } from 'ant-design-vue'

// props
const props = defineProps<{
  schema: any,                 // JSON Schema（含 ui 配置）
  modelValue?: Record<string, any>,
  layout?: 'horizontal' | 'vertical' | 'inline'
}>()

const emit = defineEmits<{
  (e: 'update:modelValue', v: any): void
  (e: 'submit', v: any): void
  (e: 'change', v: any): void
}>()

// 内部模型
const innerModel = reactive({ ...(props.modelValue || {}) })

watch(() => props.modelValue, (v) => {
  if (!v) return
  Object.assign(innerModel, v)
}, { deep: true })

watch(innerModel, (v) => {
  emit('update:modelValue', toRaw(v))
  emit('change', toRaw(v))
}, { deep: true })

// 解析 schema → 节点数组（这里只做最基础的铺平）
const fields = computed(() => {
  const { properties = {}, required = [] } = props.schema || {}
  return Object.keys(properties).map((key) => {
    const node = properties[key]
    return {
      field: key,
      label: node.title || key,
      required: required.includes(key),
      widget: node['ui:widget'] || guessWidgetByType(node),
      rules: buildAntdRules(node),             // 把 JSON Schema 校验映射到 antd 规则
      props: node['ui:props'] || {},
      options: node['ui:options'] || [],
      schema: node
    }
  })
})

function guessWidgetByType(node: any) {
  if (node.enum) return 'select'
  if (node.type === 'boolean') return 'switch'
  if (node.type === 'number' || node.type === 'integer') return 'input-number'
  if (node.format === 'date') return 'date-picker'
  return 'input'
}

// 把常见 JSON Schema 关键字映射到 antd 规则
function buildAntdRules(node: any) {
  const rules: any[] = []
  if (node.minLength != null) rules.push({ min: node.minLength, message: `至少 ${node.minLength} 个字符` })
  if (node.maxLength != null) rules.push({ max: node.maxLength, message: `最多 ${node.maxLength} 个字符` })
  if (node.pattern) rules.push({ pattern: new RegExp(node.pattern), message: '格式不正确' })
  if (node.minimum != null) rules.push({ type: 'number', min: node.minimum, message: `不能小于 ${node.minimum}` })
  if (node.maximum != null) rules.push({ type: 'number', max: node.maximum, message: `不能大于 ${node.maximum}` })
  return rules
}

// 绑定 v-model 属性名适配
function modelBinding(fieldNode: any, fieldKey: string) {
  const widget = fieldNode.widget
  if (widget === 'a-switch') {
    return { 'v-model:checked': innerModel[fieldKey] }
  }
  return { 'v-model:value': innerModel[fieldKey] }
}

// 提交
const [form] = Form.useForm(innerModel)
async function onSubmit() {
  try {
    await form.validate()
    emit('submit', toRaw(innerModel))
  } catch (e) { /* 校验不通过，antd 已提示 */ }
}
</script>

<template>
  <a-form :model="innerModel" :layout="layout || 'horizontal'">
    <a-row :gutter="12">
      <a-col :span="24" v-for="node in fields" :key="node.field">
        <a-form-item :name="node.field" :label="node.label" :rules="node.rules" :required="node.required">
          <component
            :is="widgetMap[node.widget] || 'a-input'"
            v-bind="node.props"
            v-on="node.props?.on"
            v-model:value="innerModel[node.field]"
            v-if="node.widget !== 'a-switch'"
          />
          <component
            :is="widgetMap[node.widget] || 'a-input'"
            v-bind="node.props"
            v-on="node.props?.on"
            v-model:checked="innerModel[node.field]"
            v-else
          />
          <!-- 选项型组件 -->
          <template v-if="node.widget === 'select'">
            <a-select-option v-for="opt in node.options" :key="opt.value" :value="opt.value">
              {{ opt.label }}
            </a-select-option>
          </template>
        </a-form-item>
      </a-col>
    </a-row>

    <a-form-item>
      <a-space>
        <a-button type="primary" @click="onSubmit">提交</a-button>
        <a-button @click="form.resetFields()">重置</a-button>
      </a-space>
    </a-form-item>
  </a-form>
</template>

说明：

这里只演示了最常见的 string/number/boolean/select/date 场景
复杂类型（array/object）可递归渲染，或用“子表单/可增删列表”包装
生产可增加 slot：label、extra、suffix、custom-render 等

使用方式（两行起飞）#

<script setup lang="ts">
import DynamicForm from '@/components/dynamic-form.vue'
import schema from './user.schema.json'
import { ref } from 'vue'

const formData = ref({})
function handleSubmit(val: any) {
  console.log('提交数据：', val)
}
</script>

<template>
  <dynamic-form :schema="schema" v-model="formData" @submit="handleSubmit" />
</template>

校验策略：两条路，随你挑#

轻量方案（上文示例）
- 把 JSON Schema 的常见关键字映射到 antd Form 的 rules
- 优点：无第三方依赖，集成简单
- 缺点：高级语义（oneOf、if/then/else）需要自己写
重装方案（Ajv）
- 用 Ajv 直接按 JSON Schema 做校验，antd 只负责展示错误
- 优点：标准、强大、覆盖面广
- 实战建议：将 Ajv 的错误转换为 { name, errors } 注入到 Form 的 validateMessages 或手动 setFields

动态联动：表单最“会整活”的地方#

常见需求：选中“公司”才显示“公司名称”，或者“证件类型=护照”时“号码校验”变更。

几种做法：

解析时生成“显示条件表达式”（如 node[‘ui’]）
在 dynamic-form 里 watch(innerModel)，计算每个字段的 visible/disabled
使用 v-if 控制渲染、或 props.disabled 控制交互
高阶玩法：if/then/else（JSON Schema 自带），配合 Ajv 能完整描述

示例（简版条件）：

"companyName": {
  "type": "string",
  "title": "公司名称",
  "ui:widget": "input",
  "ui:visibleIf": { "workType": "company" }
}

自定义组件：给高级玩法留条活路#

组件注册表支持外部扩展：widgetMap = { …default, …props.widgets }
每个字段可接受 render 函数/slot 名称，走插槽直接手写
例：富文本、级联选择、上传、地图点选等都可以插进去
配合动态 import 和 Suspense，让大体积组件延迟加载

小结：省的不是几行代码，是一整套心智负担#

用 JSON Schema 驱动表单，最香的地方不是“少写几行 input”，而是：

统一的描述方式，让“字段/校验/渲染”三件事拧成一股绳
新增/改动字段只改配置，UI、校验、交互自动跟上
自定义能力和联动逻辑也能优雅落地，不用写成意大利面

如果你们项目也正被表单“反复横跳”折磨，不妨试试这套方案。