Calendar
按日期组织事件或状态。中文惯用名：日历。
稳定本期新增已接入
元信息
| 字段 | 值 |
|---|---|
| 规范 ID | component.calendar |
| 名称 | Calendar |
| 二级分类 | 数据展示（data-display） |
| 用途 | 按日期组织事件或状态 |
| 描述 | 中文惯用名：日历。 |
预览
静态结构：Calendar 直接渲染 vendored react-day-picker 月历（无自定义 data-slot，容器 bg-card p-3、宽 w-fit）：顶部月份标题与左右导航箭头（outline 圆形按钮），下方星期表头 + 日期网格按钮；选中日经 DayPicker selected 样式（--calendar-selected-* 令牌）高亮，hover 走 --calendar-day-hover-*，showOutsideDays 缺省 true 以弱化样式补齐当月之外日期。值为 ISO 字符串（yyyy-MM-dd），onChange 同样传出 ISO 字符串，清除传 undefined。Form 内声明非空 name 时外层为 data-slot="form-item" 容器（label + 日历 + data-slot="form-error"），不走 FieldShell。
DSL 结构
{
"type": "Calendar",
"props": {
"name": "checkDate",
"label": "核对日期",
"mode": "single",
"value": "2026-09-21"
}
}何时用
何时使用
- 需要常驻可见的月历视图：日程安排、排班、内容日历、日期概览。
- 日期选择需要「看着日历选」而非弹层一闪而过（与 DatePicker 的触发器形态互补）。
- 表单内的日期字段，且布局允许日历常驻：声明 name 即自动注册为表单项。
何时不用
- 常规表单中的日期字段、版面紧凑：使用 DatePicker（触发器 + Popover 弹层）。
- 需要选择日期区间（开始 - 结束）：使用 DatePicker 的 mode="range" 双面板；Calendar 当前仅支持 single。
- 需要时间点或日期时间的完整录入：使用 TimePicker 或 DatePicker + TimePicker 组合。
变体
| 变体 | 视觉形态 | 适用场景 |
|---|---|---|
| 默认（single 单选） | 单月日历网格，点击日期即选中高亮 | 常驻日历视图、表单内日期字段 |
| 已选值回显 | value 传入的日期带选中样式 | 编辑回显、按当前日期定位 |
| 无选中值 | 未选时不命中任何日期 | 初始化状态、允许留空的字段 |
| Form 表单项 | form-item 容器：label + 日历 + 校验错误行 | 表单内日期字段（声明 name 自动注册） |
| disabled 禁用 | 全部日期不可点击 | 只读回显、条件未满足 |
API 属性
| 属性 | 类型 | 默认值 | 说明 |
|---|---|---|---|
name | string | — | 字段名；在 Form 内声明即自动成为表单项 |
label | string | — | 表单项标签（Form 内由 label 标签呈现） |
rules | FieldRule[] | — | 校验规则 |
mode | 'single' | 'single' | 选择模式（当前仅支持 single） |
value | string | — | 受控值（ISO 日期字符串 yyyy-MM-dd）；Form 内作为字段初始值（优先于 Form initialValues） |
disabled | boolean | false | 禁用全部日期选择 |
onChange | `(value: string | undefined) => void` | — |
className / style | string / CSSProperties | — | 通用：根节点 class 合并 / 内联样式（Form 内为 form-item 容器，独立渲染时为日历本身） |
使用规范
- 值与格式固定为 ISO 字符串 yyyy-MM-dd：不要传 Date 对象，也不要传本地化格式字符串。
- Calendar 常驻占位较大（整月网格），仅适合布局宽裕的场景；表单常规字段用 DatePicker 更省版面。
- 区间选择走 DatePicker 的 mode="range"，Calendar 当前无区间能力，不要用两个 Calendar 自行拼装。
- 日历语言随 useI18n().locale 映射 date-fns locale（内置 zh-CN / en-US），交付前确认目标语言。
- Form 内声明非空 name 才注册字段；未声明 name 时为独立受控日历。
正例
- ✓ 排班页面：Calendar 常驻展示整月，点击日期切换当日排班明细。
- ✓ Form 内「核对日期」：name + rules 必填，提交时值为 "2026-09-21"。
- ✓ 编辑回显：value 传已存日期，日历打开即定位到该月并高亮选中日。
反例
- ✕ 在紧凑表单里塞常驻 Calendar 挤占版面（应使用 DatePicker 弹层形态）。
- ✕ 用 Calendar 期望选择日期区间（区间应使用 DatePicker mode="range"）。
- ✕ 传入 Date 对象或 "2026/09/21" 等非 ISO 字符串导致选中态失效。
Design Token 映射
不适用：组件 tokenRefs 为空：样式 Token 数据尚未接入，三层映射（Primitive → Semantic → Component）待样式 Token 接入后回填。