@wenext/schema-form v0.0.7
一个轻量的 Schema Form 核心,基于 JSON Schema / UI Schema 渲染表单,并通过 Element Plus entry 提供基础与高阶控件。
安装
pnpm add @wenext/schema-form @jsonforms/core @jsonforms/vue @jsonforms/vue-vanilla vue使用 Element Plus 控件时额外安装:
pnpm add element-plus @element-plus/icons-vue使用高阶控件时,再安装颜色选择器:
pnpm add vue3-colorpickervue3-colorpicker 仅由 element-plus 聚合入口和 element-plus/advanced 入口使用;只使用 element-plus/basic 时无需安装。
使用
import { SchemaForm } from '@wenext/schema-form'
import { elementPlusRenderers } from '@wenext/schema-form/element-plus'
import 'element-plus/dist/index.css'
import '@wenext/schema-form/element-plus/styles.css'<SchemaForm
v-model="data"
:schema="schema"
:ui-schema="uiSchema"
:renderers="elementPlusRenderers"
/>数组单项折叠
数组控件可通过 Control.options.itemCollapsible: true 开启单项折叠,无需额外注册 renderer:
const uiSchema = {
type: 'Control',
label: '入口配置',
scope: '#/properties/entries',
options: {
itemCollapsible: true,
itemTitle: '活动入口',
detail: {
type: 'VerticalLayout',
elements: [
{ type: 'Control', label: '入口文案', scope: '#/properties/text' },
],
},
},
};开启后,每项默认收起,标题前缀通过 options.itemTitle 配置,上例显示“活动入口-1”“活动入口-2”等;未配置时沿用数组的 label。
折叠箭头位于标题左侧,删除按钮位于最右侧。各项独立展开,折叠保留已填数据;新增项默认收起,删除一项后保留其余项的展开状态。options.defaultShrink 仍控制整个数组的初始折叠状态。
不配置 itemCollapsible 或配置为 false 时,各项保持原有的直接展开行为;itemTitle 同样可以用于这些数组的子项标题。
数字输入配置
Element Plus 基础输入控件支持 JSON Schema 的 string、number 和 integer 字段,Control.options.attrs 会透传给输入控件:
const schema = {
type: 'object',
properties: {
count: { type: 'number' },
},
};
const uiSchema = {
type: 'Control',
scope: '#/properties/count',
options: {
attrs: { type: 'number', min: 0 },
},
};number 和 integer 字段默认使用数字输入框,并在 change 时以数值类型更新数据;清空时移除字段值。min: 0 允许输入 0,负数提交时会触发校验提示并恢复原值。string 字段即使配置 attrs.type: 'number',仍以字符串类型更新数据。
时间区间选择器
使用 producer: 'datetime-range-picker' 渲染一个 datetimerange 选择器。控件绑定包含起止字段的对象,通过 startField、endField 指定字段名(默认分别为 startTime、endTime),不新增区间数组字段:
const schema = {
type: 'object',
properties: {
startTime: { type: 'string' },
endTime: { type: 'string' },
},
};
const uiSchema = {
type: 'Control',
label: '活动时间',
scope: '#',
options: {
producer: 'datetime-range-picker',
startField: 'startTime',
endField: 'endTime',
attrs: { valueFormat: 'YYYY-MM-DDTHH:mm:ss.SSSZ' },
},
};可以在数组 options.detail 中使用同样的控件,scope: '#' 绑定当前子项;若起止字段位于一个嵌套对象,则将 scope 指向该对象。选择后一次更新两个字段,并保留对象的其他配置。清空时同时移除两个字段,保存重开保持为空。控件已包含在基础和聚合 renderer 集合中,无需业务侧注册。
attrs 支持 startPlaceholder、endPlaceholder、clearable 等 Element Plus 属性;默认显示格式为 YYYY-MM-DD HH:mm:ss、保存格式为 x。上例配置为保存带时区 ISO 字符串;使用默认毫秒格式时,两个字段的 Schema 应为 number。type 固定为 datetimerange,值和只读状态由表单管理。
旧 ISO 字符串、毫秒时间戳及数字字符串可直接回显;只打开控件、切换显隐或保留不完整的旧起止字段,不会改写保存值。控件沿用 Element Plus 的浏览器本地时区编辑行为,不承载活动映射或状态判断。
值变更校验
控件可以在 UI Schema 的 Control.options 中配置变更前校验。校验失败时不会更新 v-model,默认尝试使用 ElMessage.error 提示;也可以通过 services.toast 覆盖:
const uiSchema = {
type: 'Control',
label: '连抽次数',
scope: '#/properties/multiLotteryCount',
options: {
attrs: { type: 'number', min: 2, max: 10 },
tips: '最低连抽 2 次,最多 10 次',
validator: ({ value }) =>
Number(value) % 2 === 0 || '连抽次数必须是偶数',
},
};attrs 支持 min、max、step、minLength、maxLength、pattern、required 和 type: 'number' | 'range' 等内置规则。自定义 validator 可以返回 true、false、错误文案,或 { valid, message }。
<SchemaForm
v-model="data"
:ui-schema="uiSchema"
:services="{ toast: (message) => ElMessage.error(message) }"
:schema="schema"
:renderers="elementPlusRenderers"
/>SchemaForm 默认使用 JSON Forms 的 vanillaRenderers,再叠加通过 renderers 传入的 Element Plus renderer;因此未覆盖的控件仍保持旧包的 vanilla 行为。
大区链接输入
通过 producer: 'region-link-input' 配置按大区填写的链接,字段的 JSON Schema 使用 object。控件已包含在 elementPlusRenderers 和 elementPlusAdvancedRenderers 中,无需业务侧单独注册。
const schema = {
type: 'object',
properties: { entryLink: { type: 'object' } },
};
const uiSchema = {
type: 'Control',
label: '入口链接',
scope: '#/properties/entryLink',
options: { producer: 'region-link-input', defaultRegion: 'EG' },
};
const config = {
regionOptions: [
{ label: 'EG区', value: 'EG' },
{ label: 'TR区', value: 'TR' },
],
};将 config 传给 <SchemaForm :config="config" />。大区字典由宿主提供,支持异步加载后更新;已配置的大区不会重复出现在下拉选项中。默认大区为 EG,可通过 options.defaultRegion 修改,默认大区行不可删除。未提供字典时仍显示默认大区,已有但未收录在字典中的大区以其代码显示。
字段值保存为 { EG: 'https://example.com/eg', TR: 'https://example.com/tr' }。兼容已有对象、表示此对象的 JSON 字符串,以及将普通链接字符串作为默认大区链接的旧配置;读取时保留原数据,用户编辑后统一输出对象。只保留字符串链接值。大区链接的选择、跳转及兜底策略由使用方处理,控件仅负责编辑配置。
日期时间选择器
使用 producer: 'datetime-picker' 渲染 Element Plus 日期时间选择器。默认 format: 'YYYY-MM-DD HH:mm:ss'、placeholder: '选择日期和时间'、valueFormat: 'x';字段值为毫秒时间戳,JSON Schema 使用 number:
const schema = {
type: 'object',
properties: {
executeAt: { type: 'number' },
},
};
const uiSchema = {
type: 'Control',
scope: '#/properties/executeAt',
options: {
producer: 'datetime-picker',
},
};options.attrs 会透传给 ElDatePicker,可以用 valueFormat 覆盖默认保存格式,也可以配置 clearable、disabledDate、shortcuts 等组件属性。改用字符串保存格式时,字段的 JSON Schema 应改为 string;例如 attrs.valueFormat: 'YYYY-MM-DD HH:mm:ss'。清空选择器时会移除字段值。选择器固定为单值 datetime 类型,modelValue 和 disabled 由表单管理。
只使用基础控件时,可以减少高阶控件的静态引用:
import { elementPlusBasicRenderers } from '@wenext/schema-form/element-plus/basic'高阶控件通过 services 接收外部实现,包本身不实现上传、翻译或 ZIP 解析:
<SchemaForm
v-model="data"
:schema="schema"
:ui-schema="uiSchema"
:renderers="elementPlusRenderers"
:services="{ upload, translate }"
/>颜色控件支持纯色和渐变色,使用 UI Schema 的 options.attrs 透传颜色选择器配置:
{
"type": "Control",
"scope": "#/properties/themeColor",
"options": {
"producer": "color-picker",
"attrs": {
"format": "rgb",
"useType": "both"
}
}
}多语言控件的语言列表可放在 UI Schema options,或继续使用旧包兼容的 SchemaForm.config.langOptions:
const config = {
langOptions: [
{ label: 'English', value: 'en' },
{ label: '简体中文', value: 'zh-CN' },
],
}详细的拆分原则和迁移记录见 重构实践文档。