DatePicker 日期选择DatePicker · DateRangePicker

在表单里选一个日期或一段日期，平时只占一行。DatePicker 可以直接打字，也可以点开日历；DateRangePicker 是一个按钮，点开后在日历上点两次。日期离今天很远（比如生日）时，打字比翻日历快。

基本用法

点输入框或右侧按钮都会打开日历。可以直接输入 2026-10-13、2026/10/13 或 2026.10.13，失焦或按 Enter 时生效；输入不合法或不可选的日期会退回原值。边打字日历边翻：只要已经能确定一个月份（比如打到 2026-11），日历就翻到那个月；打出完整、可选的日期时，日历里直接选中它，回车或失焦后才算选定。从日历里点选后自动收起。

出发日期

格式：年-月-日

限制、格式与尺寸

min / max / isDateDisabled 同时约束日历和手动输入。format / parse 成对自定义显示和解析。

状态

受控用法

onChange 的参数是 Date，清空输入框时是 null。

value：2026-10-20

日期范围

DateRangePicker 是一个显示起止日期的按钮。第一次点定起点，第二次点定终点后自动收起。它不支持直接打字。

受控

还没有选择

非受控与自定义文案

表单提交

DatePicker 的 name、DateRangePicker 的 startName / endName 都通过隐藏 input 以 yyyy-MM-dd 提交，和显示格式无关。

API

DatePicker

属性	类型	默认值	说明
`value`	`Date \| null`	—	选中的日期（受控）。
`defaultValue`	`Date \| null`	`null`	初始日期（非受控）。
`onChange`	`(date: Date \| null) => void`	—	日期变化时触发；清空时为 null。
`format`	`(date: Date) => string`	`formatISODate`	日期 → 输入框里显示的文字。
`parse`	`(text: string) => Date \| null`	`parseISODate`	输入的文字 → 日期；不合法返回 null。
`min / max`	`Date`	—	可选的最早 / 最晚日期（含）。
`isDateDisabled`	`(date: Date) => boolean`	—	返回 true 的日期不可选。
`weekStartsOn / locale / today`	`—`	—	传给里面的日历，见 Calendar。
`size`	`'sm' \| 'md' \| 'lg'`	`'md'`	尺寸。
`invalid`	`boolean`	—	标成校验未通过。
`placeholder`	`string`	`'年-月-日'`	占位文字。
`name / form`	`string`	—	隐藏 input 的字段名，以 yyyy-MM-dd 提交。
`open / defaultOpen / onOpenChange`	`boolean / boolean / (open) => void`	—	日历浮层的开关状态。
`placement`	`Placement`	`'bottom-start'`	日历相对输入框的位置。
`…rest`	`InputHTMLAttributes`	—	ref、className、style 落在外框上，其余原生属性（id、disabled、readOnly、aria-*）落在 <input> 上。

DateRangePicker

属性	类型	默认值	说明
`value`	`{ start: Date \| null; end: Date \| null }`	—	选中的范围（受控）。
`defaultValue`	`DateRange`	`{ start: null, end: null }`	初始范围（非受控）。
`onChange`	`(range: DateRange) => void`	—	每次点选都触发。
`placeholder`	`ReactNode`	`'开始日期 – 结束日期'`	没选时显示的文字。
`separator`	`string`	`' – '`	起止之间的连接符。
`startName / endName`	`string`	—	起 / 止两个隐藏 input 的字段名。
`format / min / max / isDateDisabled / size / invalid / open… / placement`	`—`	—	同 DatePicker。
`…rest`	`ButtonHTMLAttributes`	—	ref 和其余原生属性落在触发按钮上。