nxxy335/halo-theme-WarmIsland
1
1 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 5 Wiki Activity

feat(v1.2.7): 全面校准文档并精简三个可选 API 配置项文案

Browse Source 
- 文档对齐 1.2.7：feed/RSS 聚合改由官方链接管理插件订阅承担、Halo 要求统一 >=2.27.0、补齐设置分组文档、清理与代码不符的描述，并修复正文引用块留白
- 三个可选 API 设置项 help 只保留功能说明，隐私披露统一由 README「外部资源与隐私」与文档站承载；字段恢复按开关条件显示，修正配置块缩进
- audit:external 改为防回潮检查：字段存在、help 不得出现披露文案、README 必须保留隐私披露章节
This commit is contained in:
nxxy335 committed 2026-11-11 22:34:32 +08:00
1 parent c92429d139
commit 5c7c6325b1
34 files changed
+500 -210
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+21 -13
View File
@@ -12,7 +12,7 @@
## 特点
1. **响应式设计** — 适配桌面端与移动端，支持暗色模式，移动端使用动态视口单位适配地址栏
2. **插件兼容性** — 适配 11 款常用 Halo 插件，安装即用；提供页面布局契约，插件前台页面自动复用主题外观
2. **插件兼容性** — 适配 10 款常用 Halo 插件，安装即用；提供页面布局契约，插件前台页面自动复用主题外观
3. **内置灯箱** — 主题内置 LightGallery 灯箱（GPLv3，随主题自托管打包），支持 EXIF 信息展示；安装 lightgallery.js 插件后自动禁用
4. **可配置性** — 17 个设置分组、126 个配置项，几乎所有模块可独立开关
5. **性能优化** — 服务端字数统计（API 扩展包）、图片懒加载与响应式缩略图、首屏整屏吸附（仅首屏边界接管，内容区保留原生滚动）、Hero 离屏停绘、CSS/HTML 压缩；详见[开发指南 - 性能与滚动顺滑](https://nxxy335.top/WarmIsland/customize/development.html)
@@ -38,29 +38,33 @@
| 服务 / 资源 | 用途 | 涉及的数据类型 | 默认状态 | 关闭 / 替换方法 |
| --- | --- | --- | --- | --- |
| 主题自身静态资源 `/themes/warm-island/assets/*` | 样式、脚本、字体、图标、Logo、内置句子库 | 无（同域请求，不含用户数据） | 始终启用，渲染必需 | 不可关闭；均为随包自托管文件 |
| 自定义一言 API `hero_hitokoto_api` | Hero 首屏随机句子 | 无请求体；发起 GET 时第三方可见访客 IP / User-Agent | **默认不启用**：「描述文案来源」默认「无」，一言元素不渲染，零请求；选择「一言」时自动填入 `https://v1.hitokoto.cn/` | 主题设置 → Hero 首屏 → 描述来源改为「无」或「自定义」，或清空该字段回退到 `assets/data/hitokoto.json` 内置本地句子库 |
| 自定义一言 API `hero_hitokoto_api` | Hero 首屏随机句子 | 无请求体；发起 GET 时第三方可见访客 IP / User-Agent | **默认不启用**：「描述文案来源」默认「无」，一言元素不渲染，零请求；该字段默认预填 `https://v1.hitokoto.cn/`，仅在「一言」模式生效 | 主题设置 → Hero 首屏 → 描述来源改为「无」或「自定义」，或清空该字段回退到 `assets/data/hitokoto.json` 内置本地句子库 |
| 自定义 IP 定位主 / 备选 API `welcome_popup_api` / `welcome_popup_fallback_api` | 欢迎弹窗显示「欢迎来自 XX 的朋友」 | **访客 IP** 与第三方返回的粗略地理位置 | **关闭**：两项均留空，弹窗只显示本地欢迎语；且欢迎弹窗开关本身默认关闭。可选接口见下方清单 | 主题设置 → 欢迎弹窗 → 关闭开关，或清空两个 API 字段 |
| 分享按钮：QQ / 微博 / X / Facebook / Telegram | 分享文章到对应平台 | 文章 URL 与标题（写在目标站 URL 参数中） | 默认开启 `qq,wechat,weibo`；**仅在访客点击后**跳转，页面加载时不请求 | 主题设置 → 文章 → 关闭「显示分享按钮」，或在「分享渠道」取消勾选 |
| 微信分享弹层 | 生成并复制文章链接 | 文章 URL（浏览器本地字符串，不发送） | 与分享按钮一致 | 同上；已移除二维码远程库，改为「复制链接」 |
| 页脚备案 / Halo / 应用市场外链 | 备案信息、致谢、插件安装提示 | 无（访客主动点击才跳转） | 由站点配置决定，默认仅显示 Halo 致谢 | 主题设置 → 页脚 → 关闭对应显示项 |
| 插件前台页面（豆瓣、Steam、朋友圈、微信读书等） | 展示插件提供的数据 | 由对应插件决定，主题不发起请求 | 安装并启用对应插件后才出现 | 卸载 / 停用对应插件；主题自动降级隐藏 |
| 插件前台页面（豆瓣、Steam、微信读书、订阅动态等） | 展示插件提供的数据 | 由对应插件决定，主题不发起请求 | 安装并启用对应插件后才出现 | 卸载 / 停用对应插件；主题自动降级隐藏 |
| 内置 LightGallery 灯箱 | 图片放大预览、EXIF 展示 | 无（本地打包，不联网） | 默认启用 | 安装 lightgallery.js 插件后主题自动让位 |
#### 可选第三方接口地址（均为候选值，主题不预置请求）
| 能力 | 设置项 | 可选地址 |
| --- | --- | --- |
| Hero 一言 | `hero_hitokoto_api` | `https://v1.hitokoto.cn/`（选择「一言」时自动填入；清空则使用内置本地句子库） |
| Hero 一言 | `hero_hitokoto_api` | `https://v1.hitokoto.cn/`（默认预填，仅「一言」模式生效；清空则使用内置本地句子库） |
| IP 定位主接口 | `welcome_popup_api` | `https://myip.ipip.net/json` 或 `https://r.inews.qq.com/api/ip2city?otype=json` |
| IP 定位备选接口 | `welcome_popup_fallback_api` | 同上两个地址任选其一，主接口失败时兜底 |
**描述文案来源默认为「无」**，可选「一言」「自定义」，此时不渲染一言元素、不发起任何请求。选择「一言」后自动填入
`https://v1.hitokoto.cn/`；选择「一言」或「自定义」后若把 API 留空，则使用主题内置的本地句子库（零外部请求）。
**描述文案来源默认为「无」**，可选「一言」「自定义」，此时不渲染一言元素、不发起任何请求。API 字段默认预填
`https://v1.hitokoto.cn/`（仅「一言」模式生效）；选择「一言」或「自定义」后若把 API 留空，则使用主题内置的本地句子库（零外部请求）。
**只有填写后才会向该地址发起请求**，需自行在站点隐私说明中披露，详见本章节「逐项说明」与下方「隐私说明（5.1）」。
IP 定位接口同样默认留空；**填写后会把访客 IP 发送给该第三方服务换取地理位置**，
需自行在站点隐私说明中披露，详见本章节「逐项说明」与下方「隐私说明（5.1）」。主题不会代替站点做这项声明。
> 三个可选 API 配置项的 `help` 只保留功能说明（候选地址、留空回退规则）；完整的第三方数据流向与
> 隐私披露统一在 README「外部资源与隐私」章节和配置文档中说明，主题设置界面不重复展示冗长文案。
> 字段是否显示由对应功能开关决定，且字段可见不等于发起请求：默认值与模板的条件渲染共同保证默认零外部请求。
> 自定义 API 属于**站点管理员主动配置**的可选能力：一旦填写，浏览器会按设置向该第三方发起请求。请自行评估服务商的隐私政策，并在站点隐私说明中补充披露；主题不会代替站点做这项声明。
### 隐私说明（5.1）
@@ -107,8 +111,7 @@ IP 定位接口同样默认留空；**填写后会把访客 IP 发送给该第
|----------|---------|-------------|------|
| [瞬间](https://halo.run/store/apps/app-SnwWD) | `PluginMoments` | `/moments` | 瞬间动态页面，支持点赞、评论、标签筛选、顶部封面 |
| [图库](https://halo.run/store/apps/app-BmQJW) | `PluginPhotos` | `/photos` | 图片展示页面，支持分组、灯箱预览 |
| [友情链接](https://halo.run/store/apps/app-hfbQg) | `PluginLinks` | `/links` | 友链展示页面，支持随机排列、随机传送门、评论区开关 |
| [朋友圈](https://www.halo.run/store/apps/app-yISsV) | `plugin-friends` | `/friends` | RSS 订阅朋友圈页面 |
| [友情链接（链接管理）](https://halo.run/store/apps/app-hfbQg) | `PluginLinks` | `/links` | 友链展示页面，支持随机排列、随机传送门、评论区开关；同一插件的 RSS 订阅驱动「订阅」页面 |
| [装备管理](https://github.com/chengzhongxue/plugin-equipment) | `equipment` | `/equipments` | 装备展示页面，按分组展示，支持封面图 |
| [豆瓣](https://github.com/chengzhongxue/plugin-douban) | `plugin-douban` | `/douban` | 豆瓣记录页面，支持类型/状态/标签筛选，默认音乐；需插件 **v1.2.6+**（SQLite 数据结构） |
| [Steam 信息展示](https://github.com/Tim0x0/halo-plugin-steam) | `PluginSteam` | `/steam` | Steam 游戏库页面，含用户资料、统计数据、最近游玩、游戏库分页 |
@@ -118,22 +121,27 @@ IP 定位接口同样默认留空；**填写后会把访客 IP 发送给该第
| [API 扩展包](https://github.com/HowieHz/halo-plugin-extra-api) | `extra-api` | 全站 | 服务端字数统计、中英文混排排版、可选服务端代码高亮 |
> **注意**：插件需要单独安装，安装后主题会自动适配对应页面。若未安装某插件，对应页面或功能自动隐藏/降级，不会报错。
>
> **「朋友圈」（`plugin-friends`）插件已不再提供**：原先的 feed / RSS 聚合能力由官方
> **「链接管理」（PluginLinks）插件的订阅**取代，对应下方的「订阅」自定义页面模板。
> 主题保留 `friends.html` 与「朋友圈」设置分组仅用于兼容旧站点，新站点请勿再依赖；
> 插件不可用时会显示空状态，不会报错。
## 自定义页面模板
在 Halo 后台「页面 → 新建 → 自定义模板」中选择使用：
在 Halo 后台「页面 → 新建 → 自定义模板」中选择使用（页面地址由 slug 决定，无固定路由）：
| 模板名 | 模板文件 | 说明 |
|--------|---------|------|
| 留言板 | `page_messageboard.html` | 留言墙页面，标题与副标题可配置 |
| 订阅 | `page_subscriptions.html` | 博友文章订阅动态，依赖链接管理插件的 RSS 订阅，支持分页/下滑加载与列表/网格布局 |
| 订阅 | `page_subscriptions.html` | 博友文章订阅动态，由官方链接管理插件的 RSS 订阅提供，支持分页 / 下滑加载与列表 / 网格布局 |
| 微信读书 | `weread.html` | 微信读书书架展示，依赖微信读书插件，访客免登录查看 |
## 主要功能
### 首页
- Hero 首屏：明暗双背景图、大标题/副标题独立配色、描述文案（默认「无」；选「一言」自动填入 `https://v1.hitokoto.cn/`，清空则使用内置本地句子库；可选自定义文案与自动刷新）、下滑箭头平滑滚动
- Hero 首屏：明暗双背景图、大标题/副标题独立配色、描述文案（默认「无」；API 字段默认预填 `https://v1.hitokoto.cn/`，仅「一言」模式生效，清空则使用内置本地句子库；可选自定义文案与自动刷新）、下滑箭头平滑滚动
- 欢迎弹窗：默认显示纯本地静态欢迎语，支持 5 种位置、会话去重开关；仅在显式配置自定义 IP 定位 API 时才显示访客所在地（见[外部资源与隐私](#外部资源与隐私)）
- 滚动吸附：首屏与内容区之间滚轮/触摸自动吸附，进入内容区后恢复原生自由滚动
- 文章卡片：可配置显示字数（依赖 API 扩展包）、阅读量、分类、标签、摘要行数
@@ -278,12 +286,12 @@ pnpm smoke
| 页面 | 检查要点 |
| --- | --- |
| 首页 | Hero（描述文案默认「无」）、切换「一言」后的自动填充与清空回退、滚动吸附、文章卡片、欢迎弹窗（默认本地文案） |
| 首页 | Hero（描述文案默认「无」）、三个可选 API 设置项（help 仅功能说明，隐私披露见 README）、一言 API 清空回退、滚动吸附、文章卡片、欢迎弹窗（默认本地文案） |
| 文章 | 正文 / 代码块配色、目录、分享按钮与微信复制链接、灯箱、点赞 |
| 分类 / 标签 / 归档 | 列表、分页、空状态、暗色模式 |
| 搜索 / 错误页 | 搜索页与空结果状态、404 / 500 兜底页、暗色模式（4.4.1） |
| 内容与表单 | 标题 / 瞬间正文含尖括号时不执行脚本、JSON-LD 合法、评论与表单校验（4.4.2） |
| 友链 / 留言板 / 订阅 | 空字段兜底（作者为空不报错）、表单与分页 |
| 友链 / 留言板 / 订阅 | 空字段兜底（作者为空不报错）、表单与分页、订阅动态空状态与插件未安装提示 |
| 全局 | 导航栏、页脚、移动端抽屉、深浅色切换、键盘可达主要导航与搜索、正文对比度、控制台无报错 / 无外部请求（4.4.3 / 4.4.4） |
## 技术栈