用法

import { DatePicker, DateField, Calendar, Label } from '@heroui/react';

日期

mmddyyyy

组件结构

DatePicker 采用组合优先 API。显式组合 DateField 与 Calendar 以控制结构与样式。

import {Calendar, DateField, DatePicker, Label} from '@heroui/react';

export default () => (
  <DatePicker>
    <Label />
    <DateField.Group>
      <DateField.Input>
        {(segment) => <DateField.Segment segment={segment} />}
      </DateField.Input>
      <DateField.Suffix>
        <DatePicker.Trigger>
          <DatePicker.TriggerIndicator />
        </DatePicker.Trigger>
      </DateField.Suffix>
    </DateField.Group>
    <DatePicker.Popover>
      <Calendar aria-label="Choose date">
        <Calendar.Header>
          <Calendar.YearPickerTrigger>
            <Calendar.YearPickerTriggerHeading />
            <Calendar.YearPickerTriggerIndicator />
          </Calendar.YearPickerTrigger>
          <Calendar.NavButton slot="previous" />
          <Calendar.NavButton slot="next" />
        </Calendar.Header>
        <Calendar.Grid>
          <Calendar.GridHeader>
            {(day) => <Calendar.HeaderCell>{day}</Calendar.HeaderCell>}
          </Calendar.GridHeader>
          <Calendar.GridBody>{(date) => <Calendar.Cell date={date} />}</Calendar.GridBody>
        </Calendar.Grid>
      </Calendar>
    </DatePicker.Popover>
  </DatePicker>
)

示例

禁用

日期

8172026

该日期选择器已禁用。

受控组件

日期

8172026

当前值：2026-08-17

表单校验

预约日期

mmddyyyy

格式选项

使用 granularity、hourCycle、hideTimeZone、shouldForceLeadingZeros 等 props 控制 DatePicker 值的显示方式。

表单示例

自定义指示器

未提供 children 时，DatePicker.TriggerIndicator 渲染默认 IconCalendar。传入 children 可替换。

日期

mmddyyyy

通过传入自定义子元素替换默认日历图标。

渲染函数

日期

mmddyyyy

国际化日历

默认情况下，DatePicker 使用用户 locale 的日历系统显示日期。可用 I18nProvider 包裹并设置 Unicode 日历 locale 扩展覆盖。

以下示例展示印度日历系统：

活动日期

2651948शक

Note： 无论显示的 locale 如何，onChange 事件始终返回与 value 或 defaultValue 相同日历系统的日期（未提供 value 时为 Gregorian）。这确保应用逻辑在单一日历系统下一致运行，同时仍可按用户偏好格式显示日期。

完整支持的日历系统及其标识符列表请参阅：

自定义样式

Tailwind CSS

活动日期

mmddyyyy

全局 CSS

使用 @layer components 自定义 DatePicker 基础类。

@layer components {
  .date-picker {
    @apply inline-flex flex-col gap-1;
  }

  .date-picker__trigger {
    @apply inline-flex items-center justify-between;
  }

  .date-picker__trigger-indicator {
    @apply text-muted;
  }

  .date-picker__popover {
    @apply min-w-[var(--trigger-width)] p-0;
  }
}

样式参考

HeroUI 遵循 BEM 命名以便复用自定义。

CSS 类

DatePicker 在 packages/styles/components/date-picker.css 中使用以下类：

.date-picker - 根包裹层
.date-picker__trigger - 打开 popover 的触发器部分
.date-picker__trigger-indicator - 默认/自定义指示器 slot
.date-picker__popover - Popover 内容包裹层

交互状态

DatePicker 支持 React Aria data 属性与伪状态：

Open：触发器上 [data-open="true"]
Disabled：触发器上 [data-disabled="true"] 或 [aria-disabled="true"]
Focus visible：触发器上 :focus-visible 或 [data-focus-visible="true"]
Hover：触发器上 :hover 或 [data-hovered="true"]

API 参考

DatePicker

DatePicker 继承 React Aria DatePicker 的所有 props。

Prop	类型	默认值	描述
`value`	`DateValue \| null`	-	受控选中日期值
`defaultValue`	`DateValue \| null`	-	非受控模式下的默认选中值
`onChange`	`(value: DateValue \| null) => void`	-	选中日期变化时调用
`isOpen`	`boolean`	-	受控 popover 打开状态
`defaultOpen`	`boolean`	`false`	初始 popover 打开状态
`onOpenChange`	`(isOpen: boolean) => void`	-	popover 打开状态变化时调用
`isDisabled`	`boolean`	`false`	禁用日期选择与触发器交互
`isInvalid`	`boolean`	-	标记字段为无效以显示校验状态
`minValue`	`DateValue`	-	最小可选日期
`maxValue`	`DateValue`	-	最大可选日期
`name`	`string`	-	HTML 表单提交时使用的 name
`children`	`ReactNode \| (values: DatePickerRenderProps) => ReactNode`	-	组合内容或 render 函数
`render`	`DOMRenderFunction<keyof React.JSX.IntrinsicElements, DatePickerRenderProps>`	-	使用自定义 render 函数覆盖默认 DOM 元素

Composition Parts

Component	Description
`DatePicker.Root`	根 date picker 容器与状态所有者
`DatePicker.Trigger`	触发按钮，通常渲染在 `DateField.Suffix` 内
`DatePicker.TriggerIndicator`	带默认日历图标的指示器 slot
`DatePicker.Popover`	`Calendar` 内容的 Popover 包裹层

@internationalized/date — 所有日期组件使用的日期类型（CalendarDate、CalendarDateTime、ZonedDateTime）与工具
I18nProvider — 为子树覆盖 locale
useLocale — 读取当前 locale 与布局方向