文档
BlogChangelogStar us on GitHub
首页指南EASReferenceLearn

Reference version

存档Expo SnackDiscord and forums新闻邮件

This documentation is available as Markdown for AI agents and LLMs. See the full Markdown index or append .md to any documentation URL.

选择器

与 @react-native-picker/picker 兼容的选择器。

Android
iOS
Web
Included in Expo Go

GitHub

npm

更新日志

Recommended version:
~58.0.1

一个 API 与 @react-native-picker/picker 兼容的 Picker 组件。在 iOS 上使用 SwiftUI 滚轮式 Picker，在 Android 上使用 Material 3 ExposedDropdownMenuBox，在 web 上使用原生 <select> 元素。

在底层，此组件封装了平台专属的 @expo/ui 原语：

如果需要更精细的控制，请直接使用这些原语。

一个显示 Java 的下拉字段一个显示 Java 的下拉字段

安装

Terminal
- npx expo install @expo/ui
- yarn expo install @expo/ui
- pnpm expo install @expo/ui
- bun expo install @expo/ui

If you are installing this in an existing React Native app, make sure to install expo in your project.

从 @react-native-picker/picker 迁移

  • 将导入语句从 import { Picker } from '@react-native-picker/picker' 更新为 import { Picker } from '@expo/ui/community/picker'。
  • 不支持 mode、prompt、dropdownIconColor、dropdownIconRippleColor、numberOfLines、selectionColor、itemStyle 和 accessibilityLabel 属性。
  • 在 Picker.Item 上，style 属性仅作用于 color、backgroundColor、fontFamily 和 fontSize。顶层的 color 和 fontFamily 属性仍受支持，可作为对应 style 值的别名。
  • Picker.Item 上的 enabled 仅适用于 Android。
  • ref 的 focus() 和 blur() 方法仅在 Android 上生效（打开/关闭下拉菜单）。在 iOS 上，滚轮选择器始终可见。

基本用法

PickerExample.tsx
import { useState } from 'react';
import { Text, useColorScheme, View } from 'react-native';
import { Picker } from '@expo/ui/community/picker';

export default function PickerExample() {
  const [language, setLanguage] = useState('java');
  const colorScheme = useColorScheme();

  return (
    <View>
      <Picker selectedValue={language} onValueChange={value => setLanguage(value)}>
        <Picker.Item label="Java" value="java" />
        <Picker.Item label="JavaScript" value="js" />
        <Picker.Item label="Objective C" value="objc" />
        <Picker.Item label="Swift" value="swift" />
      </Picker>
      <Text style={{ color: colorScheme === 'dark' ? '#FFFFFF' : '#000000' }}>
        Selected: {language}
      </Text>
    </View>
  );
}

单项样式与状态

为 Picker.Item 传入 style，即可控制每个选项的 color、backgroundColor、fontFamily 和 fontSize；传入 enabled={false} 可在 Android 上禁用指定选项。

在 iOS 上，fontFamily 接受 iOS 字体名称（例如 'Menlo'）；在 Android 上，则接受 Compose 通用字体系列（'monospace'、'serif'、'sansSerif'、'cursive'）或通过 expo-font 加载的字体。

StyledPickerExample.tsx
import { useState } from 'react';
import { Platform } from 'react-native';
import { Picker } from '@expo/ui/community/picker';

const monospace = Platform.select({ ios: 'Menlo', android: 'monospace' });
const serif = Platform.select({ ios: 'Georgia', android: 'serif' });

export default function StyledPickerExample() {
  const [language, setLanguage] = useState('java');

  return (
    <Picker selectedValue={language} onValueChange={value => setLanguage(value)}>
      <Picker.Item
        label="Java"
        value="java"
        style={{ color: '#e11d48', fontFamily: monospace, fontSize: 14 }}
      />
      <Picker.Item
        label="JavaScript"
        value="js"
        style={{ color: '#2563eb', fontFamily: serif, fontSize: 18 }}
        enabled={false}
      />
      <Picker.Item
        label="Objective C"
        value="objc"
        style={{ color: '#059669', fontFamily: monospace, fontSize: 16 }}
      />
      <Picker.Item
        label="Swift"
        value="swift"
        style={{ color: '#d97706', fontFamily: serif, fontSize: 30 }}
        enabled={false}
      />
    </Picker>
  );
}

命令式聚焦与失焦（Android）

使用 ref 在 Android 上以编程方式打开和关闭下拉菜单。在 iOS 上，这些方法无效，因为滚轮选择器始终可见。

RefPickerExample.tsx
import { useRef, useState } from 'react';
import { Button } from 'react-native';
import { Picker, type PickerRef } from '@expo/ui/community/picker';

export default function RefPickerExample() {
  const [language, setLanguage] = useState('java');
  const pickerRef = useRef<PickerRef>(null);

  return (
    <>
      <Button
        title="打开，并在 2 秒后关闭"
        onPress={() => {
          pickerRef.current?.focus();
          setTimeout(() => pickerRef.current?.blur(), 2000);
        }}
      />
      <Picker ref={pickerRef} selectedValue={language} onValueChange={setLanguage}>
        <Picker.Item label="Java" value="java" />
        <Picker.Item label="JavaScript" value="js" />
        <Picker.Item label="Objective C" value="objc" />
        <Picker.Item label="Swift" value="swift" />
      </Picker>
    </>
  );
}

API

import { Picker } from '@expo/ui/community/picker';

Components

Picker

Android
iOS
Web

Type: React.Element<PickerProps<T>>

A drop-in replacement for @react-native-picker/picker on web. Renders a native <select> element.

Props for the Picker component. Compatible with @react-native-picker/picker.

PickerProps

children

Android
iOS
Web
Optional • Type: ReactNode

Picker.Item children that define the available options.

enabled

Android
iOS
Web
Optional • Type: boolean

Whether the picker is enabled.

onValueChange

Android
iOS
Web
Optional • Type: (itemValue: T, itemIndex: number) => void

Callback when an item is selected. Called with (itemValue, itemIndex).

ref

Android
iOS
Web
Optional • Type: Ref<PickerRef>

Ref handle exposing focus() and blur() methods.

selectedValue

Android
iOS
Web
Optional • Type: T

The currently selected value. Must match the value of one of the Picker.Item children.

style

Android
iOS
Web
Optional • Type: StyleProp<ViewStyle>

Style applied to the picker container.

testID

Android
iOS
Web
Optional • Type: string

Test identifier.

Picker.Item

Android
iOS
Web

Type: React.Element<ComponentType<PickerItemProps>>

Props for the Picker.Item component. Compatible with @react-native-picker/picker.

PickerItemProps

color

Android
iOS
Web
Optional • Type: string

Text color for the item. Equivalent to setting color in the style prop.

enabled

Android
Optional • Type: boolean

Whether the item is enabled.

fontFamily

Android
iOS
Web
Optional • Type: string

Custom font family for the item. Equivalent to setting fontFamily in the style prop.

label

Android
iOS
Web
Optional • Type: string

Display text for the item.

style

Android
iOS
Web
Optional • Type: StyleProp<TextStyle>

Style applied to the item label. Only the following values take effect: color, backgroundColor, fontFamily, and fontSize. When also set via the top-level color or fontFamily props, values from style win.

testID

Android
iOS
Web
Optional • Type: string

Test identifier.

value

Android
iOS
Web
Optional • Type: T

Value passed to onValueChange when this item is selected.

Types

PickerItemValue

Android
iOS
Web

Literal type: union

Acceptable values are: string | number | null

PickerRef

Android
iOS
Web

Ref handle for the Picker component. Compatible with @react-native-picker/picker.

PropertyTypeDescription
blur() => void
Only for: 
Android

Programmatically closes the picker.

focus() => void
Only for: 
Android

Programmatically opens the picker.