deploy-ease-platform/frontend/src/components/FormDesigner

表单设计器组件库

一个完整的表单可视化设计和渲染解决方案，包含设计时组件和运行时组件。

📦 组件

1. FormDesigner - 表单设计器（设计时）

可视化拖拽设计表单，用于表单管理页面。

2. FormRenderer - 表单渲染器（运行时）

根据 Schema 渲染表单，用于实际业务场景（工作流、数据录入等）。

---

🚀 快速开始

安装

组件已内置在项目中，直接导入使用：

import { FormDesigner, FormRenderer, type FormSchema } from '@/components/FormDesigner';

---

💡 使用场景

场景 1：表单管理页面

在表单管理页面使用 FormDesigner 设计和保存表单：

import { FormDesigner, type FormSchema } from '@/components/FormDesigner';

function FormManagePage() {
  const [schema, setSchema] = useState<FormSchema>();

  const handleSave = async (schema: FormSchema) => {
    // 保存到后端
    await api.saveFormSchema(schema);
  };

  return (
    <FormDesigner
      value={schema}
      onChange={setSchema}
      onSave={handleSave}
    />
  );
}

场景 2：工作流发起页面

在工作流中使用 FormRenderer 渲染表单：

import { FormRenderer, type FormSchema } from '@/components/FormDesigner';

function WorkflowStartPage() {
  const [schema, setSchema] = useState<FormSchema>();
  const [formData, setFormData] = useState({});

  useEffect(() => {
    // 从后端加载表单 Schema
    api.getFormSchema(workflowId).then(setSchema);
  }, [workflowId]);

  const handleSubmit = async (values: Record<string, any>) => {
    // 提交工作流
    await api.startWorkflow(workflowId, values);
  };

  if (!schema) return <Loading />;

  return (
    <FormRenderer
      schema={schema}
      value={formData}
      onChange={setFormData}
      onSubmit={handleSubmit}
      submitText="发起工作流"
    />
  );
}

场景 3：Modal 弹窗表单

import { Modal } from 'antd';
import { FormRenderer, type FormSchema } from '@/components/FormDesigner';

function QuickFormModal() {
  const [visible, setVisible] = useState(false);

  const formSchema: FormSchema = {
    version: '1.0',
    formConfig: { labelAlign: 'right', size: 'middle' },
    fields: [
      { id: '1', type: 'input', label: '姓名', name: 'name', required: true },
      { id: '2', type: 'input', label: '邮箱', name: 'email', required: true },
    ]
  };

  const handleSubmit = async (values: Record<string, any>) => {
    await api.submitData(values);
    setVisible(false);
  };

  return (
    <Modal open={visible} onCancel={() => setVisible(false)} footer={null}>
      <FormRenderer
        schema={formSchema}
        onSubmit={handleSubmit}
        onCancel={() => setVisible(false)}
        showCancel
      />
    </Modal>
  );
}

---

📖 API 文档

FormDesigner Props

属性	类型	默认值	说明
value	FormSchema	-	受控模式：表单 Schema
onChange	(schema: FormSchema) => void	-	Schema 变化回调
onSave	(schema: FormSchema) => void	-	保存按钮回调
readonly	boolean	false	只读模式
showToolbar	boolean	true	是否显示工具栏

FormRenderer Props

属性	类型	默认值	说明
schema	FormSchema	必填	表单 Schema
value	Record<string, any>	-	受控模式：表单值
onChange	(values) => void	-	值变化回调
onSubmit	(values) => void	-	提交回调
onCancel	() => void	-	取消回调
readonly	boolean	false	只读模式
showSubmit	boolean	true	显示提交按钮
showCancel	boolean	false	显示取消按钮
submitText	string	'提交'	提交按钮文本
cancelText	string	'取消'	取消按钮文本

FormSchema 类型

interface FormSchema {
  version: string;          // Schema 版本
  formConfig: FormConfig;   // 表单配置
  fields: FieldConfig[];    // 字段列表
}

---

🎯 完整示例

访问 /form-designer 路由查看完整的在线示例，包含：

1. 设计器示例 - 演示如何设计表单
2. 渲染器示例 - 演示如何渲染表单
3. 工作流示例 - 演示实际业务场景

---

🎨 支持的字段类型

基础字段

• 单行文本 (input)
• 多行文本 (textarea)
• 数字输入 (number)
• 下拉选择 (select)
• 单选框 (radio)
• 多选框 (checkbox)
• 开关 (switch)
• 日期选择 (date)
• 时间选择器 (datetime)
• 时间范围 (time)
• 滑块 (slider)
• 评分 (rate)
• 级联选择 (cascader)

高级字段

• 文件上传 (upload)

布局字段

• 栅格布局 (grid) - 支持拖入其他组件
• 文字 (text)
• 分割线 (divider)

---

✨ 核心特性

🎨 可视化设计

• ✅ 拖拽式组件面板
• ✅ 实时预览
• ✅ 栅格布局容器
• ✅ 智能拖放检测（边界识别）

📝 表单功能

• ✅ 字段验证规则（必填、正则、长度等）
• ✅ 字段联动规则（显示/隐藏、启用/禁用、赋值）
• ✅ 默认值设置
• ✅ 数据源配置（静态、API、预定义）
• ✅ 级联选择（支持无限层级）

🎯 拖拽体验

• ✅ 复制/粘贴（Ctrl+C / Ctrl+V）
• ✅ 删除（Delete）
• ✅ 插入指示器（视觉反馈）
• ✅ 边界检测（区分插入和拖入）

💾 数据管理

• ✅ 导入/导出 JSON Schema
• ✅ 受控/非受控模式
• ✅ 表单值双向绑定

---

🏗️ 架构设计

src/components/FormDesigner/
├── index.tsx                 # 统一导出入口 ⭐
├── Designer.tsx              # 设计器主组件 ⭐
├── Renderer.tsx              # 渲染器主组件 ⭐
├── types.ts                  # TypeScript 类型定义
├── config.ts                 # 组件配置（拖拽面板）
├── styles.css                # 样式文件
├── components/               # 子组件
│   ├── ComponentPanel.tsx    # 组件面板
│   ├── DesignCanvas.tsx      # 设计画布
│   ├── PropertyPanel.tsx     # 属性配置面板
│   ├── FormPreview.tsx       # 预览组件
│   ├── FieldRenderer.tsx     # 字段渲染器
│   ├── GridField.tsx         # 栅格布局组件
│   └── ...                   # 其他子组件
└── hooks/                    # 自定义 Hooks
    ├── useFieldOptions.ts    # 字段选项管理
    └── useCascaderOptions.ts # 级联选项管理

---

🔧 开发指南

添加新字段类型

1. 在 types.ts 中添加类型定义
2. 在 config.ts 中注册组件元数据
3. 在 FieldRenderer.tsx 中实现渲染逻辑
4. （可选）在 PropertyPanel.tsx 中添加特殊配置

自定义样式

所有样式都在 styles.css 中，使用 CSS 变量可以轻松定制主题。

---

📚 更多资源

• 在线示例
• 类型定义
• 组件配置

---

💡 最佳实践

1. Schema 存储：将 FormSchema 存储在数据库，使用 JSON 字段类型
2. 版本管理：FormSchema 包含 version 字段，便于后续升级
3. 权限控制：使用 readonly 属性控制表单是否可编辑
4. 数据验证：充分利用 validationRules 进行前端验证
5. 字段联动：使用 linkageRules 实现复杂的业务逻辑

---

Made with ❤️ by Deploy Ease Team