# 博客目录高亮逻辑优化

> **版本**: v1.0  
> **日期**: 2026-05-06  
> **状态**: ✅ 已修复

---

## 一、问题描述

### 1.1 现象

博客正文页右侧目录的高亮逻辑存在边界问题：当点击小标题（H3）时，页面正确滚动到该位置，但目录实际高亮的是上方的大标题（H2）。

### 1.2 复现步骤

1. 访问博客文章（如 `/posts/hermes-chrome-opencode-ai-agent-bug`）
2. 找到一个小标题（H3）和它上方的大标题（H2）非常接近的章节
3. 点击目录中的小标题
4. 观察右侧目录的高亮状态

**预期行为**：小标题被高亮  
**实际行为**：大标题被高亮

### 1.3 影响范围

- 影响所有博客文章页
- 影响标题间距较小的章节

---

## 二、根因分析

### 2.1 原始代码

```javascript
function updateTocHighlight() {
    let current = '';
    headings.forEach(heading => {
        const rect = heading.getBoundingClientRect();
        if (rect.top <= 80) {
            current = heading.id;
        }
    });
}
```

### 2.2 问题根因

1. 当点击小标题（H3）时，H3 滚动到 `rect.top = 80`（scroll-margin-top）
2. 由于滚动精度问题，H3 的 `rect.top` 可能是 `80.5` 或 `81`
3. 原逻辑使用 `<= 80` 判断，H3 不满足条件
4. 而上方的 H2 满足条件（`rect.top <= 80`）
5. 结果高亮选中了 H2

**核心问题**：阈值判断是硬性的，没有考虑滚动精度误差。

---

## 三、解决方案

### 3.1 方案对比

| 方案 | 实现 | 优点 | 缺点 |
|------|------|------|------|
| A. 扩大阈值 | `<= 82` | 简单 | 仍可能有边界问题 |
| B. 距离最近算法 | 选择距离 80px 最近的标题 | 精确 | 稍复杂 |
| C. 滚动后手动设置 | 点击时直接设置高亮 | 确定性高 | 需要额外逻辑 |

### 3.2 采用方案：距离最近算法

**原理**：遍历所有标题，找到距离目标位置（80px）最近的那个标题。

**实现**：
```javascript
function updateTocHighlight() {
    const SCROLL_OFFSET = 80;
    let current = '';
    let minDistance = Infinity;
    
    headings.forEach(heading => {
        const rect = heading.getBoundingClientRect();
        // 只考虑在视口上方或接近顶部的标题
        if (rect.top <= SCROLL_OFFSET + 20) {
            // 计算距离目标位置的绝对值
            const distance = Math.abs(rect.top - SCROLL_OFFSET);
            // 选择距离最近的标题
            if (distance < minDistance) {
                minDistance = distance;
                current = heading.id;
            }
        }
    });
}
```

**优点**：
- 精确：选择距离目标位置最近的标题
- 鲁棒：不受滚动精度影响
- 直观：符合用户预期

---

## 四、实现细节

### 4.1 修改文件

- `blog/templates/post.html`：修改 `updateTocHighlight()` 函数

### 4.2 算法说明

1. **目标位置**：`SCROLL_OFFSET = 80px`（导航栏高度 64px + 留白 16px）
2. **候选范围**：`rect.top <= SCROLL_OFFSET + 20`（即 <= 100px）
3. **选择标准**：`Math.abs(rect.top - SCROLL_OFFSET)` 最小的标题

### 4.3 边界情况

- **标题在视口上方**（rect.top < 0）：距离计算为 `|负数 - 80|`，值较大，不会被选中
- **标题恰好在 80px**：距离为 0，优先选中
- **标题在 80px 以下**：不满足 `<= 100` 条件，不参与计算

---

## 五、测试验证

### 5.1 测试用例

| 编号 | 测试步骤 | 预期结果 |
|------|---------|---------|
| T-001 | 点击 H3 标题（与 H2 间距 < 50px） | H3 被高亮 |
| T-002 | 点击 H2 标题 | H2 被高亮 |
| T-003 | 滚动页面（不点击） | 最接近顶部的标题被高亮 |
| T-004 | 快速连续点击多个标题 | 每次点击后高亮正确 |

### 5.2 验证方法

1. 部署后访问博客文章
2. 找到 H2 和 H3 间距较小的章节
3. 点击目录中的 H3
4. 确认 H3 被高亮（而非 H2）

---

## 六、优先级与排期

| 优先级 | 任务 | 状态 |
|--------|------|------|
| P0 | 修改高亮算法 | ✅ 已完成 |
| P1 | 测试验证 | 待部署后验证 |

---

## 附录

### A. 相关文件

- `blog/templates/post.html`：目录生成和高亮逻辑

### B. 参考资料

- [MDN: getBoundingClientRect()](https://developer.mozilla.org/en-US/docs/Web/API/Element/getBoundingClientRect)