DatePicker 日期选择器
选择日期、时间或日期时间。日期模式使用本地 Date,picker="time" 使用时间字符串;选择区间请使用 DateRangePicker。
基础用法
通过 defaultValue 设置初始日期,选择日期后自动收起。空值使用 null。
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DatePickerBasic() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="默认日期">
<DatePicker defaultValue={new Date(2026, 9, 15)} />
</FormField>
</Form>
);
}
示例
受控值与清除
通过 value 与 onChange 管理选中值。日期模式回调同时提供 Date 和格式化字符串,清除时为 null 和 ''。受控组件的表单重置需要同步重置应用状态。
import { Button, DatePicker, Form, FormField, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
const initialDate = new Date(2026, 9, 15);
export function DatePickerControlled() {
const [value, setValue] = useState<Date | null>(initialDate);
const [dateString, setDateString] = useState('2026-10-15');
return (
<Form
layout="vertical"
onSubmit={(event) => event.preventDefault()}
onReset={() => {
setValue(initialDate);
setDateString('2026-10-15');
}}
>
<FormField label="截止日期">
<DatePicker
value={value}
onChange={(next, text) => {
setValue(next);
setDateString(text);
}}
/>
</FormField>
<Text tone="muted" role="status">
回调文本:{dateString || '空字符串'}
</Text>
<Button type="reset">重置</Button>
</Form>
);
}
交互状态
disabled 禁用整个控件,readOnly 保留只读值且不能修改。inputReadOnly 只禁止键盘输入,仍可从面板选择。
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DatePickerStates() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="禁用">
<DatePicker defaultValue={new Date(2026, 9, 15)} disabled />
</FormField>
<FormField label="只读">
<DatePicker defaultValue={new Date(2026, 9, 15)} readOnly />
</FormField>
<FormField label="仅面板选择">
<DatePicker defaultValue={new Date(2026, 9, 15)} inputReadOnly />
</FormField>
</Form>
);
}
选择粒度
通过 picker 选择年份、季度、月份或周;返回的 Date 为对应周期的起始日期。周起点由 ConfigProvider 的 weekStartsOn 设置,默认星期一。
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';
export function ExtensionDemo() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
{(['year', 'quarter', 'month', 'week'] as const).map((picker) => (
<FormField
key={picker}
label={{ year: '年份', quarter: '季度', month: '月份', week: '周' }[picker]}
>
<DatePicker picker={picker} />
</FormField>
))}
</Form>
);
}
限制可选日期
minDate / maxDate 包含边界,disabledDate 返回 true 时禁用该日期。下面只允许选择十月的工作日。限制同时用于输入和面板选择,但不会自动清除已有值;业务规则变化后由应用检查原值。日期时间模式按完整时间戳比较边界。
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DisabledDates() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="十月工作日">
<DatePicker
defaultValue={new Date(2026, 9, 15)}
minDate={new Date(2026, 9, 1)}
maxDate={new Date(2026, 9, 31)}
disabledDate={(date) => date.getDay() === 0 || date.getDay() === 6}
/>
</FormField>
</Form>
);
}
日期与时间
设置 picker="datetime" 后选择日期和时间,再点击“确定”提交。此模式默认 needConfirm={true},点击外部会放弃尚未确定的日期和时间。
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DatePickerDateTime() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="预约时间">
<DatePicker picker="datetime" defaultValue={new Date(2026, 9, 3, 14, 30)} />
</FormField>
</Form>
);
}
仅选择时间
picker="time" 的值和 onChange 参数为 24 小时制 HH:mm 字符串,清除时为 null;开启 showSeconds 后使用 HH:mm:ss。用 minTime / maxTime 限制时间,或通过 disabledTime 排除业务禁用时间。
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DatePickerTime() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="默认时间">
<DatePicker picker="time" defaultValue="09:30" />
</FormField>
</Form>
);
}
12 小时制与秒
use12Hours 只改变显示方式,值仍为 24 小时制。minuteStep / secondStep 控制步进,已有的非步长值仍可保留;不显示秒时提交值的秒为 0。
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';
export function DatePickerTwelveHours() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="12 小时制">
<DatePicker picker="time" use12Hours defaultValue="14:30" />
</FormField>
<FormField label="精确到秒">
<DatePicker picker="time" use12Hours showSeconds secondStep={10} defaultValue="00:05:30" />
</FormField>
</Form>
);
}
显示格式与表单提交
format 改变显示和 onChange 的字符串参数,不改变 FormData 的规范值。下面显示 DD/MM/YYYY,提交 YYYY-MM-DD;清除后提交空字符串,非受控字段重置后恢复 defaultValue。
import { Button, DatePicker, Form, FormField, Space, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';
export function Format() {
const [submitted, setSubmitted] = useState<string | null>(null);
return (
<Form
layout="vertical"
onSubmit={(event) => {
event.preventDefault();
setSubmitted(String(new FormData(event.currentTarget).get('meetingDate') ?? ''));
}}
onReset={() => setSubmitted(null)}
>
<FormField label="会议日期">
<DatePicker name="meetingDate" format="DD/MM/YYYY" defaultValue={new Date(2026, 9, 15)} />
</FormField>
<Space>
<Button type="submit">提交</Button>
<Button type="reset">重置</Button>
</Space>
<Text tone="muted" role="status">
FormData:{submitted === null ? '尚未提交' : JSON.stringify(submitted)}
</Text>
</Form>
);
}
各模式的规范值为 date: YYYY-MM-DD、year: YYYY、quarter: YYYY-QN、month: YYYY-MM、week: YYYY-Www,日期时间为 YYYY-MM-DD HH:mm[:ss]。日期使用本地时间,业务时区转换由应用处理,避免把 UTC 日期字符串当成本地日历值。
字符串格式支持 YYYY、MM、DD、HH、mm、ss、Q,用方括号转义文字,例如 YYYY-[Q]Q。函数格式化若不能由默认解析识别,应同时提供 parse,失败时返回 null。更多表单配置见 Form。
快捷日期
通过 presets 提供常用日期。快捷值可以是 Date 或同步返回 Date 的函数,不接收 Promise;点击有效快捷项会立即提交并收起,不等待“确定”。今天按钮可通过 showToday / todayText 配置,自定义底部内容使用 renderExtraFooter,其中的业务操作由应用处理。
import { DatePicker, Form, FormField } from '@ifhover/leaf-ui';
function tomorrow() {
const date = new Date();
date.setDate(date.getDate() + 1);
date.setHours(0, 0, 0, 0);
return date;
}
export function DatePickerPresets() {
return (
<Form layout="vertical" onSubmit={(event) => event.preventDefault()}>
<FormField label="交付日期">
<DatePicker presets={[{ label: '明天', value: tomorrow }]} />
</FormField>
</Form>
);
}
输入与确认
可直接输入或粘贴完整值,点击或用左右键选择日期分段。Enter 提交有效输入,Escape 放弃当前编辑;无效或未完成输入在焦点离开整个选择器时恢复已提交值。Alt + ↓ 可将焦点移入面板。
日期和纯时间模式默认不要求确认,有效改动可在离开时提交。设置 needConfirm 后,未确认的编辑在离开时放弃;清除和快捷日期仍会直接提交。
API
DatePicker API
主表包含不同 picker 模式的参数:format、parse、presets、minDate / maxDate 和日历展示配置用于日期模式;minTime / maxTime 用于纯时间模式。disabledTime 在日期时间模式额外接收当前 Date。
其余原生 input 属性和 aria-* 传给输入框,className / style 作用于外层。共享浮层配置见 PopupOptions。
SingleDatePicker API
日期模式的值与回调类型;通用参数见主表。
DatePreset
presets 使用的快捷项类型。T 在单值中为 Date,在区间中为日期元组;函数应同步、无副作用,并允许多次求值。
TimePickerMode API
picker="time" 的属性与回调,值始终使用 24 小时制字符串。
TimeParts
disabledTime 接收的时间部分。