# 表单设计器扩展字段

本目录包含表单设计器的扩展字段，采用松耦合的架构设计，不影响核心组件功能。

## 📁 目录结构

```
extensions/
└── workflow/                    # 工作流扩展字段
    ├── index.ts                 # 导出文件
    ├── config.ts                # 字段配置
    ├── ApproverSelector.tsx     # 审批人选择器组件
    └── README.md                # 使用文档（本文件）
```

---

## 🎯 工作流扩展字段

### 1. 审批人选择器 (`approver-selector`)

与审批节点功能保持一致的审批人选择组件。

#### 功能特性

- ✅ **审批模式**：单人审批、会签（所有人同意）、或签（任一人同意）
- ✅ **选择模式**：按用户、按角色、按部门
- ✅ **数据源集成**：使用项目统一的 DataSourceType (USERS/ROLES/DEPARTMENTS)
- ✅ **实时数据加载**：通过 `useFieldOptions` Hook 获取数据
- ✅ **多选支持**：会签和或签模式自动启用多选
- ✅ **视觉提示**：清晰的模式说明和选择提示

---

## 🚀 快速开始

### 基础使用

```tsx
import { FormDesigner } from '@/components/FormDesigner';
import { WORKFLOW_COMPONENTS } from '@/components/FormDesigner/extensions/workflow';

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

  return (
    <FormDesigner
      value={schema}
      onChange={setSchema}
      // 🔑 关键：注入工作流扩展字段
      extraComponents={WORKFLOW_COMPONENTS}
    />
  );
}
```

### 完整示例

查看 `/src/pages/FormDesigner/WorkflowExample.tsx` 获取完整的使用示例。

---

## 📊 数据结构

### FormSchema 中的审批人字段

```typescript
{
  id: 'field_xxx',
  type: 'approver-selector',
  label: '审批人',
  name: 'approver',
  required: true,
  selectionMode: 'user',    // 'user' | 'role' | 'department'
  approvalMode: 'single',   // 'single' | 'countersign' | 'or-sign'
  placeholder: '请选择审批人'
}
```

### 提交的表单数据

**单人审批**：
```json
{
  "approver": "user_1"
}
```

**会签/或签**：
```json
{
  "approver": ["user_1", "user_2", "user_3"]
}
```

---

## 🔧 开发指南

### 添加新的扩展字段

1. **创建组件文件** (`MyExtensionField.tsx`)

```typescript
import React from 'react';
import type { FieldConfig } from '../../types';

interface MyExtensionFieldProps {
  field: FieldConfig;
  value?: any;
  onChange?: (value: any) => void;
  disabled?: boolean;
  isPreview?: boolean;
}

export const MyExtensionField: React.FC<MyExtensionFieldProps> = ({
  field,
  value,
  onChange,
  disabled,
  isPreview,
}) => {
  return (
    <div>
      {/* 你的组件实现 */}
    </div>
  );
};
```

2. **更新配置** (`config.ts`)

```typescript
export const WORKFLOW_COMPONENTS: ComponentMeta[] = [
  // ... existing
  {
    type: 'my-extension-field',
    label: '我的扩展字段',
    icon: MyIcon,
    category: '高级字段',
    defaultConfig: {
      id: '',
      type: 'my-extension-field',
      label: '我的扩展字段',
      name: 'myField',
      // ... 其他配置
    },
  },
];
```

3. **更新类型定义** (`types.ts`)

```typescript
export type FieldType =
  | 'input'
  // ... existing types
  | 'my-extension-field';
```

4. **更新 FieldRenderer** (`FieldRenderer.tsx`)

```typescript
case 'my-extension-field':
  const { MyExtensionField } = require('../extensions/workflow/MyExtensionField');
  return (
    <MyExtensionField
      field={field}
      value={value}
      onChange={onChange}
      disabled={field.disabled}
      isPreview={isPreview}
    />
  );
```

5. **（可选）添加属性配置** (`PropertyPanel.tsx`)

```typescript
{selectedField.type === 'my-extension-field' && (
  <Form.Item label="自定义属性" name="customProp">
    <Input />
  </Form.Item>
)}
```

---

## 🎨 设计原则

### 1. 松耦合
- 扩展字段独立于核心组件
- 通过 `extraComponents` 参数注入
- 不影响现有功能

### 2. 按需加载
- 使用动态 `require()` 加载扩展组件
- 只在使用时加载代码
- 减少打包体积

### 3. 数据源统一
- 使用项目统一的 DataSourceType
- 复用现有的数据加载逻辑
- 保持数据格式一致

### 4. 类型安全
- 完整的 TypeScript 类型定义
- 扩展字段类型纳入 FieldType
- IDE 自动补全支持

---

## 🧪 测试

### 访问测试页面

1. 启动开发服务器
```bash
npm run dev
```

2. 访问工作流表单示例
```
http://localhost:3000/form-designer/workflow-example
```

### 测试步骤

1. **拖拽审批人字段**到设计画布
2. **配置字段属性**：
   - 选择模式（用户/角色/部门）
   - 审批模式（单人/会签/或签）
3. **预览表单**：测试审批人选择功能
4. **查看数据**：检查提交的数据格式

---

## 📝 API 参考

### ApproverSelector Props

| 属性 | 类型 | 默认值 | 说明 |
|------|------|--------|------|
| field | FieldConfig | - | 字段配置对象 |
| value | string \| string[] | - | 当前选中值 |
| onChange | (value) => void | - | 值变化回调 |
| disabled | boolean | false | 是否禁用 |
| isPreview | boolean | false | 是否为预览模式 |

### 字段配置属性

| 属性 | 类型 | 可选值 | 说明 |
|------|------|--------|------|
| selectionMode | string | 'user' \| 'role' \| 'department' | 选择模式 |
| approvalMode | string | 'single' \| 'countersign' \| 'or-sign' | 审批模式 |

---

## 🤝 贡献

欢迎贡献新的扩展字段！请遵循以下步骤：

1. Fork 项目
2. 在 `extensions/` 下创建你的扩展目录
3. 实现组件和配置
4. 添加测试和文档
5. 提交 Pull Request

---

## 📚 相关文档

- [表单设计器主文档](../README.md)
- [类型定义](../types.ts)
- [组件配置](../config.ts)
- [工作流示例](/src/pages/FormDesigner/WorkflowExample.tsx)

---

Made with ❤️ for 链宇Deploy Ease平台

