# RecordListWrapper 增强说明

## 概述

`RecordListWrapper` 是一个增强的表单组件，用于管理多个记录的表单数据。它支持：

1. **Tab 导航**：通过 `options` 驱动多个记录的切换
2. **动态表单**：支持低代码引擎动态添加表单字段
3. **Schema 驱动**：通过 `xRecordSchema` 配置字段结构
4. **完整的表单能力**：复用 DataSourceForm 的所有能力（验证、格式化、多语言等）

## 核心增强

### 1. 数据源上下文支持

现在 RecordListWrapper 会为子组件提供完整的 Provider 链：

- `FormSettingProvider`：提供表单设置（renderMode、size 等）
- `DataSourceProvider`：提供模拟数据源，让子组件能正常工作
- `JsonWrapperContext`：提供 JSON 嵌套路径支持

### 2. 字段自动渲染

当配置 `xRecordSchema` 时：

```typescript
const xRecordSchema = [
  {
    name: 'code',
    uiSchema: {
      title: '代码',
      'x-component': 'Input',
      'x-component-props': {
        placeholder: '请输入代码'
      }
    }
  },
  {
    name: 'type',
    interface: 'Select',
    uiSchema: {
      title: '类型',
      enum: [
        { label: '类型A', value: 'a' },
        { label: '类型B', value: 'b' }
      ]
    }
  }
];
```

### 3. 低代码集成

在低代码平台上：

1. **配置 xRecordSchema**：
   - 打开组件配置面板
   - 找到 "Schema" 分组
   - 在 "记录字段配置" 中输入 JSON 配置
   - 系统会自动解析并生成表单字段

2. **手动添加组件**：
   - RecordListWrapper 是容器组件（`isContainer: true`）
   - 可以直接拖拽表单项到容器中
   - 子组件会自动获得正确的上下文

3. **自定义 Tab 导航**：
   - 可以拖拽自定义组件到 "Tab 区域" 插槽
   - 组件会自动接收 `options`、`value`、`onChange` 属性

## 值结构

```typescript
// RecordListWrapper 的值是一个 Map 结构：
{
  // key: option 的 value
  // value: 该 option 对应的表单字段值
  "option1": {
    "code": "ABC",
    "type": "a",
    "name": "名称1"
  },
  "option2": {
    "code": "DEF",
    "type": "b",
    "name": "名称2"
  }
}
```

## 使用示例

### 基础用法

```tsx
import { FormItemRecordListWrapper } from '@pisell/materials';

const options = [
  { label: '记录1', value: '1' },
  { label: '记录2', value: '2' },
];

const xRecordSchema = [
  {
    name: 'code',
    uiSchema: {
      title: '代码',
      'x-component': 'Input',
    }
  },
  {
    name: 'name',
    uiSchema: {
      title: '名称',
      'x-component': 'Input',
    }
  }
];

<FormItemRecordListWrapper
  name="records"
  label="记录列表"
  options={options}
  xRecordSchema={xRecordSchema}
  renderMode="edit"
/>
```

### 在 DataSourceForm 中使用

```tsx
<DataSourceForm renderMode="add">
  <FormItemRecordListWrapper
    name="channelRecords"
    label="渠道配置"
    options={channelOptions}
    xRecordSchema={channelFieldSchema}
  />
</DataSourceForm>
```

### 低代码平台配置示例

1. **配置选项数据源**：
   - optionSourceType: `api`
   - dataSource: 选择一个表
   - labelField: `name`
   - valueField: `id`

2. **配置 xRecordSchema**：
```json
[
  {
    "name": "productCode",
    "uiSchema": {
      "title": "产品代码",
      "x-component": "Input",
      "x-component-props": {
        "placeholder": "请输入产品代码"
      }
    }
  },
  {
    "name": "priority",
    "uiSchema": {
      "title": "优先级",
      "x-component": "InputNumber",
      "x-component-props": {
        "min": 0,
        "max": 100
      }
    }
  }
]
```

## 注意事项

1. **字段命名**：
   - xRecordSchema 中的字段名会成为最终提交的 key
   - 避免使用系统保留字段（createdAt、updatedAt 等）

2. **验证规则**：
   - 支持所有 DataSourceForm 的验证规则
   - 可以通过 `uiSchema['x-component-props'].requiredobj` 配置必填

3. **性能优化**：
   - 切换 tab 时不会清空表单，只是切换显示的数据
   - 所有 tab 的数据都会保存在 value 中

4. **嵌套结构**：
   - 支持嵌套的 JSON 字段（通过 Input.JSON 组件）
   - 可以配置 children 来定义嵌套结构

## 常见问题

### Q: 如何动态增减 option？

A: 通过修改 `options` prop，RecordListWrapper 会自动更新 tab 导航。新增的 option 会创建空的表单数据。

### Q: 如何验证所有 tab 的数据？

A: 将 RecordListWrapper 放在 Form 中，调用 `form.validateFields()` 会自动验证所有 tab 的数据。

### Q: 如何获取所有 tab 的数据？

A: 通过 `onChange` 回调或 Form 的 `getFieldValue('fieldName')` 获取完整的 Map 结构。

### Q: 支持哪些字段组件？

A: 支持所有 DataSourceForm 支持的组件，但**渲染方式有两种**：

#### 方式一：完整支持（推荐）- 在低代码平台配置 xRecordSchema
在低代码平台上配置 `xRecordSchema` 后，系统会自动调用 `createFormItemSchema` 生成完整的表单组件，**完全支持**所有类型：
- ✅ Input 系列（Input、TextArea、Email、Phone、Mobile、URL、Password、Subdomain）
- ✅ Select、Radio、Radio.Group、Checkbox、Checkbox.Group、Switch
- ✅ InputNumber、Percent
- ✅ DatePicker、TimePicker
- ✅ ColorPicker
- ✅ Upload
- ✅ Translation（多语言输入）
- ✅ Input.JSON（JSON 编辑器）
- ✅ IconPicker（图标选择器）
- ✅ RecordListWrapper（支持嵌套）

#### 方式二：简化支持（回退方案）- 直接传入 xRecordSchema 不通过低代码平台
如果直接在代码中使用 xRecordSchema，会使用简化的 `renderFallbackField` 回退渲染：
- ✅ Input 系列（基础支持）
- ✅ Select、Radio.Group、Checkbox.Group、Switch、Checkbox
- ✅ InputNumber、Percent
- ✅ DatePicker、TimePicker
- ✅ ColorPicker
- ✅ Upload（基础支持）
- ⚠️ Translation、IconPicker（使用 Input 代替）
- ⚠️ Input.JSON（使用 TextArea 代替）

**推荐做法：**
在低代码平台配置 xRecordSchema，让系统自动生成完整的表单组件，这样可以获得最佳体验和完整功能。

## 更新日志

### v1.0.0
- ✅ 增强渲染能力，支持完整的 Provider 链
- ✅ 支持低代码引擎动态添加组件
- ✅ 复用 DataSourceForm 的所有表单能力
- ✅ 支持 xRecordSchema 配置驱动
- ✅ 自动提供数据源上下文给子组件
