> 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-range-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. # DateRangePicker 日期区间选择器 选择起止日期或时间，限定一个区间。 ## 受控区间 日期区间 basic.tsx 复制代码 ```tsx lineNumbers file="../../src/examples/date-range-picker/basic.tsx" import { type DateRange, DateRangePicker, Form, FormField, Text } from '@ifhover/leaf-ui'; import { useState } from 'react'; export function DateRangePickerBasic() { const [range, setRange] = useState(null); return (
{range && ( {range[0].toLocaleDateString()} – {range[1].toLocaleDateString()} )}
); } ``` 展开代码 ## 选择粒度 年份区间 月份区间 周区间 日期时间区间 modes.tsx 复制代码 ```tsx lineNumbers file="../../src/examples/date-range-picker/modes.tsx" import { DateRangePicker, Form, FormField } from '@ifhover/leaf-ui'; export function DateRangePickerModes() { return (
); } ``` 展开代码 ## 季度、预设与开放端点 季度区间 允许结束为空，或选择最近七天 capabilities.tsx 复制代码 ```tsx lineNumbers file="../../src/examples/date-range-picker/capabilities.tsx" import { DateRangePicker, Flex, Space, Text } from '@ifhover/leaf-ui'; export function Capabilities() { return ( {'季度区间'} {'允许结束为空，或选择最近七天'} date.getDay() === 0} presets={[ { label: '最近七天', value: () => { const end = new Date(); const start = new Date(); start.setDate(start.getDate() - 6); return [start, end]; }, }, ]} /> ); } ``` 展开代码 ## 显示格式与提交值 `format` 改变显示文字和 `onChange` 的字符串参数；FormData 保持日期或周期的稳定序列化格式。方括号可以转义固定文字，例如 `YYYY-[Q]Q`。使用函数格式化时，请同时提供 `parse`。Date 表示本地日历值，业务时区在应用的数据边界完成转换。周起点通过 ConfigProvider 的 `weekStartsOn` 设置。 ## DateRangePicker 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` | — | 面板初始展开状态。 | | `picker` | `'year' \| 'quarter' \| 'month' \| 'week' \| 'date' \| 'datetime'` | `'date'` | 选择粒度 | | `minDate` | `Date` | — | 最早 / 最晚可选边界 | | `maxDate` | `Date` | — | 最早 / 最晚可选边界 | | `use12Hours` | `boolean` | `false` | 使用 12 小时制展示及上午、下午选项 | | `showSeconds` | `boolean` | `true` | 日期时间区间展示秒，关闭时秒为 0 | | `minuteStep` | `number` | `1` | 分钟 / 秒间隔，1–60 的整数 | | `secondStep` | `number` | `1` | 分钟 / 秒间隔，1–60 的整数 | | `onOpenChange` | `(open: boolean) => void` | — | 面板展开或收起 | | `disabledDate` | `(date: Date, position: 'start' \| 'end') => boolean` | — | 按业务规则禁用日期。 | | `disabledTime` | `(parts: `[`TimeParts`](https://ifhover.github.io/leaf-ui/v/0.6.0/components/time-picker.md#timeparts)`, position: 'start' \| 'end', date: Date) => boolean` | — | 按业务规则禁用时间，输入和面板选择使用同一规则。 | | `format` | `string \| ((date: Date) => string)` | — | 显示格式；日期支持 YYYY、MM、DD、HH、mm、ss、Q。 | | `parse` | `(text: string) => Date \| null` | — | 自定义文本解析，失败时返回 null。 | | `presets` | `readonly `[`DatePreset`](https://ifhover.github.io/leaf-ui/v/0.6.0/components/date-picker.md#datepreset)`[]` | — | 快捷选项；value 可以动态计算。 | | `onCalendarChange` | `(range: readonly [Date \| null, Date \| null], info: { position: 'start' \| 'end' }) => void` | — | 选择过程中的日期变化，包含当前起止位置。 | | `panelValue` | `Date` | — | 受控的日历显示日期。 | | `onPanelChange` | `(date: Date) => void` | — | 日历显示的周期改变时调用。 | | `cellRender` | `(date: Date) => ReactNode` | — | 自定义日历单元格内容。 | | `allowEmpty` | `false \| true \| readonly [boolean, boolean]` | `false` | 明确允许空的起止端点。 | | `value` | `readonly [Date, Date] \| null \| readonly [Date \| null, Date \| null] \| null` | `null` | 受控区间 / 初始区间 | | `defaultValue` | `readonly [Date, Date] \| null \| readonly [Date \| null, Date \| null] \| null` | `null` | 受控区间 / 初始区间 | | `onChange` | `((value: readonly [Date, Date] \| null, dateStrings: readonly [string, string]) => void) \| ((value: readonly [Date \| null, Date \| null] \| null, dateStrings: readonly [string, string]) => void)` | — | 完成选择后返回有序区间与字符串；清除返回 null | | `disabled` | `boolean` | `false` | 禁用交互。 | | `required` | `boolean` | `false` | 要求整体值非空，复合控件只校验一次。 | | `name` | `string` | — | 原生 FormData 中的字段名。 | | `form` | `string` | — | 关联的原生表单 ID。 | | `ref` | `Ref` | — | 输入框引用 | ## DateRange | 属性 | 类型 | 默认值 | 说明 | | --- | ------ | --- | ------------ | | `0` | `Date` | 必填 | 起始值，早于或等于终止值 | | `1` | `Date` | 必填 | 终止值 | ## 类型 定义组件属性或组装变量时可导入相关类型。 ```ts import type { DateRangePickerProps, DateRange } from '@ifhover/leaf-ui'; ``` ## 使用说明 `DateRange` 是 `readonly [Date, Date]`，可导入它组装变量。年取 1 月 1 日，月取当月 1 日，周从星期一开始并使用 ISO 周编号。日期使用本地时间。 两个日历联动导航。选好起点后，悬停年份、月份、周或日期即可预览区间；选好终点立即完成，所有模式都没有底部确定按钮。逆序选择会自动排列。 日期时间区间通过两个日历右上角的时间按钮分别调整起止时间，再返回日期面板选择日期。请在选定结束日期前调整时间。“当前时间”设置该端点的时间。 已有完整区间时，调整任一端点的时间会直接更新有效区间，无需重新选择日期。 也可以输入以 `~` 分隔的两个值，按 Enter 或移走焦点提交。格式依次为 `YYYY`、`YYYY-MM`、`YYYY-Www`、`YYYY-MM-DD`、`YYYY-MM-DD HH:mm:ss`；关闭秒时省略秒。无效或越界输入不会提交，Escape 放弃未完成的输入。 FormData 使用 `start/end` 格式提交对应字符串。非受控组件支持表单 reset；受控组件需同步重置自己的状态。