• 低代码
• 前端
• UI组件

本篇文章围绕开源项目 form-create 中的 TDesign 适配包@form-create/tdesign展开：它让开发者通过 JSON 规则即可生成基于 TDesign（tdesign-vue-next）的 Vue3 动态表单，并自带数据收集、验证、提交、联动与子表单能力。读完本文，你将掌握该包的版本分支选择与安装方式、JSON 规则与 maker 链式生成两种建模方式、表单与按钮的默认配置项，以及从入口到渲染的源码级工作原理，可直接在政务、OA、ERP 等 Vue3 + TDesign 项目中落地使用。

包定位与核心特性

根据 packages/tdesign/README.md 的定义，FormCreate 是一个可以通过 JSON 生成具有动态渲染、数据收集、验证和提交功能的低代码表单生成组件，而@form-create/tdesign正是其在 TDesign 体系下的实现版本（Vue3），对应 npm 上的next分支。

其官方列出如下特点：

• 使用 JSON 数据生成表单；
• 支持扩展，可生成任何 Vue 组件和 HTML 标签；
• 支持 8 个 UI 框架（Element、Ant Design Vue、Arco、Naive、TDesign、iView、View Design、Vant 等）；
• 支持组件之间联动（control配置项）；
• 提供丰富的表单操作 API；
• 支持子表单（object/subForm）和分组（group/array）；
• 高性能；
• 适配移动端；
• 支持多语言。

从仓库结构看，该包位于 packages/tdesign，monorepo 中同时存在 element-ui、ant-design-vue、arco-design、naive-ui、tiny-vue、vant 等同类适配包，@form-create/tdesign是其中专门面向腾讯 TDesign 组件库的一版。

支持的 UI 框架与包生态

原文档中的「包说明」表完整列出了 form-create 家族的各版本包及其适用框架：

从 packages/tdesign/package.json 可以看到，@form-create/tdesign的运行时依赖集中在 form-create 内部包与核心库：

• @form-create/core：表单引擎核心；
• @form-create/utils：工具函数库；
• @form-create/component-subform：子表单组件；
• @form-create/component-tdesign-frame：TDesign 版 frame（弹层选择）组件；
• @form-create/component-tdesign-group：TDesign 版 group（批量添加）组件；
• @form-create/component-tdesign-upload：TDesign 版 upload（上传）组件；

同时其peerDependencies声明了vue: ^3.5.12，开发依赖中则使用tdesign-vue-next: ^1.10.7作为底层组件库，版本号（package.json 中为3.3.4）与 Vue3 分支保持同步。

版本分支与安装方式

原文档明确指出仓库按分支管理版本，这点在使用时最容易踩坑：

• latest：Vue 2.0 版本分支；
• super：Vue 2.7 版本分支（该版本功能和 next 分支功能一致）；
• next：Vue 3.0 版本分支。

因此安装@form-create/tdesign时必须显式指定分支标签，否则默认拿到的是 Vue2 的 latest 版本。例如：

安装 Vue 2.7 版本的@form-create/tdesign：

npm install @form-create/tdesign@super

安装 Vue 3 版本的@form-create/tdesign：

npm install @form-create/tdesign@next

在使用 Vue3 项目时务必安装next标签版本；Vue2.7 项目则安装super标签版本，两者功能对齐，便于平滑升级。

快速开始：引入与注册

以 Vue3 项目为例，安装@form-create/tdesign@next后，可通过两种方式接入 TDesign 组件。

方式一：按需自动注册（推荐）

@form-create/tdesign自带的 auto-import.js 会从tdesign-vue-next中按需导入 Form、FormItem、Row、Col、Input、Button、Cascader、AutoComplete、CheckboxGroup、RadioGroup、ColorPicker、DatePicker、DateRangePicker、InputNumber、RangeInput、Select、Slider、Switch、TagInput、TimePicker、TimeRangePicker、TreeSelect、Upload、Tree、Dialog、Popup、Transfer 等 20 余个组件，并注册到当前应用实例，同时引入 TDesign 样式。在入口文件中这样使用（参考 examples/main.js）：

import { createApp } from 'vue'; import install from '@form-create/tdesign/auto-import'; import FormCreate from '@form-create/tdesign'; import App from './App.vue'; const app = createApp(App); FormCreate.use(install); // 按需注册 TDesign 组件与样式 app.use(FormCreate); // 安装 FormCreate 插件 app.mount('#app');

方式二：全量引入 TDesign

也可以全量引入tdesign-vue-next插件，再安装 FormCreate，两种方式最终都会让表单引擎拿到所需的t-form、t-input等组件。

在组件模板中，通过form-create组件绑定规则、选项与数据即可渲染表单（参考 examples/App.vue）：

<template> <form-create :rule="rule" v-model:api="fapi" :option="option" v-model="formData" @change="change" /> </template>

其中rule是表单生成规则数组（JSON 结构），option是表单整体配置（布局、按钮等），formData是表单数据对象（v-model 双向绑定），fapi拿到表单实例 API 后可动态操作表单。

JSON 驱动：两种规则建模方式

TDesign 包同时支持纯 JSON 规则与maker 链式生成两种建模方式，二者最终都会归一为同一套规则结构。

方式一：纯 JSON 规则

直接给出规则数组即可，每个字段描述一个组件（参考 examples/jsonRule.js）：

const rule = [ { type: 'input', // 组件类型（对应 TDesign 组件别名） title: '商品名称', field: 'goods_name', // 字段名，对应 formData 中的 key value: 'iphone', props: { placeholder: '请输入商品名称', disabled: false, }, validate: [ { required: true, message: '请输入商品名称', trigger: 'blur' } ] }, { type: 'radio', title: '是否包邮', field: 'is_postage', value: '0', options: [ { value: '0', label: '不包邮', disabled: false }, { value: '1', label: '包邮', disabled: false }, { value: '2', label: '未知', disabled: true }, ] }, { type: 'select', field: 'cate_id', title: '产品分类', value: ['104', '105'], props: { multiple: true }, options: [ { value: '104', label: '生态蔬菜' }, { value: '105', label: '新鲜水果' }, ] }, ];

规则中的type会经过组件别名映射层解析到具体的 TDesign 组件（详见下一节），props原样透传给该组件，validate为校验规则数组，options为选项数据。

方式二：maker 链式生成

@form-create/tdesign从入口 src/index.js 导出maker对象，支持以链式调用生成规则（参考 examples/rule.js）：

import { maker } from '@form-create/tdesign'; const rule = [ maker.hidden('id', '14'), maker.input('商品名称', 'goods_name', 'iphone') .props({ placeholder: '请输入商品名称', clearable: true, maxlength: 10, }) .validate([ { required: true, message: '请输入商品名称', trigger: 'change' } ]) .style('color:red') .wrap({ style: 'color:red', class: 'asdfasdf' }) .info('请输入商品名称!!!!!'), maker.radio('是否包邮', 'is_postage', 0) .options([ { value: 0, label: '不包邮' }, { value: 1, label: '包邮' }, ]) .control([/* 联动规则 */]) .validate([{ required: true }]), maker.select('产品分类', 'cate_id', '105') .props({ multiple: true }) .options([ { value: '104', label: '生态蔬菜' }, { value: '105', label: '新鲜水果' }, ]), ];

maker 链式 API 的底层实现在 src/core/maker.js，它基于@form-create/core的creatorFactory批量生成了大量便捷方法，包括：

• 输入类：input、password、url、text、tel、textarea、inputNumber/number、rangeInput；
• 选择类：select、selectMultiple、selectOne、cascader、autoComplete/auto、treeSelect、treeSelectMultiple、transfer、tagInput/tag；
• 日期类：datePicker/date、dateRangePicker/dateRange、timePicker/time、timeRangePicker/timeRange；
• 其他：switch、slider、sliderRange、checkbox、radio、colorPicker/color、upload（含image、file、uploadFileOne、uploadImageOne等）、frame（含frameInputs、frameFiles、frameImages、frameInputOne等）、group、tree。

这些方法在 types/maker.d.ts 中均有类型声明，TypeScript 项目可获得完整智能提示。

组件别名映射：规则 type 到 TDesign 组件的桥梁

JSON 规则中的type并非直接等于 TDesign 组件名，而是先经过别名映射。核心文件 src/core/alias.js 中定义了完整映射（前缀t即 TDesign 组件前缀）：

其中frame、group、upload、subForm四类属于 form-create 自定义组件，其实现分别在 components/tdesign/frame/src/component.jsx、components/tdesign/group/src/component.jsx、components/tdesign/upload/src/component.jsx 以及公共子表单组件中，由 src/components/index.js 统一注册，并附带QuestionCircleOutlined图标组件用于表单标题的提示气泡。

除 TDesign 内置组件外，form-create 还支持生成任何 Vue 组件和 HTML 标签：通过FormCreate.component(name, component)注册自定义组件后即可在规则中以该 name 为 type 使用（examples/main.js 中注册了wangEditor富文本与testSlot插槽示例组件）。

表单配置项（option）与默认值

规则之外，option控制表单整体行为。默认值定义在 src/core/config.js：

{ form: { layout: 'vertical', // 布局：vertical / inline / horizontal labelAlign: 'right', // 标签对齐方式 labelWidth: '125px', // 标签宽度 }, row: { show: true, // 是否启用栅格行 gutter: 0, // 栅格间距 }, submitBtn: { theme: 'primary', // TDesign 按钮主题 loading: false, disabled: false, innerText: '', // 按钮文字，为空时取多语言默认 '提交' show: true, // 是否显示提交按钮 col: undefined, // 按钮所在栅格列配置 click: undefined, // 自定义点击回调，未设置时执行 fApi.submit() }, resetBtn: { theme: 'default', loading: false, disabled: false, innerText: '', show: false, // 默认不显示重置按钮 col: undefined, click: undefined, // 未设置时执行 fApi.resetFields() }, }

submitBtn/resetBtn还支持简写为布尔值（true/false控制显隐），或传入ButtonProps对象。这些 option 在渲染层 src/core/manager.js 的makeFormBtn/makeSubmitBtn/makeResetBtn中消费：按钮默认文案来自多语言api.t('submit')/api.t('reset')（中文环境即为「提交」「重置」），且布局为inline时按钮会直接嵌入行内。

除按钮外，option还支持col（列宽）、wrap（表单项包裹）、info（标题提示）、title（标题）等结构，其类型定义见 types/config.d.ts，例如col支持span与labelWidth，info支持type: 'popup' | 'tooltip'、icon、align: 'left' | 'right'等。

表单操作 API：数据、验证与提交

通过v-model:api拿到表单实例后，TDesign 包在核心 API 之上扩展了丰富的操作方法，实现在 src/core/api.js。以下方法在 examples/App.vue 中均有直接演示：

从实现细节看，validate()会收集当前表单及所有非作用域子表单的校验任务并合并为 Promise 执行；校验失败时会触发validate-fail事件。submit()默认在提交前执行validate()（可通过option.validateOnSubmit: false关闭），验证通过后调用successFn、option.onSubmit回调并派发submit事件，最后 resolve 出表单数据。按钮的loading/disabled/show状态变化均通过submitBtnProps/resetBtnProps合并回option并触发refreshOptions实现响应式更新。

高级能力：子表单、分组与联动

原文档特别提到了三类高阶用法，TDesign 包均完整支持。

group 分组（批量添加）

type: 'group'（别名array）用于可增删的表单集合，例如多行商品明细。规则中通过props.rule声明子项模板，props.min/props.max限制条目数量，并可对整体加validate（如{required: true, min: 3, type: 'array', message: '最少增加3项', trigger: 'change'}）。其渲染组件 components/tdesign/group/src/component.jsx 支持sortBtn排序按钮、type: 'card'卡片样式、title模板（{index}占位）以及onBeforeAdd/onBeforeRemove拦截钩子。

object 子表单

type: 'object'（别名subForm）表示一个嵌套的对象字段，内部props.rule为该对象的字段定义，表单数据以对象形式存入父字段，适合地址、联系信息等结构化数据。子表单同样具备独立的验证与数据收集能力，这也是validate()会递归校验子表单的原因。

control 联动

在规则中通过control配置项实现字段间联动：当某字段值等于指定 value 时，动态添加/移除/更新其他规则。示例（来自 examples/rule.js）：

maker.radio('是否包邮', 'is_postage', 0) .control([ { value: 1, // 当选择「包邮」时 rule: [ maker.number('满额包邮', 'postage_money', 0) .effect({ required: true }) // 该字段变为必填 ] } ]);

此外，组件之间还可通过inject/link/update实现值注入联动，addressEffect（见 examples/addressEffect.js）演示了如何通过FormCreate.register()注册自定义属性（如自动填充省市区数据），并提供init、loaded、watch、value、control、deleted、mounted等生命周期钩子。

内置扩展组件：frame 与 upload

• frame（弹层选择）：type: 'frame'以 iframe 弹层方式选择资源，props支持type: 'input' | 'image' | 'file'、src（iframe 地址）、maxLength、width/height、modalTitle、okBtnText/closeBtnText等。其实现向 iframe 注入form_create_helper对象，提供set/get/close/onOk/onClose方法实现父子页面通信（components/tdesign/frame/src/component.jsx）。
• upload（文件上传）：type: 'upload'基于 TDesign 的t-upload封装，规则中通过props.action指定上传地址、props.onSuccess处理返回、props.max限制数量、props.uploadType: 'image' | 'file'区分类型；单文件场景（max: 1）下toValue会自动把数组收敛为单个值（components/tdesign/upload/src/component.jsx）。

本地开发与构建

仓库为 monorepo（pnpm workspace），TDesign 包提供了独立的开发与构建脚本（见 packages/tdesign/package.json）：

• pnpm dev:td：启动本地开发服务器（配置见 vite.dev.config.mjs，端口 8080，运行examples目录下的演示页面）；
• pnpm build:lib：清理并构建发布产物（dist/form-create.min.js与dist/form-create.esm.js）。

开发服务器会通过process.env.UI = '"tdesign"'注入 UI 标识，并将 TDesign 演示所需的tdesign-vue-next、dayjs加入依赖预构建。示例页面 examples/App.vue 提供了覆盖全部 API 与组件类型的交互式操作面板（获取配置、增删字段、校验、提交、JSON 生成等），是快速上手该包的最佳参考。

TypeScript 类型支持

@form-create/tdesign自带完整类型声明（typings指向 types/index.d.ts），在 core 提供的泛型基础上扩展了 TDesign 专属类型：

• OptionAttrs：将 TDesign 的FormProps、ButtonProps、RowProps、ColProps、FormItemProps、PopupProps、TooltipProps直接并入 option 类型（types/config.d.ts）；
• Maker：列出全部 maker 方法名的枚举类型（types/maker.d.ts）；
• Rule、Api、Control、Effect等泛型类型均可用。

这使得 Vue3 + TypeScript 项目在书写规则与调用 API 时可以获得准确的类型约束与编辑器补全。

小结

@form-create/tdesign是 form-create 低代码表单方案在 TDesign 生态中的落地包：安装时按分支（next/super/latest）选择对应 Vue 版本，通过 JSON 规则或 maker 链式 API 描述表单，借助组件别名映射直接复用tdesign-vue-next的 20 余个表单组件，同时以group、object、frame、upload四个扩展组件覆盖批量添加、嵌套子表单、弹层选择与文件上传场景，并通过control、inject、自定义属性实现复杂联动。其工程实现以 src/core/index.js 为安装入口，内部通过alias、manager、parser、maker、provider分层协作，任何 TDesign 组件都可被注册进规则体系，适合作为 Vue3 + TDesign 业务系统的统一表单基础设施。

该包基于 MIT 协议开源（见 packages/tdesign/LICENSE），可自由用于商业项目。

• 低代码
• 前端
• UI组件