# 表单设计器组件库

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

## 📦 组件

### 1. FormDesigner - 表单设计器（设计时）
可视化拖拽设计表单，用于表单管理页面。

### 2. FormRenderer - 表单渲染器（运行时）
根据 Schema 渲染表单，用于实际业务场景（工作流、数据录入等）。

---

## 🚀 快速开始

### 安装

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

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

---

## 💡 使用场景

### 场景 1：表单管理页面

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

```tsx
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` 渲染表单：

```tsx
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 弹窗表单

```tsx
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 类型

```typescript
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 变量可以轻松定制主题。

---

## 📚 更多资源

- [在线示例](/form-designer)
- [类型定义](./types.ts)
- [组件配置](./config.ts)

---

## 💡 最佳实践

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

---

Made with ❤️ by Deploy Ease Team

