500tech-react-select 中文文档教程

Question

React-Select

使用 React 构建的 Select 控件。 最初构建用于 KeystoneJS。

Demo & Examples

现场演示：jedwatson.github.io/react-select

要在本地构建示例，请运行：

npm install
gulp dev

然后打开 localhost:8000 在浏览器中。

Project Status

这个项目非常稳定，可以用于生产，但是有计划对其进行改进，包括：

• CSS Styles and theme support (working, could be improved)
• Documentation website (currently just examples)
• Custom options rendering

它松散地基于 Selectize （在行为和用户体验方面）和 React-Autocomplete（作为本机 React Combobox 实现），以及其他选择控件，包括 Chosen 和 Select2。

Installation

使用 React-Select 最简单的方法是从 NPM 安装它并将其包含在您自己的 React 构建过程中（使用 Browserify 等）。

npm install react-select --save

您还可以通过在页面中包含 dist/select.js 和 dist/default.css 来使用独立构建。 如果您使用它，请确保您已经包含以下依赖项：

• React
• classNames
• react-input-autosize

Usage

React-Select 生成一个包含所选值的隐藏文本字段，因此您可以将其作为标准表单的一部分提交。 您还可以使用 onChange 事件属性监听更改。

选项应作为 Object 的 Array 提供，每个选项都具有用于呈现和搜索的 value 和 label 属性. 您可以使用 disabled 属性来指示该选项是否被禁用。

每个选项的 value 属性应设置为字符串或数字。

当值更改时，onChange(newValue, [selectedOptions]) 将触发。

var Select = require('react-select');

var options = [
    { value: 'one', label: 'One' },
    { value: 'two', label: 'Two' }
];

function logChange(val) {
    console.log("Selected: " + val);
}

<Select
    name="form-field-name"
    value="one"
    options={options}
    onChange={logChange}
/>

Multiselect options

您可以通过设置 multi={true} 启用多值选择。 在这种模式下：

• Selected options will be removed from the dropdown menu
• The values of the selected items are joined using the delimiter property to create the input value
• A simple value, if provided, will be split using the delimiter property
• The onChange event provides an array of the selected options as the second argument
• The first argument to onChange is always a string, regardless of whether the values of the selected options are numbers or strings

Async options

如果你想异步加载选项，而不是提供一个 options 数组，提供一个 asyncOptions 函数。

该函数有两个参数 String input, Function callback，当输入文本改变时将被调用。

当您的异步进程完成获取选项时，将它们传递给对象 { options: [] } 中的 callback(err, data)。

选择控件将智能地缓存已获取的输入字符串的选项。 缓存的结果集将在输入更具体的搜索时进行过滤，因此如果您的异步过程只会为更具体的查询返回较小的结果集，还可以在回调对象中传递 complete: true。 可以通过将 cacheAsyncResults 设置为 false 来禁用缓存（请注意 complete: true 将无效）。

除非您指定 autoload={false} 属性，否则控件将在安装时自动加载默认选项集（即 input: ''）。

var Select = require('react-select');

var getOptions = function(input, callback) {
    setTimeout(function() {
        callback(null, {
            options: [
                { value: 'one', label: 'One' },
                { value: 'two', label: 'Two' }
            ],
            // CAREFUL! Only set this to true when there are no more options,
            // or more specific queries will not be sent to the server.
            complete: true
        });
    }, 500);
};

<Select
    name="form-field-name"
    value="one"
    asyncOptions={getOptions}
/>

Filtering options

您可以使用以下属性控制选项的过滤方式：

• matchPos: "start" or "any": whether to match the text entered at the start or any position in the option value
• matchProp: "label", "value" or "any": whether to match the value, label or both values of each option when filtering
• ignoreCase: Boolean: whether to ignore case or match the text exactly when filtering

matchProp 和 matchPos 均默认为 "any"。 ignoreCase 默认为 true。

Advanced filters

您还可以完全替换用于过滤单个选项或整个选项数组（允许自定义排序机制等）的方法

• filterOption: function(Object option, String filter) returns Boolean. Will override matchPos, matchProp and ignoreCase options.
• filterOptions: function(Array options, String filter, Array currentValues) returns Array filteredOptions. Will override filterOption, matchPos, matchProp and ignoreCase options.

。对于多选输入，在提供自定义 filterOptions 方法时，请记住从返回的选项数组中排除当前值。

Further options

Property            |   Type        |   Description

:--------------------|:------------|:-------- ---------------------- 价值 | 任何| 初始字段值 值渲染器 | 功能 | 返回自定义方式来呈现所选值的函数 多 | 布尔 | 多值输入 禁用 | 布尔 | 选择是否被禁用 选项 | 数组 | 选项数组 选项渲染器 | 功能 | 该函数返回一种自定义方式来呈现菜单中的选项 分隔符 | 字符串 | 用于连接多个值的分隔符 异步选项 | 功能 | 调用以获取选项的函数 自动加载 | 布尔 | 是否自动加载默认的异步选项集 禁用缓存 | 布尔 | 禁用 asyncOptions 的选项缓存 占位符 | 字符串 | 字段占位符，没有值时显示 没有结果文本 | 字符串 | 没有匹配的搜索结果时显示的占位符 可清除 | 布尔 | 是否可以重置值 清除值文本 | 字符串 | “清除”控件的标题 清除所有文本 | 字符串 | 多时“清除”控件的标题：true 可搜索 | 布尔 | 是否启用搜索功能 搜索提示文本 | 字符串 | 提示搜索输入的标签 姓名 | 字符串 | 字段名，用于隐藏的 标签 改变 | 功能 | onChange 处理程序：函数（新值）{} 聚焦 | 功能 | onFocus 处理程序：函数（事件）{} 模糊 | 功能 | onBlur 处理程序：函数（事件）{} 类名 | 字符串 | 外部元素的类名 过滤器选项 | 功能 | 过滤单个选项的方法：function(option, filterString) 过滤器选项 | 功能 | 过滤选项数组的方法：function([options], filterString, [values]) 匹配位置 | 字符串 | (any, start) 过滤时匹配开始或整个字符串 匹配道具 | 字符串 | (any, label, value) 要过滤的选项属性 忽略大小写 | 布尔 | 是否进行不区分大小写的过滤 输入道具 | 对象 | 输入的自定义属性（在选择控件中）例如：{'data-foo': 'bar'} 退格删除 | 布尔 | 当没有输入值时，按退格键是否删除最后一项

Contributing

请参阅我们的 CONTRIBUTING.md有关如何贡献的信息。

License

麻省理工学院许可。 版权所有 (c) Jed Watson 2015。