--- id: "calendar" title: "日历内容组件" category: "选择组件" document_type: "component-specification" spec_status: "local-current-draft" element_ui: "2.15.6" vue: "2.6.14" page: "../index.html#spec-calendar" source_data: "../component-data.json" official_components: ["calendar"] template_components: ["el-calendar"] scenario_count: 7 verification: "scenario-checklist-not-full-test-pass" --- # 日历内容组件 专题 `calendar` · 选择组件 · Element UI 2.15.6 ## 适用范围与组件映射 公共色板及字体基线适用于整个运营后台。本库整理基础组件、组件状态和可复用的组合模式；本轮补齐表单整体验证、页面布局和导航组合；具体业务字段与跨页流程仍在业务场景中说明。专题验收清单包含接入要求，不表示当前示例已实现或已验证全部场景。 官方条目映射：`calendar`。 本页模板直接使用的 Element UI 标签：`el-calendar`。 ## 通用基线 - 组件库：Element UI **2.15.6**；运行样例 Vue **2.6.14**。 - 系统中文字体：macOS 优先苹方，Windows 通常微软雅黑；工程顺序固定为 `"PingFang SC", "Microsoft YaHei", sans-serif`。不要求安装或加载网络字体，兼容回退不是另一套可选样式。 - 后续仅采用经验证且固定版本的兼容 Element UI 2.x；Element Plus 属于独立迁移路线。 - 正文、数据值、输入及已选值：`14px / 400 / 21px`，`#303133`。 - 表头及组件分组标题：`14px / 600 / 21px`；弹窗标题：`16px / 600 / 24px`，均使用 `#303133`。 - 辅助说明：`12px / 400 / 18px`，`#595959`；错误、链接、状态、禁用与占位按各自语义处理。 - 适用组件的默认尺寸为 `small / 32px`；不得将这一高度机械应用于表格、文本域、浮层等全部组件。 - 规范正文与场景说明使用 `14px / 400 / 24px`、`#303133`，不降成灰蓝小字。 - 筛选文本输入占位统一“请输入”；未选择下拉统一“请选择”；默认全部的下拉显示“全部”。字段标签保留业务含义；日期保留开始/结束语义。 - 次级文字操作（查看更多、编辑、详情、数据中心、更多）：`12px / 400 / 18px`，`#3377BB`；保留点击热区。 - 本规范库的深色目录、蓝色展示区属于文档排版，不是业务组件颜色或业务导航规范。 ## 本页用法与分类 默认用法：需要在内容区域查看整月日期时，默认使用当前月历，保留月份切换、今日定位与日期选择；仅填写日期字段时使用日期输入组件。 | 区分什么 | 本页内容 | 选用或触发条件 | | --- | --- | --- | | 用途：内容月历或日期字段 | 内容月历占用页面区域；日期输入负责表单字段。 | 本页只展示月历并选日期，不包含日程、预约或排班；不要为了填写单个日期引入整块月历。 | | 功能：展示范围与日期内容 | 展示范围配置限定可见区间，日期内容需业务自行提供。 | 默认沿用当前整月展示；需要固定展示范围或日格内容时另行接入。展示范围不等于禁止选择某日期。 | | 自动状态：今日、当前选择与月份归属 | 今日由系统日期决定，选中日由当前值决定，非本月由所在月份决定。 | 按真实日期自动显示，当前选中底覆盖悬停底；业务不可选日期需另行实现阻止选择，不能只把字改灰。 | 使用边界：不把今日、选中日和非本月当作几种可选样式。不把展示范围等同于表单的禁选日期能力。 ## 组件规则 - **CALENDAR-R01**：需要在内容区查看整月日期时，默认使用当前月历；仅填写日期字段时使用日期输入组件。两者用途不同，不是同一个输入框的大小样式。 - **CALENDAR-R02**：覆盖今日、选中日、非本月和无内容；range只规定展示范围，不等同DatePicker的禁选日期能力。需要阻止选择某日期时由宿主扩展，不声称原生示例已支持。 - **CALENDAR-R03**：本例只提供日期选择，不增加日程、预约或排班功能。 - **CALENDAR-R04**：当前日格补充键盘适配：制表键进入一个当前日期入口，左右方向键选择相邻日、上下方向键选择相隔一周的日格；起始/结束键选择本行首尾，回车/空格选择当前日。翻页键复用既有上个月/下个月按钮并将焦点移回选中日格；鼠标点击保留。每个日格提供完整中文日期名称、今天及已选语义。 - **CALENDAR-R05**：【公共用色】颜色仅从公共色值 引用：主色系 3 个基础色值、辅助功能色 3 个、中性色 10 个，共 16 个基础色值。角色可以多个，实际色值复用；不为每个组件、悬停 或不同字段再新增近似颜色。透明效果仅限遮罩 35% 与阴影 12%，从 外壳深色 派生。 - **CALENDAR-R06**：【统一字体】统一系统中文字体：macOS 优先苹方（PingFang SC），Windows 通常使用微软雅黑（Microsoft YaHei）；工程顺序固定为 "PingFang SC", "Microsoft YaHei", sans-serif。使用设备已有字体，不要求安装或加载网络字体；最后一项仅作兼容回退，不是供页面作者任选的另一套样式。正文 14px/400/21px；表头与分组标题 14px/600/21px，弹窗标题 16px/600/24px；次级文字操作和辅助说明 12px/400/18px。正文与标题同用 #303133；不通过额外加粗或透明度改变正文轻重。 - **CALENDAR-R07**：【叠加优先级】状态叠加规则：禁用阻断交互；输入类控件错误边框覆盖蓝色聚焦边框；输入框不叠加外圈或阴影，其他无边框操作保留键盘焦点提示；选中底覆盖悬停底；只读不等于禁用；加载不等于成功；业务启用/停用的文字结果不等于控件是否可点击。 - **CALENDAR-R08**：【普通日期】白底、正文深灰、分隔灰；非本月日期可用辅助深灰，事件内容保持可读。 - **CALENDAR-R09**：【今天与选中日】今天用操作蓝文字；选中日期单元格用选中浅蓝，不绘制对勾或半选横线。 - **CALENDAR-R10**：【悬停与键盘】实际可操作日期悬停或定位浅灰背景；当前选中底保持选中浅蓝；键盘焦点用操作蓝提示。 - **CALENDAR-R11**：【不可选与内容反馈】只有业务明确不可选日期才用禁用灰并阻止选择；空事件用空值提示，读取失败在内容区错误红提示，不给日期画表单红框。 - **CALENDAR-R12**：【组件边界】内容日历没有输入触发框、复选和半选；日期导航按钮按按钮规范，日格选择不套用主按钮按下位移。 - **CALENDAR-R13**：日历键盘方向键按实际日期连续移动：左右为前后一天，上下为前后七天；跨月、跨年和闰日必须落到正确日期并保持焦点。Home/End移动到当前周首/末；不能在当前网格边缘截断。 ## 场景与验收清单 以下为需核对的场景组；`[ ]` 不代表已经测试通过。 - [ ] **CALENDAR-S01**：当前样例：原生内容日历、月份切换、今日与日期选择，不包含日程或预约。 - [ ] **CALENDAR-S02**：接入验收：需要固定展示区间时再配置范围展示（range），需要日格内容时再接入业务数据；跨月/跨年/闰日、非本月、空事件与高密度内容分别作为日期和内容边界检查。 - [ ] **CALENDAR-S03**：range规定展示区间，不等同日期输入控件的禁选函数；禁止选择某日期需宿主扩展并验证。日历格本身不使用输入错误边框。 - [ ] **CALENDAR-S04**：共用视觉验收：仅核对本组件实际适用的颜色与组合状态；无此能力标为不适用，不给静态内容添加输入错误、半选或按下状态。 - [ ] **CALENDAR-S05**：共用文字验收：正文14px/400、次级操作12px/400、标题600；检查实际子元素与弹出层。输入焦点只改自身边框，按钮和链接保留键盘焦点轮廓。 - [ ] **CALENDAR-S06**：当前键盘适配：日格仅一个制表键入口，左右/上下、行首尾、回车/空格可选日；上翻页/下翻页改变月份后焦点回到选中日。中文日期名称、aria-pressed和今天aria-current一起更新。源码/逻辑测试不代替实际浏览器读屏验收。 - [ ] **CALENDAR-S07**：跨月与跨年键盘：月首按左或上、月末按右或下；验证实际日期、选中状态、焦点及唯一Tab停靠一致。 ### 专题验收重点 检查日格鼠标选择与月份按钮；制表键进入日格，方向键/回车/空格沿用原生选日，翻页键复用月份按钮；焦点、完整日期名称、今天和已选状态一致。日程内容、禁选日期及远端事件不属于当前示例。 ## 当前示例模板 以下来自本专题的结构化示例，使用 Vue 2 模板语法。`v-model`、事件方法、数据列表等依赖 [components.js](../components.js)；完整样式文件及加载顺序见 [通用基线](FOUNDATIONS.md)。自定义组合标签的内部实现由下方依赖文件提供，不能仅复制标签作为完整组件。 ### 本示例的运行依赖 - 下方只展示专题内部模板，不包含外层宿主。当前适配要求将它置于唯一的 `
` 中；只复制内部标签不会自动获得这里规定的键盘与语义行为。 - 使用 Vue **2.6.14**、Element UI **2.15.6**，接入 [components.js](../components.js) 中本例所需的数据和方法，并按 [通用基线](FOUNDATIONS.md) 加载公共样式。 - 键盘实现依赖 [calendar-keyboard.js](../calendar-keyboard.js)，焦点样式依赖 [calendar-keyboard.css](../calendar-keyboard.css)。脚本在 DOMContentLoaded 时初始化；若文档已经就绪则立即初始化，因此宿主和已挂载日历必须在初始化前存在。 - 当前读取中文 `YYYY年M月` 标题、只含日期数字的原生日格和月份按钮，提供日格唯一 Tab 入口、方向键跨日、Home/End、PageUp/PageDown 及焦点返回。日期内容插槽、其他语言或路由后插入的新日历需重新实现并验证对应映射；业务投放日历自身的按钮交互不能自动视为本适配已接入。 - 本片段及文档不是独立运行包。实际接入还需核对名称、键盘、边界、动态挂载与销毁；本地逻辑检查不代替浏览器及读屏验收。 ```html

制表键进入日格；方向键选择日期，回车或空格确认当前日。上翻页/下翻页键切换月份，也可使用上方月份按钮。

``` ## 交付与使用边界 - 规范条款、示例代码与待验收场景分开理解；有示例不等于已覆盖所有样式、交互状态和使用场景。 - 业务接口、权限、时区、金额精度、数据规模等依赖应从实际项目读取，不使用演示值代替生产约定。 - 发生样式或文案变更时，同步专题数据、页面与 Markdown，避免规范和样例分离。 ## 来源与关联 - 来源线索：本次补充；Element UI 2.15.6 packages/calendar/src/date-table.vue原生click日格，calendar-keyboard.js/css补充本规范页键盘与焦点适配。。 - [打开本专题页面](../index.html#spec-calendar) - [通用基线](FOUNDATIONS.md) - [规范总索引](README.md) - [结构化规范数据](../component-data.json)（记录 id：`calendar`） - [原始历史样板](../original-20260621.html) - [历史规范条目](../spec-notes.json) ## 本组件颜色状态表 | 状态 / 条件 | 统一规则 | | --- | --- | | 普通日期 | 白底、正文深灰、分隔灰；非本月日期可用辅助深灰，事件内容保持可读。 | | 今天与选中日 | 今天用操作蓝文字；选中日期单元格用选中浅蓝，不绘制对勾或半选横线。 | | 悬停与键盘 | 实际可操作日期悬停或定位浅灰背景；当前选中底保持选中浅蓝；键盘焦点用操作蓝提示。 | | 不可选与内容反馈 | 只有业务明确不可选日期才用禁用灰并阻止选择；空事件用空值提示，读取失败在内容区错误红提示，不给日期画表单红框。 | 内容日历没有输入触发框、复选和半选；日期导航按钮按按钮规范，日格选择不套用主按钮按下位移。 [公共颜色与字体 token](../color-tokens.json) · [公共组件样式](../color-contract.css) · [系统字体合同（最后加载）](../font-contract.css) ## 业务落地场景 - [广告管理 · 广告投放日历](../../showcase/index.html?example=calendar#adverts) · [场景文档](../../showcase/docs/adverts.md) [竞品组件拆解](../../reference-review/竞品组件反推规范.html) · [业务场景分类](../../业务场景分类清单.md)