Scrollspy 初始化后新增导航项不生效,需手动调用实例的refresh()方法重新扫描目标元素(带id的section),确保新section已插入DOM且id与href值匹配。

Scrollspy 初始化后新增导航项不生效
Bootstrap 的 scrollspy 默认只在初始化时扫描一次 .nav-link 和对应目标元素(id 匹配的 section),后续用 JS 动态插入的新导航项不会自动纳入监听范围——这不是 bug,是设计使然。它不监听 DOM 变化,也不提供“重刷” API。
必须手动调用 refresh 方法重新扫描目标元素
关键点在于:不是刷新导航栏本身,而是让 Scrollspy 重新识别所有可滚动区域内的目标锚点(即带 id 的 section)。只有目标元素列表更新了,新导航项才能正确高亮。
-
refresh是 Bootstrap 5+ 中ScrollSpy实例的方法,需先拿到实例引用(不能靠data-bs-spy自动初始化后直接调用) - 调用时机必须在新
<section id="xxx"></section>已插入 DOM 之后,否则扫描不到 - 不需要、也不应该手动给新
<a class="nav-link" href="#xxx"></a>绑定事件或添加 class;只要 href 值和现有 section 的id匹配,refresh 后就能联动
示例:
// 初始化时保留实例引用
const scrollSpy = new bootstrap.ScrollSpy(document.body, {
target: '#navbar',
offset: 80
});
// 动态添加一个 section 和对应 nav-link 后
document.querySelector('#content').insertAdjacentHTML('beforeend', `
<section id="faq"><h2>FAQ</h2></section>
`);
document.querySelector('#navbar .nav').insertAdjacentHTML('beforeend', `
<li class="nav-item">
<a class="nav-link" href="#faq">常见问题</a>
</li>
`);
// ✅ 必须调用 refresh,且要在 DOM 插入完成后
scrollSpy.refresh();
使用原生 querySelectorAll 检查是否真被识别
如果 refresh() 后仍不生效,大概率是目标元素没被正确扫描到。最直接的验证方式是手动检查 Scrollspy 实例内部缓存的目标节点:
- Bootstrap 5 中可通过
scrollSpy._targets(私有属性,仅用于调试)看当前识别到哪些id - 更稳妥的做法是模拟其逻辑:
document.querySelectorAll('[id]')看新 section 是否在结果中;再确认该id是否出现在href属性值里(注意去 #) - 常见漏掉的细节:
id含空格、特殊字符(如faq-2?),或未转义导致 CSS 选择器失败;href写成/#faq或https://site.com/#faq—— Scrollspy 只认纯#faq
动态添加后滚动位置错位或高亮延迟
这通常不是 Scrollspy 本身的问题,而是 DOM 插入后页面高度突变,但 Scrollspy 的滚动监听器还没来得及响应新的 offset 计算。解决方案很简单:
- 确保新
<section></section>插入后,浏览器已触发 layout(例如强制读取offsetHeight) - 在
refresh()前加一个微任务,让渲染队列清空:setTimeout(() => scrollSpy.refresh(), 0)或queueMicrotask(() => scrollSpy.refresh()) - 若用了 CSS transition/height:auto,考虑在插入后加
style.transition = 'none'临时禁用动画,refresh 完再恢复
nav-link 加进去了,Scrollspy 就该自动管”,其实它根本不关心导航 DOM 结构——只认目标元素的 id 和滚动位置映射关系。refresh 不是“更新菜单”,是“重新丈量页面”。


















