反应原生多选组件

适用于React Native的简易多选组件（类似Select2的React Native版本）。

重要通知

近期因工作和其他项目非常忙碌，我无法投入足够时间维护此项目。如果你有兴趣接管维护，请通过 邮箱 联系我。谢谢。

安装

$ npm install react-native-multiple-select --save

或使用yarn：

$ yarn add react-native-multiple-select

使用方法

注意：在使用此包之前，请确保已在你的项目中添加并配置了 react-native-vector-icons。

你可以克隆并尝试 示例应用，或者尝试 另一个示例。

以下代码片段展示了如何使用该组件：

// 导入组件
import React, { Component } from 'react';
import { View } from 'react-native';
import MultiSelect from 'react-native-multiple-select';

const items = [
  { id: '92iijs7yta', name: 'Ondo' },
  { id: 'a0s0a8ssbsd', name: 'Ogun' },
  // ...其他项目
  { id: 'suudydjsjd', name: 'Abuja' },
];

class MultiSelectExample extends Component {
  state = {
    selectedItems: [],
  };

  onSelectedItemsChange = (selectedItems) => {
    this.setState({ selectedItems });
  };

  render() {
    const { selectedItems } = this.state;
    
    return (
      <View style={{ flex: 1 }}>
        <MultiSelect
          hideTags
          items={items}
          uniqueKey="id"
          ref={(ref) => { this.multiSelect = ref; }}
          onSelectedItemsChange={this.onSelectedItemsChange}
          selectedItems={selectedItems}
          selectText="选择项目"
          searchInputPlaceholderText="搜索项目..."
          onChangeInput={(text) => console.log(text)}
          altFontFamily="ProximaNova-Light"
          tagRemoveIconColor="#CCC"
          tagBorderColor="#CCC"
          tagTextColor="#CCC"
          selectedItemTextColor="#CCC"
          selectedItemIconColor="#CCC"
          itemTextColor="#000"
          displayKey="name"
          searchInputStyle={{ color: '#CCC' }}
          submitButtonColor="#CCC"
          submitButtonText="提交"
        />
        <View>
          {this.multiSelect && this.multiSelect.getSelectedItemsExt(selectedItems)}
        </View>
      </View>
    );
  }
}

该组件需要三个强制属性：items、uniqueKey和onSelectedItemsChange，而其他属性是可选的。下表提供了更多详细说明。

属性列表

...（此处省略属性详情，因为原文没有给出具体的表格细节，实际使用时请参考文档提供的属性描述）

属性	必需	目的
altFontFamily	否	(字符串) searchInputPlaceholderText 的字体族
canAddItems	否	(布尔) 默认为 "false"。允许用户向项目列表中添加项。您需要在 onAddItem 函数属性中处理新增项目的逻辑。可以通过原生键盘上的回车键添加项目。
displayKey	否	(字符串) 默认为 "name"。此字符串用于从 items 数组中的对象选取显示的关键值
fixedHeight	否	(布尔) 默认为 false。指定下拉选择器是取内容高度还是固定高度并带有滚动条（当组件嵌套在 ScrollView 中时，滚动事件仅分发给父级 ScrollView，下拉组件无法滚动）。更多信息请参阅此问题。
filterMethod	否	(字符串) 默认为 "partial"。选项：["partial", "full"]。选择根据 searchTerm 过滤项目的逻辑方式。partial: 检查所有单独单词，只要至少匹配一个单词则包含该项目。full: 确保项目包含完整的搜索子串，不包括前导或尾随空格。
flatListProps	否	(对象) 对于下拉菜单的 FlatList 的属性。传递FlatList所需的任何属性。
fontFamily	否	(字符串) 组件中使用的自定义字体家族（影响除上面描述的 searchInputPlaceholderText 外的所有文本）
fontSize	否	(数字) 选中项名称作为多选标签显示的字体大小
hideDropdown	否	(布尔) 默认为 false。隐藏下拉菜单，使用取消按钮，并用返回箭头代替
hideSubmitButton	否	(布尔) 默认为 false。从下拉菜单中隐藏提交按钮，改为搜索字段内的箭头按钮
hideTags	否	(布尔) 默认为 false。隐藏标记化的已选项目，如果已选项目需要在视图的其他地方显示（更多信息请见下方）
searchIcon	否	(元素，对象，布尔，函数) 改变搜索图标的元素或功能组件
itemFontFamily	否	(字符串) 多选下拉菜单中每个未选项目所用的字体族
itemFontSize	否	(数字) 多选下拉菜单中每个项目的字体大小
itemTextColor	否	(字符串) 多选下拉菜单中每个未选项目的文字颜色
items	是	(数组，控制属性) 显示在多选组件中的项目列表。JavaScript 数组，每个对象包含一个名称和唯一标识符（查看上方示例）
noItemsText	否	(字符串) 替换默认“无项目显示”的文本
onAddItem	否	(函数) 作为参数传递的 JavaScript 函数。每次添加新项目时调用，接收整个项目列表。在这里确保新项目被添加到提供的 items 列表和其他添加新项目的结果中。
onChangeInput	否	(函数) 作为参数传递的 JavaScript 函数。每次 TextInput 变化时调用，传入值。
onClearSelector	否	(函数) 作为参数传递的 JavaScript 函数。每次点击“后退”按钮时调用。
onSelectedItemsChange	是	(函数) 作为参数传递的 JavaScript 函数。定义一个参数（selectedItems）。多选时点击“提交”按钮触发，单选时点击项目触发。（查看上方示例）
onToggleList	否	(函数) 作为参数传递的 JavaScript 函数。每次点击 multiselect 组件时调用
searchInputPlaceholderText	否	(字符串) 多选过滤输入框中的占位符文本
searchInputStyle	否	(对象) 多选输入元素的样式对象
selectText	否	(字符串) 主组件中显示的文本
selectedText	否	(字符串) 选定项目显示的文本，可以替换为任意字符串
selectedItemFontFamily	否	(字符串) 多选下拉菜单中每个已选项目的字体族
selectedItemIconColor	否	(字符串) 多选下拉菜单中每个已选项目的选中标记颜色
selectedItemTextColor	否	(字符串) 多选下拉菜单中每个已选项目的文字颜色
single	否	(布尔) 切换组件为单一选项或多选项模式
styleDropdownMenu	否	(样式) 配置下拉菜单的视图样式
styleDropdownMenuSubsection	否	(样式) 配置下拉菜单内层视图的样式
styleIndicator	否	(样式) 配置指示器图标样式
styleInputGroup	否	(样式) 配置文本输入组容器的样式
styleItemsContainer	否	(样式) 配置显示在列表中的项目容器的样式
styleListContainer	否	(样式) 配置主列表容器的样式。更多信息见此问题
styleMainWrapper	否	(样式) 配置 MultiSelector 主容器的样式
styleRowList	否	(样式) 配置显示后的行样式
styleSelectorContainer	否	(样式) 用户点击下拉时配置选择器容器的样式
styleTextDropdown	否	(文本样式) 配置下拉文本的样式
styleTextDropdownSelected	否	(文本样式) 配置已选下拉文本的样式
styleTextTag	否	(文本样式) 配置标签文本的样式
submitButtonColor	否	(字符串) 提交按钮的背景颜色
submitButtonText	否	(字符串) 提交按钮上显示的文本
tagBorderColor	否	(字符串) 已选项目边框颜色
tagContainerStyle	否	(样式) 标签视图容器的样式
tagRemoveIconColor	否	(字符串) 已选项目列表中移除图标的颜色
tagTextColor	否	(字符串) 已选项目列表的文字颜色
textColor	否	(字符串) 作为多选标签显示的已选项目名称的颜色
textInputProps	否	(对象) 文本输入的属性。传递文本输入所需任何属性
uniqueKey	是	(字符串) 作为每个项目属性一部分的唯一标识符。内部用作识别每个项目的方式（查看上方示例）
selectedItems	否	(数组，控制属性) 选定项目的键列表。JavaScript 字符串数组，可与组件实例化一起使用
removeSelected	否	(布尔) 过滤掉要显示在列表中的已选项目

注意事项

• 要在视图的其他部分显示标记化的已选项目，给 MultiSelect 组件添加一个 ref ，如 ref={(component) => { this.multiSelect = component }}，然后在屏幕任何地方添加 this.multiSelect.getSelectedItemsExt(selectedItems)。上述方法传入的 selectedItems 参数与主要组件的 selectedItems 属性相同。（见上方示例）。

• 如果不应让用户选择下拉列表中的任何项目，在项目中设置一个 disabled 键为 true。这样的项目将以灰色渲染且不可点击。

• 使用 single 属性时，仍应以已选项目键的数组形式传入 selectedItems。在单选模式下，当选项目被返回为一个字符串数组。

• items 属性必须作为包含每个对象的必需名称键的数组传递，因为名称键用于在选项组件中显示项目。

• filterMethod 示例：

  • partial 示例：若 searchTerm 为 "University of New"，将返回 "University of New York", "University of New Orleans", "The University of New York" 以及 "University of Columbia" 和 "New England Tech"，因存在部分匹配。
  • full 示例：若 searchTerm 为 "University of New"，将返回 "University of New York", "University of New Orleans", "The University of New York"，因为这三者都包含子串 "University of New"。

删除所有选中项

使用时，在父组件中给 MultiSelect 组件添加 ref，然后通过引用调用方法。例如：

<MultiSelect
  ref={(c) => { this._multiSelect = c; }}
  ...
/>

clearSelectedCategories = () => {
  this._multiSelect._removeAllItems();
};

贡献指南

我们热烈欢迎并会充分致谢您的贡献。

请通过GitHub提交拉取请求(Pull Requests)来进行贡献。

拉取请求注意事项

• 记录行为上的任何变化 - 确保 README.md 及其他相关文档保持最新。

• 考虑我们的发布周期 - 我们尽量遵循 SemVer v2.0.0。不应随意更改公共API。

• 从功能分支发起请求 - 请不要让我们从你的主分支拉取代码。

• 一事一请求 - 如果你想做多件事，请发送多个拉取请求。

• 提交清晰的历史记录 - 确保你的拉取请求中的每个单独提交都有意义。在开发过程中如有多个中间提交，提交前请使用 Git 的合并历史功能整合它们。

问题

检查问题列表以了解当前存在的问题。

贡献者

查看贡献者名单。

许可证

本项目采用 MIT 许可证。更多信息，请参考 LICENSE 文件。