Skip to content
W3S101

Bootstrap 滚动监听

Bootstrap 5 Scrollspy 插件

Section titled “Bootstrap 5 Scrollspy 插件”

Scrollspy 插件

Section titled “Scrollspy 插件”

Scrollspy 插件用于根据页面当前的滚动位置自动更新导航列表中的链接。这对于单页网站或文档页面非常有用，因为你想在导航中高亮当前活跃的区域。

当你滚动页面时，active 类会被添加到或从导航项中移除，直观地指示当前正在查看的是哪个区域。

如何创建 Scrollspy

Section titled “如何创建 Scrollspy”

以下示例展示了如何创建一个带有固定在顶部的导航条（navbar）的基本 Scrollspy：

<!-- 导航条 (navbar) -->
<nav id="navbar-example" class="navbar navbar-expand-lg navbar-dark bg-dark fixed-top px-3">
  <a class="navbar-brand" href="#">My Page</a>
  <div class="collapse navbar-collapse">
    <ul class="navbar-nav">
      <li class="nav-item"><a class="nav-link" href="#section1">Section 1</a></li>
      <li class="nav-item"><a class="nav-link" href="#section2">Section 2</a></li>
      <li class="nav-item"><a class="nav-link" href="#section3">Section 3</a></li>
    </ul>
  </div>
</nav>


<!-- 可滚动区域 (例如，body 或特定的 div) -->
<!-- 添加 data-bs-spy, data-bs-target, data-bs-offset, 和 tabindex (如果不是 body) -->
<div data-bs-spy="scroll" data-bs-target="#navbar-example" data-bs-offset="70" tabindex="0" style="padding-top: 56px;">
  <!-- 注意：可滚动区域的 padding-top 应适应固定导航条的高度 -->


  <div id="section1" style="height: 500px; background-color: #f0f0f0; padding: 20px;">
    <h2>Section 1</h2>
    <p>Content for section 1... Try to scroll this page and watch the navigation bar!</p>
  </div>
  <div id="section2" style="height: 500px; background-color: #e0e0e0; padding: 20px;">
    <h2>Section 2</h2>
    <p>Content for section 2...</p>
  </div>
  <div id="section3" style="height: 500px; background-color: #d0d0d0; padding: 20px;">
    <h2>Section 3</h2>
    <p>Content for section 3...</p>
  </div>
</div>


<!--
  重要提示：Scrollspy 需要 JavaScript。确保包含了 Bootstrap 的 JS (bootstrap.bundle.min.js 或 scrollspy.js + 依赖项)。
  上面的示例为了清晰使用了内联样式设置高度和背景；在实际项目中，请使用 CSS 类。
-->

示例解释

Section titled “示例解释”
  • 将 data-bs-spy="scroll" 添加到作为可滚动区域的元素上。通常，这是 <body> 元素，但也可以是任何可滚动的 <div>。
  • 如果可滚动区域不是 <body>，它必须设置 height 和 overflow-y: scroll; 以便在其内部发生滚动。它还需要 tabindex="0" 以便通过键盘进行导航时可聚焦。
  • 添加 data-bs-target 属性，其值是导航条的 ID 或类名（例如，data-bs-target="#navbar-example" 或 data-bs-target=".navbar"）。这将可滚动区域链接到导航组件。
  • 导航条内链接的 href 属性（例如，<a class="nav-link" href="#section1">）必须与可滚动区域中各部分的 id 属性（例如，<div id="section1">）匹配。
  • 可选的 data-bs-offset 属性（例如，data-bs-offset="70"）指定从顶部偏移的像素数，用于计算滚动位置。当使用固定/吸顶导航条时，这至关重要，以确保当某区域的顶部与导航条底部对齐时，正确区域被高亮，而不是与视口的最顶部对齐。
  • CSS position: relative; 要求： 带有 data-bs-spy="scroll" 的元素（如果不是 <body>）必须在其 CSS 中设置 position: relative;，Scrollspy 才能正常工作。

实际应用：适用于单页应用、落地页或文档网站，其中导航帮助用户在内容区域之间跳转并查看当前位置。

常见障碍：不正确的 data-bs-offset 值，导致高亮错误区域或过早/过晚高亮。通常需要调整此值以匹配任何固定/吸顶顶部导航的高度。

提示：Scrollspy 通过 data-bs-spy 属性自动初始化。你也可以使用 JavaScript 以编程方式初始化它：new bootstrap.ScrollSpy(document.body, { target: '#navbar-example', offset: 70 })。

带有垂直导航菜单的 Scrollspy（例如 Nav Pills）

Section titled “带有垂直导航菜单的 Scrollspy（例如 Nav Pills）”

Scrollspy 同样适用于垂直导航菜单。原理相同。

在此示例中，我们使用 Bootstrap 网格布局，在其中一列放置垂直导航（.nav-pills.flex-column），在另一列放置可滚动内容。<body> 本身就是可滚动区域。

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Vertical Scrollspy Example</title>
  <link href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/css/bootstrap.min.css" rel="stylesheet">
  <style>
    body { position: relative; /* Scrollspy 在 body 上需要 */ }
    #myScrollspy { position: sticky; top: 20px; /* 使导航吸顶 */ }
    .content-section { height: 400px; padding: 20px; margin-bottom: 20px; border: 1px solid #ccc; }
  </style>
</head>
<body data-bs-spy="scroll" data-bs-target="#myScrollspy" data-bs-offset="20">


<div class="container mt-3">
  <div class="row">
    <nav class="col-sm-3 col-md-2" id="myScrollspy">
      <ul class="nav nav-pills flex-column">
        <li class="nav-item">
          <a class="nav-link" href="#contentSection1">Section 1</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#contentSection2">Section 2</a>
        </li>
        <li class="nav-item">
          <a class="nav-link" href="#contentSection3">Section 3</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="#contentSection4">Section 4</a></li>
            <li><a class="dropdown-item" href="#contentSection5">Section 5</a></li>
          </ul>
        </li>
      </ul>
    </nav>


    <div class="col-sm-9 col-md-10">
      <div id="contentSection1" class="content-section bg-light">
        <h4>Section 1</h4>
        <p>Content for section 1...</p>
      </div>
      <div id="contentSection2" class="content-section bg-light">
        <h4>Section 2</h4>
        <p>Content for section 2...</p>
      </div>
      <div id="contentSection3" class="content-section bg-light">
        <h4>Section 3</h4>
        <p>Content for section 3...</p>
      </div>
      <div id="contentSection4" class="content-section bg-light">
        <h4>Section 4 (from dropdown)</h4>
        <p>Content for section 4...</p>
      </div>
      <div id="contentSection5" class="content-section bg-light">
        <h4>Section 5 (from dropdown)</h4>
        <p>Content for section 5...</p>
      </div>
    </div>
  </div>
</div>


<script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.0/dist/js/bootstrap.bundle.min.js"></script>
</body>
</html>


<!-- 进一步阅读：有关所有选项、方法和事件，请查阅官方 Bootstrap Scrollspy 文档：https://getbootstrap.com/docs/5.3/components/scrollspy/ -->