# DatePicker 日期选择器
日期选择器，支持 `date` / `daterange` / `month` / `monthrange` / `year` / `yearrange` / `datetime` / `datetimerange` / `week` / `quarter` 十种类型，键盘可操作，`Intl.DateTimeFormat` 格式化；触发器为输入框，可直接键入日期（失焦或回车提交，非法输入自动回退）。
## 基础选择
点击输入框展开日期面板，点击日期选中并关闭；也可直接键入 `2026-08-15`、`2026/8/15` 等形式后按 `Enter` / 失焦提交。
## 日期范围
双月网格，先选起点再选终点，提交 JSON 数组 `["start","end"]`；悬停可预览区间。每次起止落选都会派发 `oas-calendar-change`（见[事件](#受控与事件)）。范围选择默认**双月网格**（左月 + 右月联动）；移动形态（窄屏抽屉面板）下双月网格纵向堆叠为单列，桌面容器不自动收缩为单面板。
## 月份与月份区间
monthrange 值为 JSON 数组 `["yyyy-MM","yyyy-MM"]`，双年面板起止选月。
## 年份与年份区间
年面板按 12 年一页翻动，值为 `yyyy`；yearrange 值为 JSON 数组 `["yyyy","yyyy"]`。
## 周与季度
week 类型点击任一天即选中该天所在的整周（整行高亮 + 周号列）；quarter 面板为四格季度选择。
## 日期时间与时间范围
datetime 选日期与时分秒后点「确定」提交；datetimerange 双月 + 起止两组时间列，确定后提交 JSON 数组 `["yyyy-MM-ddTHH:mm:ss","yyyy-MM-ddTHH:mm:ss"]`。
## 范围分隔符
`separator` 自定义范围类型触发器内起止值的分隔符（缺省 `~`）；仅影响显示，value 契约不变。
## 范围默认时刻
`default-time`（`["起始时刻","结束时刻"]`，也支持单个 `"HH:mm:ss"` 起止同值）为 datetimerange 的起止时间列提供默认时刻：值为空或端点缺时间部分时自动补齐——`["00:00:00","23:59:59"]` 为常见整天区间惯例，选完日期点「确定」即得整天范围；快捷预设同样按此补时刻。未设置属性时内置惯例即为 `00:00:00` / `23:59:59`；值端点已带时刻时面板跟随已有时刻，不被覆盖。
## 触发器图标插槽
`slot="prefix-icon"` / `slot="suffix-icon"` 在触发器内分发前/后缀图标（装饰位：点击穿透到触发器开面板）。触发器文本自动让位；`clearable` 的清除钮与后缀图标同区，清除钮可见时后缀图标让位隐藏、清空后恢复。
## 禁用范围与导航边界
越界日期不可选；同时翻页按钮到达 `min` / `max` 边界时置灰，不能再向外翻。
## 快捷预设
`shortcuts`（property，`{ label, value }` 或 `{ label, getValue() }`），点击即应用并派发 `oas-change`、关闭面板。date / datetime / month / week / year / daterange / datetimerange / monthrange / yearrange 内置默认预设（标签走 locale）。
预设较多时可用 `shortcuts-position="left"` 将快捷栏改为面板左侧纵栏。
## 时区（timezone）
`timezone` 接受 IANA 时区名（如 `America/New_York`）或 `UTC`，缺省 / 非法值回落宿主本地时区。它只改变「何时算今天」与由此派生的默认值——面板中的「今天」高亮、「今天」快捷预设、`datetime` / `datetimerange` 的默认时刻推导都按指定时区的墙钟解释；`value` 契约（`yyyy-MM-dd` / ISO 时刻墙钟串）不变。打开左例面板可见「今天」外圈高亮落在纽约的当天，右例落在本地当天；下方对照行给出两个时区当前的日期。
## 禁用日期
`disabledDate`（property，`(date: Date) => boolean`）返回 true 的日期置灰不可选（点击与键盘导航均跳过）；与 `min` / `max` 叠加禁用。
## 多选
`multiple` 时连续点选日期累加/取消，面板保持打开；值存 JSON 数组 `["yyyy-MM-dd", ...]`。
## 自定义格式
format 支持 `yyyy`/`MM`/`dd`/`HH`/`mm`/`ss` token（week / quarter 为固定值格式）。
## 面板能力
范围面板默认双月联动翻页；`unlink-panels` 后左右两栏各自独立翻页（长区间跨年选择）。
无值时打开面板默认落在当前月；设置 `default-value` 后锚定到指定日期所在月（回显生日月份等场景）。
`caption-layout="dropdown"` 把日面板标题换成**月 / 年两个下拉**（出生日期等远年场景免逐月翻页）：年下拉默认覆盖「今年-100 ～ 今年+10」（`min` / `max` 在场时收缩到边界年，越界月整月置灰），选择即跳转——**仅导航不改值**，选中日期仍由点击日格 / 快捷预设 / 手输提交。月 / 年标题顺序随 locale（zh 系年在前）；`type=date` / `datetime` / `week` 生效，其余类型（月/年/季度/范围面板自身已是块选择形态）保持标题按钮不变。键盘可用（原生 select），切换后焦点保持在下拉上可连续跳转。
`show-week-number` 显示 ISO 周号列（`type=week` 自带）；`first-day-of-week`（0-6，0=周日）覆写周起始，默认跟随 locale。
## 单元格渲染
与 `oas-calendar` 同款双通道：`template[slot="cell"]` 克隆进每个日格（`[data-cell-date]` 自动绑定日期数字）；每个日格重建时派发 `oas-cell-render`，`detail: { date, element }`，宿主可追加徽标/价格等标记（监听须幂等）。
## 表单态
`status=error` 联动 `aria-invalid`；`clearable` 在有值时显示清除钮，点击清空并派发 `oas-clear` + `oas-change`（空值）。
readonly 下面板可展开浏览、单元格可键盘导航，但点选 / 快捷 / 清除 / 手输均不提交。
## 受控与事件
`open` 属性在场为受控模式：手势只派发 `oas-open-change`，开合由宿主增删属性决定。
范围类型每次起止落选即派发 `oas-calendar-change`（`detail.value` 为 `[start, end|null]`），可做「已选起点」提示或动态换月。
## 禁用
## 浮层定位（placement）
面板默认 `bottom-start`（面板左缘对齐触发器左缘）。触发器贴近视口右缘时自动右对齐翻转（`bottom-end`），右缘仍不足则水平夹取到视口内；下方空间不足时上翻（`top-start`/`top-end`）。`placement` 支持 12 向：`top / bottom / left / right` 各配 `-start` / `-end` 交叉轴对齐。
## 与 oas-calendar 的选择
弹层选择用 `oas-date-picker`（本组件，触发器 + 浮层面板）；筛选侧栏等常驻内嵌日历场景用 `oas-calendar`（纯面板形态，支持 `mode=year`、周号、单元格渲染等同族能力）。
## 移动形态（底部抽屉）
触屏（coarse pointer）或窄视口（<768px）下，面板自动改由 `oas-bottom-sheet` 底部抽屉承载：贴视口底升起 + 遮罩 + 拖拽把手下滑关闭（点遮罩 / Esc 同样收起），底部避让安全区；PC 形态保持原有浮层下拉不变。双月范围面板在窄屏自动收窄防横向溢出；抽屉内日格触控目标抬升至 44px（`--oas-touch-target-min`），触屏点选更易命中。
## required 必填
`required` 驱动原生校验链（form-associated）：未填时 `checkValidity()` 为 false（`valueMissing`），原生表单提交被阻止；填写后自动恢复 `:valid`。
程序性读/写当前值走公开 `value` property：`el.value` 读取——等价 `getFormValue()` 语义的当前值（单值为 `value` 属性原串；`multiple`/范围模式为字符串数组，与 `oas-change` detail 同形）；`el.value = x` 写入——写受控 `value` 属性并即时回显 trigger（范围/多选传数组自动 JSON 序列化，空值移除属性），展开态面板选中态同步重锚，不派发事件。
## API
### oas-date-picker
#### 属性
| 属性 | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `caption-layout` | 面板标题形态：buttons（默认，标题按钮切月面板）/ dropdown（月/年下拉快速跳转，出生日期等远年场景；仅日网格单值面板 date/datetime/week 生效，选择仅导航不改值） | `string` | — |
| `clearable` | 可清除：有值时显示清除钮，点击清空并派发 `oas-clear` + `oas-change`（空值） | `boolean` | — |
| `default-time` | datetimerange 起止默认时刻（JSON 数组或单串同值；值缺时间部分时补齐） | `string` | — |
| `default-value` | 空值时面板初始锚点（如回显生日月份；有值时以值为锚） | `string` | — |
| `disabled` | 禁用 | `boolean` | — |
| `first-day-of-week` | 周起始覆写（0=周日 … 6=周六），默认跟随 locale | `string` | — |
| `format` | 展示格式 token（`yyyy`/`MM`/`dd`/`HH`/`mm`/`ss`；week/quarter 为固定值格式） | `string` | — |
| `max` | 可选范围（ISO 日期）；翻页到界时导航按钮置灰 | `string` | — |
| `min` | 可选范围（ISO 日期）；翻页到界时导航按钮置灰 | `string` | — |
| `multiple` | 多选（仅 `type=date`），值存 JSON 数组；该形态手输通道只读 | `boolean` | — |
| `name` | 表单字段名（原生 FormData 提交的 key；范围模式派生 name-start / name-end 两条 entry；无 name 浏览器自动不提交） | `string` | — |
| `open` | 受控开合：在场=展开、移除=收起；手势只派发 `oas-open-change` 由宿主回写；移动形态（触屏/窄视口 <768px）下展开态由 oas-bottom-sheet 底部抽屉承载（下滑/遮罩/Esc 收起），PC 为浮层下拉 | — | — |
| `placeholder` | 占位提示 | — | — |
| `placement` | 浮层位置，12 向：`top`/`bottom`/`left`/`right` × `-start`/`-end`（默认 `bottom-start`）；触发器贴近视口右缘时自动右对齐翻转、下方空间不足时上翻，并夹取到视口内 | `string` | `bottom-start` |
| `readonly` | 只读：面板可展开浏览（单元格可键盘导航），点选/快捷/清除/手输均不提交 | `boolean` | — |
| `required` | 必填标记（驱动原生校验链 valueMissing；不透传内层控件） | `boolean` | — |
| `separator` | 范围类型触发器内起止值分隔符（仅显示层，value 契约不变） | `string` | — |
| `shortcuts-position` | 快捷预设位置：`bottom`（默认，顶部横排）/ `left`（左侧纵栏） | `string` | `bottom` |
| `show-week-number` | 显示 ISO 周号列（`type=week` 自带） | `boolean` | — |
| `size` | 尺寸档：`small` / `medium` / `large`（就近读取 config-provider 注入） | `string` | `medium` |
| `status` | 校验态：`success` / `warning` / `error`（`error` 联动 `aria-invalid`） | `string` | — |
| `timezone` | 时区锚点：IANA 时区名（如 America/New_York）或 UTC；缺省/非法回落宿主本地。「今天」高亮、快捷预设与默认时刻推导按该时区墙钟解析，value 契约不变 | `string` | — |
| `type` | 类型：`date` / `daterange` / `month` / `monthrange` / `year` / `yearrange` / `datetime` / `datetimerange` / `week` / `quarter` | `string` | `date` |
| `unlink-panels` | 范围双月各自独立翻页（默认联动） | `boolean` | — |
| `value` | 当前值：`yyyy-MM-dd` / `yyyy-MM` / `yyyy` / `yyyy-Wnn` / `yyyy-Qn` / `yyyy-MM-ddTHH:mm:ss` / JSON 范围数组 | `string \| string[] \| null` | — |
#### Property（JS property；是否写回 attribute 见各行说明）
| Property | 说明 | 类型 | 默认值 |
| --- | --- | --- | --- |
| `disabledDate` | 禁用日期谓词（property 函数通道，`(date) => boolean`） | `((d: Date) => boolean) \| null` | — |
| `shortcuts` | 快捷预设（property 通道，`[{ label, value/getValue }]`） | `ShortcutItem[] \| null` | — |
| `value` | 当前值：单值日期串；范围 / 多选为字符串数组 | `string \| string[] \| null` | — |
#### 事件
| 事件 | 说明 |
| --- | --- |
| `oas-blur` | 组件整体失焦（组件内转移不误报） |
| `oas-calendar-change` | 范围类型起止落选即派发，`detail: { value: [start, end\|null] }`（宿主可做已选起点提示） |
| `oas-cell-render` | 日格重建时逐格派发，`detail: { date, element }`（标记点/徽标场景，监听须幂等） |
| `oas-change` | 值变化，`detail: { value }`（范围/multiple 为字符串数组） |
| `oas-clear` | 清除，`detail: { value }` 为清空前的值 |
| `oas-confirm` | datetime / datetimerange 点确定提交时派发（与 `oas-change` 并行），`detail: { value }` |
| `oas-focus` | 组件整体获焦 |
| `oas-open-change` | 开合变化，`detail: { open }`（受控/非受控均派发） |
#### 插槽
| 名称 | 说明 |
| --- | --- |
| `prefix-icon` | 触发器内前置图标（装饰位，点击穿透到触发器） |
| `suffix-icon` | 触发器内后置图标（清除钮可见时让位，清空后恢复） |
| `template[slot="cell"]` | `template[slot="cell"]` 克隆进每个日格，`[data-cell-date]` 自动绑定日期数字（与 `oas-cell-render` 双通道） |
#### CSS 变量
| CSS 变量 | 默认值 |
| --- | --- |
| `--oas-glass-blur` | `none` |
| `--oas-glass-ring` | `transparent` |
#### Property（快捷预设）
- `shortcuts`：快捷预设
键盘：`Enter` / `↓` 展开，方向键 / `Home` / `End` / `PageUp` / `PageDown`（`Shift` 换年）在网格内移动，`Enter` 选中，`Esc` 关闭。