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

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

基础配置

搜索与过滤

• 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 增加了以下专属配置：

值管理

高级功能

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

实例方法

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

通用方法

组件专属方法

• 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：

快速开始

安装依赖

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)} />

最佳实践

1. 性能优化：对于大量选项，使用filterOptions实现服务端过滤
2. 自定义主题：通过修改 themes/base.styl 自定义基础样式
3. 键盘导航：利用delimiters属性配置自定义分隔符，优化键盘操作体验
4. 表单集成：通过name和serialize属性实现表单自动提交

React-Selectize 提供了灵活的 API 设计，既满足基础选择需求，又支持复杂场景的定制化开发。通过合理配置 props 和事件处理，可轻松实现功能丰富的选择框组件。完整 API 文档可参考项目 API.md。

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