npm package: @fle-ui/plus-select
Description: @fle-ui/plus-select
Latest version: 1.0.3

# @fle-ui/plus-select

> 基于 Ant Design Select 组件封装的高级下拉选择组件，支持远程搜索、分页加载、输入法组合等特性。

## 安装

使用 npm：

```bash
$ npm install --save @fle-ui/plus-select
```

或使用 yarn：

```bash
$ yarn add @fle-ui/plus-select
```

## 功能特性

- 🔍 **远程搜索**: 支持通过 API 请求进行远程数据搜索
- 📄 **分页加载**: 支持滚动到底部自动加载更多数据
- ⌨️ **输入法优化**: 优化中文输入法组合输入体验
- 🔄 **手动刷新**: 提供手动刷新数据的方法
- 🎯 **完全兼容**: 完全兼容 Ant Design Select 的所有属性

## 何时使用

- 需要从服务器动态加载选项数据
- 数据量较大，需要分页加载
- 需要支持远程搜索功能
- 需要优化中文输入体验

## API

### PlusSelect Props

| 参数 | 说明 | 类型 | 默认值 | 版本 |
| --- | --- | --- | --- | --- |
| request | 获取数据的请求函数 | `PlusSelectRequestFunction<OptionType>` | - | - |

### PlusSelectRequestFunction

远程数据请求函数的类型定义：

```typescript
interface PlusSelectRequestFunction<OptionType extends BaseOptionType = DefaultOptionType> {
  (params: { 
    keyword?: string;    // 搜索关键词
    pageNo: number;      // 页码，从 1 开始
    pageSize: number;    // 每页数量
  }): Promise<{
    list: OptionType[];  // 选项列表
    total?: number;      // 总数量
    pageNo?: number;     // 当前页码
    pageSize?: number;   // 每页数量
  }>;
}
```

### PlusSelectRef

组件实例的引用类型，提供以下方法：

| 方法 | 说明 | 参数 | 返回值 |
| --- | --- | --- | --- |
| search | 手动触发搜索 | `(value: string) => void` | - |
| reload | 重新加载数据 | `() => void` | - |

### 继承的 Props

PlusSelect 组件完全继承了 Ant Design Select 组件的所有属性，包括但不限于：

| 参数 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| allowClear | 支持清除 | `boolean` | `false` |
| autoClearSearchValue | 是否在选中项后自动清空搜索框 | `boolean` | `true` |
| defaultOpen | 是否默认展开下拉菜单 | `boolean` | - |
| disabled | 是否禁用 | `boolean` | `false` |
| dropdownClassName | 下拉菜单的 className 属性 | `string` | - |
| dropdownMatchSelectWidth | 下拉菜单和选择器同宽 | `boolean \| number` | `true` |
| dropdownRender | 自定义下拉框内容 | `(originNode: ReactNode) => ReactNode` | - |
| dropdownStyle | 下拉菜单的 style 属性 | `CSSProperties` | - |
| fieldNames | 自定义字段名 | `object` | `{ label: 'label', value: 'value', options: 'options' }` |
| filterOption | 是否根据输入项进行筛选 | `boolean \| ((inputValue: string, option?: DefaultOptionType) => boolean)` | `true` |
| getPopupContainer | 菜单渲染父节点 | `(triggerNode: HTMLElement) => HTMLElement` | `() => document.body` |
| labelInValue | 是否把每个选项的 label 包装到 value 中 | `boolean` | `false` |
| listHeight | 设置弹窗滚动高度 | `number` | `256` |
| loading | 加载中状态 | `boolean` | `false` |
| maxTagCount | 最多显示多少个 tag | `number \| responsive` | - |
| maxTagPlaceholder | 隐藏 tag 时显示的内容 | `ReactNode \| ((omittedValues: DefaultOptionType[]) => ReactNode)` | - |
| maxTagTextLength | 最大显示的 tag 文本长度 | `number` | - |
| menuItemSelectedIcon | 自定义多选时当前选中的条目图标 | `ReactNode` | - |
| mode | 设置 Select 的模式 | `'multiple' \| 'tags' \| 'combobox'` | - |
| notFoundContent | 当下拉列表为空时显示的内容 | `ReactNode` | `'Not Found'` |
| open | 是否展开下拉菜单 | `boolean` | - |
| options | 数据化配置选项内容 | `OptionType[]` | `[]` |
| placeholder | 选择框默认文字 | `string` | - |
| placement | 选择框弹出的位置 | `'bottomLeft' \| 'bottomRight' \| 'topLeft' \| 'topRight'` | `bottomLeft` |
| popupClassName | 下拉菜单的 className 属性 | `string` | - |
| removeIcon | 自定义移除图标 | `ReactNode` | - |
| searchValue | 控制搜索文本 | `string` | - |
| showSearch | 是否显示搜索框 | `boolean` | `false` |
| size | 选择框大小 | `'large' \| 'middle' \| 'small'` | `middle` |
| status | 设置校验状态 | `'error' \| 'warning'` | - |
| suffixIcon | 自定义的选择框后缀图标 | `ReactNode` | - |
| tagRender | 自定义 tag 内容渲染 | `(props: CustomTagProps) => ReactNode` | - |
| tokenSeparators | 在 tags 和 multiple 模式下自动分词的分隔符 | `string[]` | - |
| value | 当前选中的选项 | `ValueType` | - |
| virtual | 是否开启虚拟滚动 | `boolean` | `true` |

### 事件

| 事件名称 | 说明 | 回调参数 |
| --- | --- | --- |
| onBlur | 失去焦点的回调 | `function` |
| onChange | 选中 option，或 input 的 value 变化时，调用此函数 | `function(value, option)` |
| onClear | 清除内容时回调 | `function` |
| onDeselect | 取消选中时调用，参数为选中项的 value（或 key） | `function(value, option)` |
| onDropdownVisibleChange | 展开下拉菜单的回调 | `function(open)` |
| onFocus | 获得焦点时回调 | `function` |
| onInputKeyDown | 键盘按下时回调 | `function` |
| onMouseEnter | 鼠标移入时回调 | `function` |
| onMouseLeave | 鼠标移出时回调 | `function` |
| onPopupScroll | 下拉列表滚动时的回调 | `function` |
| onSearch | 文本框值变化时回调 | `function(value: string)` |
| onSelect | 被选中时调用，参数为选中项的 value（或 key） | `function(value, option)` |


## 注意事项

1. **request 函数**: 当提供 `request` 函数时，组件会忽略 `options` 属性，完全依赖远程数据
2. **分页加载**: 组件会自动处理分页逻辑，当滚动到底部时会自动加载下一页数据
3. **输入法优化**: 组件内置了中文输入法组合输入的优化，避免在输入过程中触发搜索
4. **防抖处理**: 搜索请求有 300ms 的防抖延迟，避免频繁请求
5. **错误处理**: 当请求失败时，组件会自动清空选项列表

更多详细信息请参考 [Ant Design Select 文档](https://ant-design.antgroup.com/components/select-cn)。