用法

import { DateField, DateRangePicker, Label, RangeCalendar } from '@heroui/react';

出行日期

mmddyyyy

组件结构

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

import {DateField, DateRangePicker, Label, RangeCalendar} from '@heroui/react';

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

示例

禁用

出行日期

8172026

8212026

该日期范围选择器已禁用。

受控组件

出行日期

8172026

8212026

当前值：2026-08-17 至 2026-08-21

表单校验

预订时段

mmddyyyy

格式选项

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

表单示例

自定义指示器

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

出行日期

mmddyyyy

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

渲染函数

出行日期

mmddyyyy

国际化日历

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

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

出行日期

2651948शक

261948शक

Note： 无论显示的 locale 如何，onChange 事件始终返回与 value 或 defaultValue 相同日历系统的日期（未提供 value 时为 Gregorian）。

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

自定义样式

Tailwind CSS

入住日期

mmddyyyy

全局 CSS

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

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

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

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

  .date-range-picker__range-separator {
    @apply px-2 text-default;
  }

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

样式参考

HeroUI 遵循 BEM 方法论，确保组件变体与状态可复用且易于自定义。

CSS 类

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

.date-range-picker - 根包裹层
.date-range-picker__trigger - 打开 popover 的触发器部分
.date-range-picker__trigger-indicator - 默认/自定义指示器 slot
.date-range-picker__range-separator - 开始与结束日期输入之间的分隔符
.date-range-picker__popover - Popover 内容包裹层

交互状态

DateRangePicker 支持 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 参考

DateRangePicker

DateRangePicker 继承 React Aria DateRangePicker 的所有 props。

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

Composition Parts

Component	Description
`DateRangePicker.Root`	根 date range picker 容器与状态所有者
`DateRangePicker.Trigger`	触发按钮，通常渲染在 `DateField.Suffix` 内
`DateRangePicker.TriggerIndicator`	带默认日历图标的指示器 slot
`DateRangePicker.RangeSeparator`	开始与结束日期输入之间的分隔符部分
`DateRangePicker.Popover`	`RangeCalendar` 内容的 Popover 包裹层

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