表单组件开发文档

本文档说明如何在 TDUCK 表单系统中新增一个自定义组件，示例以 Nps 组件为例，涉及后端注册、前端配置、组件实现、组件配置及图标引入等步骤。

---

1. 后端注册组件类型

在后端项目中打开枚举文件：

com.tduck.cloud.form.entity.enums.FormItemTypeEnum

在枚举中新增 NPS 类型：

NPS("NPS", "Nps组件"),

---

2. 前端组件注册

打开前端路径：

src/views/formgen/components/GenerateForm/config.ts

在组件注册数组中添加如下对象：

{
  typeId: 'NPS',
  config: {
    label: 'Nps组件',
    tag: 't-nps',
    tagIcon: 'nps',
    defaultValue: 0,
    span: 24,
    showLabel: true,
    showRegList: false,
    labelWidth: null,
    required: true,
    regList: []
  },
  max: 10,
  disabled: false
}

注：额外配置（如 max, disabled）将以 prop 的形式传入组件。

---

字段说明

字段名	类型	描述	示例或默认值
typeId	string	组件类型 ID，需与后端保持一致	"NPS"
config	object	基础配置对象
├─ label	string	显示名称	"Nps组件"
├─ tag	string	Vue 组件标签名	"t-nps"
├─ tagIcon	string	图标名（SVG 文件名）	"nps"
├─ defaultValue	number	默认值	0
├─ span	number	所占栅格宽度（24 栅格制）	24
├─ showLabel	boolean	是否显示标题	true
├─ showRegList	boolean	是否显示正则配置项	false
├─ labelWidth	number/null	标签宽度，null 表示不设置	null
├─ required	boolean	是否为必填项	true
├─ regList	array	正则验证配置项	[]
其他自定义字段	any	如max,scoreLimit等扩展配置

---

3. 新建组件文件

目录结构

在路径：

src/views/formgen/components/FormItem/

创建目录 TNps，并在其中创建 index.vue 文件。

然后在 index.ts 中注册组件：

export const TNps = defineAsyncComponent(() =>
  import("@/views/formgen/components/FormItem/TNps/index.vue")
);

注意：组件名需与 config.ts 中的 config.tag 保持一致（如 t-nps 对应 TNps）

组件实现示例

<template>
  <el-input-number
    v-bind="{ ...item }"
    v-model="changeValue"
    @change="handleChange"
  />
</template>

<script setup lang="ts" name="TNps">
import { useFormItemExam } from "@/views/formgen/components/FormItem/hooks/useExamHook";
import { formEmits, formItemProps, useFormItem } from "@/views/formgen/components/FormItem/hooks/useFormItemHook";
import { BasicComponent } from "@/views/formgen/components/GenerateForm/types/form";

const props = defineProps({ ...formItemProps });
const emits = defineEmits(formEmits);

const formItemHook = useFormItem(props, emits);
const { changeValue } = formItemHook;

const handleChange = (val: any) => {
  // 值更新处理逻辑
};
</script>

---

4. 组件配置（用于表单设计器）

打开路径：

src/views/formgen/components/FormDesign/ItemConfig/index.ts

注册组件配置面板：

export const nps = defineAsyncComponent(() =>
  import("@/views/formgen/components/FormDesign/ItemConfig/nps.vue")
);

---

5. 图标配置

图标为 SVG 格式，存放路径：

src/views/formgen/assets/icons/svg/

文件名需与 config.tagIcon 保持一致，例如 nps.svg。

---

TypeScript 类型定义

export interface NpsComponentConfig {
  typeId: 'NPS';
  config: {
    label: string;
    tag: string;
    tagIcon: string;
    defaultValue: number;
    span: number;
    showLabel: boolean;
    showRegList: boolean;
    labelWidth: number | null;
    required: boolean;
    regList: any[];
  };
  [key: string]: any;
}

6. 数据列表

表单收集后有几个地方显示数据，如果你的值是复杂对象或者数组，需要进行数据格式化处理，不然会直接显示个[Object]之类的。

代码入口添加具体的判断

src/views/form/data/table/formatTableColumn.ts:8 数据表格格式化

src/views/form/data/view/ViewData.vue:22 点击数据详情显示