247 lines
7.9 KiB
Markdown
247 lines
7.9 KiB
Markdown
# 实施计划：TOC 优化、图片描述样式、灯箱修复、Logo 修复、瞬间评论计数修复
|
||
|
||
## 任务概览
|
||
|
||
| # | 任务 | 优先级 |
|
||
|---|------|--------|
|
||
| 1 | TOC 优化：子标题缩进 + 当前项高亮 + 删除全目录展开/收起 + 二级目录折叠/展开 | 高 |
|
||
| 2 | 文章图片描述（figcaption）颜色 #545164 + 字号缩小 | 中 |
|
||
| 3 | 图库页灯箱插件图片无法点击大图预览 | 高 |
|
||
| 4 | 主题 Logo 在后台主题详情/管理器不显示 | 中 |
|
||
| 5 | 瞬间页评论计数修复 | 高 |
|
||
|
||
---
|
||
|
||
## 任务 1：TOC 优化
|
||
|
||
### 现状分析
|
||
|
||
当前 TOC 实现（[post.astro](file:///c:/Users/Zhang/Documents/Halo/WarmIsland/src/pages/post.astro)）：
|
||
|
||
1. **子标题缩进**：已有 `wi-toc__link--h2/h3/h4/h5/h6` 类，h2 无缩进，h3 12px，h4 24px 等。但缩进量较小，层级感不够明显。
|
||
2. **当前项高亮**：已有 `wi-toc__link--active` 类（`color: var(--accent); font-weight: 600;`），但高亮效果不够明显，缺少视觉锚点。
|
||
3. **全目录展开/收起**：当前 `wi-toc__toggle` 按钮控制整个目录的展开/收起（`wi-toc__nav--collapsed` 类），需要删除此功能。
|
||
4. **二级目录折叠/展开**：当前没有此功能，需要新增。当进入某一个一级分类（h2）时展开其下属的二级分类（h3-h6），其他一级分类的子项折叠。
|
||
|
||
### 修改方案
|
||
|
||
#### 步骤 1.1：增强子标题缩进
|
||
|
||
修改 CSS 中的缩进量，使层级更清晰：
|
||
|
||
```css
|
||
.wi-toc__link--h2 { padding-left: 0; }
|
||
.wi-toc__link--h3 { padding-left: 16px; }
|
||
.wi-toc__link--h4 { padding-left: 32px; }
|
||
.wi-toc__link--h5 { padding-left: 48px; }
|
||
.wi-toc__link--h6 { padding-left: 64px; }
|
||
```
|
||
|
||
同时为 h2 级目录项添加左侧竖线指示器，增强层级感。
|
||
|
||
#### 步骤 1.2：增强当前阅读项高亮样式
|
||
|
||
改进 `wi-toc__link--active` 样式：
|
||
- 左侧添加竖线指示器（accent 色）
|
||
- 背景色微调（半透明 accent）
|
||
- 字重加粗
|
||
- 平滑过渡动画
|
||
|
||
```css
|
||
.wi-toc__link--active {
|
||
color: var(--accent);
|
||
font-weight: 600;
|
||
border-left: 2px solid var(--accent);
|
||
padding-left: calc(原缩进 - 2px);
|
||
background: color-mix(in srgb, var(--accent) 8%, transparent);
|
||
}
|
||
```
|
||
|
||
#### 步骤 1.3：删除全目录展开/收起功能
|
||
|
||
1. 删除 `wi-toc__header` 中的 `wi-toc__toggle` 按钮
|
||
2. 删除 JS 中 `toggleBtn` 相关的事件监听代码
|
||
3. 删除 CSS 中 `wi-toc__nav--collapsed` 相关样式
|
||
|
||
#### 步骤 1.4：增加二级目录折叠/展开功能
|
||
|
||
1. 修改 JS 中 TOC 生成逻辑，将 h2 作为一级目录项，h3-h6 作为二级目录项
|
||
2. 每个 h2 项下方创建一个可折叠的子容器
|
||
3. 默认只展开当前活跃 h2 的子项，其他 h2 的子项折叠
|
||
4. 点击 h2 项可手动展开/折叠其子项
|
||
5. 当滚动位置变化时，自动展开当前活跃 h2 的子项
|
||
|
||
HTML 结构改为：
|
||
```html
|
||
<div class="wi-toc__group" data-h2="wi-heading-0">
|
||
<a class="wi-toc__link wi-toc__link--h2" href="#wi-heading-0">一级标题</a>
|
||
<div class="wi-toc__sub">
|
||
<a class="wi-toc__link wi-toc__link--h3" href="#wi-heading-1">二级标题</a>
|
||
...
|
||
</div>
|
||
</div>
|
||
```
|
||
|
||
CSS：
|
||
```css
|
||
.wi-toc__sub {
|
||
overflow: hidden;
|
||
max-height: 0;
|
||
opacity: 0;
|
||
transition: max-height 0.3s ease, opacity 0.2s ease;
|
||
}
|
||
|
||
.wi-toc__group--active .wi-toc__sub,
|
||
.wi-toc__group--expanded .wi-toc__sub {
|
||
max-height: 500px;
|
||
opacity: 1;
|
||
}
|
||
```
|
||
|
||
JS 逻辑：
|
||
- 生成 TOC 时，将 h3-h6 归入前一个 h2 的子组
|
||
- IntersectionObserver 检测到活跃标题时，自动展开对应的 h2 组
|
||
- 点击 h2 项时，切换该组的展开/折叠状态
|
||
|
||
---
|
||
|
||
## 任务 2：文章图片描述样式
|
||
|
||
### 现状分析
|
||
|
||
Halo 文章编辑器中，图片可以添加描述（alt/caption），渲染后通常为 `<figure>` + `<figcaption>` 结构。当前主题没有为 `figcaption` 定义样式，使用默认样式。
|
||
|
||
### 修改方案
|
||
|
||
在 [post.astro](file:///c:/Users/Zhang/Documents/Halo/WarmIsland/src/pages/post.astro) 的 `<style>` 中添加 `figcaption` 样式：
|
||
|
||
```css
|
||
.wi-post__body figcaption {
|
||
color: #545164;
|
||
font-size: 0.875rem;
|
||
text-align: center;
|
||
margin-top: -0.8em;
|
||
margin-bottom: 1.2em;
|
||
line-height: 1.5;
|
||
}
|
||
|
||
html.dark .wi-post__body figcaption {
|
||
color: #8a8494;
|
||
}
|
||
```
|
||
|
||
字号 `0.875rem`（14px）比正文字号 `1rem`（16px）小一点。
|
||
|
||
---
|
||
|
||
## 任务 3：图库页灯箱插件图片无法点击大图预览
|
||
|
||
### 现状分析
|
||
|
||
当前图库页 [photos.astro](file:///c:/Users/Zhang/Documents/Halo/WarmIsland/src/pages/photos.astro) 中，图片结构为：
|
||
|
||
```html
|
||
<div class="wi-photos-page__wrap">
|
||
<img th:src="${photo.spec.cover ?: photo.spec.url}" class="wi-photos-page__image" />
|
||
<div class="wi-photos-page__overlay">...</div>
|
||
</div>
|
||
```
|
||
|
||
lightgallery.js 插件的工作原理：
|
||
1. 需要在匹配区域的 DOM 节点上初始化 `lightGallery()`
|
||
2. 默认情况下，lightGallery 会查找 `<a>` 标签包裹的 `<img>`，`<a>` 的 `href` 属性作为大图 URL
|
||
3. 或者使用 `selector` 选项指定点击目标
|
||
|
||
**问题原因**：当前图片没有用 `<a>` 标签包裹，lightGallery 无法识别可点击的图片。`wi-photos-page__overlay` 遮罩层也可能拦截点击事件。
|
||
|
||
### 修改方案
|
||
|
||
将每个图片项的 `<img>` 用 `<a>` 标签包裹，`href` 指向原图 URL：
|
||
|
||
```html
|
||
<div class="wi-photos-page__wrap">
|
||
<a th:href="${photo.spec.url}" class="wi-photos-page__link">
|
||
<img th:src="${photo.spec.cover ?: photo.spec.url}" class="wi-photos-page__image" />
|
||
</a>
|
||
<div class="wi-photos-page__overlay">...</div>
|
||
</div>
|
||
```
|
||
|
||
CSS 添加：
|
||
```css
|
||
.wi-photos-page__link {
|
||
display: block;
|
||
text-decoration: none;
|
||
}
|
||
```
|
||
|
||
这样 lightGallery 插件配置路径匹配 `/photos`、DOM 节点 `.wi-photos-page__grid`、selector `a` 即可正常工作。
|
||
|
||
---
|
||
|
||
## 任务 4：主题 Logo 在后台不显示
|
||
|
||
### 现状分析
|
||
|
||
当前 [theme.yaml](file:///c:/Users/Zhang/Documents/Halo/WarmIsland/theme.yaml) 中：
|
||
|
||
```yaml
|
||
spec:
|
||
logo: /themes/warm-island/public/logo.png
|
||
```
|
||
|
||
问题分析：
|
||
1. Halo 2.x 主题的静态资源在 `templates/` 目录下，通过 `/themes/{theme-name}/assets/` 路径访问
|
||
2. `public/` 目录下的文件在构建时被复制到 `templates/` 根目录
|
||
3. `logo.png` 在构建后位于 `templates/logo.png`
|
||
4. 路径 `/themes/warm-island/public/logo.png` 不正确，因为 `public/` 不是资源访问路径的一部分
|
||
|
||
### 修改方案
|
||
|
||
将 `theme.yaml` 中的 logo 路径改为正确的资源路径：
|
||
|
||
```yaml
|
||
spec:
|
||
logo: /themes/warm-island/assets/logo.png
|
||
```
|
||
|
||
或者如果 logo 在 templates 根目录下，使用：
|
||
|
||
```yaml
|
||
spec:
|
||
logo: /themes/warm-island/logo.png
|
||
```
|
||
|
||
需要验证 Halo 2.x 主题的静态资源访问路径规则。根据 vite-plugin-halo-theme 的构建输出，`public/` 目录下的文件被复制到 `templates/` 根目录，而 `templates/assets/` 下是构建产物。所以正确的路径应该是 `/themes/warm-island/logo.png`。
|
||
|
||
---
|
||
|
||
## 任务 5：瞬间页评论计数修复
|
||
|
||
### 现状分析
|
||
|
||
上一轮已修复了点赞计数问题（upvote API group 从 `moment.moment.halo.run` 改为 `moment.halo.run`），并添加了 `loadMomentStats()` 客户端函数通过 `/apis/api.moment.halo.run/v1alpha1/moments` API 获取统计数据。
|
||
|
||
当前 `loadMomentStats()` 函数已正确获取 `stats.approvedComment` 并更新 DOM。但评论计数仍然显示 0，可能原因：
|
||
|
||
1. 评论确实为 0（没有审核通过的评论）
|
||
2. `moment.stats?.approvedComment` 在 Thymeleaf 渲染时为 null，`?: 0` 兜底显示 0
|
||
3. 客户端 `loadMomentStats()` 可能未正确执行
|
||
|
||
### 修改方案
|
||
|
||
1. 使用浏览器验证评论数据是否存在
|
||
2. 确认 `loadMomentStats()` 函数是否正确更新了评论计数
|
||
3. 如果评论计数在评论提交后没有实时更新，需要在评论提交后重新调用 `loadMomentStats()`
|
||
|
||
---
|
||
|
||
## 执行顺序
|
||
|
||
1. 修改 theme.yaml 修复 Logo 路径
|
||
2. 修改 post.astro：TOC 优化 + figcaption 样式
|
||
3. 修改 photos.astro：图片添加 `<a>` 标签包裹
|
||
4. 验证瞬间页评论计数
|
||
5. 构建部署
|
||
6. 浏览器验证
|