1.1.0 - 2026-07-23

这次更新不只是让访客切换主题，也把不同主题的页面模板和导航真正串联起来。站长无需再为了每套主题重复创建页面、创建菜单和逐项绑定，只需拖拽模板即可完成一套独立导航。

新增

• 新增主题导航编排功能，为每套主题维护独立的一级、二级导航结构。
• 自动识别 Halo 内置模板，以及主题声明并真实存在的自定义页面模板。
• 自动关联当前主题与对应模板，集中展示模板名称、来源、访问路径和可用状态。
• 支持把待选模板拖入导航结构，并通过拖拽调整一级导航、二级导航和显示顺序。
• 保存编排时自动生成并复用缺少的页面与导航数据，无需提前在 Halo 后台创建页面或菜单。
• 支持直接编辑导航名称和访问路径，可使用站内真实路径或自定义链接。
• 已完成的导航编排可以直接作为主题菜单使用，并随访客当前选择的主题自动切换。
• 新增前台主题适配接口，支持稳定挂载锚点、自定义切换按钮、CSS 变量、Shadow Parts 和 setAppearance()。

优化

• 优化模板池与导航结构的双栏拖拽体验，拖入右侧后自动从待选区域移除。
• 优化嵌套导航的层级提示、拖拽占位和排序反馈，让一级、二级关系更直观。
• 优化前台切换入口样式，可继承主题按钮的颜色、尺寸、圆角、边框和阴影。
• 优化主题切换入口在 React、SPA 和局部重渲染页面中的挂载稳定性。
• 优化主题选择弹窗的打开过程，已有目录数据时不再重复请求和重建弹窗。
• 保留访客当前真实访问路径进行主题切换，不修改 Halo 全局启用主题，也不影响其他访客。

修复

• 修复页面切换或顶部导航重新渲染后，主题漫游入口偶尔消失的问题。
• 修复主题适配颜色被插件内部默认变量覆盖的问题。
• 修复点击主题切换按钮时弹窗短暂闪烁、入场动画重复执行的问题。
• 修复未提前创建页面或菜单时，部分主题模板无法正常加入导航的问题。
• 修复清空导航编排后旧数据仍被复用的问题。
• 修复主题模板名称、访问路径与实际模板文件对应不准确的问题。

主题漫游

主题漫游是一个面向 Halo 2.25+ 的多主题访客切换插件。站长可以把已安装主题与对应菜单绑定后开放给访客；每位访客只改变自己的页面渲染，不会启用或停用 Halo 的全局主题，也不会影响其他访客。

告别一个站只能穿一套衣服的烦恼。今天宠这个，明天宠那个，让安装过的主题都能雨露均沾。

主要能力

• 自动读取 Halo 中已经安装的主题和菜单，无需手工新增主题数据。
• 每套主题都能绑定自己的菜单，并决定是否开放给访客。访客可以自由切换站长准备的多套主题，不再只能看到一种风格，也让安装的每套主题都有机会派上用场。

安装与使用

1. 安装并启动插件。
2. 在 Console 左侧进入“主题漫游”。
3. 为每个主题选择对应菜单。
4. 打开需要向访客展示的主题。
5. 在“漫游配置”中设置记忆时间、开放范围、入口位置和切换动画。

如果没有任何主题处于“前台开放”状态，插件不会向站点页面注入入口。

主题接入

插件不要求主题适配，默认会自动注入完整切换入口。主题需要自定义位置时，可提供一个锚点：

<div data-theme-roaming-anchor></div>

使用主题自己的按钮打开面板：

<button type="button" data-theme-roaming-open>切换主题</button>

前台 JavaScript 接口为 window.ThemeRoaming，提供 open()、close()、toggle()、refresh()、select(themeName)、getState() 和 mount(anchor)。调用前应判断接口是否存在：

window.ThemeRoaming?.open();

开放主题目录：

GET /apis/roaming.serenity/v1alpha1/catalog

Thymeleaf 可通过 themeRoamingFinder.getCatalog() 获取当前主题和开放主题列表。

菜单绑定建议使用 themeRoamingMenuFinder。未安装插件时必须保留 Halo 原生 menuFinder 回退：

${themeRoamingMenuFinder != null
  ? themeRoamingMenuFinder.getForTheme(theme.metadata.name).menuItems
  : menuFinder.getPrimary().menuItems}

开发与构建

插件版本仅在 gradle.properties 的 pluginVersion 中维护，插件元数据和 JAR 文件名会在构建时自动同步。

.\gradlew clean build

构建包含 Console 前端、Java 编译和单元测试，产物位于 build/libs/。

兼容性

• Halo：>= 2.25.0
• Java：21

Halo 升级后建议重新执行完整构建，并验证首页、列表页、文章页、主题静态资源和菜单绑定。

源码与反馈

• 源码仓库：https://github.com/atangccc/Roaming
• 问题反馈：https://github.com/atangccc/Roaming/issues
• 协议：GPL-3.0