> Leaf UI 0.6.0 · Package: @ifhover/leaf-ui · Source: b30c3d3a8fa9c5e15d0d0522cebfbd33f60c6b06 > Browser documentation: https://ifhover.github.io/leaf-ui/v/0.6.0/components/date-picker.html > For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/v/0.6.0/llms-full.txt. # DatePicker 日期选择器 用于选择日期。 需要同时选择时间时，使用 [DateTimePicker](https://ifhover.github.io/leaf-ui/v/0.6.0/components/date-time-picker.md)；需要起止区间时，使用 [DateRangePicker](https://ifhover.github.io/leaf-ui/v/0.6.0/components/date-range-picker.md)。 ## 基础选择 点击控件打开日历，选择日期后收起。`defaultValue` 设置初始日期，`disabled` 禁用整个控件。 选择日期 默认日期 禁用日期 basic.tsx 复制代码 ```tsx lineNumbers file="../../src/examples/date-picker/basic.tsx" import { DatePicker, Form, FormField } from '@ifhover/leaf-ui'; export function DatePickerBasic() { return (
); } ``` 展开代码 ## 受控与日期限制 通过 `minDate` / `maxDate` 限定可选日期，边界当天也可以选择。`onChange` 同时提供 Date 对象和本地日期字符串。 十月的日期 可选 10 月 5–25 日，当前值：2026-10-15 必填日期 · 错误 controlled.tsx 复制代码 ```tsx lineNumbers file="../../src/examples/date-picker/controlled.tsx" import { DatePicker, Form, FormField, Text } from '@ifhover/leaf-ui'; import { useState } from 'react'; export function DatePickerControlled() { const [date, setDate] = useState(new Date(2026, 9, 15)); const [dateString, setDateString] = useState('2026-10-15'); return (
{ setDate(next); setDateString(text); }} /> 可选 10 月 5–25 日，当前值：{dateString || '未选择'}
); } ``` 展开代码 ## 快捷日期 通过 todayText 修改今天按钮文字，renderExtraFooter 增加快捷操作，showToday=false 隐藏今天按钮。 自定义快捷日期 footer.tsx 复制代码 ```tsx lineNumbers file="../../src/examples/date-picker/footer.tsx" import { Button, DatePicker, Flex, Text } from '@ifhover/leaf-ui'; import { useState } from 'react'; export function DatePickerFooter() { const [value, setValue] = useState(null); const tomorrow = () => { const next = new Date(); next.setDate(next.getDate() + 1); next.setHours(0, 0, 0, 0); setValue(next); }; return ( 自定义快捷日期 明天 } /> ); } ``` 展开代码 ## 扩展用法 年份季度月份周 extensions.tsx 复制代码 ```tsx lineNumbers file="../../src/examples/date-picker/extensions.tsx" import { DatePicker, Space } from '@ifhover/leaf-ui'; export function ExtensionDemo() { return ( {(['year', 'quarter', 'month', 'week'] as const).map((picker) => ( ))} ); } ``` 展开代码 ## 格式、预设与多日期 自定义显示格式与工作日限制 选择最多三个日期 capabilities.tsx 复制代码 ```tsx lineNumbers file="../../src/examples/date-picker/capabilities.tsx" import { DatePicker, Flex, Space, Text } from '@ifhover/leaf-ui'; export function Capabilities() { return ( {'自定义显示格式与工作日限制'} date.getDay() === 0 || date.getDay() === 6} presets={[{ label: '今天', value: () => new Date() }]} /> {'选择最多三个日期'} ); } ``` 展开代码 ## 显示格式与提交值 `format` 改变显示文字和 `onChange` 的字符串参数；FormData 保持日期或周期的稳定序列化格式。方括号可以转义固定文字，例如 `YYYY-[Q]Q`。使用函数格式化时，请同时提供 `parse`。Date 表示本地日历值，业务时区在应用的数据边界完成转换。周起点通过 ConfigProvider 的 `weekStartsOn` 设置。 ## DatePicker API | 属性 | 类型 | 默认值 | 说明 | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------- | | `popupPlacement` | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | — | 浮层相对触发控件的位置。 | | `popupClassName` | `string` | — | 浮层的自定义类名。 | | `popupStyle` | `CSSProperties` | — | 浮层的自定义样式。 | | `popupRender` | `(content: React.ReactNode) => React.ReactNode` | — | 包装或补充面板内容，保留传入的内容以维持交互。 | | `getPopupContainer` | `() => Element \| DocumentFragment` | — | 返回浮层的挂载容器，也可返回 ShadowRoot。 | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 选择器尺寸 | | `status` | `'error' \| 'warning'` | — | 校验状态 | | `allowClear` | `boolean` | `true` | 展示清除按钮 | | `inputReadOnly` | `boolean` | — | 只禁止手动输入，仍可在面板中选择。 | | `open` | `boolean` | — | 控制面板是否展开。 | | `defaultOpen` | `boolean` | — | 面板初始展开状态。 | | `multiple` | `false \| true` | — | 启用多选；value 和回调的类型随之变化。 | | `value` | `Date \| null \| readonly Date[]` | `null` | 受控日期 / 非受控初始日期 | | `defaultValue` | `Date \| null \| readonly Date[]` | `null` | 受控日期 / 非受控初始日期 | | `minDate` | `Date` | — | 最早 / 最晚可选日期，按本地年月日比较 | | `maxDate` | `Date` | — | 最早 / 最晚可选日期，按本地年月日比较 | | `picker` | `'date' \| 'year' \| 'quarter' \| 'month' \| 'week'` | `'date'` | 选择日期、年、季度、月或周 | | `disabledDate` | `(date: Date) => boolean` | — | 限制可选择日期 | | `showToday` | `boolean` | `true` | 展示今天快捷按钮 | | `todayText` | `ReactNode` | 语言默认值 | 自定义今天按钮文字 | | `renderExtraFooter` | `ReactNode` | — | 额外底部内容，可放快捷操作 | | `onChange` | `((value: Date \| null, dateString: string) => void) \| ((value: Date[], dateStrings: string[]) => void)` | — | 日期变更；清除时返回 null 和空字符串 | | `onOpenChange` | `(open: boolean) => void` | — | 日历展开或收起 | | `format` | `string \| ((date: Date) => string)` | — | 显示格式；日期支持 YYYY、MM、DD、HH、mm、ss、Q。 | | `parse` | `(text: string) => Date \| null` | — | 自定义文本解析，失败时返回 null。 | | `presets` | `readonly `[`DatePreset`](#datepreset)`[]` | — | 快捷选项；value 可以动态计算。 | | `panelValue` | `Date` | — | 受控的日历显示日期。 | | `onPanelChange` | `(date: Date) => void` | — | 日历显示的周期改变时调用。 | | `cellRender` | `(date: Date) => ReactNode` | — | 自定义日历单元格内容。 | | `maxCount` | `number` | — | 最多可选的数量。 | | `disabled` | `boolean` | `false` | 禁用交互。 | | `name` | `string` | — | 原生 FormData 中的字段名。 | | `form` | `string` | — | 关联的原生表单 ID。 | | `required` | `boolean` | `false` | 要求整体值非空，复合控件只校验一次。 | | `ref` | `Ref` | — | 输入框引用 | 其余原生 input 属性和 `aria-*` 透传至输入框；`className` / `style` 作用于外层容器。 ## 类型 可导入 [`DatePickerProps`](#datepicker-api) 定义组件属性，或单独使用尺寸、校验状态类型： ```ts import type { DatePickerProps, ControlSize, ControlStatus } from '@ifhover/leaf-ui'; ``` ## 日期与表单 传入有效 Date 对象，且 `minDate` 不晚于 `maxDate`。组件按本地日期处理：可用 `new Date(2026, 9, 15)` 表示 2026 年 10 月 15 日，月份从 0 开始。选择结果为本地当天零点；避免用 UTC 字符串转换代替本地日期构造。 设置 `name` 后，FormData 提交当前 picker 模式的字符串，清除后为空字符串。非受控组件支持表单 reset，受控组件需同步重置自己的状态。年、季度、月、周模式的 Date 值为对应周期的起始日期，日历从默认周一开始，可通过 ConfigProvider 的 weekStartsOn 修改。 ## 键盘与主题 点击控件打开日历，↓ 移入日历。方向键按日或周移动，Home / End 移至本周首尾，PageUp / PageDown 切换月份，Enter 选择。Tab 依次访问月切换与日期；离开面板时回到表单中的后续控件，Escape 收起并聚焦输入框。 为控件提供 label 或 aria-label。日历沿用控件所在容器的主题色、圆角和浅深色变量；点击外部或移走焦点会收起。 可以直接输入 `YYYY-MM-DD`，按 Enter 或移走焦点提交。无效日期和超出 minDate / maxDate 的值不会提交。点击日历顶部的月份、年份可切换选择面板；默认展示“今天”快捷按钮，可通过 `showToday`、`todayText` 与 `renderExtraFooter` 定制。 点击输入框保留输入焦点；↓ 将焦点移入日历，Escape 放弃未完成输入。 各模式格式：`date → YYYY-MM-DD`、`year → YYYY`、`quarter → YYYY-QN`、`month → YYYY-MM`、`week → YYYY-Www`。显示、手动输入、onChange 字符串和 FormData 使用相同格式。 ## SingleDatePicker API | 属性 | 类型 | 默认值 | 说明 | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------- | | `popupPlacement` | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | — | 浮层相对触发控件的位置。 | | `popupClassName` | `string` | — | 浮层的自定义类名。 | | `popupStyle` | `CSSProperties` | — | 浮层的自定义样式。 | | `popupRender` | `(content: React.ReactNode) => React.ReactNode` | — | 包装或补充面板内容，保留传入的内容以维持交互。 | | `getPopupContainer` | `() => Element \| DocumentFragment` | — | 返回浮层的挂载容器，也可返回 ShadowRoot。 | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 展示尺寸。 | | `status` | `'error' \| 'warning'` | — | 设置 status。 | | `allowClear` | `boolean` | `true` | 展示清除操作。 | | `inputReadOnly` | `boolean` | — | 只禁止手动输入，仍可在面板中选择。 | | `open` | `boolean` | — | 控制面板是否展开。 | | `defaultOpen` | `boolean` | — | 面板初始展开状态。 | | `multiple` | `false` | — | 启用多选；value 和回调的类型随之变化。 | | `value` | `Date \| null` | — | 受控值。 | | `defaultValue` | `Date \| null` | `null` | 初始值；非受控模式支持表单重置。 | | `minDate` | `Date` | — | 最早可选的日期（含边界）。 | | `maxDate` | `Date` | — | 最晚可选的日期（含边界）。 | | `picker` | `'date' \| 'year' \| 'quarter' \| 'month' \| 'week'` | `'date'` | 设置 picker。 | | `disabledDate` | `(date: Date) => boolean` | — | 按业务规则禁用日期。 | | `showToday` | `boolean` | `true` | 设置 showToday。 | | `todayText` | `ReactNode` | — | 设置 todayText。 | | `renderExtraFooter` | `ReactNode` | — | 设置 renderExtraFooter。 | | `onChange` | `(value: Date \| null, dateString: string) => void` | — | 值发生变化时调用。 | | `onOpenChange` | `(open: boolean) => void` | — | 面板展开或收起时调用。 | | `format` | `string \| ((date: Date) => string)` | — | 显示格式；日期支持 YYYY、MM、DD、HH、mm、ss、Q。 | | `parse` | `(text: string) => Date \| null` | — | 自定义文本解析，失败时返回 null。 | | `presets` | `readonly `[`DatePreset`](#datepreset)`[]` | — | 快捷选项；value 可以动态计算。 | | `panelValue` | `Date` | — | 受控的日历显示日期。 | | `onPanelChange` | `(date: Date) => void` | — | 日历显示的周期改变时调用。 | | `cellRender` | `(date: Date) => ReactNode` | — | 自定义日历单元格内容。 | ## MultipleDatePicker API | 属性 | 类型 | 默认值 | 说明 | | ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------- | | `popupPlacement` | `'top' \| 'top-start' \| 'top-end' \| 'bottom' \| 'bottom-start' \| 'bottom-end' \| 'left' \| 'left-start' \| 'left-end' \| 'right' \| 'right-start' \| 'right-end'` | — | 浮层相对触发控件的位置。 | | `popupClassName` | `string` | — | 浮层的自定义类名。 | | `popupStyle` | `CSSProperties` | — | 浮层的自定义样式。 | | `popupRender` | `(content: React.ReactNode) => React.ReactNode` | — | 包装或补充面板内容，保留传入的内容以维持交互。 | | `getPopupContainer` | `() => Element \| DocumentFragment` | — | 返回浮层的挂载容器，也可返回 ShadowRoot。 | | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 展示尺寸。 | | `status` | `'error' \| 'warning'` | — | 设置 status。 | | `allowClear` | `boolean` | `true` | 展示清除操作。 | | `inputReadOnly` | `boolean` | — | 只禁止手动输入，仍可在面板中选择。 | | `open` | `boolean` | — | 控制面板是否展开。 | | `defaultOpen` | `boolean` | — | 面板初始展开状态。 | | `minDate` | `Date` | — | 最早可选的日期（含边界）。 | | `maxDate` | `Date` | — | 最晚可选的日期（含边界）。 | | `picker` | `'date' \| 'year' \| 'quarter' \| 'month' \| 'week'` | `'date'` | 设置 picker。 | | `disabledDate` | `(date: Date) => boolean` | — | 按业务规则禁用日期。 | | `showToday` | `boolean` | `true` | 设置 showToday。 | | `todayText` | `ReactNode` | — | 设置 todayText。 | | `renderExtraFooter` | `ReactNode` | — | 设置 renderExtraFooter。 | | `onOpenChange` | `(open: boolean) => void` | — | 面板展开或收起时调用。 | | `format` | `string \| ((date: Date) => string)` | — | 显示格式；日期支持 YYYY、MM、DD、HH、mm、ss、Q。 | | `parse` | `(text: string) => Date \| null` | — | 自定义文本解析，失败时返回 null。 | | `panelValue` | `Date` | — | 受控的日历显示日期。 | | `onPanelChange` | `(date: Date) => void` | — | 日历显示的周期改变时调用。 | | `cellRender` | `(date: Date) => ReactNode` | — | 自定义日历单元格内容。 | | `multiple` | `true` | — | 必需。启用多选；value 和回调的类型随之变化。 | | `value` | `readonly Date[]` | — | 受控值。 | | `defaultValue` | `readonly Date[]` | — | 初始值；非受控模式支持表单重置。 | | `maxCount` | `number` | — | 最多可选的数量。 | | `onChange` | `(value: Date[], dateStrings: string[]) => void` | — | 值发生变化时调用。 | ## DatePreset | 属性 | 类型 | 默认值 | 说明 | | ------- | ---------------- | --- | ----------- | | `key` | `string` | — | 稳定且唯一的标识。 | | `label` | `ReactNode` | — | 必需。展示文字或内容。 | | `value` | `T \| (() => T)` | — | 必需。受控值。 |