React-Selectize API完全手册：Props、方法与事件处理详解

发布时间：2026/7/28 23:02:21

React-Selectize API完全手册：Props、方法与事件处理详解

【免费下载链接】react-selectize项目地址: https://gitcode.com/gh_mirrors/re/react-selectize

React-Selectize 是一个功能强大的 React 选择框组件库，提供了简单选择（SimpleSelect）和多选（MultiSelect）两种核心组件，支持自定义渲染、搜索过滤、选项分组等高级功能。本文将详细解析其 API 设计，包括 props 配置、实例方法和事件处理，帮助开发者快速掌握这个高效选择框组件的使用技巧。

核心组件概览

React-Selectize 主要提供两种选择框组件，满足不同场景需求：

SimpleSelect：单选选择框

适用于从选项列表中选择单个值的场景，如表单中的下拉选择、筛选条件设置等。核心特性包括搜索过滤、自定义渲染和键盘导航，定义在 src/SimpleSelect.ls 中。

MultiSelect：多选选择框

支持同时选择多个选项，常用于标签选择、多条件筛选等场景。在单选功能基础上增加了值集合管理、最大选择限制等特性，定义在 src/MultiSelect.ls 中。

SimpleSelect 核心 Props

基础配置

属性名	类型	描述
`options`	`[Item]`	选项列表，默认要求包含`label`和`value`属性
`value`	`Item`	当前选中值
`defaultValue`	`Item`	初始默认值
`placeholder`	`String`	无值时显示的占位文本
`disabled`	`Boolean`	是否禁用组件交互

搜索与过滤

filterOptions：自定义过滤逻辑，默认根据标签文本模糊匹配。示例：

(options, search) => options.filter(item => item.label.toLowerCase().includes(search.toLowerCase()) )

createFromSearch：允许从搜索文本创建新选项，适用于动态添加场景：
```
(options, search) => ({ label: search, value: search })
```

自定义渲染

renderOption：自定义选项渲染函数
renderValue：自定义选中值显示样式
renderNoResultsFound：无搜索结果时的展示内容

交互行为

autofocus：加载时自动聚焦并打开下拉菜单
dropdownDirection：下拉方向（1: 向下，-1: 向上）
tether：启用 Tether 库实现下拉菜单定位，适用于复杂布局场景

MultiSelect 扩展 Props

在 SimpleSelect 基础上，MultiSelect 增加了以下专属配置：

值管理

属性名	类型	描述
`values`	`[Item]`	当前选中值集合
`defaultValues`	`[Item]`	初始默认值集合
`maxValues`	`Int`	最大选择数量限制
`closeOnSelect`	`Boolean`	选中后是否关闭下拉菜单

高级功能

anchor：控制光标在多选值之间的位置
valuesFromPaste：处理粘贴文本并转换为选中值
restoreOnBackspace：退格键删除值时恢复为编辑状态

实例方法

通过组件 ref 可调用以下实例方法：

通用方法

方法名	描述
`focus()`	聚焦输入框并打开下拉菜单
`blur()`	移除焦点并关闭下拉菜单
`highlightFirstSelectableOption()`	高亮第一个可选选项

组件专属方法

SimpleSelect：value()- 获取当前选中值
MultiSelect：values()- 获取当前选中值集合

事件处理

状态变更事件

onValueChange(SimpleSelect)：单选值变更时触发

(selectedValue) => console.log('选中值:', selectedValue)

onValuesChange(MultiSelect)：多选值集合变更时触发
```
(values) => console.log('选中值集合:', values)
```

交互事件

onOpenChange：下拉菜单展开/收起时触发
onSearchChange：搜索文本变化时触发
onHighlightedUidChange：高亮选项变化时触发

主题与样式

React-Selectize 支持多种内置主题，通过theme属性指定：

<SimpleSelect theme="material" />

主题样式定义在 themes/ 目录下，包含：

default.styl：默认主题
material.styl：Material Design 风格
bootstrap3.styl：Bootstrap 3 风格

实用工具组件

HighlightedText

用于搜索结果高亮显示，定义在 src/HighlightedText.ls，核心 props：

属性名	类型	描述
`text`	`String`	原始文本
`partitions`	`[[Int, Int, Boolean]]`	高亮区间配置
`highlightStyle`	`Object`	高亮文本样式

快速开始

安装依赖

git clone https://gitcode.com/gh_mirrors/re/react-selectize cd react-selectize npm install

基础用法示例

SimpleSelect：

<SimpleSelect options={[ { label: '选项1', value: '1' }, { label: '选项2', value: '2' } ]} placeholder="请选择..." onValueChange={(value) => console.log('选中:', value)} />

MultiSelect：

<MultiSelect options={[ { label: '标签1', value: '1' }, { label: '标签2', value: '2' } ]} placeholder="选择标签..." maxValues={3} onValuesChange={(values) => console.log('选中标签:', values)} />