bootstrap_ref_js_scrollspy

Bootstrap 5 JavaScript Scrollspy 插件

Scrollspy (scrollspy.js)

Scrollspy 插件会根据页面当前的滚动位置，动态更新导航列表中的链接。这对于单页设计或具有清晰章节、用户可以导航到的页面非常有用。

注意：Scrollspy 需要 Bootstrap 的 JavaScript 和 Popper.js（这些包含在 Bootstrap 的 bootstrap.bundle.min.js 包中）。它还需要导航组件具有 position: sticky; 或 position: fixed; 样式，以便在滚动时清晰地看到“侦测”效果（spy effect）。

通过数据属性使用

要轻松添加 Scrollspy 行为，请将 data-bs-spy="scroll" 添加到你想要“侦测”的元素上（通常是 <body> 元素）。然后，添加 data-bs-target，其值是你导航组件（例如 <nav> 或 <ul>）的 ID 或类选择器。如果被“侦测”的不是 <body>，请确保该可滚动元素具有固定的高度和 overflow-y: scroll; 样式。

你的导航链接中的 href 属性必须与你想要“侦测”的章节的 id 属性相匹配。

<!-- Navigation Bar -->
<nav id="navbar-example" class="navbar navbar-light bg-light px-3 sticky-top">
  <a class="navbar-brand" href="#">Navbar</a>
  <ul class="nav nav-pills">
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading1">First</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#scrollspyHeading2">Second</a>
    </li>
    <li class="nav-item dropdown">
      <a class="nav-link dropdown-toggle" data-bs-toggle="dropdown" href="#" role="button" aria-expanded="false">Dropdown</a>
      <ul class="dropdown-menu">
        <li><a class="dropdown-item" href="#scrollspyHeading3">Third</a></li>
        <li><a class="dropdown-item" href="#scrollspyHeading4">Fourth</a></li>
        <li><hr class="dropdown-divider"></li>
        <li><a class="dropdown-item" href="#scrollspyHeading5">Fifth</a></li>
      </ul>
    </li>
  </ul>
</nav>

<!-- Scrollable Area -->
<div data-bs-spy="scroll" data-bs-target="#navbar-example" data-bs-offset="0" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0" style="position: relative; height: 200px; overflow-y: scroll;">
  <h4 id="scrollspyHeading1">First heading</h4>
  <p>Content for first heading...</p>
  <h4 id="scrollspyHeading2">Second heading</h4>
  <p>Content for second heading...</p>
  <h4 id="scrollspyHeading3">Third heading</h4>
  <p>Content for third heading...</p>
  <h4 id="scrollspyHeading4">Fourth heading</h4>
  <p>Content for fourth heading...</p>
  <h4 id="scrollspyHeading5">Fifth heading</h4>
  <p>Content for fifth heading...</p>
</div>

关键属性：data-bs-spy="scroll"、data-bs-target="#navbar-example"、data-bs-offset="value"（计算滚动位置时距离顶部的偏移像素）以及 data-bs-smooth-scroll="true"（用于点击导航链接时实现平滑滚动）。

通过 JavaScript 使用

你也可以通过 JavaScript 手动初始化 Scrollspy：

var scrollSpy = new bootstrap.ScrollSpy(document.body, {
  target: '#navbar-example'
});

// Or on a specific scrollable element:
var dataSpyList = [].slice.call(document.querySelectorAll('[data-bs-spy="scroll"]'))
dataSpyList.forEach(function (dataSpyEl) {
  bootstrap.ScrollSpy.getInstance(dataSpyEl)
    .refresh()
});

Scrollspy 选项

选项可以通过数据属性或 JavaScript 传递。对于数据属性，请将选项名称附加到 data-bs- 前缀后面，例如 data-bs-offset="50"。

名称	类型	默认值	描述
offset	number	10	指定计算滚动位置时距离顶部的偏移像素数。如果你有固定头部（fixed header），这会很有用。
target	string | Element	null	指定目标导航元素（ID 或类选择器），其链接将被更新。
smoothScroll	boolean	false	点击导航链接时启用平滑滚动。通过 data-bs-smooth-scroll="true" 设置。

Scrollspy 方法

这些方法允许通过程序控制 Scrollspy 实例。

方法 描述 示例

.refresh() 当从 DOM 中动态添加或移除影响 Scrollspy 目标的元素时，调用此方法来更新 Scrollspy 实例。 bootstrap.ScrollSpy.getInstance(element).refresh() 尝试

.dispose() 销毁元素的 Scrollspy 实例。 bootstrap.ScrollSpy.getInstance(element).dispose() 尝试

.getInstance(element) 静态方法，允许你获取与 DOM 元素关联的 Scrollspy 实例。 var scrollSpyInstance = bootstrap.ScrollSpy.getInstance(myScrollspyElement) 尝试

.getOrCreateInstance(element, [config]) 静态方法，允许你获取与 DOM 元素关联的 Scrollspy 实例，或者在未初始化的情况下创建一个新的。 var scrollSpyInstance = bootstrap.ScrollSpy.getOrCreateInstance(myScrollspyElement, {offset: 20}) 尝试

Scrollspy 事件

Bootstrap 的 Scrollspy 插件暴露了一个你可以钩入（hook into）的事件。

事件 描述 示例

activate.bs.scrollspy 当 Scrollspy 激活新项目时，此事件会在导航列表上触发。该事件提供了 relatedTarget 属性，该属性是激活部分的 ID。 myScrollSpyElement.addEventListener('activate.bs.scrollspy', function (event) { console.log('Active section:', event.relatedTarget); }) 尝试

应用场景：一个产品落地页（landing page），包含 ‘特性’（Features）、‘规格’（Specifications）、‘定价’（Pricing）和 ‘联系方式’（Contact）等章节。页面顶部的固定导航栏（sticky navigation bar）使用 Scrollspy 来高亮用户滚动时当前所在的章节链接，并且点击链接可以平滑滚动到该章节。

常见陷阱：确保你的目标章节（例如 <div id="section1">）有足够的内容使其可滚动，并且它们的顶部能够经过 Scrollspy 偏移量指定的位置。如果章节太短，Scrollspy 可能无法正确激活。