手写目录索引：滚动高亮与锚点定位的完整实践

1. 目录索引到底解决了什么问题：从一次“翻不到内容”的吐槽说起

这事得从我自己写博客的体验说起。早几年我做了一个技术博客，文章越写越长，好几篇都逼近五六千字，结果自己翻回去想改一段内容都得滚动半天。读者更直接，有朋友留言说“你文章里那个配置项在哪儿来着？翻了三分钟没找到”。那会儿我意识到一个事：长页面如果没有清晰的导航结构，内容质量再高也会被阅读成本拖垮。

目录索引功能，本质上就是给长文页面加一个“可点击、可定位、可感知当前位置”的导航骨架。它做的事情很朴素：把页面上各级标题抽取出来，生成一个树状目录，用户点击目录项就平滑滚动到对应章节；用户滚动页面时，目录里对应章节高亮，实时告诉读者“你现在读到哪了”。听起来简单，但真正做好、做稳、做到像大厂文档站点那样顺滑，里面有不少细节值得拆开讲。

这篇文章我会按我实际做的过程来讲：先聊需求边界和方案选型，再做核心实现，最后展开那些容易翻车的边界情况和排错过程。适合三类人看：给自己博客或团队文档站点加导航的前端开发者，刚接触前端工程化想练手的中级学习者，以及想评估“手写目录还是引插件”的维护者。不管你是哪种，看完都能直接落到代码里。

先说明白一点：我讲的“目录索引”，指的是页面内正文标题的自动抽取与导航定位，不是搜索引擎那个索引，更不是文件系统的目录服务。两者的核心差异在于场景：我们面对的是已经渲染好的HTML结构，需要的是“读取DOM-生成目录-联动滚动”这一条链路。

2. 方案选型：现成插件与手写实现的取舍逻辑

很多朋友第一反应是“这功能不有现成插件吗，干嘛自己写”。确实，市面上优秀的TOC（Table of Contents）组件不少，像GitHub上star很高的tocbot、mdBook和VuePress内置的目录组件、百度搜索里一抓一把的jQuery右侧目录插件。但我在对比之后，还是选择了手写。原因不是现成方案不好，而是要评估几个关键维度。

2.1 现成方案的三个典型局限

第一个局限是样式锁定和定制成本。大多数TOC插件自带一套样式，无论是胶囊形高亮、左侧竖线还是折叠箭头，想改成符合自己站点设计语言的样子，往往要写一堆覆盖样式，或者在插件配置项里纠结半天。tocbot算好的，提供了很多配置项和CSS变量，但复杂定制时依然受限于它内部的DOM结构和类名设计。

第二个局限是标题来源绑定。很多插件依赖markdown渲染引擎输出的目录数据，比如VuePress可以直接从markdown解析阶段拿到标题树，但这意味着你被绑死在特定框架或特定构建链路上。如果你的页面是从接口动态渲染的HTML，标题结构在后端模板里生成，那么这类插件很难直接接入。

第三个局限是滚动容器假设。大部分插件默认监听document滚动。实际项目里，正文常被放在一个overflow: auto的局部容器中，比如带固定顶栏和侧边栏的后台管理系统。插件假设改了，很容易出现目录高亮始终不触发或者点击滚动错位的怪问题。

2.2 手写前先想清楚：你要的能力清单

决定手写之前，我列了一个能力清单，确保实现时不至于漏项：

• 从正文容器中提取指定级别标题（比如h2和h3，或h1-h4），并保持文档顺序
• 为没有id的标题自动生成稳定且唯一的锚点
• 生成嵌套树状的目录数据，而不是扁平列表
• 渲染目录DOM，支持点击平滑滚动到目标标题，并处理固定顶栏的偏移量
• 滚动过程中正确高亮当前阅读章节
• 处理局部滚动容器，而不只支持window滚动
• 动态内容（比如前端路由切换、异步加载正文）后能重新扫描
• 目录本身较长时，目录区域内部也能滚动定位到当前高亮项

这个清单本身就是需求文档。你对照一下就会发现，很多插件败在第5和第6条上，而这两个恰恰是“用起来舒不舒服”的关键。

2.3 我的选型结论

我的结论是：如果项目是纯markdown博客，框架又自带目录能力，先用自带方案，省心；如果项目是动态页面、定制需求多、又要适配局部滚动容器，手写一个百来行的小模块反而比改插件更快。我现在手写的这套目录索引大概是200行左右（含样式），没有引入任何依赖，且可以封装成ES模块塞进任何工程。这里不是鼓吹“一切必须手写”，而是建议你对着上面的能力清单判断：插件的学习成本和定制成本加起来超过了手写成本，就别硬用插件。

3. 手写目录索引的核心实现：标题提取、锚点注入与滚动高亮

这一节是主菜。我会按数据流顺序拆开讲：先拿到标题，再生成锚点，再构建目录树，最后做滚动联动。代码用原生JavaScript，框架无关，你迁移到Vue或React里也就多一步生命周期处理。

3.1 标题提取：从DOM里捞内容骨架

第一步是从正文容器中拿到需要索引的标题节点。这里有一个关键设计：不要直接document.querySelectorAll('h1, h2, h3')，而是先确定一个正文容器，限定搜索范围。原因有两个：一是避免把侧边栏组件里的标题也抓进来；二是局部容器环境下，后续计算滚动位置需要依赖容器边界。

javascript复制function collectHeadings(container, selectors = ['h2', 'h3']) {
  if (!container) return [];
  const nodes = Array.from(container.querySelectorAll(selectors.join(',')));
  return nodes;
}

这里还有个细节：同一篇文章里，h1一般是页面标题（大标题），正文内部通常从h2开始。所以我会把selectors设成['h2', 'h3', 'h4']，而不是从h1开始。具体选哪些级别，取决于你的页面结构，建议用配置项控制，不要写死。

标题节点的顺序很关键。querySelectorAll返回的本身就是文档顺序，这点不用额外排序，但要注意：如果你后面用Array.prototype.filter过滤掉隐藏标题或空标题，顺序依然保持，所以filter要放心用。

哪些标题应该被过滤掉？我总结了几种：

• display: none或visibility: hidden的标题（比如折叠面板里的标题）
• textContent.trim()为空的标题
• 已经被某个“目录容器”包含的标题（防止递归把目录自身的标题也抓进去，通常用容器隔离就可以规避）

3.2 锚点注入：让标题可以被定位

浏览器默认的锚点跳转依赖id，所以第二步是确保每个目标标题都有id。如果后端模板里已经写了id，直接用；如果没写，就自动生成。

javascript复制function ensureHeadingIds(headings) {
  headings.forEach((heading, index) => {
    if (!heading.id) {
      const base = heading.textContent.trim()
        .toLowerCase()
        .replace(/[^\w\u4e00-\u9fa5]+/g, '-')
        .replace(/^-+|-+$/g, '') || 'section';
      heading.id = `${base}-${index}`;
    }
  });
}

这里有几个容易踩的坑，我逐个说明。

第一，中英文混排场景。\w是匹配不到中文的，所以我在正则里显式加了\u4e00-\u9fa5，这个范围覆盖常用汉字。如果你处理的是日文、韩文，需要追加对应的Unicode范围，或者干脆转用更宽松的策略：只用标题文本生成纯section-序号风格的锚点。

第二，重复id问题。两个标题都叫“环境准备”时，如果后端没生成id，按上面的逻辑会生成两个环境准备-0和环境准备-1，因为后面追加了index，所以不会冲突。但如果你去掉index，第二个标题的id就重复了，getElementById只能取到第一个，点击目录跳转就会错位。

第三，锚点生成的稳定性。我见过有人用随机数或者时间戳生成id，刷新一次变一次。这会导致分享链接失效——用户复制了一个带#heading-xxx的URL，下次打开却找不到这个锚点了。所以id要可复现，基于标题文本加序号是最稳的。

3.3 目录树生成与渲染

有了标题数组后，需要构建嵌套结构。这里最核心的逻辑是“根据当前标题的级别，找到它的父级”。

先定义级别映射。假设h2是最外层目录项，对应level 1；h3对应level 2；h4对应level 3。这个映射允许你灵活控制“哪些标题进目录”。

javascript复制function buildTocTree(headings, levelMap = { H2: 1, H3: 2, H4: 3 }) {
  const root = [];
  const stack = [];

  headings.forEach((heading) => {
    const level = levelMap[heading.tagName];
    if (!level) return;

    const item = {
      id: heading.id,
      text: heading.textContent.trim(),
      children: []
    };

    // 栈顶级别 >= 当前级别时，说明当前节点应该往上层挂
    while (stack.length > 0 && stack[stack.length - 1].level >= level) {
      stack.pop();
    }

    if (stack.length === 0) {
      root.push(item);
    } else {
      stack[stack.length - 1].item.children.push(item);
    }

    stack.push({ level, item });
  });

  return root;
}

这个算法是经典“单调栈”思路，处理树形嵌套非常合适。你要注意的点：假设标题顺序是H2 -> H3 -> H3 -> H2，那第一个H2是根节点，两个H3都是它的子节点，第二个H2出现时，因为它的level是1，而栈顶H3的level是2，所以会先弹出H3，再对照H2（栈里还有第一个H2，level也是1，>= 1成立，所以把它也弹出了），然后挂到root上。

渲染端，我们可以递归生成DOM。不依赖框架的话，我更喜欢用createElement或innerHTML生成。考虑到目录项一般还要绑定点击事件，createElement更直观：

javascript复制function renderToc(tree, container) {
  container.innerHTML = '';
  if (!tree.length) return;

  const ul = document.createElement('ul');
  ul.className = 'toc-list';

  function createBranch(items, parentUl) {
    items.forEach((item) => {
      const li = document.createElement('li');
      li.className = 'toc-item';
      const a = document.createElement('a');
      a.href = `#${item.id}`;
      a.textContent = item.text;
      a.dataset.tocTargetId = item.id;
      li.appendChild(a);
      if (item.children.length > 0) {
        const childUl = document.createElement('ul');
        childUl.className = 'toc-sublist';
        createBranch(item.children, childUl);
        li.appendChild(childUl);
      }
      parentUl.appendChild(li);
    });
  }

  createBranch(tree, ul);
  container.appendChild(ul);
}

这里我额外加了一个dataset属性，用来标识目录项对应的目标id。为什么不直接靠a.hash来关联？因为在局部滚动容器里我后面要用getElementById精确取目标，直接读dataset比解析href里的#更稳。

点击事件的绑定不要直接往每个a上挂addEventListener，更优做法是事件委托。目录树动辄几十项，逐项绑定性能上没问题，但委托更干净：

javascript复制container.addEventListener('click', (e) => {
  const link = e.target.closest('a[data-toc-target-id]');
  if (!link) return;
  e.preventDefault();
  const targetId = link.dataset.tocTargetId;
  smoothScrollToHeading(targetId);
});

3.4 滚动高亮：用IntersectionObserver替代scroll事件

这是整个目录索引实现里我认为价值最高的一部分。很早以前做这个功能，大家普遍是给window挂scroll监听，然后滚动时遍历所有标题，比较getBoundingClientRect().top的位置，找到“最靠近视口顶部但还没超过顶部”的标题。这个逻辑本身没错，但它有两个天生缺陷：

• 滚动事件触发频率极高，每次滚动都要遍历所有标题取布局信息，性能差
• 标题数量多或者页面里有重排操作时，滚动过程中计算出来的位置会跳变，高亮闪烁

所以我推荐用IntersectionObserver。它的核心价值是让浏览器在元素与视口（或指定容器）的相交状态发生变化时主动通知你，不需要你反复轮询几何位置。

具体思路是这样：给页面划出一条“观察线”，我把它设置在视口顶部偏下的位置。当某个标题越过这条线时，就认为它是当前阅读章节。

javascript复制function initScrollSpy(headings, callback) {
  const activeHeadingIds = new Set();
  let currentActiveId = null;

  const observer = new IntersectionObserver((entries) => {
    entries.forEach((entry) => {
      if (entry.isIntersecting) {
        activeHeadingIds.add(entry.target.id);
      } else {
        activeHeadingIds.delete(entry.target.id);
      }
    });

    // 从可见标题里选最靠上的那个作为当前章节
    const visibleHeadings = headings.filter((h) => activeHeadingIds.has(h.id));
    if (visibleHeadings.length > 0) {
      visibleHeadings.sort((a, b) => a.getBoundingClientRect().top - b.getBoundingClientRect().top);
      const newActiveId = visibleHeadings[0].id;
      if (newActiveId !== currentActiveId) {
        currentActiveId = newActiveId;
        callback(newActiveId);
      }
    }
  }, {
    root: scrollContainer || null,
    rootMargin: '-20px 0px -70% 0px',
    threshold: 0
  });

  headings.forEach((h) => observer.observe(h));
  return observer;
}

注意看rootMargin，这是整个监听策略的灵魂。

• -20px 0px：表示观察区域的上边界向下偏移20px。为什么？因为固定顶栏高度一般60px左右，标题滚动到视口顶边时会被顶栏挡住，如果直接按视口顶边判定，高亮切换会比实际阅读位置晚，所以把判定线上移一点。
• -70% 0px：表示观察区域的下边界向上收，只保留视口顶部30%区域作为“激活区”。这个设计解决了一个经典问题：当页面一屏里有多个标题时，到底高亮哪个？我的方案是只有进入视口顶部30%区域的标题才认为“当前”，低于这个区域的标题即使可见也不算。这和很多阅读类App“读到哪一章了”的体验一致。

这个思路比单纯判断“是否进入视口”更贴近真实阅读状态，我强烈建议你直接抄这个配置，然后按自己顶栏高度微调第一个值。

3.5 平滑滚动与偏移补偿

点击目录项之后，页面要滚动到标题位置，而不是让标题被固定顶栏挡住。这里的处理不能直接用href="#id"，那会把标题怼到视口最顶端，也就是顶栏下面，视觉效果很差。

javascript复制function smoothScrollToHeading(id) {
  const heading = document.getElementById(id);
  if (!heading) return;

  const scrollContainer = getScrollContainer(); // 可能是window，也可能是某个div
  const topOffset = getOffsetTopInContainer(heading, scrollContainer);
  const fixedHeaderHeight = 80; // 顶栏高度，建议做成配置

  if (scrollContainer === window) {
    window.scrollTo({
      top: topOffset - fixedHeaderHeight,
      behavior: 'smooth'
    });
  } else {
    scrollContainer.scrollTo({
      top: topOffset - fixedHeaderHeight + scrollContainer.scrollTop,
      behavior: 'smooth'
    });
  }
}

这里有一个很隐蔽的坑：element.offsetTop是相对offsetParent的，如果你的标题外面有多个定位层级，直接offsetTop - fixedHeaderHeight会算错，滚动位置飘到十万八千里。稳妥的做法是循环向上累加offsetTop，直到遇到滚动容器为止。我最早写目录功能时就是没注意这个，点击导航直接滚到了页面最底部，排查了大半天，最后发现是offsetParent链上有个position: relative的包裹层。所以这里要写一个通用计算函数：

javascript复制function getOffsetTopInContainer(el, container) {
  let top = 0;
  let current = el;
  while (current && current !== container) {
    top += current.offsetTop;
    current = current.offsetParent;
  }
  return top;
}

注意循环条件里的current !== container，如果你的容器不是标题的offsetParent祖先链中的一环，这个循环会一直走到null，所以调用前最好先确认container.contains(el)。

4. 高亮联动中的边界情况与性能优化

滚动高亮做出来是一回事，做得不闪不跳不卡是另一回事。这一节我专门把我踩过的边界情况拎出来讲，这些都是真实项目里大概率会遇到的。

4.1 一屏多个标题时，高亮策略如何取舍？

IntersectionObserver的rootMargin策略是“视口顶部30%为激活区”，但极端情况还是存在：某个章节特别短，两三个标题挤在一屏里，用户还没读完H2的内容，H3就已经进入激活区，高亮提前跳到H3上。

这个问题没有完美解，只能按场景权衡。我验证下来比较实用的方案是“标题级别加权”：同屏时优先高亮更高层级的标题。实现思路是在收集可见标题时，不只按照位置排序，还考虑级别：

javascript复制function selectActiveHeading(visibleHeadings) {
  const sorted = visibleHeadings.sort((a, b) => {
    const levelDiff = (levelMap[a.tagName] || 0) - (levelMap[b.tagName] || 0);
    if (levelDiff !== 0) return levelDiff;
    return a.getBoundingClientRect().top - b.getBoundingClientRect().top;
  });
  return sorted[0];
}

这样当H2和H3都处于激活区时，H2优先高亮；只有H3越过激活区而H2已经滚出激活区，H3才接管高亮。这个策略更符合“大章节感”。

4.2 监听回调里的大量读取操作怎么堵住？

IntersectionObserver的回调虽然不像scroll事件那样每秒跑几十次，但它触发频率依然不低，而且在快速滚动时，每个标题进入/离开都会触发一次回调。如果回调里每次都重新querySelectorAll、重新读大量几何信息，照样会卡。

我的优化手段有几点：

• 标题列表提前缓存，回调里只做Set操作和数组过滤，不做DOM查询
• getBoundingClientRect只在可见标题数组里调用，而不是遍历全部标题
• 高亮更新用requestAnimationFrame合帧，避免一次滚动同时更新多个状态导致的布局抖动

javascript复制let ticking = false;

function updateActiveState(newActiveId) {
  if (ticking) return;
  ticking = true;
  requestAnimationFrame(() => {
    // 更新目录项高亮class
    ticking = false;
  });
}

4.3 局部滚动容器怎么识别？

前面多次提到局部滚动容器，很多目录功能做成一半就翻在它手上。判断一个页面有没有局部滚动容器，方法很简单：看你的正文是不是overflow: auto或overflow-y: scroll的DOM元素内，而不是document上滚动。

我的做法是给模块传一个container配置项。如果设了，滚动监听和高亮监听的root都指向它；如果不设，root传null，代表视口。

javascript复制function createToc(options) {
  const {
    contentSelector = '.article-content',
    tocContainerSelector = '.toc',
    scrollContainer = document.scrollingElement || document.documentElement,
    headingsSelector = 'h2, h3, h4'
  } = options;
  // ...
}

document.scrollingElement是我后来补的一个细节。老版本兼容时，标准模式和怪异模式的滚动元素不一样，有些浏览器里document.documentElement不是实际滚动容器，直接用它做滚动监听会不触发。写document.scrollingElement || document.documentElement可以避免这个坑。

4.4 高亮项跟随：目录太长时定位不丢

当目录项很多，目录容器本身溢出了常见高度，用户虽然滚着正文，但高亮的那一项可能早滚出屏幕了。这时候需要在目录容器内部也做一次“高亮项滚入视野”的操作。调用时机是每次高亮状态更新之后。

javascript复制function scrollActiveTocItemIntoView(tocContainer, activeElement) {
  if (!activeElement) return;
  const containerRect = tocContainer.getBoundingClientRect();
  const itemRect = activeElement.getBoundingClientRect();

  if (itemRect.top < containerRect.top) {
    // 高亮项在容器可视区上方，让容器向上滚动
    tocContainer.scrollTop += itemRect.top - containerRect.top;
  } else if (itemRect.bottom > containerRect.bottom) {
    // 高亮项在可视区下方，让容器向下滚动
    tocContainer.scrollTop += itemRect.bottom - containerRect.bottom;
  }
}

这个思路就是“手动控制滚动位移”，而不是依赖scrollIntoView。为什么不直接用scrollIntoView？因为它会改变整个页面的滚动位置，哪怕你只想让目录容器内部滚动，它也可能连带把正文滚跑。所以我坚持手写位移，局部处理。

5. 目录的折叠交互、动态内容与模块化封装

核心链路跑通后，工作还没完。目录索引作为可复用模块，要能应对折叠交互、路由变化这类真实场景。

5.1 多层嵌套的折叠体验怎么做？

嵌套目录会让长文结构更清晰，但也会让目录变得很长。我通常的做法是默认只展开到二级层级，三级及以下默认折叠，用户点击父级目录项时展开子项。折叠的本质是控制子列表的max-height或display切换。display切换最省事，但失去高度过渡动画；用max-height可以平滑展开，但要小心子项很多时max-height设得太小导致内容截断。

更平滑的实现是用grid-template-rows: 0fr -> 1fr过渡，兼容性在现代浏览器里已经可以接受：

css复制.toc-sublist {
  display: grid;
  grid-template-rows: 0fr;
  transition: grid-template-rows 0.2s ease;
  overflow: hidden;
}

.toc-item.expanded .toc-sublist {
  grid-template-rows: 1fr;
}

需要配合JS在点击父级目录链接时切换expanded类。注意：这时点击父级不一定要滚动到目标标题，而是先展开子项。只有子项展开后再点击才滚动。交互上不要混为一谈，避免用户想展开子目录却直接跳到正文里。

5.2 动态内容：路由切换和异步加载后如何重新扫描？

我的博客是纯静态页面，本来不需要动态扫描。但后来我把它应用到一个后台管理项目里，需要支持用户切换不同文章时，目录跟着变化。这时候你就不能只在初始化时扫描一次标题，而要在内容更新后重新扫描。

我写了一个refresh()方法，内部做几件事：

• 断开上一个IntersectionObserver
• 清空目录容器DOM
• 重新执行collectHeadings、ensureHeadingIds、buildTocTree、renderToc
• 重新创建和绑定IntersectionObserver

这个方法在Vue里可以放在watch回调里，在React里可以放在useEffect里。调用时机要注意：必须在DOM已经渲染出新内容之后再refresh，否则会扫到空内容。异步获取文章数据时，我常在数据返回并在nextTick（Vue）或flushSync（React）之后才调用。

javascript复制// 伪代码示例，以React为例
useEffect(() => {
  const toc = new TocModule({
    contentSelector: '.article-content',
    tocContainerSelector: '.toc-sidebar'
  });
  toc.refresh(); // 首次初始化

  return () => toc.destroy(); // 清理监听器
}, [articleId]);

5.3 一个可复用的目录索引类：把散装代码收敛起来

前文代码都是散的，实际工程里我建议把它们收敛成一个类TocIndex。对外只暴露三个核心方法：init、refresh、destroy。内部私有方法包括标题收集、锚点注入、树构建、渲染、滚动监听初始化等。这样不管接Vue、React还是原生页面，使用方都是一致的。

javascript复制class TocIndex {
  constructor(options) {
    // 存储配置、缓存DOM引用
  }

  init() {
    this.headings = this.collect();
    this.ensureIds();
    const tree = this.buildTree();
    this.render(tree);
    this.bindClick();
    this.createScrollSpy();
    return this;
  }

  refresh() {
    this.destroyScrollSpy();
    this.container.innerHTML = '';
    this.init();
  }

  destroy() {
    this.destroyScrollSpy();
    this.container.removeEventListener('click', this.clickHandler);
  }
}

这个类的好处是方便单元测试。我后来给它的树构建逻辑、偏移计算逻辑各写了一组测试，把纯函数和DOM操作分离出来，这样即使以后换框架，核心逻辑也能直接复用。

6. 实践中常见的兼容性陷阱与排错过程

最后这一节，我分享几个真实的排错经历。每个问题我都标注了表象、根因和解决方式，方便你对照排查。

6.1 标题带特殊字符导致锚点失效

表象：点击目录项，URL变了#xxx，但页面不滚动。

根因：标题里有特殊字符或空格，导致生成的id不规范，或者querySelector匹配出现问题。举个实际例子：一个标题叫“Android 12 适配：存储权限变更”，文本里少了中划线，空格还在，但生成id时我原来的正则只过滤空格不过滤冒号，结果id里残留了中文冒号，虽然HTML5允许id含冒号，但某些浏览器里getElementById遇到了兼容问题。

解决方式：规范锚点生成逻辑，全部转换为[a-z0-9-]字符集，连续性分隔符合并，并且始终以字符串“section-”做前缀保证不以数字开头。改成这样以后，这类问题彻底消失。

6.2 字体加载导致锚点偏移错位

表象：首次打开页面，目录点击滚动位置偏了几十像素；刷新后正常。

根因：页面字体（尤其是中文Web字体）加载完成后，正文行高和标题字号发生变化，标题的几何位置整体下移或上移。而初始化时我按照字体加载前的getBoundingClientRect缓存了位置，字体加载后没有更新，于是滚动偏移全错。

解决方式：监听document.fonts.ready，在字体加载完成后调用一次refresh()，重新绑定滚动监听和高亮观察。这是一个很隐蔽、但对阅读类站点影响很大的问题，强烈建议你也处理一下。

6.3 移动端软键盘弹起导致视口高度变化，高亮乱跳

表象：在移动端打开一个带搜索框的页面，点击搜索框时软键盘弹起，目录高亮瞬间跳到第一项。

根因：软键盘弹起改变了浏览器视口高度，IntersectionObserver的相交状态被批量触发，大量标题短暂“离开”视口，导致活跃项被清空并回退到第一个。

解决方式：这不是改动逻辑能解决的事，需要在交互层面规避。我采取两个动作：一是当document.activeElement是input/textarea时，暂时禁用高亮更新；二是监听visualViewport.resize，判断视口尺寸变化超过一定阈值时，在一段时间内不去更新高亮，避免抖动。

javascript复制let isKeyboardOpening = false;
window.visualViewport?.addEventListener('resize', () => {
  const heightDiff = Math.abs(window.visualViewport.height - window.innerHeight);
  if (heightDiff > 200) {
    isKeyboardOpening = true;
    setTimeout(() => { isKeyboardOpening = false; }, 500);
  }
});

6.4 一次最耗时的排错：局部容器中scrollTop计算飘移

这是我整篇里踩过最深的一个坑。当时后台管理页面，正文区是一个独立滚动的div，我给目录索引传入了scrollContainer: '#main-content'。实现后点击目录，页面滚动时好时坏，有时候滚到了完全无关的位置。

先怀疑是滚动偏移算错了，打断点看getBoundingClientRect().top和offsetTop，数值都正常，直到单步执行看到scrollContainer.scrollTop在滚动过程中被外部逻辑修改了——因为页面里有一个“回到顶部”按钮，它监听滚动事件并把scrollTop设置为0。这个按钮的事件绑定在window上，而局部容器的滚动事件并不冒泡到window，但它用了document.addEventListener('scroll', ...)加上capture: true，结果局部滚动也被捕捉，然后粗暴调用了scrollTo(0,0)。

根因找到了：不是目录模块本身的问题，而是外部代码对局部滚动容器的不当假设。这给我提了个醒：做目录索引时，一定要拿到页面里所有“全局滚动监听”的代码梳理一遍，否则局部容器滚动会被各种意想不到的逻辑干扰。如果你遇到“点击目录滚动位置诡异”的问题，第一件事不是怀疑偏移计算，而是排查有没有别的代码也在动滚动位置。

这类问题还有个更隐蔽的变体：CSS里设置了scroll-behavior: smooth，又和JS的window.scrollTo({behavior: 'smooth'})叠加，导致连续点击目录项时滚动动画互相抵消，位置停在中途。解决方式是连续点击时先取消之前的动画，比较直接的做法是scrollTo之前把behavior临时改成auto立即到位一次，再平滑滚动。

一个关于选型和维护的最终体会

整个目录索引功能从最初几十行脚本，到后来演变成可复用的TocIndex模块，我最大的体会是：这个功能看着不起眼，但它是内容和读者之间最直接的导航契约。读者判断一个网站专不专业，很多时候不靠花哨的动效，而是靠“我能不能轻松找到我要的那段内容”。

如果你现在正准备给项目加目录索引，我的建议很简单：先别急着引插件，花十分钟明确你的页面结构、滚动容器、标题层级和动态内容场景，再决定是手写还是用工具。把核心交互（锚点、高亮、滚动偏移）亲手实现一遍，你会对浏览器滚动机制、IntersectionObserver的行为边界有一个非常扎实的理解。这份理解以后排查任何带滚动交互的需求都会用得上。

一个小技巧作为收尾送给各位：如果你做完后发现目录高亮偶尔慢半拍，不用急着改算法，先检查一下你的高亮样式是不是触发了很多CSS重绘，比如box-shadow、transform过渡这类属性。把高亮形式从“改变背景色”换成“改变左边框宽度”，性能通常能改善不少，这是我实测后的经验。