DateTimePicker

一个用于选择日期和时间的 Jetpack Compose 日期时间选择器组件。

Android

Included in Expo Go

Recommended version:

~57.0.22

Expo UI DateTimePicker 与官方的 Jetpack Compose 日期选择器和时间选择器 API 相匹配，支持日期、时间和组合选择。

🌐 Expo UI DateTimePicker matches the official Jetpack Compose Date Picker and Time Picker APIs and supports date, time, and combined selection.

注意：日期变体会渲染 Material 的日历网格和输入字段，两者内部都是水平滚动的。父元素 Host 必须在水平方向上提供有限宽度，使用 matchContents={{ vertical: true }} 搭配 style={{ width: '100%' }}（或任何有限宽度）。详情请参见 Host 参考中的匹配内容。

Material 3 date picker showing a selected date in a calendar grid

安装

🌐 Installation

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.

用法

🌐 Usage

日期选择器

🌐 Date picker

DatePickerExample.tsx

import { useState } from 'react';
import { Host, DateTimePicker } from '@expo/ui/jetpack-compose';

export default function DatePickerExample() {
  const [selectedDate, setSelectedDate] = useState(new Date());

  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <DateTimePicker
        onDateSelected={date => {
          setSelectedDate(date);
        }}
        displayedComponents="date"
        initialDate={selectedDate.toISOString()}
        variant="picker"
      />
    </Host>
  );
}

时间选择器

🌐 Time picker

TimePickerExample.tsx

import { useState } from 'react';
import { Host, DateTimePicker } from '@expo/ui/jetpack-compose';

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

  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <DateTimePicker
        onDateSelected={date => {
          setSelectedDate(date);
        }}
        displayedComponents="hourAndMinute"
        initialDate={selectedDate.toISOString()}
        variant="picker"
      />
    </Host>
  );
}

输入变体

🌐 Input variant

使用 variant="input" 将选择器显示为文本输入字段，而不是默认的选择器界面。

🌐 Use variant="input" to display the picker as a text input field instead of the default picker UI.

InputVariantExample.tsx

import { useState } from 'react';
import { Host, DateTimePicker } from '@expo/ui/jetpack-compose';

export default function InputVariantExample() {
  const [selectedDate, setSelectedDate] = useState(new Date());

  return (
    <Host
      matchContents={{ vertical: true }}
      style={{ width: '100%' }}>
      <DateTimePicker
        onDateSelected={date => {
          setSelectedDate(date);
        }}
        displayedComponents="date"
        initialDate={selectedDate.toISOString()}
        variant="input"
      />
    </Host>
  );
}

应用接口

🌐 API

import { DateTimePicker } from '@expo/ui/jetpack-compose';

Components

`DatePickerDialog`

Android

Type: React.Element<DatePickerDialogProps>

DatePickerDialogProps

`color`

Android

Optional • Type: ColorValue

`confirmButtonLabel`

Android

Optional • Type: string

`dismissButtonLabel`

Android

Optional • Type: string

`elementColors`

Android

Optional • Type: DatePickerElementColors & TimePickerElementColors

`initialDate`

Android

Optional • Literal type: union

Acceptable values are: string | null

`onDateSelected`

Android

Optional • Type: (date: Date) => void

`onDismissRequest`

Android

Type: () => void

`selectableDates`

Android

Optional • Type:

{
  end: Date, 
  start: Date
}

`showVariantToggle`

Android

Optional • Type: boolean

`variant`

Android

Optional • Type: AndroidVariant

`DateTimePicker`

Android

Type: React.Element<DateTimePickerProps>

Renders an inline DateTimePicker component.

DateTimePickerProps

`color`

Android

Optional • Type: ColorValue

The tint color to use on the picker elements. When elementColors is not provided, this color is applied to a subset of picker elements (selected day, title, headline, today border for date picker; selector, selected time segment, clock dial for time picker).

`displayedComponents`

Android

Optional • Type: DisplayedComponents • Default: 'date'

The components that the picker should display. On Android, you can have a picker that selects just the date or just the time. dateAndTime is only available on iOS and will result in a date picker on Android. On iOS, you can have a picker that selects both date and time.

`elementColors`

Android

Optional • Type: DatePickerElementColors & TimePickerElementColors

Fine-grained color overrides for individual picker elements. When provided, these take precedence over the color prop. Date picker color keys are used when displayedComponents is 'date' or 'dateAndTime'. Time picker color keys are used when displayedComponents is 'hourAndMinute'. Unset values fall back to Material 3 theme defaults.

`initialDate`

Android

Optional • Literal type: union

The initial date to display on the picker.

Acceptable values are: string | null

`is24Hour`

Android

Optional • Type: boolean • Default: true

Determines what format the clock should be displayed in on Android.

`modifiers`

Android

Optional • Type: ModifierConfig[]

Modifiers for the component.

`onDateSelected`

Android

Optional • Type: (date: Date) => void

Callback function that is called when a date is selected.

`selectableDates`

Android

Optional • Type:

{
  end: Date, 
  start: Date
}

Constrains which dates can be selected. Mirrors the native Compose selectableDates parameter. start is the earliest selectable date, end is the latest.

`showVariantToggle`

Android

Optional • Type: boolean • Default: true

Show to button to toggle between variants on Android.

`variant`

Android

Optional • Type: AndroidVariant • Default: 'picker'

The variant of the picker, which determines its appearance and behavior.

`TimePickerDialog`

Android

Type: React.Element<TimePickerDialogProps>

TimePickerDialogProps

`color`

Android

Optional • Type: ColorValue

`confirmButtonLabel`

Android

Optional • Type: string

`dismissButtonLabel`

Android

Optional • Type: string

`elementColors`

Android

Optional • Type: DatePickerElementColors & TimePickerElementColors

`initialDate`

Android

Optional • Literal type: union

Acceptable values are: string | null

`is24Hour`

Android

Optional • Type: boolean

`onDateSelected`

Android

Optional • Type: (date: Date) => void

`onDismissRequest`

Android

Type: () => void

Types

`AndroidVariant`

Android

Literal type: string

Acceptable values are: 'picker' | 'input'

`DatePickerElementColors`

Android

Color overrides for the Material 3 DatePicker component. All properties are optional — unset values use Material 3 theme defaults.

Property	Type	Description
containerColor(optional)	`ColorValue`	The background color of the date picker.
currentYearContentColor(optional)	`ColorValue`	The color used for the current year content.
dayContentColor(optional)	`ColorValue`	The color used for day content (number text).
dayInSelectionRangeContainerColor(optional)	`ColorValue`	The container color for days within a date range selection.
dayInSelectionRangeContentColor(optional)	`ColorValue`	The content color for days within a date range selection.
disabledDayContentColor(optional)	`ColorValue`	The color used for disabled day content.
disabledSelectedDayContainerColor(optional)	`ColorValue`	The color used for a disabled selected day container.
disabledSelectedDayContentColor(optional)	`ColorValue`	The color used for a disabled selected day content.
disabledSelectedYearContainerColor(optional)	`ColorValue`	The color used for a disabled selected year container.
disabledSelectedYearContentColor(optional)	`ColorValue`	The color used for a disabled selected year content.
disabledYearContentColor(optional)	`ColorValue`	The color used for disabled year item content.
dividerColor(optional)	`ColorValue`	The color used for divider lines.
headlineContentColor(optional)	`ColorValue`	The color used for the date picker's headline.
navigationContentColor(optional)	`ColorValue`	The color used for navigation arrows and year selection menu button.
selectedDayContainerColor(optional)	`ColorValue`	The color used for the selected day container/background circle.
selectedDayContentColor(optional)	`ColorValue`	The color used for selected day content.
selectedYearContainerColor(optional)	`ColorValue`	The color used for the selected year container/background.
selectedYearContentColor(optional)	`ColorValue`	The color used for the selected year content.
subheadContentColor(optional)	`ColorValue`	The color used for the month and year subhead labels.
titleContentColor(optional)	`ColorValue`	The color used for the date picker's title.
todayContentColor(optional)	`ColorValue`	The color used for today's date text.
todayDateBorderColor(optional)	`ColorValue`	The color used for today's date border.
weekdayContentColor(optional)	`ColorValue`	The color used for the weekday letters (Mon, Tue, etc.).
yearContentColor(optional)	`ColorValue`	The color used for year item content.

`DisplayedComponents`

Android

Literal type: string

Acceptable values are: 'date' | 'hourAndMinute' | 'dateAndTime'

`TimePickerElementColors`

Android

Color overrides for the Material 3 TimePicker component. All properties are optional — unset values use Material 3 theme defaults.

Property	Type	Description
clockDialColor(optional)	`ColorValue`	The background color of the clock dial.
clockDialSelectedContentColor(optional)	`ColorValue`	The color of clock dial numbers when selected or overlapping the selector.
clockDialUnselectedContentColor(optional)	`ColorValue`	The color of clock dial numbers when unselected.
containerColor(optional)	`ColorValue`	The container/background color of the time picker.
periodSelectorBorderColor(optional)	`ColorValue`	The border color of the AM/PM period selector.
periodSelectorSelectedContainerColor(optional)	`ColorValue`	The background color of the selected AM/PM period.
periodSelectorSelectedContentColor(optional)	`ColorValue`	The text color of the selected AM/PM period.
periodSelectorUnselectedContainerColor(optional)	`ColorValue`	The background color of the unselected AM/PM period.
periodSelectorUnselectedContentColor(optional)	`ColorValue`	The text color of the unselected AM/PM period.
selectorColor(optional)	`ColorValue`	The color of the clock dial selector (hand).
timeSelectorSelectedContainerColor(optional)	`ColorValue`	The background color of the selected hour/minute segment.
timeSelectorSelectedContentColor(optional)	`ColorValue`	The text color of the selected hour/minute segment.
timeSelectorUnselectedContainerColor(optional)	`ColorValue`	The background color of the unselected hour/minute segment.
timeSelectorUnselectedContentColor(optional)	`ColorValue`	The text color of the unselected hour/minute segment.