103 lines
3.4 KiB
Markdown
Executable File
103 lines
3.4 KiB
Markdown
Executable File
# 更新说明（2026-01-02）
|
||
|
||
本文档用于说明 Issue #30（外部资源/图标/嵌套交互）相关改动中，**配置层面的新增字段、行为变更与迁移要点**。
|
||
|
||
关联 Issue：https://github.com/rbetree/menav/issues/30
|
||
|
||
最后更新：2026-01-02
|
||
|
||
---
|
||
|
||
## 1. 新增/扩展的配置字段
|
||
|
||
### 1.1 `site.yml -> icons.mode`（站点卡片图标模式 / 隐私）
|
||
|
||
用途：控制“站点卡片图标”的全局渲染方式。
|
||
|
||
取值：
|
||
|
||
- `favicon`：根据站点 URL 通过第三方服务加载站点 favicon（失败时回退到 Font Awesome 图标）
|
||
- `manual`：始终使用配置中的 Font Awesome 图标类名（不发起 favicon 外部请求）
|
||
|
||
注意：
|
||
|
||
- 该配置位于 `site.yml` 的 `icons:` 节点下（默认示例见 `config/_default/site.yml`）。
|
||
- 配置目录采用“完全替换”策略：若启用 `config/user/`，需要在 `config/user/site.yml` 中设置该字段才会生效。
|
||
- 切换后需要重新生成页面（`npm run build` / `npm run dev`）才能影响生成的 HTML。
|
||
|
||
示例：
|
||
|
||
```yml
|
||
# config/user/site.yml
|
||
icons:
|
||
mode: manual
|
||
```
|
||
|
||
---
|
||
|
||
### 1.2 `pages/*.yml -> sites[].faviconUrl`（站点级自定义图标链接）
|
||
|
||
用途：为单个站点指定图标链接（可远程或本地相对路径），用于兜底“favicon 服务返回默认图标/网络不可达”等情况。
|
||
|
||
说明：
|
||
|
||
- `faviconUrl` 优先级最高：一旦设置，将直接使用该图片链接渲染图标。
|
||
- 本地路径建议以 `assets/` 开头；构建时会复制到 `dist/` 同路径，便于离线/内网使用。
|
||
|
||
示例：
|
||
|
||
```yml
|
||
sites:
|
||
- name: '内部系统'
|
||
url: 'https://intranet.example/'
|
||
faviconUrl: 'assets/icons/intranet.png'
|
||
```
|
||
|
||
---
|
||
|
||
### 1.3 `pages/*.yml -> sites[].forceIconMode`（站点级强制图标模式）
|
||
|
||
用途：强制该站点使用指定模式（不设置则跟随全局 `icons.mode`）。
|
||
|
||
取值：
|
||
|
||
- `favicon`：强制走 favicon（外部请求）
|
||
- `manual`：强制走手动图标（不发起 favicon 外部请求）
|
||
|
||
优先级：
|
||
|
||
- `faviconUrl` > `forceIconMode` > 全局 `icons.mode`
|
||
|
||
示例：
|
||
|
||
```yml
|
||
sites:
|
||
- name: 'Ant Design'
|
||
url: 'https://ant.design/'
|
||
icon: 'fas fa-th'
|
||
forceIconMode: manual
|
||
```
|
||
|
||
---
|
||
|
||
## 2. 行为变更与修复要点（无需迁移字段）
|
||
|
||
### 2.1 `icons.mode` 全局切换修复
|
||
|
||
修复点：此前 `site.yml` 中的 `icons` 没有被提升为顶层 `icons`，导致模板与运行时读取到的仍是默认 `favicon`。本次已修复，`site.yml -> icons.mode` 会被模板/运行时统一读取生效。
|
||
|
||
### 2.2 favicon 双域名回退（`.com` → `.cn`）
|
||
|
||
修复点：favicon 默认使用 `t3.gstatic.com`，失败时自动切换 `t3.gstatic.cn` 重试一次，提升国内网络可用性。
|
||
|
||
### 2.3 多级结构站点新标签页打开一致性
|
||
|
||
修复点：多级结构（`subcategories/groups/subgroups`）下站点默认值未递归补齐，导致 `external` 为 `undefined` 时不输出 `target="_blank"`。本次已在生成阶段递归补齐 `sites[].external` 默认 `true`（显式 `external: false` 保持同页打开）。
|
||
|
||
---
|
||
|
||
## 3. 迁移建议（从旧版本升级）
|
||
|
||
1. 若使用 `config/user/`：请在 `config/user/site.yml` 中设置 `icons.mode`，然后执行 `npm run build` 重新生成页面。
|
||
2. 若遇到某些站点 favicon 始终显示默认图标：建议对该站点配置 `forceIconMode: manual`（使用 Font Awesome）或提供 `faviconUrl` 指向可靠图片（远程或本地 `assets/`）。
|