【免费下载链接】v-calendar
An elegant calendar and datepicker plugin for Vue.
导读：v-calendar 是 Vue 生态中一款优雅的日历与日期选择器插件（当前仓库版本已迭代至 2.4.2）。v0.5 系列（v0.5.0 至 v0.5.5）是该插件从"基础日历渲染"迈向"可定制属性日历与复杂日期选择器"的关键里程碑：它在属性系统上新增了 day popover（日期气泡）、日期范围
span简写、事件回调中的targetDate、导航头部多态可见性、pane-width手动宽度控制等核心能力，并引入了componentPrefix插件级配置与 Jest 测试体系。阅读本文后，你将完整掌握 v0.5 引入的每项特性、对应的源码实现位置，以及它们对 v0.6 及后续版本（如dayclick事件对象化、input-props收敛、tint-color统一着色）产生的直接铺垫作用。
一、v0.5.0：奠定属性日历核心能力的首个大版本
v0.5.0 是 v0.5 系列中功能增量最集中的一次发布，它围绕"属性（attribute）驱动的日历"这一核心设计，同时打通了日期选择器与日历的联动。以下特性全部在本次发布中落地：
1. 为属性（Attribute）增加 Day Popover 支持
v0.5.0 支持为任意属性配置 popover（气泡提示），并且支持自定义插槽。该特性对应 GitHub Issue #13 的关闭。在今天的源码中，day popover 的渲染逻辑位于 Calendar.vue 的 getDayPopover 方法：它读取当天 attributes 中所有声明了 popover 配置的属性，按 dayPopover 掩码格式化日期标题，然后通过 day-popover 作用域插槽渲染自定义内容；未提供自定义插槽时，默认渲染 vc-day-popover-header 头部与逐条 PopoverRow 属性行。
从属性定义侧看，attribute.js 会原样保留属性对象上的 popover 字段，而日期选择器内部还会自动构造 select-drag 属性（见 DatePicker.vue 的 selectAttribute_ / dragAttribute_），为选中区与拖拽区生成 popover——这正是 v0.5.4 中"重新设计选中/拖拽区域 popover"的基础。
2. dayPopoverContent 主题样式
配合 popover 能力，本次发布了 dayPopoverContent 主题样式，允许开发者整体控制 popover 内容区的视觉呈现。主题样式的归一化逻辑集中在 theme.js 的 normalizeAttr：无论配置传布尔值、字符串（颜色名）还是对象，最终都会被归一化为 base / start / end 三个目标位点的样式结构，并自动补齐缺失的主题色。
3. 导航头部多态可见性：hover / focus / visible / hidden
导航（月/年切换）头部新增四种可见性模式，取代原先单一的显隐控制。在当前的默认配置中，导航可见性由 defaults/index.js 的 pluginDefaults 中的 navVisibility: 'click' 控制，而 Popover 的显隐状态机则由 popovers.js 统一管理。本次发布同时"简化了 popover 可见性状态转换"，为后续 v-date-picker 的 popover 属性配置（visibility: 'hover-focus' 等）打下了统一的实现基础。
4. 日期范围支持 span（天数长度）简写
在配置属性日期范围时，除了显式给出 start 与 end，v0.5.0 起可以使用 span 字段指定天数。该逻辑至今仍保留在 dateInfo.js 的构造函数：当 start 存在、span >= 1 且未显式指定 end 时，end = addDays(start, span - 1)，即从起始日顺延 span - 1 天得到结束日。这一简写让"持续 N 天的区间"表达变得非常直观。
5. 事件回调中的 targetDate 属性
当属性命中某个日期时，事件回调中现在可以拿到 targetDate，标识属性实际命中的那一天。该字段的注入逻辑可见于 Calendar.vue 的 refreshAttrs：每当属性与某天相交，attr.intersectsDay(d) 返回命中的日期信息，随后以 { ...attr, targetDate } 形式重建属性并写入当天的 attributesMap。这意味着在渲染回调中，你既能拿到原始属性配置，也能精确知道它命中的目标日期。
6. 触摸手势处理器抽取为独立状态函数
横向滑动翻页的手势识别被重构为独立模块。当前实现位于 touch.js 的 addHorizontalSwipeHandler，它通过 touchstart / touchend 记录起点与时间戳，在满足 maxSwipeTime、minHorizontalSwipeDistance、maxVerticalSwipeDistance 三个阈值后回调 { toLeft, toRight } 方向；Calendar.vue 的 mounted 钩子 在未禁用 disablePageSwipe 时挂载该处理器，左滑 moveNext()、右滑 movePrev()。状态抽取使手势逻辑与组件生命周期解耦，也方便后续复用与测试。
7. 运行时要求提升：Vue v2.5.0+
v0.5.0 起要求 Vue 2.5.0 及以上版本。当前 package.json 的 peerDependencies 声明 vue: ^2.5.18，与这一门槛保持延续。
二、v0.5.1：导航 Popover 布局修复与 CSS 变量体系重组
- Bug 修复：修复导航 popover 中的布局问题。导航 popover 的渲染入口位于 Calendar.vue 的 getNavPopover，它复用
Popover组件承载CalendarNav，布局问题主要出现在箭头按钮与标题的定位协同上。 - 改进：重组 CSS 变量并改善默认样式。当前基础样式集中在 src/styles/base.css，
Calendar.vue的样式块中大量使用var(--gray-*)、var(--rounded)、var(--shadow)等语义化变量（见.vc-day-popover-container等规则），正是本次"CSS 变量化"持续演进的结果，使得主题定制只需覆盖变量即可。
三、v0.5.2：日期事件参数修复、自定义 Cap 样式与 show-caps
1. 修复日期事件的错误/缺失参数
修复了日期事件回调中参数错误或缺失的问题（Issue #33）。虽然当时的参数传递方式在 v0.6.0 中被整体替换为单一对象参数（见 v0.6 变更日志 的 day 事件参数表），但 v0.5.2 的这次修复保证了事件参数在旧接口下的正确性与稳定性。
2. 允许自定义 highlight 与 content 样式属性的 Cap 样式
"Cap" 指日期范围首尾（start / end）两个端点单元格的呈现。v0.5.2 允许开发者为 highlight 和 content 类属性自定义端点样式。对应能力在 theme.js 的 normalizeAttr 中有完整体现：配置对象可以显式声明 base / start / end / startEnd 四个目标位点，也可以只写通用样式，由归一化逻辑自动平铺到三个位点并补齐颜色，实现"全区间统一、首尾端特殊"的灵活组合。
3. 新增 show-caps 属性（日期选择器）
v-date-picker 新增 show-caps 属性，用于控制是否显示选中区间首尾的端点标记（cap）。从 DatePicker.vue 的 dragAttribute_ 默认值 可以看出，拖拽属性默认使用 highlight: { startEnd: { fillMode: 'outline' } } 作为占位样式，而 show-caps 决定这些端点是否参与渲染，是调整区间视觉密度的重要开关。
4. 新增瑞典语翻译
本地化词典在 defaults/locales.js 中登记了 sv: { dow: 2, L: 'YYYY-MM-DD' }，即瑞典语首日为周一、长日期格式为 YYYY-MM-DD。当前该文件已收录 40+ 语言地区条目，任何新语言只需在此追加一行 { dow, L } 配置即可接入。
四、v0.5.3：disabled-dates 与日期范围的交集检测
v0.5.3 修复了禁用日期与日期范围之间的交集检测（Issue #12），确保当禁用区间与所选/拖拽区间重叠时能够正确拦截。这一能力沉淀在属性系统的日期交集算法中：
- attribute.js 的 intersectsDate：判断属性日期是否与给定日期/范围部分相交；
- dateInfo.js 的 dateShallowIntersectsDate：对两个范围做浅层交集判断（端点比较）；
- DatePicker.vue 的 valueIsDisabled：选择器在赋值前用
disabledAttribute.intersectsDate(value)校验，命中禁用区间则拒绝赋值并回退到旧值（拖拽中则直接忽略）。
这套"属性归一化 → 浅层交集 → 深度模式匹配"的三级检测链路，是 v0.5.3 修复的核心支撑，也是后续 v0.6.1 中"提高日期交集检测效率"的优化对象。
五、v0.5.4：增强渲染能力与插件化配置的重要版本
v0.5.4 是本系列中除 v0.5.0 外增量最大的一次发布，横跨日历渲染、插件注册与日期选择器体验三个方面。
1. header-title 插槽获得 page 属性
日历标题插槽现在可以收到完整的 page 对象。page 对象由 Calendar.vue 的 buildPage 构造，包含 key / month / year / weeks / title / monthLabel / shortMonthLabel / shortYearLabel / yearLabel 以及 canMove / move / moveThisMonth / movePrevMonth / moveNextMonth 等导航方法，模板层可以直接消费这些字段做自定义标题。
2. 新增 pane-width 属性
v-calendar 新增 pane-width 属性，允许手动指定日历面板宽度；同时它成为可通过默认配置（defaults）设置的全局项。结合默认配置体系（defaults/index.js 的 setupDefaults 与 propOrDefault），使用者既可以在组件上传 prop 覆盖，也可以通过 setupCalendar({ ... }) 为所有实例统一设定，实现了"组件级覆盖、全局级兜底"的双层取值模型。
3. shortMonthLabel 与 shortYearLabel 属性
page 对象新增 shortMonthLabel（如 "Jan"）与 shortYearLabel（如 "21"，取年份后两位），实现见 buildPage：前者用 MMM 掩码格式化，后者直接 year.toString().substring(2)。它们为紧凑型标题、分组导航等场景提供了现成的短标签。
4. 非当月单元格样式联动：dayCellNotInMonth 的 opacity: 0
当 theme-styles.dayCellNotInMonth 中设置了 opacity: 0 时，非当月日单元格将禁用指针事件（不可点击）。这是主题样式与交互行为的联动优化：视觉上隐藏的单元格不应再响应点击，避免用户误操作。此类"样式配置驱动交互行为"的模式在 v-calendar 的主题体系中具有代表性。
5. 新增 componentPrefix 构造器选项
使用插件注册时，可以通过 componentPrefix 选项定制组件前缀（默认 v）。对应实现位于 defaults/index.js 的 pluginDefaults，默认值为 'v'；开发者传入如 componentPrefix: 'vc' 后，即可使用 <vc-calendar>、<vc-date-picker> 等自定义前缀组件，避免与既有全局组件命名冲突（Issue #37）。这也解释了为什么官方文档示例中组件名统一为 v-calendar / v-date-picker。
6. 日期选择器 Popover 交互重构
- 重新设计了
v-date-picker中选中区与拖拽区的 popover 视觉（沿用"属性 popover"机制，即选中/拖拽区域本身是select-drag属性，携带 popover 配置）； - 新增
show-popover属性，可整体隐藏选中/拖拽区域的 popover； - 支持通过
component属性为 popover 指定自定义组件，实现对提示内容的完全接管； - 输入框在使用带
disabled-dates/available-dates的日期掩码时，不再强制要求readonly属性——输入与禁用校验可以并存。
7. 测试框架迁移至 Jest
v0.5.4 将测试框架迁移到 Jest，并新增了日期冲突检测的测试用例。当前仓库的 Jest 配置与单元测试分别位于 jest.config.js 与 tests/unit/specs，其中 Calendar.spec.js、DatePicker.spec.js 等规格文件覆盖了渲染与交互行为，而 disabledTests.js 集中沉淀了禁用日期场景的断言逻辑，是 v0.5.3 日期交集检测修复的可回归证据。
六、v0.5.5：firstDayOfWeek 非 1 时的上月日期计算修复
v0.5.5 修复了当 firstDayOfWeek !== 1 时，上一月日期编号计算错误的问题（Issue #44）。该问题与日历栅格的周起始日换算直接相关——dateInfo.js 的 startOfWeek 展示了按 firstDayOfWeek 归位到周起始日的核心算法：当 day >= firstDayOfWeek 时前移 firstDayOfWeek - day 天，否则回退 -(7 - (firstDayOfWeek - day)) 天。周起始日的正确性直接影响上月补位日期的编号与 week / weekdayOrdinal 等派生字段，因此这一修复对启用不同 dow 的地区（如 locales.js 中 dow: 2 的 zh-CN、dow: 1 的 en-US 等）都至关重要。
七、v0.5 系列的承上启下：走向 v0.6 的铺垫
理解 v0.5 的价值，还需要看到它为 v0.6 及后续版本铺平的道路：
- 事件参数对象化：v0.5.2 修复事件参数后，v0.6.0 将
dayselect重命名为dayclick，并把多参数顺序传递改为包含day / weekday / week / month / year / date / attributes / attributesMap / event等 19 个字段的单一对象（完整字段表见 v0.6 变更日志），从根本上解决了"必须记住参数顺序"的痛点； - Popover 状态机统一：v0.5.0 简化 popover 可见性状态转换、v0.5.4 重设计选中/拖拽 popover，最终在 v0.6.0 演进为
v-date-picker的popover配置对象与visibility选项； - 输入框属性收敛：v0.5.4 放开输入框
readonly限制后，v0.6.0 进一步用input-props对象替换全部input...系列属性； - 着色体系收敛：v0.6.0 用
tint-color统一替代select-color与drag-color，其"拖拽属性透明度 0.5"的默认行为正是对 v0.5.4 拖拽区 popover 重构的延续； - 图标系统：v0.6.2 起以 SVG 图标替换字体图标（关闭 Issue #59），今日 Calendar.vue 中
SvgIcon的left-arrow/right-arrow即该迁移的最终形态。
八、实践建议：如何安全地使用 v0.5 时代引入的 API
虽然当前仓库版本已远超 v0.5，但 v0.5 确立的许多 API 仍然可用且值得遵循：
- 属性区间优先使用
span而非手工计算end：span语义清晰且自动处理加减一天，见 dateInfo.js； - 利用
targetDate区分"属性配置"与"实际命中日期"：在自定义 content 插槽或事件回调中，优先从attributesMap读取带targetDate的属性对象； - 通过
componentPrefix规避全局组件名冲突：在大型应用中注册时显式指定前缀； - 用
pane-width或全局 defaults 统一日历宽度：组件级 prop 优先，全局setupCalendar兜底； - 迁移注意：若你的代码基于 v0.5 的事件多参数接口，请参照 v0.6 事件参数表 迁移到单对象参数，以获得更稳定的字段契约。
参考资料
- 本文核心依据：docs/changelog/v0.5.md
- 关联版本演进：docs/changelog/v0.6.md、CHANGELOG.md
- 核心实现：Calendar.vue、DatePicker.vue、attribute.js、dateInfo.js、theme.js
- 配置体系：src/utils/defaults/index.js、src/utils/defaults/locales.js
- 测试佐证：tests/unit/specs、tests/unit/util/disabledTests.js
【免费下载链接】v-calendar
An elegant calendar and datepicker plugin for Vue.
创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
