DatePicker
选择日期、区间或周期。中文惯用名：日期选择器。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.date-picker |
| 名称 | DatePicker |
| 二级分类 | 数据录入（data-entry） |
| 用途 | 选择日期、区间或周期 |
| 描述 | 中文惯用名：日期选择器。 |
预览
静态结构：DatePicker 为触发器（data-slot="datepicker-trigger"，左侧截断文本显示已选值或 placeholder、右侧 Calendar 图标）+ 受控 Popover 弹层（PopoverContent w-auto p-0）。single 为单月日历；range 为左右双面板（data-slot="datepicker-start-panel" / "datepicker-end-panel"，各自受控月份且左右至少相差一个月），选择语义为「任意面板两次点击」：首击设开始日并清空结束日，第二击不早于开始日即提交、早于则重设开始日，已有完整区间再点击即开始新一轮；区间端点与中间日期经 DayPicker modifiers 施加选中 / 过渡样式。presets 快捷栏（data-slot="datepicker-presets"，左列按钮）在 range 模式缺省内置「今天 / 本周 / 本月」，除定位型「今天」外点击即提交区间且不关弹层。Form 内声明非空 name 时外层为 data-slot="form-item" 容器（label + 控件 + data-slot="form-error"）。
DSL 结构
{
"type": "DatePicker",
"props": {
"name": "statDate",
"label": "统计区间",
"mode": "range",
"value": {
"start": "2026-09-01",
"end": "2026-09-21"
}
}
}何时用
何时使用
- 选择单个日期：截止日、生效日、生日（mode 缺省 single，值为 ISO 字符串）。
- 选择日期区间：统计周期、报表时间范围（mode="range"，值为 { start, end }）。
- 需要快捷预设快速定位：range 模式缺省提供「今天 / 本周 / 本月」，也可自定义预设。
何时不用
- 只选时间点、不含日期：使用 TimePicker；DatePicker 与 TimePicker 分开选日期与时间。
- 需要日期 + 时刻的完整时间戳：组合 DatePicker + TimePicker 两个字段，不要在一个控件内混选。
- 需要面向月 / 季 / 年粒度的选择面板：当前实现为日粒度日历，粒度更粗的选择需业务侧另行处理。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| single 单日期（缺省） | 单月日历，点击日期即选中并回填触发器 | 截止日、生效日等单个日期字段 |
| range 日期区间 | 左右双月面板，端点高亮 + 中间区间过渡色 | 统计周期、报表时间范围 |
| presets 内置预设 | 弹层左侧「今天 / 本周 / 本月」快捷列 | range 模式的高频区间（本周、本月） |
| presets 自定义 | 按 { key } / { days } / { range } 自定义快捷项，false 关闭 | 业务化区间（如「最近 7 天」「本财年」） |
| Form 表单项 | form-item 容器：label + 触发器 + 校验错误行 | 表单内日期字段（声明 name 自动注册） |
| disabled 禁用 | 触发器半透明不可点开 | 联动未就绪或只读场景 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项 |
label | string | — | 表单项标签（Form 内由 label 标签呈现） |
rules | FieldRule[] | — | 校验规则 |
mode | `'single' | 'range'` | 'single' |
value | `string | DateRangeValue` | — |
onChange | `(value: string | DateRangeValue | undefined) => void` |
placeholder | string | — | 空态提示文案；缺省取 i18n key，按 mode 区分 single / range |
disabled | boolean | false | 禁用触发器 |
presets | `DatePickerPreset[] | false` | — |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式（Form 内为 form-item 容器，独立渲染时为触发器） |
使用规范
- 值与格式固定为 ISO 字符串 yyyy-MM-dd（range 为 { start, end } 对象），不要传 Date 对象或本地化格式。
- range 模式仅在两端齐备时触发 onChange：单端点期间无值，不要在此期间读取表单值做逻辑判断。
- 日期区间用 mode="range" 而非两个 single 字段；同时需要时刻时用 DatePicker + TimePicker 组合两个字段。
- presets 用于收敛高频区间；range 模式缺省已提供「今天 / 本周 / 本月」，single 模式不渲染预设栏。
- 日历语言随 useI18n().locale 映射（内置 zh-CN / en-US），未知 locale 回退 en-US，交付前确认目标语言。
正例
- ✓ 报表时间范围：mode="range" + 缺省预设，用户点「本月」即得完整区间，onChange 触发查询。
- ✓ 表单「生效日期」：single 模式 + name + rules 必填，值为 "2026-09-21"。
- ✓ 自定义预设：presets 传 { label: "最近 7 天", days: 7 }，贴合业务高频口径。
反例
- ✕ 用两个 single DatePicker 拼区间，失去双面板与端点高亮体验（应使用 mode="range"）。
- ✕ 把 range 模式的中间态（只选了开始日）当作有效值提交。
- ✕ 传入 Date 对象或 "2026/09/21" 等非 ISO 字符串，回显失效。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。