DateRangePicker

DateRangePicker 从 HeroUI v2 到 v3 的迁移指南。

完整的 API 参考、样式指南与高级示例请参阅 v3 DateRangePicker 文档。本指南只关注从 HeroUI v2 的迁移。

结构变化

在 v2 中，DateRangePicker 是单一自包含组件，通过 prop 配置标签、输入、日历与时间字段等：

1import { DateRangePicker } from "@lenso/ui";2
3export default function App() {4  return (5    <DateRangePicker label="Trip dates" />6  );7}

在 v3 中，DateRangePicker 采用“组合优先”的 API，需要你显式组合 DateField 与 RangeCalendar：

1import { DateField, DateRangePicker, Label, RangeCalendar } from "@lenso/ui";2
3export default function App() {4  return (5    <DateRangePicker>6      <Label>Trip dates</Label>7      <DateField.Group>8        <DateField.InputContainer>9          <DateField.Input slot="start">10            {(segment) => <DateField.Segment segment={segment} />}11          </DateField.Input>12          <DateRangePicker.RangeSeparator />13          <DateField.Input slot="end">14            {(segment) => <DateField.Segment segment={segment} />}15          </DateField.Input>16        </DateField.InputContainer>17        <DateField.Suffix>18          <DateRangePicker.Trigger>19            <DateRangePicker.TriggerIndicator />20          </DateRangePicker.Trigger>21        </DateField.Suffix>22      </DateField.Group>23      <DateRangePicker.Popover>24        <RangeCalendar aria-label="Choose trip dates">25          <RangeCalendar.Header>26            <RangeCalendar.YearPickerTrigger>27              <RangeCalendar.YearPickerTriggerHeading />28              <RangeCalendar.YearPickerTriggerIndicator />29            </RangeCalendar.YearPickerTrigger>30            <RangeCalendar.NavButton slot="previous" />31            <RangeCalendar.NavButton slot="next" />32          </RangeCalendar.Header>33          <RangeCalendar.Grid>34            <RangeCalendar.GridHeader>35              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}36            </RangeCalendar.GridHeader>37            <RangeCalendar.GridBody>38              {(date) => <RangeCalendar.Cell date={date} />}39            </RangeCalendar.GridBody>40          </RangeCalendar.Grid>41        </RangeCalendar>42      </DateRangePicker.Popover>43    </DateRangePicker>44  );45}

主要变化

1. 组件结构

v2： 单一 DateRangePicker，两个输入、分隔符、日历、标签、popover 等主要由内部 prop 处理。
v3： 组合式 API：将 DateRangePicker、DateField、RangeCalendar 与 Label 等组合在一起；两个 DateField.Input 分别使用 slot="start" 与 slot="end" 表示范围输入。

2. 组合结构说明

v3 组件	说明
`DateRangePicker`	根容器与状态持有者
`DateRangePicker.Trigger`	打开日历 popover 的按钮
`DateRangePicker.TriggerIndicator`	日历图标（默认）或自定义指示器
`DateRangePicker.RangeSeparator`	开始/结束日期输入之间的分隔符（默认 `" - "`）
`DateRangePicker.Popover`	包裹范围日历的 popover
`DateField.Group`	输入组外层
`DateField.InputContainer`	开始/结束输入与分隔符容器
`DateField.Input slot="start"`	开始日期的分段输入
`DateField.Input slot="end"`	结束日期的分段输入
`DateField.Segment`	单个日期片段（月/日/年等）
`DateField.Suffix`	触发按钮的后缀插槽
`RangeCalendar`	完整范围日历（参见 RangeCalendar 迁移）
`Label`	外部标签组件

3. Prop 变更

v2 prop	v3 对应	说明
`value`	`value`	相同
`defaultValue`	`defaultValue`	相同
`onChange`	`onChange`	相同
`minValue`	`minValue`	相同
`maxValue`	`maxValue`	相同
`isDisabled`	`isDisabled`	相同
`isReadOnly`	`isReadOnly`	相同
`isRequired`	`isRequired`	相同
`isInvalid`	`isInvalid`	相同
`isOpen`	`isOpen`	相同
`defaultOpen`	`defaultOpen`	相同
`onOpenChange`	`onOpenChange`	相同
`granularity`	`granularity`	相同
`hourCycle`	`hourCycle`	相同
`hideTimeZone`	`hideTimeZone`	相同
`shouldForceLeadingZeros`	`shouldForceLeadingZeros`	相同
`allowsNonContiguousRanges`	—	直接在 `RangeCalendar` 上设置
`pageBehavior`	—	直接在 `RangeCalendar` 上设置
`label`	—	使用 `Label` 组件
`description`	—	使用 `Description` 组件
`errorMessage`	—	使用 `FieldError` 组件
`variant`	—	使用 `DateField.Group` 的 `variant` prop，或 Tailwind CSS
`color`	—	已移除（请用 Tailwind CSS）
`size`	—	已移除（请用 Tailwind CSS）
`radius`	—	已移除（请用 Tailwind CSS）
`labelPlacement`	—	用 Tailwind CSS 控制布局
`selectorIcon`	—	将 children 传给 `DateRangePicker.TriggerIndicator`
`selectorButtonPlacement`	—	通过 `DateField.Prefix` 或 `DateField.Suffix` 组合触发器位置
`visibleMonths`	—	使用 `RangeCalendar` 的 `visibleDuration` prop
`showMonthAndYearPickers`	—	使用 `RangeCalendar.YearPickerTrigger` 与 `RangeCalendar.YearPickerGrid`
`calendarProps`	—	直接将 prop 传给 `RangeCalendar`
`popoverProps`	—	直接将 prop 传给 `DateRangePicker.Popover`
`selectorButtonProps`	—	直接将 prop 传给 `DateRangePicker.Trigger`
`timeInputProps`	—	时间输入需单独组合实现
`calendarWidth`	—	已移除（请用 Tailwind CSS）
`validate`	—	在外部处理校验
`placeholderValue`	`placeholderValue`	相同
`autoFocus`	`autoFocus`	相同
`disableAnimation`	—	已移除
`classNames`	—	在各子组件上使用 `className`

迁移示例

基础 DateRangePicker

1import { DateRangePicker } from "@lenso/ui";2
3<DateRangePicker label="Trip dates" />

受控状态

1import { useState } from "react";2import { DateRangePicker } from "@lenso/ui";3import { parseDate } from "@internationalized/date";4
5const [value, setValue] = useState({6  start: parseDate("2024-03-01"),7  end: parseDate("2024-03-14"),8});9
10<DateRangePicker11  label="Trip dates"12  value={value}13  onChange={setValue}14/>

描述与错误信息

1<DateRangePicker2  label="Trip dates"3  description="Select your travel period"4  errorMessage="End date must be after start date"5  isInvalid={isInvalid}6/>

自定义选择器图标

1import { Icon } from "@iconify/react";2
3<DateRangePicker4  label="Trip dates"5  selectorIcon={<Icon icon="gravity-ui:calendar" />}6/>

多月份显示与年份选择器

1<DateRangePicker2  label="Trip dates"3  visibleMonths={2}4  showMonthAndYearPickers5/>

样式相关变化

v2：`classNames` prop

1<DateRangePicker2  classNames={{3    base: "custom-base",4    label: "custom-label",5    selectorButton: "custom-trigger",6    selectorIcon: "custom-icon",7    separator: "custom-separator",8    popoverContent: "custom-popover",9    calendar: "custom-calendar",10  }}11/>

v3：直接使用 `className`

1<DateRangePicker className="custom-base">2  <Label className="custom-label">Trip dates</Label>3  <DateField.Group>4    <DateField.InputContainer>5      <DateField.Input slot="start">6        {(segment) => <DateField.Segment segment={segment} />}7      </DateField.Input>8      <DateRangePicker.RangeSeparator className="custom-separator" />9      <DateField.Input slot="end">10        {(segment) => <DateField.Segment segment={segment} />}11      </DateField.Input>12    </DateField.InputContainer>13    <DateField.Suffix>14      <DateRangePicker.Trigger className="custom-trigger">15        <DateRangePicker.TriggerIndicator className="custom-icon" />16      </DateRangePicker.Trigger>17    </DateField.Suffix>18  </DateField.Group>19  <DateRangePicker.Popover className="custom-popover">20    <RangeCalendar aria-label="Choose trip dates" className="custom-calendar">21      {/* RangeCalendar compound components */}22    </RangeCalendar>23  </DateRangePicker.Popover>24</DateRangePicker>

组件结构（Anatomy）

v3 的 DateRangePicker 结构如下：

1DateRangePicker (Root)2  ├── Label3  ├── DateField.Group4  │   ├── DateField.InputContainer5  │   │   ├── DateField.Input slot="start"6  │   │   │   └── DateField.Segment（每个 segment 的渲染 prop）7  │   │   ├── DateRangePicker.RangeSeparator8  │   │   └── DateField.Input slot="end"9  │   │       └── DateField.Segment（每个 segment 的渲染 prop）10  │   └── DateField.Suffix11  │       └── DateRangePicker.Trigger12  │           └── DateRangePicker.TriggerIndicator13  ├── Description (optional)14  ├── FieldError (optional)15  └── DateRangePicker.Popover16      └── RangeCalendar (参见 RangeCalendar 迁移指南)

总结

组件结构：由单一组件 → 组合 DateRangePicker、DateField、RangeCalendar 与 Label 等。
双输入：内置起止输入 → 两个 DateField.Input，分别使用 slot="start" 与 slot="end"。
分隔符：内置分隔 → DateRangePicker.RangeSeparator。
标签：label prop → Label 组件。
描述/错误：prop → Description 与 FieldError 组件。
日历：内置日历 → 在 DateRangePicker.Popover 内组合 RangeCalendar 及其子组件。
选择器图标：selectorIcon prop → 将 children 传给 DateRangePicker.TriggerIndicator。
年份选择器：showMonthAndYearPickers prop → 使用 RangeCalendar.YearPickerTrigger 与 RangeCalendar.YearPickerGrid。
样式类 prop 移除：variant、color、size、radius → 使用 Tailwind CSS，或 DateField.Group 的 variant。
classNames 移除：在各复合子组件上使用 className。