日期选择 DatePicker

选择一个日期：出生日期、成立日期、证件有效期。既可以打开日历点选，也可以直接输入。

examples/datepicker/basic.html

试一试

点击输入框或日历图标打开日历；点击标题「2026年9月」切换到月份，再点一次切换到年份，选出生日期时很方便
直接输入 19900521、1990/5/21 都会被规范成 1990-05-21
「证件有效期」设置了 data-min="today"，今天之前的日期不可选

结构

html

<div class="relative" data-cb-datepicker data-max="today">
  <div class="relative">
    <input type="text" data-cb-datepicker-input name="birthday" inputmode="numeric" placeholder="YYYY-MM-DD"
           class="h-11 w-full … pr-11 font-mono" />
    <button type="button" data-cb-datepicker-trigger aria-label="打开日历" class="absolute top-1/2 right-1.5 …">
      <svg>calendar</svg>
    </button>
  </div>
  <!-- 日历由脚本渲染 -->
  <div data-cb-datepicker-panel hidden class="absolute top-full left-0 z-40 mt-1 rounded-lg border … p-3 shadow-lg"></div>
</div>

属性	说明
`data-min` / `data-max`	可选范围，`YYYY-MM-DD` 或 `today`
`data-locale`	月份、星期的语言，默认取 `<html lang>`；`zh-*` 显示中文，其他显示英文
`data-week-start`	一周从哪天开始，`0` 周日 / `1` 周一；默认 `en-US` 为周日，其余为周一
`el.cbDisableDate`	JS 属性，自定义不可选日期，例如 `el.cbDisableDate = (d) => d.getDay() === 0`

取值与事件

输入框的值始终是 YYYY-MM-DD，与语言无关，直接提交给后端
选择后输入框派发 input / change，根元素派发 cb:date-change，detail = { value, date }
输入无法识别或超出范围的日期时，输入框会被加上 aria-invalid="true"（显示错误描边），修正后自动移除
JS 设置：CbtisUI.setDate(el, '2026-09-15')，清空传 ''

键盘

按键	结果
在输入框按 `↓`	打开日历，焦点进入日期
`←` `→` `↑` `↓`	前 / 后一天、前 / 后一周
`PageUp` `PageDown`	上 / 下个月（加 `Shift` 为上 / 下一年）
`Home` `End`	本周第一天 / 最后一天
`Enter` / `Space`	选择
`Esc`	关闭并回到输入框

使用建议

无障碍

日历面板 role="dialog"，每个月份是 role="grid"；每个日期按钮的 aria-label 为完整日期（「2026年9月15日星期二」），今天带 aria-current="date"，选中项带 aria-pressed="true"
标题按钮切换月份时通过 aria-live 播报新的年月
输入框始终可以直接输入，不依赖日历

与 v2 的差异

v2 现状	规范
`PersonModal` 的出生日期、成立日期使用 `type="date"`	日期选择组件，统一 `YYYY-MM-DD`

日期选择 DatePicker ​

结构 ​

取值与事件 ​

键盘 ​

使用建议 ​

无障碍 ​

与 v2 的差异 ​

日期选择 DatePicker

结构

取值与事件

键盘

使用建议

无障碍

与 v2 的差异