新增自定义表单组件指南 #

Tduck 的表单设计器支持拖拽生成表单。很多时候，现有的基础组件（如单行输入、下拉选择）无法满足特殊的业务场景，需要开发者扩展出新的表单组件。本节将简要介绍新增一个自定义表单组件的前后端修改思路。

💡 1. 核心设计思想 #

在开始修改前，需要先理解 Tduck 是如何处理动态表单字段的：

• 配置态 (Design)：表单设计器将所有的组件解析为一份 JSON Schema。每一个表单项都是该 JSON 数组中的一个对象，例如：
  json

  {
    "type": "custom-input",
    "label": "身份证号",
    "required": true,
    "regList": []
  }
  

• 运行态 (Render/Fill)：表单填写页面根据上面的 JSON 渲染对应的表单项。
• 存储态 (Store)：表单提交时，前端将表单填写的值以 键值对 (Key-Value Map) 的形式序列化为 JSON，并整体存储在数据库中，后端无需动态修改物理表字段即可完美接收！

🎨 2. 前端修改步骤 (tduck-front 与 tduck-form-generator) #

如果您拥有设计器核心包源码，增加一个自定义组件（例如“车牌号”组件 plate-number）的完整流程如下：

Step 1. 定义组件的 JSON 模式配置 #

在设计器核心包（formgen）的配置文件中（通常在 src/components/generator/config.js），定义该组件的 JSON 格式与默认值：

{
  __config__: {
    tag: 'el-input',          // 对应的基础渲染标签或自定义标签
    tagIcon: 'input',         // 侧边栏图标
    label: '车牌号',
    layout: 'colFormItem',    // 布局模式
    regList: [],              // 默认校验正则
    required: true,
    changeTag: true,
    document: 'https://...'   // 帮助文档链接
  },
  placeholder: '请输入车牌号',
  style: { width: '100%' },
  __vModel__: 'plateNumber',  // 绑定的数据模型字段名
  maxlength: 8
}

Step 2. 实现前端渲染引擎 (Render/Parser) #

1. 在 formgen 项目的组件包中编写该组件的具体展示逻辑 PlateNumber.vue：
   vue

   <template>
     <div class="plate-number-item">
       <el-input 
         v-model="value" 
         :placeholder="placeholder"
         :maxlength="maxlength"
         @input="handleInput"
       />
     </div>
   </template>
   
   <script>
   export default {
     props: ['value', 'placeholder', 'maxlength'],
     methods: {
       handleInput(val) {
         this.$emit('input', val);
       }
     }
   }
   </script>
   

2. 将该自定义组件注册进渲染引擎（即 formgen 的全局解析组件列表中），确保在 Design 态和 Fill 态（填写态）下能够被 <FormDesign> 和 <FormRender> 正确渲染。

Step 3. 关联配置属性面板 #

在设计器右侧的“组件属性”栏（如 RightPanel.vue）中，根据 tag === 'plate-number' 添加特定的配置项（例如车牌号码格式、是否限制新能源车牌等）。

☕ 3. 后端修改步骤 (tduck-platform) #

得益于 Tduck 的无模式设计 (Schemaless / NoSQL 思想)，当您在前端新增组件时：

• 一般数据收集场景下，后端 0 修改！
• 设计原理：表单的用户提交数据在后端是通过 Map<String, Object> 动态接收并直接序列化存入 original_data（结构化大字段）中，因此数据库中无需动态新建或修改物理列即可完美兼容新组件。

例外情况：需要后端特有校验、流程控制或统计计算 #

若您新加的组件涉及特殊的后台业务逻辑（例如“车牌限行日期校验”、“库存名额扣减”）：

1. 在后端服务 tduck-form 模块的 UserFormDataServiceImpl.java 中找到保存表单数据的方法 saveFormResult(UserFormDataEntity entity)。
2. 在该方法中，可以从 entity.getOriginalData() 获取前端提交的全部 JSON 键值对，提取对应的自定义字段值，并添加您特有的校验、扣减或业务逻辑处理。