MicroImmersion v1.6.0 发布日志

发布日期：2026-08-24
适配版本：Halo 2.26.0 及以上

本次版本主要完成 Docsme 文档插件的主题布局适配，解决文档页面空白、加载动画不消失、顶部菜单缺失、明暗模式冲突及版本切换 404 等问题。同时适配 plugin-douban 1.2.6+ 的新数据结构，并修复 51LA 统计功能的开关判断。

重点更新

Docsme 文档插件适配

• 文档列表、文档目录和文档详情页面接入主题统一布局。
• 文档页面现在可以正常显示主题顶部菜单、页脚及全局组件。
• 保持 Halo 2.26.0 要求的根目录 templates/layout.html 布局结构。
• 未配置文档模板来源时默认使用主题适配模板。
• 显式选择插件模板时继续使用 Docsme 原生页面，不受主题覆盖影响。

修复文档页面空白和持续加载

• 修复文档布局中 Thymeleaf 片段参数同名导致的递归渲染风险。
• 增加文档页面加载动画禁用标记。
• 文档页面不再等待插件资源的 window.load 事件关闭主题加载动画。
• 解决部署后文档页面持续转圈、内容无法显示的问题。

修复主题菜单与 Docsme 初始化冲突

Docsme 和主题都使用 Alpine.js，原有加载顺序可能导致 Docsme 提前接管主题节点，使顶部菜单一直保留 x-cloak 状态。

本次更新：

• 将 Docsme 主脚本调整为延迟执行。
• 增加 Docsme 就绪事件和主题启动等待机制。
• Docsme 继续负责文档侧栏、目录和版本切换。
• 主题 Alpine 继续负责顶部菜单、明暗切换及主题交互。
• 增加 3 秒超时兜底，避免插件脚本异常时阻塞主题初始化。

文档页面主题颜色适配

当后台选择“由主题提供文档模板”时，文档页面颜色会自动跟随主题设置：

• 主色和品牌色
• 激活状态颜色
• 悬停颜色
• 侧栏选中状态
• 文档目录高亮
• 页面及卡片背景
• 边框和分割线
• 多级文字颜色
• 亮色与暗色模式背景

选择 Docsme 插件原生模板时，不会加载这些主题颜色覆盖。

修复文档页面明暗模式

• 关闭 Docsme 自带的主题模式控制。
• 统一由主题维护 data-color-scheme 和明暗模式状态。
• 修复明暗模式偶尔点击不生效、刷新后才生效的问题。
• 修复 Docsme 覆盖主题“跟随系统”状态的问题。
• 文档页面位于顶部时使用实色菜单背景。
• 首页及带 Banner 的页面继续保留透明菜单效果。
• 统一文档页面、主题宿主和顶部菜单的背景色，修复圆角区域露出相反模式底色的问题。

修复文档版本切换 404

• 不再直接使用字符串替换生成目标版本地址。
• 对当前版本和目标版本 permalink 进行路径规范化。
• 切换版本时保留当前文档的后缀路径。
• 支持绝对地址和相对地址。
• 支持站点部署在子路径下的情况。
• 兼容 permalink 尾斜杠差异。
• 保留当前查询参数和页面锚点。

豆瓣插件适配

适配 plugin-douban 1.2.6+ 返回的 SQLite 扁平化数据结构。

数据结构调整

• 将原来的 spec、faves 嵌套结构调整为扁平字段。
• 新增 DoubanMovieData 类型。
• 更新豆瓣列表、详情和组件字段读取方式。
• 支持可空的名称、封面、类型、状态、评分和日期字段。
• 增加无效日期判断，避免渲染异常。

页面优化

• 更新卡片数据绑定和列表唯一标识。
• 筛选器、内容列表、空状态和分页区域增加 x-cloak。
• 减少 Alpine 初始化完成前的页面闪烁。
• 未改变豆瓣页面原有布局和视觉样式。

51LA 统计修复

• 将 51LA 开关默认值调整为 false。
• 使用明确的字符串布尔判断，避免空字符串被识别为已启用。
• 只有开关明确为 true 时才加载统计脚本。
• 只有同时配置监控 ID 时才执行 51LA 初始化。
• 修复控制台统计组件的变量命名和显示条件。

兼容性说明

• 最低 Halo 版本：2.26.0
• 豆瓣页面新数据结构适用于 plugin-douban 1.2.6+
• Docsme 原生模板模式保持不变
• 主题提供的文档模板会启用主题菜单、页脚、明暗模式和主题颜色
• 51LA 统计升级后需要在主题设置中明确启用，并配置有效的监控 ID