react-native-picker-select

React Native 的选择器组件，模仿了 iOS 和 Android 原生 <select> 表单控件的界面。

• 在 iOS 上，默认使用未加样式的 TextInput 组件作为基础，并可通过传入样式来自定义。
• 对于 Android，默认采用原生的 Picker 组件。如果需要，可以设置 useNativeAndroidPickerStyle 为 false 来替换为无样式的 TextInput，同样支持自定义样式调整。
• 不论哪个平台，也可以直接传递一个子元素，该元素会被包裹在一个可触碰区域内。

在 Expo 上查看示例代码：snack.expo.io/@lfkwtz/react-native-picker-select

开始使用

安装

此包依赖于 @react-native-picker/picker。请确保正确安装以下依赖：

npm install react-native-picker-select
# 对于 React Native 用户
npm install @react-native-picker/picker
npx pod-install
# 对于 Expo
expo install @react-native-picker/picker

基础用法

import RNPickerSelect from 'react-native-picker-select';

const Dropdown = () => {
  return (
    <RNPickerSelect
      onValueChange={(value) => console.log(value)}
      items={[
        { label: '足球', value: 'football' },
        { label: '棒球', value: 'baseball' },
        { label: '曲棍球', value: 'hockey' },
      ]}
    />
  );
};

版本说明

版本	注意事项
>= 8.0.0	使用 @react-native-picker/picker。适用于 React Native 0.60 及以上版本。如果使用 Expo，则需 SDK38 或更高版本。
>= 3.0.0	需要 React v16.3 或更高版本。
< 3.0.0	支持 React v16.2 及更低版本。

属性概览

名称	描述	细节
onValueChange	返回选中项的值和索引的回调函数。	必需 函数
items	渲染所需的选择项数组。 每项格式如：{label: '橘子', value: 'orange', ...}，其中 label 和 value 必填，其余属性（如 key, color, testID, inputLabel）可选。若未提供 key，则默认等于 label。inputLabel 如存在，将优先在输入框显示其值而非 label。	必需 数组
placeholder	自定义占位符对象，以替代默认的 Select an item...。可用空对象来完全禁用占位符。	对象
disabled	禁止与组件交互。	布尔值
value	根据 items 数组中的 value 属性查找匹配项并设为选定项。找不到匹配项时默认选第一项。注意：计划允许用户通过 Picker 修改值时，iOS 应避免使用此属性，转而使用 itemKey。	任意类型
itemKey	根据 items 中的 key 属性查找匹配项，否则尝试按 value 查找。	字符串或数字
style	组件大部分部分的样式覆盖。 更多细节见 样式定制部分。	对象
darkTheme (仅限iOS)	使用深色主题。	布尔值
pickerProps	传递给 Picker 的额外属性（一些核心功能已使用特定属性，使用时需谨慎）。	对象
图标 (Icon)	自定义图标组件，用于渲染。 更多详情请参考样式设置部分。	组件类型 (Component)
--------------------------------------------	--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------	-----------------------
输入框额外属性 (textInputProps)	传递给TextInput的额外属性（某些属性被核心功能使用，因此需谨慎使用）。此属性仅适用于iOS，除非设置了useNativeAndroidPickerStyle={false}。	对象类型 (object)
包裹触控组件额外属性 (touchableWrapperProps)	传递给包裹TextInput的触控组件的额外属性（同样，一些属性用于核心功能，应谨慎使用）。	对象类型 (object)
打开回调 (onOpen())	在选择器打开前触发的回调函数。 当useNativeAndroidPickerStyle={true}时不支持。	函数类型 (function)
使用原生安卓样式 (useNativeAndroidPickerStyle)	组件默认在未选中状态下使用原生安卓选择器。将此标志设为false，则模拟iOS的默认展示方式，显示一个可点击的TextInput。 详细信息见样式设置部分。	布尔类型 (boolean)
修复安卓触控问题 (fixAndroidTouchableBug)	实验性标志，用于解决问题#354。	布尔类型 (boolean)
自定义输入辅助视图 (InputAccessoryView)	用自定义组件替换打开的选择器中的输入辅助视图区域（带有切换箭头和“完成”按钮的栏）。也可以返回null以完全隐藏该区域。虽然这种栏在网页的select元素上很常见，但根据iOS人机界面指南并不包含它。查看Snack示例了解如何自定义。	组件类型 (Component)
完成按钮文本 (doneText)	模态窗口中“完成”按钮的默认文本，可以在此处重写。	字符串类型 (string)
上箭头回调 (onUpArrow()) / 下箭头回调 (onDownArrow())	启用对应的箭头功能： - 关闭选择器 - 触发提供的回调函数 (仅限iOS)	函数类型 (function)
完成按钮点击回调 (onDonePress())	当按下“完成”按钮时触发的回调函数。（仅限iOS）	函数类型 (function)
关闭回调 (onClose(Bool))	选择器即将关闭时触发的回调，带有一个布尔参数，指示是否通过按“完成”按钮触发关闭。 (仅限iOS)	函数类型 (function)
模态对话框额外属性 (modalProps)	传递给Modal组件的额外属性（请小心，有些属性已由核心功能使用）。	对象类型 (object)
完成按钮触控额外属性 (touchableDoneProps)	传递给“完成”触控按钮的额外属性（需谨慎处理与核心功能冲突的属性）。	对象类型 (object)

样式设定

所有提及的属性都需嵌套在style属性下。不同的样式选项示例可在示例Snack中查看。

iOS 具体特性

• 组件包裹了一个未经修饰的TextInput，你可以使用inputIOS来定位并设置 TextInput 的样式。
• 可以修改的适用于 iOS 的其他样式包括：inputIOSContainer、placeholder、viewContainer、chevronContainer、chevron、chevronUp、chevronDown、chevronActive、done、modalViewTop、modalViewMiddle 和 modalViewBottom。

Android 具体特性

• 状态未激活时，原生的 Picker 类似于一个 TextInput，但自定义样式有限制。通过inputAndroid可以应用所有可能的样式。
• 你可以在活跃状态下的原生 Picker 上添加一些样式定制，但这需要修改一些 XML 文件。
• 如果你将属性 useNativeAndroidPickerStyle 设置为 false，则组件会允许其他几个样式对象：inputAndroidContainer、placeholder 和 inputAndroid。
• 可以修改的适用于 Android 的其他样式包括：headlessAndroidContainer 和 viewContainer。

Web 具体特性

• 组件创建了一个 select 标签。
• 可以通过一个内联对象（键为inputWeb）修改此 select 标签的样式。

图标

• 若通过Icon属性传递了一个组件，它将在包装容器上渲染，并应用 { position: 'absolute', right: 0 } 样式。你可以通过修改iconContainer来调整这些值和添加额外间距，以便根据需要定位图标。你可能还需要对输入样式添加一些 paddingRight，以避免较长的文字出现在图标后面。
• 你可以传入自选的组件（如 CSS、图像、SVG 等）作为图标。为了方便使用，可考虑使用像 react-native-shapes 或 react-native-vector-icons 这样的库。
• 不同图标的示例及其用法可以在示例 Snack 中找到。

辅助功能

如果需要向渲染组件添加辅助功能属性，可以使用 pickerProps 和 touchableWrapperProps 将它们传递进去。

pickerProps 接受一个对象，其中的属性直接传递给原生的 <Picker /> 组件。 touchableWrapperProps 同样接受一个对象，但它会被传递给一个用于切换 picker 显示状态的 <TouchableOpacity />。（注：touchableWrapperProps 在 Web 或 useNativeAndroidPickerStyle={true} 时不支持）

辅助功能示例

下面的例子中，我们渲染了带有补充描述文本的 picker，但在屏幕阅读器中，我们通过仅将标题传递到accessibilityLabel属性，省略了这段描述文字。

const selectedItem = {
  title: '选定项目标题',
  description: '次要的长描述性文本...',
};

export const Dropdown = () => {
  return (
    <RNPickerSelect
      pickerProps={{
        accessibilityLabel: selectedItem.title,
      }}
    >
      <Text>{selectedItem.title}</Text>
      <Text>{selectedItem.description}</Text>
    </RNPickerSelect>
  );
};

测试

包含测试套件。该组件从 React Native v0.51 版本起已被使用和测试。

许可证

react-native-picker-select 是MIT许可的，由得克萨斯州奥斯汀市的LawnStarter团队带着爱心构建。