DateRangePicker 日期区间选择器
选择起止日期、日期时间或时间区间。日期模式使用本地 Date 元组,纯时间模式使用字符串元组;选择单值使用 DatePicker。
基础用法
先选起点,再选终点,完整区间会提交并收起。日期模式支持逆序选择,结果按起止顺序排列;defaultValue 设置非受控初始区间。
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 用于观察面板选择草稿和当前端点,不代表整个区间已经提交,也不覆盖文本输入或快捷区间的所有变化。受控重置由应用更新状态。
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 设置,默认星期一。
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 只提供新选端点的初始时间,不是初始区间。
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 区分起点和终点。下面只允许十月内的端点,周日不能作为端点;区间中间仍可经过周日,需要整段可用性校验时由应用处理。
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]。
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。
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。
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;函数可能多次求值,应保持无副作用。
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。
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 属于纯时间分支。
原生 input 属性和 aria-* 传给输入框,className / style 作用于外层。共享浮层配置见 PopupOptions。
DateRange
非开放日期区间的类型是 readonly [Date, Date];设置 allowEmpty 时使用根入口导出的 OpenDateRange,即 readonly [Date | null, Date | null]。快捷项类型见 DatePreset。
TimeRangePickerMode API
picker="time" 的属性;值类型 TimeRange 为 readonly [string, string]。