@sunzhiyang/tdesign-visual-form

基于 Vue 3 与 tdesign-vue-next 的可视化表单设计与运行态渲染组件。当前发布版本为纯 JavaScript 版本 0.0.3。

特性

• 设计态：左侧组件面板、中间字段配置、右侧运行态预览。
• 运行态：覆盖 TDesign 常用表单字段类型。
• 数据同步：支持 v-model:schema 与 v-model:data。
• 发布结构：提交时返回稳定的发布态 Schema 与表单数据。
• 必填校验：提交前自动校验 required 字段，失败时触发 validation-fail。
• 轻量发布：vue 与 tdesign-vue-next 均作为 peerDependencies，不打进组件包。

安装

npm install @sunzhiyang/tdesign-visual-form vue tdesign-vue-next

全局注册

import { createApp } from 'vue';
import TDesign from 'tdesign-vue-next';
import 'tdesign-vue-next/es/style/index.css';
import TdesignVisualForm from '@sunzhiyang/tdesign-visual-form';
import '@sunzhiyang/tdesign-visual-form/style.css';
import App from './App.vue';

createApp(App).use(TDesign).use(TdesignVisualForm).mount('#app');

按需使用

<template>
  <TdesignVisualForm v-model:schema="schema" v-model:data="formData" submit-text="提交表单" @submit="handleSubmit" @validation-fail="handleValidationFail" />
</template>

<script setup>
import { reactive } from 'vue';
import { TdesignVisualForm } from '@sunzhiyang/tdesign-visual-form';
import '@sunzhiyang/tdesign-visual-form/style.css';

const schema = reactive({
  title: '客户回访表单',
  fields: [
    {
      id: 'field-name',
      type: 'input',
      field: 'customerName',
      label: '客户姓名',
      placeholder: '请输入客户姓名',
      required: true,
      optionText: '',
    },
    {
      id: 'field-status',
      type: 'select',
      field: 'visitStatus',
      label: '回访状态',
      placeholder: '请选择回访状态',
      required: true,
      optionText: '待回访,已接通,需二次跟进',
    },
  ],
});

const formData = reactive({
  customerName: '张三',
  visitStatus: '待回访',
});

const handleSubmit = ({ schema, payload }) => {
  console.log('发布 Schema：', schema);
  console.log('提交数据：', payload);
};

const handleValidationFail = (errors) => {
  console.warn('校验失败：', errors);
};
</script>

Props

| 参数 | 说明 | 类型 | 默认值 | | ------------------ | ---------------------------------------- | --------- | ------------------------------------- | | schema | 表单设计态 Schema，支持 v-model:schema | Object | { title: '可视化表单', fields: [] } | | data | 运行态表单数据，支持 v-model:data | Object | {} | | palette | 左侧组件面板配置 | Array | 内置全部常用字段类型 | | readonly | 是否禁用设计态编辑 | Boolean | false | | labelWidth | 运行态表单 label 宽度 | String | 96px | | submitText | 提交按钮文案 | String | 模拟提交 | | validateRequired | 提交时是否校验必填字段 | Boolean | true | | helpText | 设计态提示文案 | String | 内置中文提示 |

Events

| 事件 | 说明 | | ----------------- | ----------------------------------------------------------- | | update:schema | 设计态 Schema 更新时触发，保留 optionText 等编辑态字段 | | update:data | 表单数据更新时触发 | | submit | 校验通过后触发，返回 { schema, payload } | | validation-fail | 必填校验失败时触发，返回 Array<{ field, label, message }> | | field-add | 新增字段时触发 | | field-remove | 删除字段时触发 |

已支持字段类型

| 类型 | 说明 | | -------------- | -------------------------------------------------------- | | input | 单行输入 | | textarea | 多行文本 | | input-number | 数字输入 | | select | 下拉选择 | | multi-select | 多选下拉 | | radio | 单选组 | | checkbox | 复选组 | | switch | 开关 | | date | 日期选择 | | date-range | 日期范围 | | time | 时间选择 | | time-range | 时间范围 | | rate | 评分 | | slider | 滑块 | | cascader | 级联选择，选项格式如 华东/上海,华东/杭州 | | tree-select | 树形选择，选项格式如 组织/研发部,组织/产品部 | | color-picker | 颜色选择 | | upload | 文件上传，默认 autoUpload: false，表单数据保存文件列表 |

Schema 工具函数

import {
  FIELD_TYPE_DEFINITIONS,
  cloneDesignSchema,
  createDefaultField,
  normalizeVisualFormSchema,
  parseOptionText,
  parseTreeOptionText,
  toPublishedSchema,
} from '@sunzhiyang/tdesign-visual-form';

发布前检查

npm run build
npm pack --dry-run

版本说明

• 当前版本：0.0.3
• 当前语言：JavaScript
• 暂不内置 TypeScript 类型声明，如需 TS 项目类型提示，可在业务项目中自行补充声明文件。