halo-theme-WarmIsland/.trae/documents/toc-image-lightbox-logo-moments.md

实施计划：TOC 优化、图片描述样式、灯箱修复、Logo 修复、瞬间评论计数修复

任务概览

#	任务	优先级
1	TOC 优化：子标题缩进 + 当前项高亮 + 删除全目录展开/收起 + 二级目录折叠/展开	高
2	文章图片描述（figcaption）颜色 #545164 + 字号缩小	中
3	图库页灯箱插件图片无法点击大图预览	高
4	主题 Logo 在后台主题详情/管理器不显示	中
5	瞬间页评论计数修复	高

---

任务 1：TOC 优化

现状分析

当前 TOC 实现（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 中的缩进量，使层级更清晰：

.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）
• 字重加粗
• 平滑过渡动画

.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 结构改为：

<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：

.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 的 <style> 中添加 figcaption 样式：

.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 中，图片结构为：

<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：

<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 添加：

.wi-photos-page__link {
  display: block;
  text-decoration: none;
}

这样 lightGallery 插件配置路径匹配 /photos、DOM 节点 .wi-photos-page__grid、selector a 即可正常工作。

---

任务 4：主题 Logo 在后台不显示

现状分析

当前 theme.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 路径改为正确的资源路径：

spec:
  logo: /themes/warm-island/assets/logo.png

或者如果 logo 在 templates 根目录下，使用：

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. 浏览器验证