点击TOC锚点时标题被粘性头部遮挡的滚动问题求助

问题场景 #

点击右侧TOC目录链接时，页面滚动到对应H2/H3标题后，标题会被顶部的sticky头部遮挡，无法完整显示。

修复方案 #

方案1：CSS全局滚动偏移（快速生效） #

直接给页面中的标题元素添加scroll-margin-top，值设置为头部高度+额外间距，确保滚动后标题不会被遮挡：

/* 在全局样式文件中添加 */
h2, h3 {
  scroll-margin-top: 60px; /* 假设头部高度为50px，额外留10px间距 */
}

方案2：修改TableOfContents组件逻辑（自定义滚动行为） #

如果需要更精细的控制，修改TableOfContents.js文件：

1. 调整滚动偏移常量
   将原代码中的TOP_OFFSET值改为匹配头部高度的数值：

// 替换原TOP_OFFSET定义
const TOP_OFFSET = 60; // 头部高度+额外间距

2. 重写TOC链接的点击事件
   修改组件中链接的渲染逻辑，添加自定义滚动处理，避免默认滚动的遮挡问题：

// 在TableOfContents组件的headings.map循环中修改a标签
<li key={i} data-depth={heading.depth}>
  <a 
    href={heading.url}
    onClick={(e) => {
      e.preventDefault();
      const targetId = heading.url.split('#')[1];
      const targetElement = document.getElementById(targetId);
      if (!targetElement) return;

      // 计算滚动目标位置
      const headerHeight = 50; // 实际头部高度
      const targetTop = targetElement.getBoundingClientRect().top + window.pageYOffset;
      const scrollToTop = targetTop - headerHeight - 10; // 减去头部高度和额外间距

      // 平滑滚动到目标位置
      window.scrollTo({
        top: scrollToTop,
        behavior: 'smooth'
      });

      // 更新URL哈希，保持路由同步
      window.history.pushState(null, null, heading.url);
    }}
  >
    {heading.text}
  </a>
</li>

3. 同步滚动高亮判断逻辑
   确保useTocHighlight中的getActiveHeaderAnchor函数里的阈值和新的偏移值一致，保证高亮的标题是当前可见的那个：

// 在getActiveHeaderAnchor函数中，保持top判断和TOP_OFFSET匹配
if (top >= 0 && top <= TOP_OFFSET) {
  activeHeaderAnchor = headerAnchor;
}

方案3：组合方案（推荐） #

• 用CSS的scroll-margin-top处理基础滚动偏移，保证原生行为正常
• 调整组件中的TOP_OFFSET值，确保滚动高亮逻辑和视觉位置一致

内容的提问来源于stack exchange，提问作者Guru Pawar