文档
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.

DateTimePicker

与 @react-native-community/datetimepicker 兼容的日期和时间选择器。

Android
iOS
Included in Expo Go

GitHub

npm

更新日志

Recommended version:
~58.0.1

一个 API 与 @react-native-community/datetimepicker 兼容的 DateTimePicker 组件。它在 Android 上使用 Jetpack Compose，在 iOS 上使用 SwiftUI，默认提供现代的 Material 3 和 SwiftUI 外观（社区模块在 Android 上默认使用较旧的外观）。

DateTimePicker 组件完全采用声明式方式。使用 presentation 属性，可在视图层级中直接渲染 'inline' 选择器，或在 Android 上以 'dialog' 形式显示。没有 Android 命令式 API（DateTimePickerAndroid.open()）。

在底层，此组件封装了平台专用的 @expo/ui 基础组件：

如果需要更细粒度的控制（自定义修饰符、样式或布局），请直接使用这些基础组件。

一个 Material 3 日期选择器对话框一个 Material 3 日期选择器对话框

安装

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-community/datetimepicker 迁移

  • 将导入语句从 import DateTimePicker from '@react-native-community/datetimepicker' 更新为 import DateTimePicker from '@expo/ui/community/datetime-picker'。
  • 没有命令式的 DateTimePickerAndroid.open() API。渲染组件，并改用 presentation="dialog"。
  • 不支持 minuteInterval、textColor、firstDayOfWeek、neutralButton、onNeutralButtonPress、fullscreen、title 和 startOnYearSelection 属性。
  • 使用 timeZoneName（IANA 名称）代替 timeZoneOffsetInMinutes。
  • 不支持 countdown 模式。
  • 无需使用 onError 属性。

基本用法

DateTimePickerExample.tsx
import { useState } from 'react';
import DateTimePicker from '@expo/ui/community/datetime-picker';

export default function DateTimePickerExample() {
  const [date, setDate] = useState(new Date());

  return (
    <DateTimePicker
      value={date}
      onValueChange={(event, selectedDate) => {
        setDate(selectedDate);
      }}
      mode="date"
    />
  );
}

时间选择器

TimePickerExample.tsx
import { useState } from 'react';
import DateTimePicker from '@expo/ui/community/datetime-picker';

export default function TimePickerExample() {
  const [date, setDate] = useState(new Date());

  return (
    <DateTimePicker
      value={date}
      onValueChange={(event, selectedDate) => {
        setDate(selectedDate);
      }}
      mode="time"
    />
  );
}

设置日期限制

ConstrainedDatePickerExample.tsx
import { useState } from 'react';
import DateTimePicker from '@expo/ui/community/datetime-picker';

const today = new Date();
const thirtyDaysFromNow = new Date(today.getTime() + 30 * 24 * 60 * 60 * 1000);

export default function ConstrainedDatePickerExample() {
  const [date, setDate] = useState(new Date());

  return (
    <DateTimePicker
      value={date}
      onValueChange={(event, selectedDate) => {
        setDate(selectedDate);
      }}
      mode="date"
      minimumDate={today}
      maximumDate={thirtyDaysFromNow}
    />
  );
}

对话框显示方式

在 Android 上，可以使用 presentation="dialog" 将选择器显示为模态对话框。组件挂载时，对话框会打开。在响应 onValueChange 或 onDismiss 时卸载组件。在 iOS 上，此属性会被忽略，选择器始终以内嵌方式渲染。

AndroidDialogExample.tsx
import { useState } from 'react';
import { Button, View } from 'react-native';
import DateTimePicker from '@expo/ui/community/datetime-picker';

export default function AndroidDialogExample() {
  const [date, setDate] = useState(new Date());
  const [show, setShow] = useState(false);

  return (
    <View>
      <Button title="Pick a date" onPress={() => setShow(true)} />
      {show && (
        <DateTimePicker
          value={date}
          onValueChange={(event, selectedDate) => {
            setShow(false);
            setDate(selectedDate);
          }}
          onDismiss={() => {
            setShow(false);
          }}
          mode="date"
          presentation="dialog"
        />
      )}
    </View>
  );
}

API

import DateTimePicker from '@expo/ui/community/datetime-picker';

Component

DateTimePicker

Android
iOS

Type: React.Element<DateTimePickerProps>

DateTimePickerProps

accentColor

Android
iOS
Optional • Type: string

Accent/tint color applied to the picker. Maps to color on Android and tint on iOS.

disabled

iOS
Optional • Type: boolean

Whether the picker is disabled.

display

Android
iOS
Optional • Literal type: string • Default: 'default'

Display style. Android supports 'default' | 'spinner' — 'spinner' shows a text input rather than a scroll wheel (Material 3 does not have a wheel-style picker). iOS supports 'default' | 'spinner' | 'compact' | 'inline'.

Acceptable values are: 'default' | 'compact' | 'inline' | 'spinner' | 'calendar' | 'clock'

is24Hour

Android
Optional • Type: boolean

Use 24-hour format.

locale

iOS
Optional • Type: string

Locale identifier (e.g. 'en_US', 'fr_FR') for the picker display.

maximumDate

Android
iOS
Optional • Type: Date

The latest selectable date.

minimumDate

Android
iOS
Optional • Type: Date

The earliest selectable date.

mode

Android
iOS
Optional • Literal type: string • Default: 'date'

The picker mode.

Acceptable values are: 'time' | 'date' | 'datetime'

negativeButton

Android
Optional • Type: { label: string }

Set the negative (cancel) button label.

Deprecated: Use onValueChange and onDismiss instead.

onChange

Android
iOS
Optional • Type: (event: DateTimePickerEvent, date?: Date) => void

Called when the user changes the date/time or dismisses the picker. The event type is encoded in event.type. If the new specific listeners are provided, they take precedence.

onDismiss

Android
Optional • Type: () => void

Called when the picker is dismissed without selecting a value.

onValueChange

Android
iOS
Optional • Type: (event: DateTimePickerChangeEvent, date: Date) => void

Called when the user selects a date or time.

positiveButton

Android
Optional • Type: { label: string }

Set the positive (confirm) button label.

presentation

Android
Optional • Literal type: string • Default: 'dialog'

How the picker is presented.

  • 'inline' renders the picker directly in the view hierarchy.
  • 'dialog' shows a modal dialog that opens on mount. Fires onValueChange on confirmation, onDismiss on cancel. The caller should unmount the component in response.

On iOS this prop is accepted but ignored (always inline). On Android the default is 'dialog'.

Acceptable values are: 'dialog' | 'inline'

testID

Android
iOS
Optional • Type: string

A test ID forwarded to the native view. Note: on Android dialog presentation, the test ID is not forwarded.

themeVariant

iOS
Optional • Literal type: string

Force a specific color scheme on the picker.

Acceptable values are: 'light' | 'dark'

timeZoneName

iOS
Optional • Type: string

IANA time zone name (e.g. 'America/New_York') for the picker display.

value

Android
iOS
Type: Date

The current date value (controlled).

Inherited props

Types

DateTimePickerChangeEvent

Android
iOS
PropertyTypeDescription
nativeEvent{ timestamp: number, utcOffset: number }
-

Deprecated: Used with the deprecated onChange prop.

DateTimePickerEvent

Android
iOS
PropertyTypeDescription
nativeEvent{ timestamp: number, utcOffset: number }
-
type'set' | 'dismissed'

'set' when the user selects a date. 'dismissed' when the user cancels an Android dialog picker. iOS never fires 'dismissed'.