# CategorySelector 品类选择器组件

品类选择器组件，用于从树形结构中选择产品或服务品类。支持单选和多选模式，具有搜索过滤功能。

## 组件特点

- 树形结构展示品类层级关系
- 支持单选和多选模式
- 支持搜索过滤功能
- 仅叶子节点可选，中间节点不可选
- 自动加载品类数据
- 支持表单受控模式

## 使用场景

- 供应商评估任务中选择相关品类
- 供应商准入管理中设置品类范围
- 任何需要选择产品品类或服务类别的场景

## 使用方法

### 基础用法

```jsx
import React, { useState } from 'react';
import { CategorySelector } from '@/components';

const Demo = () => {
  const [selectedCategories, setSelectedCategories] = useState([]);

  const handleCategoryChange = (categories) => {
    setSelectedCategories(categories);
    console.log('已选择的品类:', categories);
  };

  return (
    <CategorySelector 
      value={selectedCategories} 
      onChange={handleCategoryChange} 
    />
  );
};
```

### 单选模式

```jsx
import React, { useState } from 'react';
import { CategorySelector } from '@/components';

const SingleSelectDemo = () => {
  const [selectedCategory, setSelectedCategory] = useState('');

  return (
    <CategorySelector 
      value={selectedCategory}
      onChange={setSelectedCategory}
      multiple={false}
      placeholder="请选择一个品类"
    />
  );
};
```

### 配合表单使用

```jsx
import React from 'react';
import { Form, Button } from 'antd';
import { CategorySelector } from '@/components';

const FormDemo = () => {
  const [form] = Form.useForm();

  const handleFinish = (values) => {
    console.log('表单提交的值:', values);
  };

  return (
    <Form form={form} onFinish={handleFinish}>
      <Form.Item
        name="categories"
        label="选择品类"
        rules={[{ required: true, message: '请至少选择一个品类' }]}
      >
        <CategorySelector />
      </Form.Item>
      
      <Form.Item>
        <Button type="primary" htmlType="submit">
          提交
        </Button>
      </Form.Item>
    </Form>
  );
};
```

### 自定义样式

```jsx
import React from 'react';
import { CategorySelector } from '@/components';

const CustomStyleDemo = () => {
  return (
    <CategorySelector 
      style={{ width: '300px' }}
      placeholder="选择品类（自定义宽度）"
    />
  );
};
```

## API

### 组件属性

| 参数 | 说明 | 类型 | 默认值 | 是否必填 |
|------|------|------|--------|----------|
| value | 当前选中的品类ID或ID数组 | `string \| string[]` | - | 否 |
| onChange | 选择变化时的回调函数 | `(value: string \| string[]) => void` | - | 否 |
| disabled | 是否禁用选择器 | `boolean` | `false` | 否 |
| multiple | 是否支持多选 | `boolean` | `true` | 否 |
| placeholder | 占位文本 | `string` | `"请选择品类"` | 否 |
| style | 自定义样式 | `React.CSSProperties` | `{ width: '100%' }` | 否 |

## 设计实现

组件基于 Ant Design 的 TreeSelect 组件开发，并与后端 API 集成，从服务器获取品类数据。主要特点：

1. **纯受控组件**：完全符合 React 受控组件模式，方便与表单结合使用
2. **树形数据处理**：后端返回的数据经过格式转换，适配 TreeSelect 的要求
3. **性能优化**：
   - 只在组件挂载时加载一次数据
   - 数据量大时不自动展开所有节点
   - 使用 `filter(Boolean)` 过滤空值，避免错误
4. **用户体验优化**：
   - 加载状态显示
   - 搜索过滤功能
   - 只允许选择叶子节点，防止选择中间类别

## 后端 API 集成

组件通过 `getCategoryTree` API 获取品类数据。预期的响应格式：

```typescript
interface ApiResponse {
  success: boolean;
  data: CategoryItem[];
}

interface CategoryItem {
  id: string;
  categoryName: string;
  type: string; // '1' 表示叶子节点
  children?: CategoryItem[];
}
```

## 常见问题

### 1. 如何刷新品类数据？

当前版本不支持手动刷新，品类数据只在组件挂载时加载一次。如需刷新功能，可以扩展组件添加刷新方法。

### 2. 如何自定义节点渲染？

当前版本使用默认的节点渲染。如需自定义，可以通过修改组件源码添加 `treeNodeLabelProp` 或自定义 `title` 渲染函数。

### 3. 选择了品类但没有在表单中显示值？

请确保正确传递了 `value` 和 `onChange` 属性，并在 Form.Item 中设置了正确的 `name` 属性。 
