react-select-search - React轻量级下拉选择组件支持搜索和自定义

⚠️ 招募维护者

首先，我要感谢大家多年来的鼎力支持。这是我最早的开源项目之一，也是我第一个成功的项目。我非常感激所有33位贡献者，没有你们就不可能运营这个项目。

去年发生了很多事。我有了第一个儿子，接了一些耗时的自由职业工作，还有几个创业公司在发展。这些都占用了我投入开源的时间，我感觉自己已经无法很好地维护这个组件了。至少不能单靠我一个人。

我仍然相信一个小巧、超快速且零依赖的选择组件的价值。如果有人愿意与我共同维护这个项目，请联系我讨论下一步计划。可以发邮件到hola@tobiasbleckert.se或在Twitter上联系我。

React Select Search

演示 · 快速开始 · 配置 · 无头模式

特性

轻量级，零依赖
无障碍
无头模式
基本的HTML select功能，包括多选
搜索/过滤选项
异步选项
应用渲染器来更改标记和行为
键盘支持
使用组名对选项分组，可搜索组名
完全可定制样式

安装

使用npm（npm i react-select-search）或yarn（yarn add react-select-search）安装，然后像平常一样导入。

快速开始

import SelectSearch from 'react-select-search';

/**
 * options数组应包含对象。
 * 必需的键是"name"和"value"，但你可以使用任意数量的键值对。
 */
const options = [
    {name: '瑞典语', value: 'sv'},
    {name: '英语', value: 'en'},
    {
        type: 'group',
        name: '组名',
        items: [
            {name: '西班牙语', value: 'es'},
        ]
    },
];

/* 简单示例 */
<SelectSearch options={options} value="sv" name="language" placeholder="选择你的语言" />

更多示例，可以查看stories目录。

你还需要一些CSS来使其看起来正确。示例主题可以在style.css中找到。你也可以直接导入：

import 'react-select-search/style.css'

与SSR一起使用

对于SSR使用，你可能需要使用CommonJS包（react-select-search/dist/cjs）。如果你想使用示例主题（style.css），需要检查你的构建脚本是否操作类名，例如最小化它们。如果是这样，你可以使用CSS模块获取style.css文件中的类名，并使用className对象应用它们。示例可以在这里和这里看到。

使用钩子的无头模式

如果你想完全控制（比样式和自定义渲染器更多），你可以使用钩子将数据传递给你自己的组件并自行构建。

import React from 'react';
import { useSelect } from 'react-select-search';

const CustomSelect = ({ options, value, multiple, disabled }) => {
    const [snapshot, valueProps, optionProps] = useSelect({
        options,
        value,
        multiple,
        disabled,
    });

    return (
        <div>
            <button {...valueProps}>{snapshot.displayValue}</button>
            {snapshot.focus && (
                <ul>
                    {snapshot.options.map((option) => (
                        <li key={option.value}>
                            <button {...optionProps} value={option.value}>{option.name}</button>
                        </li>
                    ))}
                </ul>
            )}
        </div>
    );
};

配置

以下是你可以传递给组件的所有可用选项。没有默认值的选项是必需的。

名称	类型	默认值	描述
options	数组		请参阅下方的选项文档
getOptions	函数	null	通过函数调用获取选项，可以返回 Promise 用于异步使用。更多详情请参阅获取选项。
filterOptions	数组	null	一组函数，接收最后过滤的选项和搜索查询（如果有）。在 getOptions 之后运行。
value	字符串、数组	null	如果是多选模式，值应该是一个数组。
multiple	布尔值	false	如果想允许多选，请设置为 true。
search	布尔值	false	设置为 true 以启用搜索功能
disabled	布尔值	false	禁用所有功能
closeOnSelect	布尔值	true	默认情况下，选择选项时选择框会失去焦点。设置为 false 可以阻止此行为。
debounce	数字	0	搜索时等待调用获取选项的毫秒数。
placeholder	字符串	空字符串	当未选择选项和/或搜索字段聚焦且值为空时显示。
id	字符串	null	顶层元素的 HTML ID。
autoComplete	字符串，on/off	off	禁用/启用搜索字段的自动完成功能。
autoFocus	布尔值	false	自动聚焦选择框
className	字符串、对象	select-search-box	设置基础类字符串或传递函数以完全控制。更多详情请参阅自定义类名。
renderOption	函数	null	渲染选项的函数。更多详情请参阅自定义渲染器。
renderGroupHeader	函数	null	渲染组标题的函数。更多详情请参阅自定义渲染器。
renderValue	函数	null	渲染值/搜索字段的函数。更多详情请参阅自定义渲染器。
emptyMessage	React 节点	null	为空选项列表设置空消息，可以提供不带参数的渲染函数，而不是纯字符串消息
onChange	函数	null	接收和处理值变化的函数。
onFocus	函数	null	聚焦回调。
onBlur	函数	null	失焦回调。

选项对象

选项对象可以包含任何你喜欢的属性和值。唯一必需的是 name。

属性	类型	描述	是否必需
name	字符串	选项的名称	是
value	字符串	选项的值	是，如果类型不是 "group"
type	字符串	如果将类型设置为 "group"，你可以添加一个将被分组的选项数组	否
items	数组	如果类型设置为 "group"，将使用的选项对象数组	是，如果 `type` 设置为 "group"
disabled	布尔值	设置为 `true` 以禁用此选项	否

自定义类名

如果将字符串设置为 className 属性值，组件将使用它作为所有元素的基础。如果你想完全控制类名，可以传递一个包含类名的对象。存在以下键：

container
value
input
select
options
row
option
group
group-header
is-selected
is-highlighted
is-loading
is-multiple
has-focus

自定义渲染器

如果 CSS 不够用，你还可以控制组件不同部分的 HTML。

回调	参数	描述
renderOption	optionsProps: 对象, optionData: 对象, optionSnapshot: 对象, className: 字符串	控制选项的渲染。
renderGroupHeader	name: 字符串	控制组标题名称的渲染
renderValue	valueProps: 对象, snapshot: 对象, className: 字符串	控制值/输入元素的渲染

optionProps 和 valueProps 对你渲染的组件正常工作是必需的。例如：

<SelectSearch renderValue={(valueProps) => <input {...valueProps} />} />

如果需要，可以修改它，但确保不要删除重要的属性。

optionSnapshot 是一个包含对象状态的对象：{ selected: bool, highlighted: bool }。

获取选项

你可以使用 getOptions 属性异步获取选项。你可以直接返回选项或通过 Promise 返回。

function getOptions(query) {
    return new Promise((resolve, reject) => {
        fetch(`https://www.thecocktaildb.com/api/json/v1/1/search.php?s=${query}`)
            .then(response => response.json())
            .then(({ drinks }) => {
                resolve(drinks.map(({ idDrink, strDrink }) => ({ value: idDrink, name: strDrink })))
            })
            .catch(reject);
    });
}

该函数在每次搜索查询更新时运行，因此你可能想要限制获取频率。如果你返回一个 promise，类 is-loading 将应用于主元素，让你有机会改变外观，比如添加一个加载图标。fetching 属性也在发送到你的渲染回调的快照中可用。

贡献者

使用 contrib.rocks 制作。