Element UI 日历组件el-calendar完整使用指南与源码实现解析【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/elementElement UIVue.js 2.0 UI Toolkit for Web提供的el-calendar日历组件用于以月视图形式展示日期并支持通过value/v-model双向绑定选中日期、通过range限定显示区间、通过dateCell作用域插槽scoped slot自由定制每个单元格的内容。本文以 examples/docs/fr-FR/calendar.md 为骨架结合仓库中packages/calendar的源码实现与单元测试完整讲解该组件的全部用法、API 参数及其底层工作机制帮助你直接上手并在项目中灵活定制。一、组件定位与基本用法el-calendar的核心作用就是“显示日期”——以月为粒度渲染一个日历网格。最基础的用法是设置value指定当前显示的月份如果value未指定则默认显示当月。value支持v-model双向绑定用户点击任意日期后绑定值会被更新为对应的Date对象。el-calendar v-modelvalue /el-calendar script export default { data() { return { value: new Date() } } } /script上述写法即 examples/docs/fr-FR/calendar.md 中“Usage basique”基本用法一节的完整示例直接复制即可运行。从源码角度看value的类型在 packages/calendar/src/main.vue 中定义为[Date, String, Number]即同时接受Date对象、ISO 格式日期字符串或时间戳数值。组件内部通过toDate(val)方法见 packages/calendar/src/main.vue统一将各类输入归一化为Date对象当用户点击某一天时realSelectedDay的 setter 会触发this.$emit(input, date)从而完成v-model的双向更新见 packages/calendar/src/main.vue。顶部的月份切换按钮当没有设置range时日历头部el-calendar__header会渲染一组按钮组el-button-group包含“上个月 / 今天 / 下个月”三个按钮见 packages/calendar/src/main.vue按钮文案取自el.datepicker.prevMonth、el.datepicker.today、el.datepicker.nextMonth的国际化配置因此会跟随 src/locale 下的语言包自动本地化。点击按钮会调用selectDate(type)该方法内部仅接受prev-month、today、next-month三种合法类型其余值会抛出invalid type异常见 packages/calendar/src/main.vue。二、使用dateCell作用域插槽自定义单元格内容默认情况下日历每个单元格只显示一个日期数字。若需要在单元格中展示自定义内容例如标记节假日、展示日程、附加图标等可以通过名为dateCell的作用域插槽实现el-calendar !-- 这里使用的是 Vue 2.5 的 slot 语法对于新项目请使用 Vue 2.6 的新插槽语法 -- template slotdateCell slot-scope{date, data} p :classdata.isSelected ? is-selected : {{ data.day.split(-).slice(1).join(-) }} {{ data.isSelected ? ✔️ : }} /p /template /el-calendar style .is-selected { color: #1989FA; } /style示例中通过data.day.split(-).slice(1).join(-)将yyyy-MM-dd格式的日期裁剪为MM-dd展示并在日期被选中时附加✔️标识、加上.is-selected样式。这段示例来自 examples/docs/fr-FR/calendar.md 的“Contenu personnalisé”一节其注释也明确提示示例使用 Vue 2.5 插槽语法Vue 2.6 项目应改用v-slot新语法。插槽参数说明dateCell slot 参数dateCell作用域插槽对外暴露两个参数说明如下参数说明类型可选值默认值date单元格代表的日期Date——data{ type, isSelected, day }type表示该日期所属月份可选值有prev-month、current-month、next-monthisSelected标明该日期是否被选中day是格式化后的日期格式为yyyy-MM-ddObject——从源码看这两个参数正是在 packages/calendar/src/date-table.vue 的cellRenderProxy方法中组装的组件取出elCalendar.$scopedSlots.dateCell若未提供插槽则默认渲染span{ text }/span否则将每个单元格构造为const day this.getFormateDate(text, type); const date new Date(day); const data { isSelected: this.selectedDay day, type: ${type}-month, // 即 prev-month / current-month / next-month day }; return render({ date, data });值得注意的细节是type在内部计算时取值为prev/current/next对应行内getCellClass中使用的原始类型对外暴露时拼接为prev-month/current-month/next-month与文档表格中列出的可选值完全一致。三、使用range限定显示区间当业务场景只需要展示某一段日期例如从某周一至某周日时可设置range属性el-calendar :range[2019-03-04, 2019-03-24] /el-calendar该用法来自 examples/docs/fr-FR/calendar.md 的“Intervalle”区间一节。使用时有三个硬性约束组件会逐一校验开始时间必须是周起始日默认周一结束时间必须是周结束日默认周日时间跨度不能超过两个月传入方式为包含两个元素的数组每个元素可以是日期字符串、数字或Date对象。range属性的 prop 定义带有自定义校验器见 packages/calendar/src/main.vue数组长度必须为 2且每个元素必须是string、number或Date实例否则校验失败。区间模式的内部处理逻辑validatedRange计算属性见 packages/calendar/src/main.vue承载了区间校验与拆分的核心逻辑首先对区间起点和终点分别调用rangeValidator校验“周起始/周结束”约束不合法时向控制台输出[ElementCalendar]前缀的警告start/end of range should be xxx并忽略该端点若起点晚于终点输出end time should be greater than start time警告并返回空数组若起止日期在同一月份内通过 src/utils/date-util.js 的validateRangeInOneMonth判断则只渲染一张日期表若跨月但总跨度不超过两个月则拆分为两张日期表第一张表覆盖当月从起点到月末第二张表从下月第一个周起始日覆盖到终点若下月首日到终点的跨度不足一周则仅渲染一张表。在模板中见 packages/calendar/src/main.vue是否设置range直接决定了渲染分支未设置时渲染单张date-table并显示头部按钮组设置后按validatedRange逐段渲染多张date-table且只有第一张显示表头:hide-headerindex ! 0同时隐藏顶部月份切换按钮。date-table组件内部在区间模式下会精确截取区间内的日期currentMonthRange并补足到整周nextMonthRange见 packages/calendar/src/date-table.vue。四、组件属性 API 一览el-calendar支持的属性完整汇总如下源自 examples/docs/fr-FR/calendar.md 的“Attributs”一节属性说明类型可选值默认值value / v-model绑定值Date/string/number——range时间范围含开始与结束时间。开始时间必须是周起始日结束时间必须是周结束日且时间跨度不能超过两个月Array——first-day-of-week周起始日Number1 到 71其中first-day-of-week的取值语义值得展开说明源码中realFirstDayOfWeek计算属性见 packages/calendar/src/main.vue对传入值做了规整——当值小于 1 或大于 6 时回退为0并向下取整。因此传1默认值表示周一作为每周第一天传0表示周日作为每周第一天符合美式日历习惯见下方测试用例传7实际等价于0周日。该值同时影响两处行为一是表头星期的排列顺序二是首行单元格的起始偏移。在date-table.vue中weekDays计算属性packages/calendar/src/date-table.vue会根据firstDayOfWeek将国际化星期名数组做循环位移rows计算属性则通过(7 firstDay - firstDayOfWeek) % 7计算月初之前的补位天数packages/calendar/src/date-table.vue补位日期来自上月的最后几天getPrevMonthLastDays。五、源码结构全景与工作机制el-calendar的实现集中在packages/calendar目录整体结构非常精简packages/calendar/ ├── index.js # 组件入口注册为 ElCalendar └── src/ ├── main.vue # 日历主组件props 校验、区间拆分、选中逻辑、头部 └── date-table.vue # 日期网格渲染行列生成、单元格状态、dateCell 插槽代理packages/calendar/index.js 将主组件挂载为Vue.component(Calendar.name, Calendar)组件name为ElCalendar因此标签名为el-calendarmain.vue通过provide向子组件注入elCalendar实例packages/calendar/src/main.vuedate-table.vue用inject接收并借此访问父组件的$scopedSlots.dateCell与formatedTodaypackages/calendar/src/date-table.vue日期相关的纯工具函数getFirstDayOfMonth、getPrevMonthLastDays、getMonthDays、validateRangeInOneMonth等统一沉淀在 src/utils/date-util.js与 date-picker 等其他日期组件共享体现 Element UI 工具层复用的设计默认渲染采用固定 6 行 × 7 列的网格rangeArr(42 - days.length)补齐保证月视图布局稳定。选中与今日状态的样式标识date-table.vue的getCellClass方法packages/calendar/src/date-table.vue为单元格追加语义化 class当前月日期附加current选中日期附加is-selected今天附加is-today。对应样式定义在 packages/theme-chalk/src/calendar.scss选中单元格使用主题变量$--calendar-selected-background-color高亮背景今天则使用主题色$--color-primary着色文字非当前月的prev/next单元格使用占位色$--color-text-placeholder。整个组件样式基于 BEM 命名.el-calendar__header、.el-calendar__body、.el-calendar-table等可通过覆盖 SCSS 变量或引入主题定制进行视觉调整。六、单元测试对核心行为的验证仓库在 test/unit/specs/calendar.spec.js 中为日历组件提供了 5 组测试用例可作为理解组件行为边界的权威参考create基础创建与选中联动传入2019-04-01的value后断言标题包含2019与月份4表头存在 7 个th默认渲染 6 行日期行点击最后一行首个单元格后标题切换为 5 月且v-model绑定的value变为2019-05-06选中单元格显示6——完整验证了点击切换月份与双向绑定闭环range单月区间使用[2019-03-04, 2019-03-24]断言只渲染 3 行区间不足四周时行数按需缩减且头部按钮组el-calendar__button-group为null——验证区间模式下隐藏切换按钮range tow monthes跨月区间使用[2019-04-15, 2019-05-19]断言渲染两张is-range日期表共 5 行点击最后一张表首格后标题切换为 5 月且该格获得is-selected——验证跨月拆分为两张表及区间内选中逻辑firstDayOfWeekfirst-day-of-week传0时表头首列为“日”、末列为“六”首行首格为上月31号——验证周起始日对表头与补位日期的影响firstDayOfWeek in range modefirst-day-of-week传7等价 0配合[2019-02-03, 2019-03-23]区间表头仍从“日”开始——验证区间模式下周起始日同样生效。这些用例所断言的标题格式年 月与 packages/calendar/src/main.vue 中i18nDate的计算方式${year} ${t(el.datepicker.year)} ${t(el.datepicker.month month)}一一对应。七、总结与选型建议el-calendar以极小的 API 面3 个属性 1 个作用域插槽覆盖了日历展示的核心场景需要整月浏览、点击选日期并回写数据时使用v-model绑定value即可需要月历看板、排期标记等富内容场景优先使用dateCell插槽结合data.type/data.isSelected/data.day做条件渲染需要固定展示某段日期如考勤周期、排班表时使用range并牢记“周起始日对齐 跨度不超过两个月”的约束需要改变一周从周几开始时使用first-day-of-week1 表示周一0 或 7 表示周日。若需要查看法语版原始文档可阅读 examples/docs/fr-FR/calendar.md中文版对照见 examples/docs/zh-CN/calendar.md。配合源码 packages/calendar/src/main.vue 与 packages/calendar/src/date-table.vue 阅读即可完整掌握该组件从属性校验、区间拆分到单元格渲染的全部细节。【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Element UI 日历组件el-calendar完整使用指南与源码实现解析【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/elementElement UIVue.js 2.0 UI Toolkit for Web提供的el-calendar日历组件用于以月视图形式展示日期并支持通过value/v-model双向绑定选中日期、通过range限定显示区间、通过dateCell作用域插槽scoped slot自由定制每个单元格的内容。本文以 examples/docs/fr-FR/calendar.md 为骨架结合仓库中packages/calendar的源码实现与单元测试完整讲解该组件的全部用法、API 参数及其底层工作机制帮助你直接上手并在项目中灵活定制。一、组件定位与基本用法el-calendar的核心作用就是“显示日期”——以月为粒度渲染一个日历网格。最基础的用法是设置value指定当前显示的月份如果value未指定则默认显示当月。value支持v-model双向绑定用户点击任意日期后绑定值会被更新为对应的Date对象。el-calendar v-modelvalue /el-calendar script export default { data() { return { value: new Date() } } } /script上述写法即 examples/docs/fr-FR/calendar.md 中“Usage basique”基本用法一节的完整示例直接复制即可运行。从源码角度看value的类型在 packages/calendar/src/main.vue 中定义为[Date, String, Number]即同时接受Date对象、ISO 格式日期字符串或时间戳数值。组件内部通过toDate(val)方法见 packages/calendar/src/main.vue统一将各类输入归一化为Date对象当用户点击某一天时realSelectedDay的 setter 会触发this.$emit(input, date)从而完成v-model的双向更新见 packages/calendar/src/main.vue。顶部的月份切换按钮当没有设置range时日历头部el-calendar__header会渲染一组按钮组el-button-group包含“上个月 / 今天 / 下个月”三个按钮见 packages/calendar/src/main.vue按钮文案取自el.datepicker.prevMonth、el.datepicker.today、el.datepicker.nextMonth的国际化配置因此会跟随 src/locale 下的语言包自动本地化。点击按钮会调用selectDate(type)该方法内部仅接受prev-month、today、next-month三种合法类型其余值会抛出invalid type异常见 packages/calendar/src/main.vue。二、使用dateCell作用域插槽自定义单元格内容默认情况下日历每个单元格只显示一个日期数字。若需要在单元格中展示自定义内容例如标记节假日、展示日程、附加图标等可以通过名为dateCell的作用域插槽实现el-calendar !-- 这里使用的是 Vue 2.5 的 slot 语法对于新项目请使用 Vue 2.6 的新插槽语法 -- template slotdateCell slot-scope{date, data} p :classdata.isSelected ? is-selected : {{ data.day.split(-).slice(1).join(-) }} {{ data.isSelected ? ✔️ : }} /p /template /el-calendar style .is-selected { color: #1989FA; } /style示例中通过data.day.split(-).slice(1).join(-)将yyyy-MM-dd格式的日期裁剪为MM-dd展示并在日期被选中时附加✔️标识、加上.is-selected样式。这段示例来自 examples/docs/fr-FR/calendar.md 的“Contenu personnalisé”一节其注释也明确提示示例使用 Vue 2.5 插槽语法Vue 2.6 项目应改用v-slot新语法。插槽参数说明dateCell slot 参数dateCell作用域插槽对外暴露两个参数说明如下参数说明类型可选值默认值date单元格代表的日期Date——data{ type, isSelected, day }type表示该日期所属月份可选值有prev-month、current-month、next-monthisSelected标明该日期是否被选中day是格式化后的日期格式为yyyy-MM-ddObject——从源码看这两个参数正是在 packages/calendar/src/date-table.vue 的cellRenderProxy方法中组装的组件取出elCalendar.$scopedSlots.dateCell若未提供插槽则默认渲染span{ text }/span否则将每个单元格构造为const day this.getFormateDate(text, type); const date new Date(day); const data { isSelected: this.selectedDay day, type: ${type}-month, // 即 prev-month / current-month / next-month day }; return render({ date, data });值得注意的细节是type在内部计算时取值为prev/current/next对应行内getCellClass中使用的原始类型对外暴露时拼接为prev-month/current-month/next-month与文档表格中列出的可选值完全一致。三、使用range限定显示区间当业务场景只需要展示某一段日期例如从某周一至某周日时可设置range属性el-calendar :range[2019-03-04, 2019-03-24] /el-calendar该用法来自 examples/docs/fr-FR/calendar.md 的“Intervalle”区间一节。使用时有三个硬性约束组件会逐一校验开始时间必须是周起始日默认周一结束时间必须是周结束日默认周日时间跨度不能超过两个月传入方式为包含两个元素的数组每个元素可以是日期字符串、数字或Date对象。range属性的 prop 定义带有自定义校验器见 packages/calendar/src/main.vue数组长度必须为 2且每个元素必须是string、number或Date实例否则校验失败。区间模式的内部处理逻辑validatedRange计算属性见 packages/calendar/src/main.vue承载了区间校验与拆分的核心逻辑首先对区间起点和终点分别调用rangeValidator校验“周起始/周结束”约束不合法时向控制台输出[ElementCalendar]前缀的警告start/end of range should be xxx并忽略该端点若起点晚于终点输出end time should be greater than start time警告并返回空数组若起止日期在同一月份内通过 src/utils/date-util.js 的validateRangeInOneMonth判断则只渲染一张日期表若跨月但总跨度不超过两个月则拆分为两张日期表第一张表覆盖当月从起点到月末第二张表从下月第一个周起始日覆盖到终点若下月首日到终点的跨度不足一周则仅渲染一张表。在模板中见 packages/calendar/src/main.vue是否设置range直接决定了渲染分支未设置时渲染单张date-table并显示头部按钮组设置后按validatedRange逐段渲染多张date-table且只有第一张显示表头:hide-headerindex ! 0同时隐藏顶部月份切换按钮。date-table组件内部在区间模式下会精确截取区间内的日期currentMonthRange并补足到整周nextMonthRange见 packages/calendar/src/date-table.vue。四、组件属性 API 一览el-calendar支持的属性完整汇总如下源自 examples/docs/fr-FR/calendar.md 的“Attributs”一节属性说明类型可选值默认值value / v-model绑定值Date/string/number——range时间范围含开始与结束时间。开始时间必须是周起始日结束时间必须是周结束日且时间跨度不能超过两个月Array——first-day-of-week周起始日Number1 到 71其中first-day-of-week的取值语义值得展开说明源码中realFirstDayOfWeek计算属性见 packages/calendar/src/main.vue对传入值做了规整——当值小于 1 或大于 6 时回退为0并向下取整。因此传1默认值表示周一作为每周第一天传0表示周日作为每周第一天符合美式日历习惯见下方测试用例传7实际等价于0周日。该值同时影响两处行为一是表头星期的排列顺序二是首行单元格的起始偏移。在date-table.vue中weekDays计算属性packages/calendar/src/date-table.vue会根据firstDayOfWeek将国际化星期名数组做循环位移rows计算属性则通过(7 firstDay - firstDayOfWeek) % 7计算月初之前的补位天数packages/calendar/src/date-table.vue补位日期来自上月的最后几天getPrevMonthLastDays。五、源码结构全景与工作机制el-calendar的实现集中在packages/calendar目录整体结构非常精简packages/calendar/ ├── index.js # 组件入口注册为 ElCalendar └── src/ ├── main.vue # 日历主组件props 校验、区间拆分、选中逻辑、头部 └── date-table.vue # 日期网格渲染行列生成、单元格状态、dateCell 插槽代理packages/calendar/index.js 将主组件挂载为Vue.component(Calendar.name, Calendar)组件name为ElCalendar因此标签名为el-calendarmain.vue通过provide向子组件注入elCalendar实例packages/calendar/src/main.vuedate-table.vue用inject接收并借此访问父组件的$scopedSlots.dateCell与formatedTodaypackages/calendar/src/date-table.vue日期相关的纯工具函数getFirstDayOfMonth、getPrevMonthLastDays、getMonthDays、validateRangeInOneMonth等统一沉淀在 src/utils/date-util.js与 date-picker 等其他日期组件共享体现 Element UI 工具层复用的设计默认渲染采用固定 6 行 × 7 列的网格rangeArr(42 - days.length)补齐保证月视图布局稳定。选中与今日状态的样式标识date-table.vue的getCellClass方法packages/calendar/src/date-table.vue为单元格追加语义化 class当前月日期附加current选中日期附加is-selected今天附加is-today。对应样式定义在 packages/theme-chalk/src/calendar.scss选中单元格使用主题变量$--calendar-selected-background-color高亮背景今天则使用主题色$--color-primary着色文字非当前月的prev/next单元格使用占位色$--color-text-placeholder。整个组件样式基于 BEM 命名.el-calendar__header、.el-calendar__body、.el-calendar-table等可通过覆盖 SCSS 变量或引入主题定制进行视觉调整。六、单元测试对核心行为的验证仓库在 test/unit/specs/calendar.spec.js 中为日历组件提供了 5 组测试用例可作为理解组件行为边界的权威参考create基础创建与选中联动传入2019-04-01的value后断言标题包含2019与月份4表头存在 7 个th默认渲染 6 行日期行点击最后一行首个单元格后标题切换为 5 月且v-model绑定的value变为2019-05-06选中单元格显示6——完整验证了点击切换月份与双向绑定闭环range单月区间使用[2019-03-04, 2019-03-24]断言只渲染 3 行区间不足四周时行数按需缩减且头部按钮组el-calendar__button-group为null——验证区间模式下隐藏切换按钮range tow monthes跨月区间使用[2019-04-15, 2019-05-19]断言渲染两张is-range日期表共 5 行点击最后一张表首格后标题切换为 5 月且该格获得is-selected——验证跨月拆分为两张表及区间内选中逻辑firstDayOfWeekfirst-day-of-week传0时表头首列为“日”、末列为“六”首行首格为上月31号——验证周起始日对表头与补位日期的影响firstDayOfWeek in range modefirst-day-of-week传7等价 0配合[2019-02-03, 2019-03-23]区间表头仍从“日”开始——验证区间模式下周起始日同样生效。这些用例所断言的标题格式年 月与 packages/calendar/src/main.vue 中i18nDate的计算方式${year} ${t(el.datepicker.year)} ${t(el.datepicker.month month)}一一对应。七、总结与选型建议el-calendar以极小的 API 面3 个属性 1 个作用域插槽覆盖了日历展示的核心场景需要整月浏览、点击选日期并回写数据时使用v-model绑定value即可需要月历看板、排期标记等富内容场景优先使用dateCell插槽结合data.type/data.isSelected/data.day做条件渲染需要固定展示某段日期如考勤周期、排班表时使用range并牢记“周起始日对齐 跨度不超过两个月”的约束需要改变一周从周几开始时使用first-day-of-week1 表示周一0 或 7 表示周日。若需要查看法语版原始文档可阅读 examples/docs/fr-FR/calendar.md中文版对照见 examples/docs/zh-CN/calendar.md。配合源码 packages/calendar/src/main.vue 与 packages/calendar/src/date-table.vue 阅读即可完整掌握该组件从属性校验、区间拆分到单元格渲染的全部细节。【免费下载链接】elementA Vue.js 2.0 UI Toolkit for Web项目地址: https://gitcode.com/gh_mirrors/eleme/element创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
