Atomic Calendar Revive 版本选择完整指南:Home Assistant 各版本兼容性与升级避坑

原创2026-11-03 12:29:121,906 阅读

Atomic Calendar Revive 版本选择完整指南:Home Assistant 各版本兼容性与升级避坑

Atomic Calendar Revive 是一款面向 Home Assistant 的进阶日历卡片(Calendar Card),支持 Google Calendar 与 CalDAV,提供事件列表、月视图等多种模式。选对卡片版本、正确匹配 Home Assistant 版本,是避免升级踩坑的关键。本文整理了各版本的兼容对照表和 5 个高频升级问题的一键排查思路,帮你快速定版、平滑升级。

先认识一下:这张日历卡片能做什么

Atomic Calendar Revive 在默认日历的基础上提供了大量可选配置(见 docs/configuration/main.rst),常用亮点包括:

  • 📋 事件列表模式与月视图模式两种主视图,另有 Planner、Inline 等扩展视图(源码位于 src/lib/views/)
  • 🔍 关键词白名单 / 黑名单过滤,隐藏已结束事件
  • 📊 事件进度条、相对时间提示、事件数量上限
  • 🌍 18 种语言本地化翻译(见 src/localize/languages/)
  • ✏️ 内置 Lovelace 图形编辑器,支持 YAML 精细配置

Atomic Calendar Revive 日历卡片事件列表模式效果

版本兼容对照表:30 秒查出该装哪个版本

官方在 README.md 中维护了一张兼容性对照表,核心内容如下:

卡片版本 兼容的 Home Assistant 版本 备注
v7.0.0 2022.6 及以上 当前推荐主线
v6.0.0 2021.11 及以上 旧版 HA 上进度条不生效
v5.0.0 – v5.2.2 2021.6 ~ 2021.10.x 更老的 HA 或可运行,但需手动设置 hoursFormat
v4.1.1 0.117 及以上 早期版本

⚠️ 重点提醒:Home Assistant 2022.5 无法使用这张卡片,必须升级到 2022.6 或更高版本——这是官方明确标注的最大坑。

当前开发版本号(10.x 系列)可在 package.json 中查看,HACS 安装信息定义在 hacs.json。较新的卡片版本(9、10 系列)面向更新的 HA 版本,安装前建议浏览对应 Release 的更新说明确认你的 HA 版本在支持范围内。

Atomic Calendar Revive 日历卡片月视图与事件标记效果

三种典型场景:快速定版

场景一:全新安装

直接选 HACS 上的最新版本即可。前提是 Home Assistant 中已配置好 Google Calendar)。

场景二:HA 版本较老

优先升级 Home Assistant,再装新版卡片。只有当 HA 确实无法升级时,才按上表"倒推":例如 HA 停留在 2021.6–2021.10,则固定 v5.2.2;停留在 2021.11–2022.5 区间,则注意 2022.5 不可用,需升到 2022.6 后使用 v7 及以上。

场景三:升级后出现问题

先回滚到上一个可用版本,确认问题是否由卡片版本引起。判断思路可参考 docs/contribute/bugs.rst。

另外,该项目遵循语义化版本(Semantic Versioning,见 docs/contribute/devcycle.rst):

  • Major(如 v9→v10):破坏性变更,可能需要用户手动调整配置
  • Minor:向后兼容的新功能
  • Patch:仅修 Bug

跨 Major 版本升级前,务必看一遍 Release 说明。

升级避坑:5 个最高频的问题

坑 1:升级后提示 "No card type configured"

多半是浏览器缓存了旧 JS。按 Ctrl+Shift+R(Mac 为 Shift+F5)强制刷新即可,升级文档中也专门提醒了这一点(见 docs/overview/quickstart.rst)。

坑 2:时间位置出现奇怪的数字

老配置中的 hoursFormat: 24h 已不再需要,直接从 YAML 中删掉该参数(见 docs/overview/faq.rst)。

坑 3:HA 2022.5 装不上 / 不显示

不是卡片 Bug,是版本不兼容,把 Home Assistant 升到 2022.6+ 即可。

坑 4:v9 之后自定义样式"失灵"

从 v9 开始,精细样式改为交由 card-mod 接管(通过 --cal-day-color 等 CSS 自定义属性控制),旧版的一键颜色参数不再适用。升级跨过大版本时,请对照 docs/configuration/styling.rst 调整配置。

坑 5:提示 "The calendar can't be loaded from Home Assistant component"

通常是日历组件未授权导致。Google Calendar 用户可删除 .google.token 文件后重新授权。

Atomic Calendar Revive 事件进度条与相对时间显示效果

升级实操:HACS 与手动两种方式

方式一:HACS(推荐)

  1. 打开 HACS,切换到 Frontend 标签页
  2. 搜索 Atomic Calendar Revive,查看可用更新
  3. 点击更新,等待下载完成
  4. 强制刷新浏览器缓存(Ctrl+Shift+R)
  5. 打开浏览器控制台,确认能看到卡片名称与版本号

方式二:手动安装

  1. 从最新 Release 的 dist 目录下载 atomic-calendar-revive.js
  2. 上传到 HA 的 /www/community/atomic-calendar-revive/atomic-calendar-revive.js
  3. 在 Lovelace Resources 中登记 /local/community/atomic-calendar-revive/atomic-calendar-revive.js(类型 module),或写入 ui-lovelace.yaml
  4. 强制刷新浏览器缓存

Atomic Calendar Revive 升级后日历模式今日事件显示效果

出问题后的排查顺序

按以下顺序自查,可覆盖绝大多数升级故障:

  1. 看控制台:确认卡片名称和版本号正常加载
  2. 对版本:确认 HA 版本与卡片版本在兼容表范围内
  3. 排主题干扰:临时切回默认主题,排除自定义主题冲突
  4. 做对比:回退旧版本确认问题是否由本次升级引入
  5. 报 Bug:提供 HA 版本、卡片版本与复现步骤,参考 docs/contribute/bugs.rst

小结

  • 新安装:HACS 装最新版,HA 保持 2022.6+(建议跟随最新稳定版)
  • 老 HA:能升 HA 就升 HA,升不了再按兼容表固定旧卡片版本
  • 升级前:看 Release 说明,跨 Major 版本重点关注配置变更(尤其 v9 的样式机制)
  • 升级后:强制刷新缓存,用控制台版本号确认加载成功

掌握这套"先定版、再升级、后排查"的流程,Atomic Calendar Revive 的版本选择与升级就会变得简单可控。

登录后查看全文
atomic-calendar-revive