文档
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:
~57.0.18

一个与 @react-native-picker/picker 兼容 API 的 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，并且在 Android 上使用 enabled={false} 可禁用特定项。

fontFamily 在 iOS 上接受 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.