组件 · 数据录入

DatePicker 日期选择

将 Headless 日期状态适配到主题按钮与弹层，测试标记落在触发器根节点。

入口 @selrux/ui/date-picker · 源码 src/components/date-picker/index.ts · 2 个组件

引入

tsx

import { DatePicker, DateRangePicker } from '@selrux/ui/date-picker';

调节下方可实现的字面量属性，实时预览真实组件。函数、Portal、样式逃生口等见代码演示与 API 表。

未选择日期时显示 placeholder，选中后显示日期。

单日与范围选择器均可配置 iconPosition。

第一次点击确定起点，第二次点击确定终点；反向点击会按日期排序。

范围已选定，再次点击日期可重新选择

预设按钮与月历共用同一受控值。

常用时间段按钮直接更新范围，也可在日历中逐日选择。

以 null 表示受控空值，onChange 更新外部状态。

初始显示在可选范围内，限制年份并禁用周末。

仅允许 2026 年工作日作为起止日期，日历周从星期一开始。

formatOptions 控制触发器中已选日期的显示方式。

切换单日与范围选择器，检查悬停、点击及重新启用后的弹层行为。

禁用时悬停或点击均不应打开日历。

属性覆盖：示例用到 24 / 24 个自有属性（100%）

由 scripts/demo-coverage.mjs 统计，不含 className / style / 原生透传属性与纯转发事件。

将 Headless 日期状态适配到主题按钮与弹层，测试标记落在触发器根节点。

属性	说明	类型	默认值
`value`	受控选中日期；null 表示受控空值，与 defaultValue 二选一。	`Date \| null`	-
`defaultValue`	非受控初始日期。	`Date`	-
`onChange`	选中日期变更回调。	`((value: Date \| undefined) => void)`	-
`placeholder`	空值时的触发器文案，默认 '选择日期'。	`string`	`'选择日期'`
`iconPosition`	日历图标在触发器中的位置，默认左侧。	`"left" \| "right"`	-
`locale`	Intl 日期格式语言标签，默认跟随浏览器。	`string`	-
`disabled`	禁用整个选择器。	`boolean`	-
`minDate`	可选日期下界，包含当日。	`Date`	-
`maxDate`	可选日期上界，包含当日。	`Date`	-
`isDateDisabled`	单独禁用日期的判断函数。	`((date: Date) => boolean)`	-
`weekStartsOn`	显式指定一周的首日；默认按 locale 推导。	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	-
`formatOptions`	格式化触发器日期的 Intl 选项。	`Intl.DateTimeFormatOptions`	-
`className`	触发器附加 class。	`string`	-

第一次点击保留弹层，完成范围后收起；测试标记落在触发器根节点。

属性	说明	类型	默认值
`value`	受控范围；null 表示受控空值。	`CalendarDateRange \| null`	-
`defaultValue`	非受控初始范围。	`CalendarDateRange`	-
`onChange`	首次选择与完成范围时均调用。	`((range: CalendarDateRange) => void)`	-
`placeholder`	空值文案，默认 '选择日期范围'。	`string`	`'选择日期范围'`
`className`	触发器附加 class。	`string`	-
`disabled`	禁用整个选择器。	`boolean`	-
`locale`	Intl 日期格式语言标签，默认跟随浏览器。	`string`	-
`weekStartsOn`	显式指定一周的首日；默认按 locale 推导。	`0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6`	-
`minDate`	可选日期下界，包含当日。	`Date`	-
`maxDate`	可选日期上界，包含当日。	`Date`	-
`isDateDisabled`	单独禁用日期的判断函数。	`((date: Date) => boolean)`	-
`iconPosition`	日历图标在触发器中的位置，默认左侧。	`"left" \| "right"`	-
`formatOptions`	格式化触发器日期的 Intl 选项。	`Intl.DateTimeFormatOptions`	-

导出类型：CalendarDateRange、DatePickerProps、DateRangePickerProps