DatePicker
日期选择器，type=date 日历面板 / type=dateTime 日期+时间（复用 TimePicker 时分秒列）/ type=month 月份面板 / type=year 年份面板，受控/非受控；显示与星期/月份/年份均经 Intl.DateTimeFormat 本地化。支持 multiple 多选（value 为 Date[]、max 上限）、presets 快捷选项（可置四向）、format token 串使触发器变可输入文本框、disabledDate/disabledTime 禁用、密度/无边框/自定义单元格与触发器渲染、面板四向 slot。日期区间选择用配套的 RangePicker。
如何引入
import { DatePicker } from '@chenzy-design/svelte';基础用法
支持日期、日期时间、月份、年份类型，含范围选择、快捷预设、禁用时间。
基础日期选择
单日期选择与范围选择器的基础用法。
日期类型
type 切换日期时间、月份、年份选择。
范围选择
RangePicker 配合 disabledDate 与 maxRange 限制可选区间。
禁用日期与快捷预设
disabledDate 禁用周末，presets/presetPosition 提供快捷选项。
自定义格式与外观
format 自定义解析格式，size/status/disabled 控制外观状态。
带时间范围选择
RangePicker type=dateTimeRange 双面板 + 起止时/分/秒列 + 确认提交，支持 showSecond、disabledTime。
月份范围选择
RangePicker type=monthRange 双月份面板（头部年份 + 左右切年）选起止月，value 为 [起始月, 结束月]。
面板内嵌输入
insetInput 在面板顶部渲染可编辑输入框（date 日期框；dateTime 日期框+时间框），键盘可直接键入，与面板选择双向同步。
年月滚轮快速跳转
点头部年月标题展开年 + 月滚轮列（复用 ScrollList），快速跳转任意年月；yearAndMonthOpts 控制循环滚动。
点击面板头部的「年月」标题，展开年 + 月滚轮列，快速跳转到任意年月，再选具体日期。 已选：（未选） yearAndMonthOpts 开启循环滚动（年列 + 月列首尾相接）。 已选：（未选）
周日周一周二周三周四周五周六
多选日期
multiple 多选（仅 type=date），value 为 Date[]，max 限制数量。
时区显示
timeZone 按 IANA 时区显示同一时刻（格式化层注入，底层绝对时刻不变）。
确认选择
needConfirm 使 dateTime 需点击确认才写入值，配合 onConfirm 回调。
面板插槽与自定义日期
topSlot/bottomSlot 面板额外区域，renderDate 自定义日期单元格内容。
自定义触发器
triggerRender 完全自定义触发器外观。
范围快捷区间
RangePicker presets 提供最近 7 天等快捷区间，presetPosition 控制位置。
周选择
RangePicker startDateOffset/endDateOffset 单击任意日期即选中整周。
API 参考
DatePicker
Props
| 属性 | 说明 | 类型 | 默认值 |
|---|---|---|---|
type | — | 'date'|'dateTime'|'month'|'year' | 'date' |
value | — | Date | null | undefined |
defaultValue | — | Date | null | null |
open | — | boolean | undefined |
defaultOpen | — | boolean | false |
placeholder | — | string | '请选择日期' |
size | — | 'small'|'default'|'large' | 'default' |
status | — | 'default'|'warning'|'error' | 'default' |
disabled | — | boolean | false |
clearable | — | boolean | true |
disabledDate | — | (date: Date) => boolean | undefined |
disabledTime | — | (date: Date) => { disabledHours?: () => number[]; disabledMinutes?: (hour: number) => number[]; disabledSeconds?: (hour: number, minute: number) => number[] } | undefined |
presets | — | { label: string; value: Date | (() => Date) }[] | undefined |
weekStart | 一周起始日（0=周日 … 6=周六） | 0|1|2|3|4|5|6 | 0 |
showSecond | — | boolean | true |
locale | — | string | 'zh-CN' |
defaultPickerValue | 面板初始定位日期（非受控，不改选中值）；仅无选中值时 seed 面板游标显示的月/年 | Date | Date[] | undefined |
timeZone | 按 IANA 时区显示（仅格式化层注入 Intl { timeZone }；不做完整跨时区值转换，底层 Date 绝对时刻不变） | string | undefined |
format | — | string | undefined |
onChange | 值变化回调；第二参 dateString 为格式化字符串，参数顺序由 onChangeWithDateFirst 控制 | (value: Date | Date[] | null, dateString: string) => void | undefined |
onOpenChange | — | (open: boolean) => void | undefined |
onParseError | — | (e: { text: string }) => void | undefined |
onPanelChange | — | (e: { panelDate: Date }) => void | undefined |
onPresetClick | — | (e: { preset: { label: string; value: Date | (() => Date) } }) => void | undefined |
onClear | — | (e: {}) => void | undefined |
onConfirm | — | (e: { value: Date | null }) => void | undefined |
onFocus | — | (e: FocusEvent) => void | undefined |
onBlur | — | (e: FocusEvent) => void | undefined |
ariaLabel | — | string | undefined |
insetLabel | 内嵌标签：浮入触发器左侧的常驻标签（纯展示，不影响值/解析） | string | Snippet | undefined |
insetLabelId | insetLabel 的 id，经 aria-labelledby 关联触发器 combobox（仅 insetLabel 存在时生效） | string | undefined |
rangeSeparator | 范围日期分隔符 | string | '~' |
autoSwitchDate | 年月滚轮（PANEL_YAM）里选完年/月后自动切回日期网格视图（仅 type=date/dateTime） | boolean | true |
autoAdjustOverflow | 浮层自动调整位置防溢出 | boolean | true |
insetInput | 在面板顶部内嵌可编辑输入框（仅 type=date/dateTime）：date 一个日期框，dateTime 日期框+时间框；与面板选择双向同步，键入解析复用 formatDate/parseDateString | boolean | false |
position | 浮层弹出位置 | string | 'bottomLeft' |
spacing | 触发器与浮层间距 | number | undefined |
getPopupContainer | 浮层挂载容器 | () => HTMLElement | undefined |
weekStartsOn | weekStart 别名（weekStart 优先） | 0|1|2|3|4|5|6 | undefined |
onCancel | 点击取消按钮 | (date: Date | Date[] | null, dateStr: string) => void | undefined |
onChangeWithDateFirst | true→onChange(value, dateString)（默认，value-first）；false→onChange(dateString, value) | boolean | true |
onClickOutSide | 点击外部关闭时触发 | (e: MouseEvent) => void | undefined |
borderless | 无边框模式 | boolean | false |
density | compact 时面板更紧凑 | 'default' | 'compact' | 'default' |
prefix | 触发器前缀内容，渲染在 input 左侧 | Snippet | string | undefined |
clearIcon | 自定义清除按钮图标 | Snippet | undefined |
showClear | 是否显示清除按钮（受 clearable 控制） | boolean | true |
inputReadOnly | 输入框 readonly 属性 | boolean | false |
inputStyle | 输入框内联样式 | CSSProperties | string | undefined |
autoFocus | 挂载时自动聚焦 | boolean | false |
dropdownClassName | 下拉浮层 className | string | undefined |
dropdownStyle | 下拉浮层样式 | CSSProperties | string | undefined |
dropdownMargin | 浮层溢出冗余值 | number | { x?: number; y?: number } | undefined |
zIndex | 浮层 z-index | number | 1030 |
motion | 面板展开动画，false 时添加 cd-date-picker--no-motion | boolean | true |
preventScroll | 聚焦时阻止滚动 | boolean | false |
stopPropagation | 阻止浮层点击事件冒泡 | boolean | true |
topSlot | 面板顶部额外区域 | Snippet | undefined |
bottomSlot | 面板底部额外区域 | Snippet | undefined |
leftSlot | 面板左侧额外区域 | Snippet | undefined |
rightSlot | 面板右侧额外区域 | Snippet | undefined |
multiple | 多选（仅 type='date'），value 变为 Date[] | boolean | false |
max | multiple=true 时最多选择数量 | number | undefined |
startYear | 年份滚轮最小年 | number | undefined |
endYear | 年份滚轮最大年 | number | undefined |
renderDate | 自定义日期单元格内容 | Snippet<[{ day: number; fullDate: string }]> | undefined |
renderFullDate | 完全自定义日期格子 | Snippet<[{ day: number; fullDate: string; dayStatus: DayStatus }]> | undefined |
triggerRender | 完全自定义触发器 | Snippet<[{ value: Date | Date[] | null; placeholder: string }]> | undefined |
hideDisabledOptions | 隐藏禁止的时间选项 | boolean | false |
disabledTimePicker | 禁止时间选择 | boolean | false |
needConfirm | dateTime/dateTimeRange 时需要点击确认才写入 | boolean | false |
presetPosition | 快捷选项列表位置 | 'left'|'right'|'top'|'bottom' | 'bottom' |
yearAndMonthOpts | 透传给年月 ScrollList 的参数 | { yearCyclic?: boolean; monthCyclic?: boolean } | Record<string, unknown> | undefined |
class | 根节点自定义类名（对齐 Semi className） | string | '' |
style | 根节点内联样式 | string | undefined |
Methods
| 属性 | 类型 | 说明 |
|---|---|---|
open() | — | 命令式展开面板（对齐 Semi） |
close() | — | 命令式关闭面板（对齐 Semi） |
focus() | — | 命令式聚焦触发器（尊重 preventScroll，对齐 Semi） |
blur() | — | 命令式移除触发器焦点（对齐 Semi） |
Accessibility
| ARIA role | dialog |
- 触发器 button aria-haspopup=dialog、aria-expanded、aria-controls 指向面板
- 面板 role=dialog；日期网格 role=grid，单元格 role=gridcell + aria-selected
- 触发器 Enter/Space/↓ 打开；面板内方向键移动高亮日、Enter 选中、Esc 关闭
- roving tabindex：仅高亮日可聚焦
- type=dateTime：时/分/秒列 role=listbox + option，选日期不关面板，点确定关闭
- disabledTime：dateTime 时/分/秒列被禁用值 aria-disabled、点击/键盘无效（分/秒列联动已选时/分）
- presets：面板侧边快捷日期按钮 role=group，点击直接选中（dateTime 连带时间）并关闭
- type=month：12 个月格，头部显示年份 + 左右切年；点月份选中并关闭
- type=year：一页 12 年（一十年 + 前后各 1 占位），头部显示十年范围 + 左右切十年；点年份选中并关闭
- format：传 token 串（YYYY/MM/DD/HH/mm/ss）时触发器变 text 输入框，显示+手输解析均走 formatDate/parseDateString；不传沿用 Intl 显示
- insetInput：面板顶部渲染可编辑输入框（date 一个日期框；dateTime 日期框+时间框），键盘用户可直接键入起止日期；Enter/blur 提交解析，Esc 关闭；与日历/时间列选择双向同步
- 年月滚轮快速跳转（PANEL_YAM，对齐 Semi）：点头部年/月标题（button aria-expanded）展开年 + 月两列 ScrollList（复用 ScrollList，role=listbox 逐列），选中即跳转面板游标（不写 value），「返回」按钮回日期网格；yearAndMonthOpts.yearCyclic/monthCyclic 控制列循环滚动；type=year 面板仍走十年格，不进滚轮
设计变量
| 变量 | 默认值 | 用法 |
|---|---|---|
--cd-transition-date-picker-range-input | background-color .16s ease-in-out |