gavin/kindle-calendar
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e5becf63cf1d12977c9aa6b014718424653fbfb9
kindle-calendar/dash/docs/theme-switching-plan.zh.md
douboer@gmail.com e5becf63cf update at 2026-03-16 10:41:39
2026-03-16 10:41:39 +08:00

13 KiB
Raw Blame History

Kindle Dashboard 多主题方案

1. 背景

当前链路已经稳定分成两部分：

  • calendar/ 负责渲染网页和导出背景图
  • dash/ 运行在 Kindle 上，负责拉取背景图并在本地重画时钟

这里先明确一个约束，后续方案都基于它展开：

  • Kindle 端仍然保持“拉背景图片 + 绘制时钟”的职责
  • 不把整页日历渲染放回 Kindle
  • 主题的名称、路径、时钟占位信息都由 calendar/ 提供

这次多主题方案要同时满足两类需求：

  1. 访问 calendar 网站时，可以在页面上切换主题预览效果
  2. 后续 Kindle 端如果需要切换主题，也只依赖 calendar 提供的主题配置，不自己猜路径或布局

2. 目标

本方案的目标是：

  1. 访问网站时，可以通过顶部可选菜单切换主题样式
  2. 网站预览效果应尽量与 Kindle 最终显示效果一致
  3. 当前背景生成流程继续可用，不因主题预览被破坏
  4. calendar/ 提供统一的主题清单 JSON，作为主题的单一真相源
  5. Kindle 只需要读取固定位置的主题清单和主题配置 JSON
  6. Kindle 切换主题后，应立即拉取该主题背景和主题级配置并刷新
  7. 时钟的位置、尺寸和绘制参数由 calendar 的主题配置决定，Kindle 不自行决定

非目标：

  • 不在 Kindle 上重新渲染整张页面
  • 不让 Kindle 维护主题路径规则
  • 不要求第一阶段就把现有导出脚本改成强制批量导出
  • 不要求第一阶段就做“本地表盘素材包”体系

3. 设计原则

3.1 calendar/ 是主题真相源

主题系统的单一真相源放在 calendar/ 侧。

建议由 calendar/ 产出：

  • 一个主题清单文件，例如 themes.json
  • 每个主题自己的配置文件，例如 default.json、paper.json
  • 每个主题自己的背景图

其中 themes.json 至少描述：

  • 有哪些主题
  • 每个主题叫什么名字
  • 每个主题的配置 JSON 在哪里
  • 默认主题是谁

这样做的好处是：

  • 主题路径由 calendar 管理，不在 Kindle 端写死
  • 新增主题时，Kindle 无需改代码里的路径规则
  • 网站预览和 Kindle 切换都依赖同一套主题元数据

这里再明确一下边界。

远端主题配置只有两类：

  • themes.json
  • 每个主题自己的 JSON，例如 themes/default.json

除此之外：

  • 背景图属于资源文件，不属于主题配置
  • Kindle 本地缓存属于运行时状态，不属于主题配置

3.2 网站预览与导出解耦

主题预览只是网站访问时的交互能力，不应破坏当前导出主流程。

建议明确两条链路：

  • 预览链路：用户访问 /?mode=full&theme=<id>，通过页面菜单切换主题
  • 导出链路：现有脚本继续生成默认背景图，保持兼容

也就是说：

  • 预览能力先落地
  • 当前 kindlebg.png 导出链路先不强制变化
  • 多主题导出作为后续增量能力接入

3.3 Kindle 侧最简化

Kindle 侧只保留最小能力：

  • 拉取背景图
  • 读取主题 JSON
  • 按 JSON 提供的时钟参数绘制时钟

Kindle 不负责：

  • 推导主题路径
  • 决定时钟区域坐标
  • 维护主题布局规则

推荐让 Kindle 只认识一个固定入口，例如：

https://shell.biboer.cn:20001/themes.json

然后从这个 JSON 中知道：

  • 当前有哪些主题
  • 每个主题的配置 JSON 在哪里
  • 切换到该主题时该去拉哪个背景图

3.4 当前时钟实现已经足够轻量

当前 Kindle 侧时钟是本地几何绘制，不依赖外部表盘或指针素材文件。

这意味着第一阶段主题切换只需要关注：

  • 背景图 URL
  • 时钟区域位置和尺寸
  • 本地绘制时钟所需的参数

不需要先引入复杂的“主题素材包”机制。

4. 数据约定

4.1 主题清单 themes.json

建议由 calendar/ 在固定位置提供主题清单，例如：

{
  "updatedAt": "2026-03-16T10:00:00+08:00",
  "defaultThemeId": "default",
  "themes": [
    {
      "id": "default",
      "label": "Default",
      "configUrl": "https://shell.biboer.cn:20001/themes/default.json",
      "previewQuery": "?mode=full&theme=default"
    },
    {
      "id": "paper",
      "label": "Paper",
      "configUrl": "https://shell.biboer.cn:20001/themes/paper.json",
      "previewQuery": "?mode=full&theme=paper"
    },
    {
      "id": "classic",
      "label": "Classic",
      "configUrl": "https://shell.biboer.cn:20001/themes/classic.json",
      "previewQuery": "?mode=full&theme=classic"
    }
  ]
}

第一阶段建议先保留当前主题并命名为 default，然后新增：

  • paper
  • classic

4.2 主题配置 <theme-id>.json

每个主题再提供一份主题级配置，例如：

{
  "id": "default",
  "label": "Default",
  "background": {
    "url": "https://shell.biboer.cn:20001/themes/default/kindlebg.png",
    "refreshIntervalMinutes": 120
  },
  "clock": {
    "x": 262,
    "y": 55,
    "width": 220,
    "height": 220,
    "faceRadiusRatio": 0.47,
    "faceStroke": 3,
    "tickOuterInset": 6,
    "majorTickLength": 14,
    "minorTickLength": 7,
    "majorTickThickness": 4,
    "minorTickThickness": 2,
    "hourLengthRatio": 0.48,
    "minuteLengthRatio": 0.72,
    "hourThickness": 9,
    "minuteThickness": 5,
    "centerRadius": 7
  }
}

说明：

  • 背景图真实路径由主题配置提供，不在 Kindle 端拼接猜测
  • 时钟坐标和大小来自 calendar 中该主题的时钟占位，不允许 Kindle 任意改
  • 后续如果某个主题需要不同的时钟绘制参数，也由该 JSON 一起提供

4.3 Kindle 本地状态

Kindle 本地只需要保存少量状态：

/mnt/us/dashboard/local/theme.env
/mnt/us/dashboard/local/state/themes.json
/mnt/us/dashboard/local/state/current-theme.json
/mnt/us/dashboard/local/state/background-updated-at

其中：

  • theme.env 只记录当前主题 ID
  • themes.json 是最近一次同步到本地的主题清单缓存
  • current-theme.json 是当前主题配置缓存

这几项是 Kindle 本地运行状态，不属于远端主题配置。

5. calendar/ 侧方案

5.1 网站访问时增加主题预览菜单

主题预览菜单只出现在网站访问场景，不出现在背景截图结果里。

建议行为：

  1. 用户访问 /?mode=full 时，在页面顶部显示一个可选主题菜单
  2. 切换菜单时更新当前页面的 theme 参数
  3. 菜单位置放在顶部任意不影响截图的位置即可
  4. 在 mode=background 下不显示该菜单，避免影响截图导出

建议 URL 形态如下：

  • /?mode=full&theme=default
  • /?mode=full&theme=paper
  • /?mode=full&theme=classic

5.2 预览效果与 Kindle 效果对齐

主题预览不能只是“网页版好看”，还需要尽量接近 Kindle 最终效果。

建议做到：

  • 预览和导出使用同一套主题配置
  • 背景导出与预览使用同一套时钟占位信息
  • Kindle 侧按主题 JSON 中的时钟参数绘制，避免预览和实机错位

这样评审主题时，看到的页面效果和 Kindle 最终效果才是一致的。

5.3 现有导出流程保持兼容

当前默认导出链路继续保留：

calendar/dist/kindlebg.png
calendar/dist/dashboard-manifest.json
calendar/dist/clock-region.json

兼容规则建议如下：

  • 如果导出脚本没有显式传入 theme，默认导出 default
  • 现有 export:background 的行为保持不变
  • 先不强制要求所有主题都参与默认导出

这样可以保证：

  • 网站预览菜单先落地
  • 当前生产链路不被打断
  • Kindle 当前单主题使用方式继续可用

5.4 多主题导出作为附加能力

当需要支持 Kindle 端多主题切换时，再增加多主题导出，例如：

calendar/dist/themes.json
calendar/dist/themes/default.json
calendar/dist/themes/default/kindlebg.png
calendar/dist/themes/paper.json
calendar/dist/themes/paper/kindlebg.png
calendar/dist/themes/classic.json
calendar/dist/themes/classic/kindlebg.png

这里的关键点是：

  • 原有 calendar/dist/kindlebg.png 继续保留
  • 多主题目录和 themes.json 是新增能力，不是替换能力
  • 主题路径管理由 calendar 决定，不在 Kindle 侧固化为固定模式

6. Kindle 侧方案

6.1 主题发现方式

Kindle 只需要知道一个固定地址：

themes.json 的 URL

推荐两种同步方式并存：

  • 被动同步：Kindle 每天拉取一次 themes.json
  • 主动同步：用户进入主题切换流程时，先即时拉取最新 themes.json

这样能兼顾：

  • 平时低频更新
  • 切换主题时拿到最新主题清单

6.2 主题切换流程

主题切换时建议执行以下流程：

  1. 拉取最新 themes.json
  2. 根据用户选择的主题 ID 找到对应 configUrl
  3. 拉取该主题对应的 <theme-id>.json
  4. 将 THEME_ID 写入本地 theme.env
  5. 将主题 JSON 缓存在本地
  6. 立即拉取该主题背景图
  7. 立即执行一次全屏刷新
  8. 之后继续按当前分钟级时钟刷新逻辑运行

这里有一个关键要求：

  • 主题切换后，不等待下一个两小时周期
  • 而是立即拉取一次新主题背景

6.3 时钟绘制保持现有模型

当前 Kindle 时钟是本地几何绘制，已经满足主题切换第一阶段需求。

因此 Kindle 侧仍然保持：

  • 拉背景图片
  • 读取主题 JSON
  • 用本地 lua + fbink 画时钟

不需要在第一阶段增加：

  • 表盘图片素材同步
  • 指针图片素材同步
  • 复杂的本地主题资源目录

如果未来某个主题确实需要独立表盘素材，再在第二阶段扩展。

6.4 主题切换入口

入口建议做成“统一主题入口”，而不是在 KUAL 里硬编码每个主题项。

目标交互是：

  1. 用户点击“Theme”
  2. 设备根据 themes.json 获取当前可用主题清单
  3. 用户点击具体主题
  4. 立即切换到该主题

实现上可以接受两种方式：

  • KUAL 能直接承载该交互，则由脚本在入口内完成
  • 如果 KUAL 不能直接动态展示，则由脚本先读取 themes.json，再生成或更新对应菜单

不管具体 UI 形态如何，数据契约都应保持一致：

  • 主题列表来自 themes.json
  • 切换行为来自所选主题对应的 <theme-id>.json

7. 分阶段落地

第一阶段：网站主题预览

目标：

  • 新增 theme 参数
  • 增加顶部主题预览菜单
  • 默认主题命名为 default
  • 新增 paper 和 classic

结果：

  • 用户可以在网站上预览三套主题
  • 现有截图导出流程保持不变

第二阶段：主题元数据发布

目标：

  • calendar/ 产出 themes.json
  • 每个主题产出自己的 <theme-id>.json
  • 每个主题有独立背景图 URL

结果：

  • 主题列表、主题路径、时钟配置都由 calendar/ 统一提供
  • Kindle 侧可以开始按 JSON 理解主题系统

第三阶段：Kindle 端主题切换

目标：

  • Kindle 能拉取 themes.json
  • Kindle 能按选择主题拉取对应的 <theme-id>.json
  • 切换后立即拉取新背景并全屏刷新

结果：

  • Kindle 端正式具备多主题切换能力
  • Kindle 侧仍保持最小职责

第四阶段：按需扩展主题能力

只有在未来确实出现需求时，再考虑：

  • 为某些主题提供独立表盘素材
  • 增加主题级本地资源同步
  • 增加更复杂的主题切换交互

这一步不是当前必需项。

8. 风险与约束

8.1 预览和实机效果偏差

如果预览和导出用的不是同一套主题配置，最终会出现：

  • 网页看起来正确
  • Kindle 上时钟错位或背景不一致

因此必须保证：

  • 预览
  • 导出
  • Kindle 时钟绘制

都依赖同一套主题元数据。

8.2 主题切换后的缓存问题

如果主题切换后没有立即拉取新背景，Kindle 可能继续显示旧缓存。

因此切换主题时必须同时处理：

  • 更新 THEME_ID
  • 拉取新的 <theme-id>.json
  • 拉取新的背景图
  • 重置背景更新时间戳或直接覆盖缓存背景

8.3 主题清单缓存过旧

如果 Kindle 长时间只读本地缓存，可能看不到新主题。

因此建议：

  • 日常低频同步一次 themes.json
  • 用户进入主题切换时再主动刷新一次

9. 推荐结论

推荐采用下面这条路线：

  1. 先在 calendar 网站上增加顶部主题预览菜单
  2. 维持当前默认背景导出链路不变
  3. 由 calendar 增量提供 themes.json 和主题级 <theme-id>.json
  4. Kindle 只读取固定位置的 themes.json
  5. 切换主题时立即拉取该主题配置和背景图，并继续使用现有本地时钟绘制

这条路线的优点是：

  • 不打断现有 kindlebg.png 生成流程
  • 主题路径和布局都由 calendar 统一管理
  • Kindle 侧实现最简化
  • 预览和实机显示可以基于同一套配置对齐
  • 当前时钟实现不依赖表盘和指针素材，第一阶段改造成本低