# 组件示例

**Repository Path**: kyle_gitee/component-example

## Basic Information

- **Project Name**: 组件示例
- **Description**: 开源组件示例代码
- **Primary Language**: JavaScript
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2024-12-20
- **Last Updated**: 2024-12-27

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# React Dynamic Form Component

一个基于 React Hook Form 的动态表单组件，支持多种输入类型、嵌套数组字段、条件渲染、异步选项加载以及可创建的选择框。

## 特性

- 🎯 支持多种输入类型（文本、邮箱、密码、选择框）
- 📦 支持嵌套数组字段
- ✨ 支持条件渲染
- 🔄 支持异步加载选项
- ✅ 内置表单验证
- 🎨 可自定义渲染
- 🆕 支持可创建的选择框

## 安装

```bash
npm install react-hook-form
```

## 基础用法

```tsx
import { Form } from './Form';

const App = () => {
  const fields = [
    {
      name: "username",
      label: "用户名",
      type: "text",
      placeholder: "请输入用户名",
      validation: { required: "用户名是必填的" }
    },
    {
      name: "role",
      label: "角色",
      type: "select",
      options: [
        { value: "admin", label: "管理员" },
        { value: "user", label: "普通用户" }
      ],
      validation: { required: "角色是必填的" }
    }
  ];

  const handleSubmit = (data) => {
    console.log(data);
  };

  return <Form fields={fields} onSubmit={handleSubmit} />;
};
```

## 字段配置

### 基础字段属性

所有字段类型都支持以下基础属性：

```typescript
interface BaseFieldConfig {
  name: string;          // 字段名称
  label: string;         // 字段标签
  type: string;          // 字段类型
  placeholder?: string;  // 占位文本
  validation?: {        // 验证规则
    required?: string;
    pattern?: { value: RegExp; message: string };
    min?: { value: number; message: string };
    max?: { value: number; message: string };
  };
  condition?: (values: Record<string, any>) => boolean; // 条件渲染函数
}
```

### 文本输入字段

```typescript
const textField = {
  name: "username",
  label: "用户名",
  type: "text", // 或 "email", "password"
  placeholder: "请输入用户名",
  validation: { required: "用户名是必填的" }
};
```

### 选择框字段

```typescript
const selectField = {
  name: "role",
  label: "角色",
  type: "select",
  options: [
    { value: "admin", label: "管理员" },
    { value: "user", label: "普通用户" }
  ],
  // 异步加载选项
  fetchOptions: async () => {
    const response = await fetch('/api/roles');
    return response.json();
  },
  // 依赖其他字段的异步选项
  fetchOptionsDependencies: ["department"],
  validation: { required: "角色是必填的" }
};
```

### 可创建的选择框

```typescript
const creatableSelectField = {
  name: "customRole",
  label: "自定义角色",
  type: "select",
  creatable: true, // 启用创建新选项
  formatCreateLabel: (inputValue) => `创建新角色: ${inputValue}`,
  options: [
    { value: "admin", label: "管理员" },
    { value: "user", label: "普通用户" }
  ],
  validation: { required: "角色是必填的" }
};
```

### 数组字段

```typescript
const arrayField = {
  name: "roles",
  label: "角色列表",
  type: "array",
  subFields: [
    {
      name: "role",
      label: "角色",
      type: "select",
      options: [
        { value: "admin", label: "管理员" },
        { value: "user", label: "用户" }
      ]
    },
    {
      name: "description",
      label: "描述",
      type: "text"
    }
  ],
  // 字段值依赖处理
  onDependencyChange: (allValues, setValue) => {
    // 处理字段间的依赖关系
  }
};
```

## 自定义渲染

### 自定义字段渲染

```tsx
const renderField = (field, control, errors) => {
  // 返回自定义的字段渲染结果
  return <CustomField field={field} control={control} errors={errors} />;
};

<Form fields={fields} onSubmit={handleSubmit} renderField={renderField} />
```

### 自定义数组控件

```tsx
const renderArrayControls = ({ append, remove, index }) => {
  if (index !== undefined) {
    return (
      <button onClick={() => remove(index)}>
        删除
      </button>
    );
  }
  return (
    <button onClick={() => append({})}>
      添加
    </button>
  );
};

<Form fields={fields} onSubmit={handleSubmit} renderArrayControls={renderArrayControls} />
```

## 条件渲染

可以通过 `condition` 属性控制字段的显示：

```typescript
const fields = [
  {
    name: "age",
    label: "年龄",
    type: "text"
  },
  {
    name: "guardian",
    label: "监护人",
    type: "text",
    condition: (values) => values.age < 18
  }
];
```

## 高级用法

### 字段间的依赖关系

```typescript
const fields = [
  {
    name: "department",
    label: "部门",
    type: "select",
    options: [
      { value: "tech", label: "技术部" },
      { value: "hr", label: "人力资源" }
    ]
  },
  {
    name: "position",
    label: "职位",
    type: "select",
    fetchOptions: async (department) => {
      // 根据部门获取职位列表
      const response = await fetch(`/api/positions?dept=${department}`);
      return response.json();
    },
    fetchOptionsDependencies: ["department"]
  }
];
```

### 表单验证

```typescript
const fields = [
  {
    name: "email",
    label: "邮箱",
    type: "email",
    validation: {
      required: "邮箱是必填的",
      pattern: {
        value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i,
        message: "请输入有效的邮箱地址"
      }
    }
  },
  {
    name: "age",
    label: "年龄",
    type: "text",
    validation: {
      required: "年龄是必填的",
      min: { value: 18, message: "年龄必须大于18岁" },
      max: { value: 100, message: "年龄必须小于100岁" }
    }
  }
];
```

## 注意事项

1. 确保正确安装了 `react-hook-form` 依赖
2. 异步选项加载时注意处理加载状态
3. 条件渲染时需要考虑字段间的依赖关系
4. 使用可创建选择框时，注意处理新创建选项的持久化
5. 数组字段的依赖关系要特别注意索引的处理

## TypeScript 支持

组件完全使用 TypeScript 编写，提供完整的类型定义。使用时可以获得完整的类型提示和检查。

## 贡献

欢迎提交 Issue 和 Pull Request！

## 许可

MIT