# Fields 组件

Fields 目录提供了一系列用于表单数据展示的高阶组件(HOC)，主要用于增强表单字段组件的功能。

## 核心高阶组件

### 1. withMode

`withMode` 用于处理组件的不同展示模式，接收两个参数：
1. 第一个参数是需要增强的组件
2. 第二个参数是组件的只读态组件，用于自定义只读模式下的展示形式

主要包括:

- `edit`: 编辑模式，显示可编辑的表单控件
- `read`: 只读模式，以文本形式展示数据（使用第二个参数传入的组件）
- `hidden`: 隐藏模式，不显示该字段

```typescript
// 使用示例
// 自定义只读态组件
const CustomReadComponent = ({ value }) => {
  return <div className="custom-read">当前值: {value}</div>;
};

// 使用 withMode 增强，传入自定义只读态组件
const EnhancedInput = withMode(Input, CustomReadComponent);

// 使用组件
<EnhancedInput mode="read" value="示例文本" />; // 将使用 CustomReadComponent 展示
<EnhancedInput mode="edit" value="示例文本" />; // 将使用 Input 组件展示
```

### 2. withFormItem

`withFormItem` 将组件包装成 Ant Design Form.Item，统一处理表单验证、标签等配置。

```typescript
// 使用示例
const FormInput = withFormItem(Input);
// 使用组件
<FormInput label="用户名" name="username" rules={[{ required: true }]} />;
```

### 3. withDataSource

`withDataSource` 用于处理组件的数据源配置，通过 DataSourceProvider 提供数据源上下文。

```typescript
interface WithDataSourceProps {
  // 数据源配置，可以是静态数据数组或数据源配置对象
  dataSource?: any;
}

// 使用示例
const SelectWithData = withDataSource(Select);

// 使用组件
<SelectWithData
  dataSource={{
    // 数据源配置
    fields: [], // 字段配置
    // ... 其他数据源配置
  }}
/>;
```

### 4. withOptions

`withOptions` 专门用于处理选项类组件（如 Select、Radio、Checkbox 等）的选项数据转换，支持静态选项和远程数据源。

```typescript
interface WithOptionsProps {
  // 静态选项数据
  options?: any[];
  // 选项数据源类型
  optionSourceType?: 'custom' | 'api' | 'default';
  // 选项标签字段名
  labelField: string;
  // 选项值字段名
  valueField: string;
}

// 使用示例
const EnhancedSelect = withOptions(Select);

// 1. 默认选项
<EnhancedSelect
  options={[
    { label: '选项1', value: '1' },
    { label: '选项2', value: '2' }
  ]}
  optionSourceType="default"
/>;

// 2. 自定义选项
<EnhancedSelect
  options={[
    { label: '选项1', value: '1' },
    { label: '选项2', value: '2' }
  ]}
  optionSourceType="custom"
/>;

// 3. 远程数据源选项
<EnhancedSelect
  optionSourceType="api"
  labelField="name"    // 指定后端数据中用作标签的字段
  valueField="id"      // 指定后端数据中用作值的字段
/>;
```

> 注意：
> 1. `optionSourceType` 支持三种类型：
>    - `default`: 默认选项模式
>    - `custom`: 自定义选项模式
>    - `api`: 远程数据源模式
> 2. 当 `optionSourceType` 为 'api' 时，组件会自动调用 `list.run()` 方法获取远程数据，默认请求参数为 `{ page: 1, pageSize: 200 }`。获取到的数据会根据 `labelField` 和 `valueField` 转换成标准的 options 格式。

## 新增自定义Fields示例

### 1. 基础字段组件
```typescript
// CustomField.tsx
import React from 'react';
import { Input } from 'antd';
import { withMode, withFormItem, withDataSource } from './hocs';

const CustomField = (props) => {
  // 实现自定义组件逻辑
  return <Input {...props} />;
};

// 自定义只读态组件
const CustomReadComponent = ({ value }) => {
   return <div className="custom-read">当前值: {value}</div>;
};

// 使用高阶组件增强（从外到内的顺序）
export default withDataSource(
  withFormItem(
    withMode(CustomField, CustomReadComponent)
  )
);
```

### 2. 选项类字段组件

```typescript
// CustomSelect.tsx
import React from 'react';
import { Select } from 'antd';
import { withMode, withFormItem, withDataSource, withOptions } from './hocs';

const CustomSelect = (props) => {
  return <Select {...props} />;
};

// 使用高阶组件增强（从外到内的顺序）
export default withDataSource(
  withOptions(
    withFormItem(
      withMode(CustomSelect)
    )
  )
);
```

## 注意事项

1. 高阶组件使用顺序（从外到内）
   - withDataSource 作为最外层包装，处理数据源和上下文
   - withOptions 在 withDataSource 内层，处理选项数据转换（如果需要）
   - withFormItem 在 withOptions 内层，处理表单项属性
   - withMode 作为最内层包装，处理组件的展示模式

2. Props 透传
   - 确保组件正确处理并透传未使用的 props
   - 注意处理 value/onChange 等受控组件属性

3. TypeScript 类型定义
   - 新增组件时需要正确定义并导出组件的 Props 类型
   - 确保与现有类型定义保持一致


## 开发建议

1. 在开发新的字段组件时，建先确认是否可以复用现有组件
2. 确保新组件同时支持编辑、只读、隐藏三种模式
3. 提供完整的类型定义和文档说明