JSON 表单 JsonForm

基本用法

默认不传 adapter 时，JsonForm 直接消费组件库自己的 schema 结构，适合业务表单、后台配置页和低代码配置面板。下面示例演示了通过一个 computed 同时处理 checkbox 控制显示/禁用、以及下拉分支字段切换。

A2UI 0.9.1 适配

传入 adapter={A2UI_0_9_1} 后，schemas 接收 A2UI v0.9.1 updateComponents.components 中的 Basic Catalog 组件列表。组件会严格从 id="root" 开始按 ID 邻接表展开，支持 Card、Column、Row、List 容器，以及 TextField、CheckBox、ChoicePicker、Slider、DateTimeInput 表单控件。列表顺序不影响渲染；没有 root 的游离节点不会显示。

输入值使用 A2UI 的 { path: "/..." } JSON Pointer 双向绑定。ChoicePicker 按协议始终读写字符串数组，mutuallyExclusive 会限制为最多选择一项。动态子列表、函数调用、展示型组件和 action 不属于 JsonForm 的表单适配范围，应由完整 A2UI Renderer 处理。

通过 ConfigProvider 注入业务组件

如果业务里已经有脚本输入框、地图选点器、审批人选择器等字段组件，可以通过 ConfigProvider 的 json-form.components 统一注入。下面示例里用组件库的 Textarea 模拟了业务自定义字段，并结合一个 computed 统一处理模式切换、字段显示/隐藏与禁用状态。推荐配合 defineJsonFormComponents 和 defineJsonFormSchemas 一起使用，这样 schema 里的 type 和 componentProps 都能保留 TypeScript 推导。

API

<json-form> Props

参数名	描述	类型	默认值
schemas	表单 schema。默认模式使用 JsonFormSchema[]；A2UI 模式使用 0.9.1 组件节点列表	JsonFormSchema[] | JsonFormA2UI_0_9_1ComponentNode[]	[]
adapter	schema 适配器。不传时使用组件库原生格式，也可按 A2UI 0.9.1 节点结构解析	'default' | 'a2ui-0.9.1'	'default'
v-model	表单数据对象	Record<string, unknown>	{}
model	非受控场景下的兼容数据对象	Record<string, unknown>	-
hide-label	是否隐藏 label	boolean	false
hide-asterisk	是否隐藏必填星号	boolean	false
show-colon	是否显示冒号	boolean	false
component	用来自定义外层表单容器，默认使用 <sd-form>	string | Component	Form

JsonFormSchema

字段	描述	类型
field	表单字段路径。默认模式使用点路径，例如 user.name	string
label	表单项标题	string
type	字段组件类型，内置支持 input、select、datePicker、switch 等，也可以接入自定义组件名	string
required	是否生成默认必填规则	boolean
hidden	是否隐藏当前字段（隐藏后不渲染表单项）	boolean
componentProps	透传给字段组件的 props	JsonFormComponentProps<T>
componentEvents	透传给字段组件的事件	JsonFormComponentEvents<T>
componentSlots	透传给字段组件的具名 slot 渲染器	Record<string, Component | (() => VNodeChild)>
formItemProps	透传给 <sd-form-item> 的 props	Omit<FormItemProps, 'field' | 'label' | 'rules'>
formItemRules	自定义校验规则	FieldRule | FieldRule[]
slotName	使用外部 slot 渲染当前字段	string
render	直接提供渲染函数	() => VNodeChild
children	当 type="row" 时的子字段列表	JsonFormSchema[]

ConfigProvider 里的 json-form

字段	描述	类型
adapter	当前作用域下 JsonForm 的默认适配器	JsonFormAdapter
components	自定义字段组件注册表	JsonFormComponentRegistry

FAQ

什么时候该用 A2UI adapter？

当表单配置直接来自 A2UI v0.9.1 的 updateComponents.components 时，使用 A2UI_0_9_1，避免在业务代码中重复转换协议节点。

A2UI 模式支持哪些字段？

A2UI 0.9.1 模式支持 Basic Catalog 的 TextField、CheckBox、ChoicePicker、Slider、DateTimeInput，以及用于连接这些字段的 Card、Row、Column、List 静态布局节点。它消费的是 updateComponents.components 字段，不负责 transport、surface 生命周期、展示型组件、action 或函数调用；这些能力需要完整 A2UI Renderer。

自定义组件怎么获得类型推导？

推荐在业务代码里先声明组件注册表，再用它创建 schema：

import { defineJsonFormComponents, defineJsonFormSchemas } from '@sdata/web-vue';

const components = defineJsonFormComponents({
  scriptField: ScriptField,
});

const createSchemas = defineJsonFormSchemas<typeof components>();

const schemas = createSchemas([
  {
    field: 'script',
    type: 'scriptField',
    componentProps: {
      placeholder: '例如：const start = true;',
    },
  },
]);

<sd-json-form v-model="formState" :schemas="schemas" />