DateRangePicker 日期范围选择器

基于 React Aria DateRangePicker，通过 DateField 与 RangeCalendar 组合的可组合日期范围选择器

用法

1import { DateField, DateRangePicker, Label, RangeCalendar } from '@lenso/ui';

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2
3/** Adapted from the pinned HeroUI v3.2.6 basic.json. Copyright NextUI Inc. Apache-2.0. Local RAC label and StyleX replace source Label and utility classes. */4import { DateField, DateRangePicker, RangeCalendar } from "@lenso/ui";5import * as stylex from "@stylexjs/stylex";6
7const styles = stylex.create({ field: { width: 320 } });8export function Basic() {9  return (10    <DateRangePicker xstyle={styles.field} endName="endDate" startName="startDate">11      <DateRangePicker.Label>Trip dates</DateRangePicker.Label>12      <DateField.Group fullWidth>13        <DateField.Input slot="start">14          {(segment) => <DateField.Segment segment={segment} />}15        </DateField.Input>16        <DateRangePicker.RangeSeparator />17        <DateField.Input slot="end">18          {(segment) => <DateField.Segment segment={segment} />}19        </DateField.Input>20        <DateField.Suffix>21          <DateRangePicker.Trigger>22            <DateRangePicker.TriggerIndicator />23          </DateRangePicker.Trigger>24        </DateField.Suffix>25      </DateField.Group>26      <DateRangePicker.Popover>27        <RangeCalendar aria-label="Trip dates">28          <RangeCalendar.Header>29            <RangeCalendar.YearPickerTrigger>30              <RangeCalendar.YearPickerTriggerHeading />31              <RangeCalendar.YearPickerTriggerIndicator />32            </RangeCalendar.YearPickerTrigger>33            <RangeCalendar.NavButton slot="previous" />34            <RangeCalendar.NavButton slot="next" />35          </RangeCalendar.Header>36          <RangeCalendar.Grid>37            <RangeCalendar.GridHeader>38              {(day) => <RangeCalendar.HeaderCell>{day}</RangeCalendar.HeaderCell>}39            </RangeCalendar.GridHeader>40            <RangeCalendar.GridBody>41              {(date) => <RangeCalendar.Cell date={date} />}42            </RangeCalendar.GridBody>43          </RangeCalendar.Grid>44          <RangeCalendar.YearPickerGrid>45            <RangeCalendar.YearPickerGridBody>46              {({ year }) => <RangeCalendar.YearPickerCell year={year} />}47            </RangeCalendar.YearPickerGridBody>48          </RangeCalendar.YearPickerGrid>49        </RangeCalendar>50      </DateRangePicker.Popover>51    </DateRangePicker>52  );53}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

组件结构

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

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

示例

禁用

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { Disabled } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

受控组件

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { Controlled } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

表单校验

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { WithValidation } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

格式选项

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

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** Adapted from HeroUI v3.2.6 format-options.json. Copyright NextUI Inc. Apache-2.0. */3import { DateRangePicker, Separator, TimeField } from "@lenso/ui";4import {5  DateFormatter,6  getLocalTimeZone,7  parseDate,8  parseZonedDateTime,9  type DateValue,10} from "@internationalized/date";11import { useLocale } from "react-aria-components/I18nProvider";12import { useMemo, useState } from "react";13import * as stylex from "@stylexjs/stylex";14import {15  FormatControls,16  formatStyles,17  type Granularity,18  type HourCycle,19} from "../date-picker/format-controls";20import { PickerCalendar, RangeInput } from "./parts";21
22export function FormatOptions() {23  const [granularity, setGranularity] = useState<Granularity>("minute");24  const [hourCycle, setHourCycle] = useState<HourCycle>(12);25  const [hideTimeZone, setHideTimeZone] = useState(false);26  const [shouldForceLeadingZeros, setShouldForceLeadingZeros] = useState(false);27  const { locale } = useLocale();28  const dateFormatter = new DateFormatter(locale, {29    day: "numeric",30    month: "short",31    year: "numeric",32  });33  const defaultValue = useMemo<{ start: DateValue; end: DateValue }>(34    () =>35      granularity === "day"36        ? { start: parseDate("2025-02-03"), end: parseDate("2025-02-10") }37        : {38            start: parseZonedDateTime(`2026-02-03T08:45:00[${getLocalTimeZone()}]`),39            end: parseZonedDateTime(`2026-02-10T18:45:00[${getLocalTimeZone()}]`),40          },41    [granularity],42  );43  const timeGranularity = granularity !== "day" ? granularity : undefined;44  return (45    <div {...stylex.props(formatStyles.rangeStack)}>46      <DateRangePicker47        key={granularity}48        xstyle={formatStyles.rangeField}49        defaultValue={defaultValue}50        startName="startDate"51        endName="endDate"52        granularity={granularity}53        hourCycle={hourCycle}54        hideTimeZone={hideTimeZone}55        shouldForceLeadingZeros={shouldForceLeadingZeros}56      >57        {({ state }) => (58          <>59            <DateRangePicker.Label>Date range</DateRangePicker.Label>60            <RangeInput container />61            <DateRangePicker.Popover xstyle={formatStyles.rangePopover}>62              <PickerCalendar fill />63              {timeGranularity && (64                <div {...stylex.props(formatStyles.times)}>65                  <div {...stylex.props(formatStyles.timeRow)}>66                    <span {...stylex.props(formatStyles.label)}>Start Time</span>67                    <TimeField68                      aria-label="Start Time"69                      granularity={timeGranularity}70                      hourCycle={hourCycle}71                      hideTimeZone={hideTimeZone}72                      name="startTime"73                      shouldForceLeadingZeros={shouldForceLeadingZeros}74                      value={state.timeRange?.start ?? null}75                      onChange={(value) => state.setTime("start", value)}76                    >77                      <TimeField.Group variant="secondary">78                        <TimeField.Input>79                          {(segment) => <TimeField.Segment segment={segment} />}80                        </TimeField.Input>81                      </TimeField.Group>82                    </TimeField>83                  </div>84                  <div {...stylex.props(formatStyles.timeRow)}>85                    <span {...stylex.props(formatStyles.label)}>End Time</span>86                    <TimeField87                      aria-label="End Time"88                      granularity={timeGranularity}89                      hourCycle={hourCycle}90                      hideTimeZone={hideTimeZone}91                      name="endTime"92                      shouldForceLeadingZeros={shouldForceLeadingZeros}93                      value={state.timeRange?.end ?? null}94                      onChange={(value) => state.setTime("end", value)}95                    >96                      <TimeField.Group variant="secondary">97                        <TimeField.Input>98                          {(segment) => <TimeField.Segment segment={segment} />}99                        </TimeField.Input>100                      </TimeField.Group>101                    </TimeField>102                  </div>103                </div>104              )}105              <span {...stylex.props(formatStyles.selected)}>106                Selected:{" "}107                {state.value?.start && state.value.end108                  ? dateFormatter.formatRange(109                      state.value.start.toDate(getLocalTimeZone()),110                      state.value.end.toDate(getLocalTimeZone()),111                    )112                  : "No date selected"}113              </span>114            </DateRangePicker.Popover>115          </>116        )}117      </DateRangePicker>118      <Separator xstyle={formatStyles.separator} />119      <span {...stylex.props(formatStyles.heading)}>Format Options</span>120      <FormatControls121        range122        {...{123          granularity,124          setGranularity,125          hourCycle,126          setHourCycle,127          hideTimeZone,128          setHideTimeZone,129          shouldForceLeadingZeros,130          setShouldForceLeadingZeros,131        }}132      />133    </div>134  );135}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

表单示例

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { FormExample } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

自定义指示器

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

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { WithCustomIndicator } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

渲染函数

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** Adapted from HeroUI v3.2.6 render-function.json. Copyright NextUI Inc. Apache-2.0. RAC 1.21 owns the native DOM render contract. */3import { DateRangePicker } from "@lenso/ui";4import { PickerCalendar, RangeInput, styles } from "./parts";5
6export function RenderFunction() {7  return (8    <DateRangePicker9      xstyle={styles.field}10      startName="startDate"11      endName="endDate"12      render={(props) => <div data-custom="foo" {...props} />}13    >14      <DateRangePicker.Label>Trip dates</DateRangePicker.Label>15      <RangeInput />16      <DateRangePicker.Popover>17        <PickerCalendar />18      </DateRangePicker.Popover>19    </DateRangePicker>20  );21}

Local adaptation source above. Derived from HeroUI v3.2.6 source.

国际化日历

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

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

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { InternationalCalendar } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

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

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

自定义样式

Tailwind CSS

此预览复用英文版适配，不代表中文源示例已完成本地实现。

1"use client";2/** HeroUI v3.2.6 adapted example. Copyright NextUI Inc. Apache-2.0. */3export { CustomStyles } from "./scenarios";

Local adaptation source above. Derived from HeroUI v3.2.6 source.

全局 CSS

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

1@layer components {2  .date-range-picker {3    @apply inline-flex flex-col gap-1;4  }5
6  .date-range-picker__trigger {7    @apply inline-flex items-center justify-between;8  }9
10  .date-range-picker__trigger-indicator {11    @apply text-muted;12  }13
14  .date-range-picker__range-separator {15    @apply px-2 text-default;16  }17
18  .date-range-picker__popover {19    @apply min-w-[var(--trigger-width)] p-0;20  }21}

样式参考

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 参考