For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/llms-full.txt, and this page is available as Markdown at https://ifhover.github.io/leaf-ui/components/date-range-picker.md.

DateRangePicker 日期区间选择器

选择起止日期、日期时间或时间区间。日期模式使用本地 Date 元组,纯时间模式使用字符串元组;选择单值使用 DatePicker。

基础用法

先选起点,再选终点,完整区间会提交并收起。日期模式支持逆序选择,结果按起止顺序排列;defaultValue 设置非受控初始区间。

basic.tsx
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerBasic() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="日期区间">
        <DateRangePicker />
      </FormField>
    </Form>
  );
}

示例

受控值与选择过程

onChange 接收提交后的区间和两个格式化字符串,清除时为 null 和 ['', '']。onCalendarChange 用于观察面板选择草稿和当前端点,不代表整个区间已经提交,也不覆盖文本输入或快捷区间的所有变化。受控重置由应用更新状态。

已提交:2026-10-05 ~ 2026-10-09最近面板操作:尚未调整
controlled.tsx
import { Button, type DateRange, DateRangePicker, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

const initialRange: DateRange = [new Date(2026, 9, 5), new Date(2026, 9, 9)];

function formatDate(date: Date | null) {
  if (!date) return '-';
  return [date.getFullYear(), date.getMonth() + 1, date.getDate()]
    .map((part, index) => (index === 0 ? String(part) : String(part).padStart(2, '0')))
    .join('-');
}

export function DateRangePickerControlled() {
  const [value, setValue] = useState<DateRange | null>(initialRange);
  const [committed, setCommitted] = useState('2026-10-05 ~ 2026-10-09');
  const [draft, setDraft] = useState('尚未调整');

  return (
    <Form
      layout="vertical"
      onSubmit={(event) => event.preventDefault()}
      onReset={() => {
        setValue(initialRange);
        setCommitted('2026-10-05 ~ 2026-10-09');
        setDraft('尚未调整');
      }}
    >
      <FormField label="受控日期区间">
        <DateRangePicker
          value={value}
          onChange={(next: DateRange | null, texts: readonly [string, string]) => {
            setValue(next);
            setCommitted(next ? texts.join(' ~ ') : '空值');
          }}
          onCalendarChange={(next, { position }) => {
            setDraft(`${position}: ${next.map(formatDate).join(' ~ ')}`);
          }}
        />
      </FormField>
      <Text tone="muted" role="status">
        已提交:{committed}
      </Text>
      <Text tone="muted" role="status">
        最近面板操作:{draft}
      </Text>
      <Button type="reset">重置</Button>
    </Form>
  );
}

选择粒度

通过 picker 选择年、季度、月或周区间,两个 Date 都表示对应周期的起点。周起点由 ConfigProvider 的 weekStartsOn 设置,默认星期一。

modes.tsx
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerModes() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="年份区间">
        <DateRangePicker picker="year" />
      </FormField>
      <FormField label="季度区间">
        <DateRangePicker picker="quarter" />
      </FormField>
      <FormField label="月份区间">
        <DateRangePicker picker="month" />
      </FormField>
      <FormField label="周区间">
        <DateRangePicker picker="week" />
      </FormField>
    </Form>
  );
}

日期时间区间

设置 picker="datetime",选择开始日期和时间,点击“下一步”进入结束端,再点击“确定”提交。日期时间面板需要结束值不早于开始值;defaultTime 只提供新选端点的初始时间,不是初始区间。

datetime.tsx
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerDateTime() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="预约时段">
        <DateRangePicker picker="datetime" defaultTime={['09:00', '18:00']} minuteStep={15} />
      </FormField>
    </Form>
  );
}

此模式默认 needConfirm={true},点击外部会放弃尚未确定的区间。其他日期模式默认选完终点即提交,也可以设置 needConfirm 要求确认;Escape 放弃当前编辑。清除或选择有效快捷区间会直接提交。

限制可选端点

minDate / maxDate 包含边界,disabledDate 可按 position 区分起点和终点。下面只允许十月内的端点,周日不能作为端点;区间中间仍可经过周日,需要整段可用性校验时由应用处理。

disabled-dates.tsx
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DisabledDates() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="十月交付周期">
        <DateRangePicker
          defaultValue={[new Date(2026, 9, 5), new Date(2026, 9, 9)]}
          minDate={new Date(2026, 9, 1)}
          maxDate={new Date(2026, 9, 31)}
          disabledDate={(date) => date.getDay() === 0}
        />
      </FormField>
    </Form>
  );
}

限制同时用于输入和面板,不会自动清除已有值。日期时间边界按完整时间戳比较,disabledTime 接收时间部分、端点位置和当前日期。inputReadOnly 只禁止输入,readOnly 才禁止修改。

开放端点

allowEmpty 可逐位允许端点为空。示例使用 [false, true] 保留必需的开始日期和可空的结束日期,值类型为从根入口导入的 OpenDateRange。至少需要一个非空端点;整个控件清空使用 null,不是 [null, null]。

起点:2026-10-05;终点:空
open-end.tsx
import { DateRangePicker, Form, FormField, type OpenDateRange, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function OpenEnd() {
  const [value, setValue] = useState<OpenDateRange | null>([new Date(2026, 9, 5), null]);
  const [texts, setTexts] = useState<readonly [string, string]>(['2026-10-05', '']);

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="进行中的项目周期">
        <DateRangePicker
          allowEmpty={[false, true]}
          value={value}
          onChange={(next: OpenDateRange | null, dateStrings: readonly [string, string]) => {
            setValue(next);
            setTexts(dateStrings);
          }}
        />
      </FormField>
      <Text tone="muted" role="status">
        起点:{texts[0] || '空'};终点:{texts[1] || '空'}
      </Text>
    </Form>
  );
}

允许的端点可通过面板底部操作清空,缺失端点的回调字符串为 ''。只有开始值时,再次打开面板会继续编辑结束端。

时间区间

picker="time" 的值和回调为 ['HH:mm', 'HH:mm'] 或 null,开启 showSeconds 时使用 HH:mm:ss。use12Hours 只改变显示,值仍使用 24 小时制;minTime / maxTime 对两个端点生效。纯时间不支持 allowEmpty。

当前值:09:00 ~ 18:00
time.tsx
import { DateRangePicker, Form, FormField, Text, type TimeRange } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DateRangePickerTime() {
  const [value, setValue] = useState<TimeRange | null>(['09:00', '18:00']);

  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="工作时段">
        <DateRangePicker picker="time" value={value} onChange={setValue} />
      </FormField>
      <Text tone="muted" role="status">
        当前值:{value ? value.join(' ~ ') : '空值'}
      </Text>
    </Form>
  );
}

跨越午夜

默认要求结束时间不早于开始时间。设置 allowOvernight 后可以提交 22:00 到次日 06:00,不交换两个端点。时间模式默认离开时提交有效调整,需要明确确认时设置 needConfirm。

overnight.tsx
import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

export function DateRangePickerOvernight() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="夜间值班">
        <DateRangePicker picker="time" allowOvernight defaultValue={['22:00', '06:00']} />
      </FormField>
    </Form>
  );
}

快捷区间

presets 提供常用区间,悬停或聚焦时预览,点击有效区间后立即提交并收起。value 可以是区间或同步返回区间的函数,不接收 Promise;函数可能多次求值,应保持无副作用。

presets.tsx
import { type DateRange, DateRangePicker, Form, FormField } from '@ifhover/leaf-ui';

function recentSevenDays(): DateRange {
  const end = new Date();
  end.setHours(0, 0, 0, 0);
  const start = new Date(end);
  start.setDate(start.getDate() - 6);
  return [start, end];
}

export function Presets() {
  return (
    <Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
      <FormField label="统计区间">
        <DateRangePicker presets={[{ label: '最近七天', value: recentSevenDays }]} />
      </FormField>
    </Form>
  );
}

显示格式与表单提交

format 改变显示及 onChange 的字符串元组,FormData 仍使用规范格式,以 start/end 连接。示例显示 DD/MM/YYYY,提交如 2026-10-05/2026-10-09;开放尾端为 2026-10-05/,全空为空字符串。非受控重置恢复 defaultValue。

FormData:尚未提交
form.tsx
import { Button, DateRangePicker, Form, FormField, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function DateRangePickerForm() {
  const [submitted, setSubmitted] = useState<string | null>(null);

  return (
    <Form
      layout="vertical"
      onSubmit={(event) => {
        event.preventDefault();
        setSubmitted(String(new FormData(event.currentTarget).get('reportingRange') ?? ''));
      }}
      onReset={() => setSubmitted(null)}
    >
      <FormField label="报表周期">
        <DateRangePicker
          name="reportingRange"
          format="DD/MM/YYYY"
          defaultValue={[new Date(2026, 9, 5), new Date(2026, 9, 9)]}
        />
      </FormField>
      <Space>
        <Button type="submit">提交</Button>
        <Button type="reset">重置</Button>
      </Space>
      <Text tone="muted" role="status">
        FormData:{submitted === null ? '尚未提交' : JSON.stringify(submitted)}
      </Text>
    </Form>
  );
}

周期与日期时间的规范格式及自定义 parse 见 DatePicker:显示格式与表单提交。日期是本地日历值,业务时区转换由应用处理。更多表单配置见 Form。

日期区间可完整粘贴以 ~ 或“至”分隔的两个值。Enter 提交有效输入,无效或未完成输入在离开整个控件时恢复已提交值,Escape 放弃编辑;更多分段输入方式见 DatePicker:输入与确认。

API

DateRangePicker API

主表覆盖日期与纯时间分支,参数并非所有模式都适用:allowEmpty、format、parse、presets、日期边界及日历配置属于日期分支;allowOvernight、minTime / maxTime 属于纯时间分支。

属性类型默认值说明
picker'year' | 'quarter' | 'month' | 'week' | 'date' | 'datetime' | 'time''date'选择日期、时间、日期时间、周、月、季度或年。
valuereadonly [Date, Date] | null | readonly [Date | null, Date | null] | readonly [string, string]—受控区间;日期模式使用 Date 元组,allowEmpty 允许空端点;纯时间使用 24 小时制字符串元组。整个空值为 null。
defaultValuereadonly [Date, Date] | null | readonly [Date | null, Date | null] | readonly [string, string]null非受控初始区间,类型由 picker 决定;表单重置时恢复。
onChange(((value: readonly [Date, Date] | null, dateStrings: readonly [string, string]) => void)) | (((value: readonly [Date | null, Date | null] | null, dateStrings: readonly [string, string]) => void)) | ((value: readonly [string, string] | null) => void)—提交整个区间时调用;日期模式返回 Date 元组和字符串元组,纯时间返回字符串元组,清空为 null。
onCalendarChange(range: readonly [Date | null, Date | null], info: { position: 'start' | 'end' }) => void—日期面板草稿、时间或端点清除变化时调用,不代表提交;文本输入和快捷项不保证触发。
allowEmptyfalse | true | readonly [boolean, boolean]false明确允许空的起止端点。
size'sm' | 'md' | 'lg''md'控件尺寸
status'error' | 'warning'—校验状态
disabledbooleanfalse禁用交互。
inputReadOnlyboolean—只禁止手动输入,仍可在面板中选择。
allowClearbooleantrue展示清除按钮
minDateDate—最早 / 最晚可选边界
maxDateDate—最早 / 最晚可选边界
disabledDate(date: Date, position: 'start' | 'end') => boolean—限制可选端点,不检查区间内的每一天;position 区分开始与结束。
minTimestring—最早可选时间(含边界),格式为 HH:mm 或 HH:mm:ss。
maxTimestring—最晚可选时间(含边界),格式为 HH:mm 或 HH:mm:ss。
disabledTime((parts: TimeParts, position: 'start' | 'end', date: Date) => boolean) | ((parts: TimeParts, position: 'start' | 'end') => boolean)—限制端点时间;日期时间模式还接收该端点的 Date。
allowOvernightbooleanfalse允许时间区间跨越午夜。
needConfirmbooleanpicker === "datetime"要求点击确定或按 Enter 提交;开启后失焦放弃草稿。
showSecondsbooleanfalse日期时间区间展示秒,关闭时秒为 0
use12Hoursbooleanfalse使用 12 小时制展示及上午、下午选项
minuteStepnumber1分钟段步进与分钟列间隔,保留已有的非步长值。
secondStepnumber1秒段步进与秒列间隔,保留已有的非步长值。
defaultTimereadonly [string, string]['00:00:00', '23:59:59']datetime 模式下新选开始、结束日期使用的时间,格式为 HH:mm[:ss]。
formatstring | ((date: Date) => string)—显示格式;日期支持 YYYY、MM、DD、HH、mm、ss、Q。
parse(text: string) => Date | null—自定义文本解析,失败时返回 null。
presetsreadonly DatePreset<readonly [Date | null, Date | null]>[]—快捷选项;value 可以动态计算。
panelValueDate—受控的日历显示日期。
onPanelChange(date: Date) => void—日历显示的周期改变时调用。
cellRender(date: Date) => ReactNode—自定义日历单元格内容。
openboolean—控制面板是否展开。
defaultOpenboolean—面板初始展开状态。
onOpenChange(open: boolean) => void—面板展开或收起
panelVariant'plain' | 'card''plain'面板外观;card 在柔和画布上以内嵌内容卡呈现。
namestring—原生 FormData 中的字段名。
formstring—关联的原生表单 ID。
requiredbooleanfalse要求整体值非空,复合控件只校验一次。
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—浮层相对触发控件的位置。
popupClassNamestring—浮层的自定义类名。
popupStyleCSSProperties—浮层的自定义样式。
popupRender(content: React.ReactNode) => React.ReactNode—包装或补充面板内容,保留传入的内容以维持交互。
getPopupContainer() => Element | DocumentFragment—返回浮层的挂载容器,也可返回 ShadowRoot。
refRef<HTMLInputElement>—输入框引用

原生 input 属性和 aria-* 传给输入框,className / style 作用于外层。共享浮层配置见 PopupOptions。

DateRange

非开放日期区间的类型是 readonly [Date, Date];设置 allowEmpty 时使用根入口导出的 OpenDateRange,即 readonly [Date | null, Date | null]。快捷项类型见 DatePreset。

属性类型默认值说明
0Date必填起始值,早于或等于终止值
1Date必填终止值

TimeRangePickerMode API

picker="time" 的属性;值类型 TimeRange 为 readonly [string, string]。

属性类型默认值说明
picker'time'必填纯时间区间模式,必须传 time。
valuereadonly [string, string] | null—受控的 24 小时制字符串元组;整个空值为 null。
defaultValuereadonly [string, string] | nullnull初始值;非受控模式支持表单重置。
onChange(value: readonly [string, string] | null) => void—提交时返回 24 小时制字符串元组;清空返回 null。
size'sm' | 'md' | 'lg''md'展示尺寸。
status'error' | 'warning'—显示错误或警告的校验外观,不执行校验。
allowClearbooleantrue展示清除操作。
inputReadOnlyboolean—只禁止手动输入,仍可在面板中选择。
minTimestring—最早可选时间(含边界),格式为 HH:mm 或 HH:mm:ss。
maxTimestring—最晚可选时间(含边界),格式为 HH:mm 或 HH:mm:ss。
disabledTime(parts: TimeParts, position: 'start' | 'end') => boolean—按业务规则禁用时间,输入和面板选择使用同一规则。
allowOvernightbooleanfalse允许时间区间跨越午夜。
needConfirmbooleanfalse要求点击确定或按 Enter 提交;开启后失焦放弃草稿。
showSecondsbooleanfalse显示并编辑秒,关闭时秒为 0。
use12Hoursbooleanfalse使用 12 小时制与上午 / 下午。
minuteStepnumber1分钟段步进与分钟列间隔,保留已有的非步长值。
secondStepnumber1秒段步进与秒列间隔,保留已有的非步长值。
openboolean—控制面板是否展开。
defaultOpenboolean—面板初始展开状态。
onOpenChange(open: boolean) => void—面板展开或收起时调用。
panelVariant'plain' | 'card''plain'面板外观;card 在柔和画布上以内嵌内容卡呈现。
popupPlacement'top' | 'top-start' | 'top-end' | 'bottom' | 'bottom-start' | 'bottom-end' | 'left' | 'left-start' | 'left-end' | 'right' | 'right-start' | 'right-end'—浮层相对触发控件的位置。
popupClassNamestring—浮层的自定义类名。
popupStyleCSSProperties—浮层的自定义样式。
popupRender(content: React.ReactNode) => React.ReactNode—包装或补充面板内容,保留传入的内容以维持交互。
getPopupContainer() => Element | DocumentFragment—返回浮层的挂载容器,也可返回 ShadowRoot。