Scrollspy

Автоматично оновлюйте навігацію Bootstrap або компоненти групи списків на основі позиції прокручування, щоб вказати, яке посилання зараз активне у вікні перегляду.

На цій сторінці

Як це працює

Scrollspy перемикає .activeклас на <a>елементах прив’язки (), коли елемент, на який idпосилається прив’язка, hrefпрокручується в поле зору. Scrollspy найкраще використовувати в поєднанні з навігаційним компонентом Bootstrap або групою списку , але він також працюватиме з будь-якими прив’язними елементами на поточній сторінці. Ось як це працює.

Для початку Scrollspy вимагає двох речей: навігації, групи списку або простого набору посилань, а також контейнер, який можна прокручувати. Контейнер, який можна прокручувати, може бути <body>або користувацьким елементом із набором heightі overflow-y: scroll.
У контейнері, який можна прокручувати, додайте data-bs-spy="scroll"та data-bs-target="#navId"де navIdє унікальним idдля пов’язаної навігації. Обов’язково також додайте , tabindex="0"щоб забезпечити доступ до клавіатури.
Коли ви прокручуєте «підглянутий» контейнер, .activeклас додається та видаляється з прив’язних посилань у пов’язаній навігації. Посилання повинні мати idцілі, які можна розв’язати, інакше вони ігноруються. Наприклад, <a href="#home">home</a>має відповідати чомусь у DOM, як<div id="home"></div>
Невидимі цільові елементи ігноруватимуться. Дивіться розділ « Невидимі елементи » нижче.

Приклади

Прокрутіть область під панеллю навігації та спостерігайте за зміною активного класу. Відкрийте меню, що випадає, і подивіться, як висвітлюються елементи спадного меню.

Перший заголовок

Це деякий вміст заповнювача для сторінки Scrollspy. Зауважте, що під час прокручування сторінки вниз відповідне навігаційне посилання буде виділено. Це повторюється в прикладі компонента. Ми продовжуємо додавати ще кілька зразків, щоб підкреслити прокручування та виділення.

Другий заголовок

Третій заголовок

Четвертий заголовок

П'ятий заголовок

<nav id="navbar-example2" class="navbar bg-light px-3 mb-3">
  <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>
<div data-bs-spy="scroll" data-bs-target="#navbar-example2" data-bs-root-margin="0px 0px -40%" data-bs-smooth-scroll="true" class="scrollspy-example bg-light p-3 rounded-2" tabindex="0">
  <h4 id="scrollspyHeading1">First heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading2">Second heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading3">Third heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading4">Fourth heading</h4>
  <p>...</p>
  <h4 id="scrollspyHeading5">Fifth heading</h4>
  <p>...</p>
</div>

Вкладена нав

Scrollspy також працює з вкладеними .navs. Якщо вкладений .navє .active, його батьки також будуть .active. Прокрутіть область поруч із панеллю навігації та спостерігайте за зміною активного класу.

Пункт 1

Майте на увазі, що плагін JavaScript намагається вибрати правильний елемент серед усього, що може бути видимим. Кілька видимих цілей Scrollspy одночасно можуть спричинити деякі проблеми.

Пункт 1-1

Пункт 1-2

Пункт 2

Пункт 3

Пункт 3-1

Пункт 3-2

<div class="row">
  <div class="col-4">
    <nav id="navbar-example3" class="h-100 flex-column align-items-stretch pe-4 border-end">
      <nav class="nav nav-pills flex-column">
        <a class="nav-link" href="#item-1">Item 1</a>
        <nav class="nav nav-pills flex-column">
          <a class="nav-link ms-3 my-1" href="#item-1-1">Item 1-1</a>
          <a class="nav-link ms-3 my-1" href="#item-1-2">Item 1-2</a>
        </nav>
        <a class="nav-link" href="#item-2">Item 2</a>
        <a class="nav-link" href="#item-3">Item 3</a>
        <nav class="nav nav-pills flex-column">
          <a class="nav-link ms-3 my-1" href="#item-3-1">Item 3-1</a>
          <a class="nav-link ms-3 my-1" href="#item-3-2">Item 3-2</a>
        </nav>
      </nav>
    </nav>
  </div>

  <div class="col-8">
    <div data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-smooth-scroll="true" class="scrollspy-example-2" tabindex="0">
      <div id="item-1">
        <h4>Item 1</h4>
        <p>...</p>
      </div>
      <div id="item-1-1">
        <h5>Item 1-1</h5>
        <p>...</p>
      </div>
      <div id="item-1-2">
        <h5>Item 1-2</h5>
        <p>...</p>
      </div>
      <div id="item-2">
        <h4>Item 2</h4>
        <p>...</p>
      </div>
      <div id="item-3">
        <h4>Item 3</h4>
        <p>...</p>
      </div>
      <div id="item-3-1">
        <h5>Item 3-1</h5>
        <p>...</p>
      </div>
      <div id="item-3-2">
        <h5>Item 3-2</h5>
        <p>...</p>
      </div>
    </div>
  </div>
</div>

Список групи

Scrollspy також працює з .list-groups. Прокрутіть область поруч із групою списку та спостерігайте за зміною активного класу.

Пункт 1 Пункт 2 Пункт 3 Пункт 4

Пункт 1

Пункт 2

Пункт 3

Пункт 4

<div class="row">
  <div class="col-4">
    <div id="list-example" class="list-group">
      <a class="list-group-item list-group-item-action" href="#list-item-1">Item 1</a>
      <a class="list-group-item list-group-item-action" href="#list-item-2">Item 2</a>
      <a class="list-group-item list-group-item-action" href="#list-item-3">Item 3</a>
      <a class="list-group-item list-group-item-action" href="#list-item-4">Item 4</a>
    </div>
  </div>
  <div class="col-8">
    <div data-bs-spy="scroll" data-bs-target="#list-example" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0">
      <h4 id="list-item-1">Item 1</h4>
      <p>...</p>
      <h4 id="list-item-2">Item 2</h4>
      <p>...</p>
      <h4 id="list-item-3">Item 3</h4>
      <p>...</p>
      <h4 id="list-item-4">Item 4</h4>
      <p>...</p>
    </div>
  </div>
</div>

Прості анкери

Scrollspy не обмежується компонентами навігації та групами списків, тому він працюватиме з будь-якими <a>елементами прив’язки в поточному документі. Прокрутіть область і спостерігайте за .activeзміною класу.

Пункт 1 Пункт 2 Пункт 3 Пункт 4 Пункт 5

Пункт 1

Пункт 2

Пункт 3

Пункт 4

Пункт 5

<div class="row">
  <div class="col-4">
    <div id="simple-list-example" class="d-flex flex-column gap-2 simple-list-example-scrollspy text-center">
      <a class="p-1 rounded" href="#simple-list-item-1">Item 1</a>
      <a class="p-1 rounded" href="#simple-list-item-2">Item 2</a>
      <a class="p-1 rounded" href="#simple-list-item-3">Item 3</a>
      <a class="p-1 rounded" href="#simple-list-item-4">Item 4</a>
      <a class="p-1 rounded" href="#simple-list-item-5">Item 5</a>
    </div>
  </div>
  <div class="col-8">
    <div data-bs-spy="scroll" data-bs-target="#simple-list-example" data-bs-offset="0" data-bs-smooth-scroll="true" class="scrollspy-example" tabindex="0">
      <h4 id="simple-list-item-1">Item 1</h4>
      <p>...</p>
      <h4 id="simple-list-item-2">Item 2</h4>
      <p>...</p>
      <h4 id="simple-list-item-3">Item 3</h4>
      <p>...</p>
      <h4 id="simple-list-item-4">Item 4</h4>
      <p>...</p>
      <h4 id="simple-list-item-5">Item 5</h4>
      <p>...</p>
    </div>
  </div>
</div>

Невидимі елементи

Невидимі цільові елементи ігноруватимуться, а їхні відповідні елементи навігації не отримають .activeклас. Екземпляри Scrollspy, ініціалізовані в невидимій обгортці, ігноруватимуть усі цільові елементи. Використовуйте refreshметод для перевірки спостережуваних елементів, коли обгортка стане видимою.

document.querySelectorAll('#nav-tab>[data-bs-toggle="tab"]').forEach(el => {
  el.addEventListener('shown.bs.tab', () => {
    const target = el.getAttribute('data-bs-target')
    const scrollElem = document.querySelector(`${target} [data-bs-spy="scroll"]`)
    bootstrap.ScrollSpy.getOrCreateInstance(scrollElem).refresh()
  })
})

Використання

Через атрибути даних

Щоб легко додати шпигунську поведінку до вашої верхньої панелі навігації, додайте data-bs-spy="scroll"до елемента, який ви хочете стежити (найчастіше це буде <body>). Потім додайте data-bs-targetатрибут із idназвою класу або батьківського елемента будь-якого .navкомпонента Bootstrap.

<body data-bs-spy="scroll" data-bs-target="#navbar-example">
  ...
  <div id="navbar-example">
    <ul class="nav nav-tabs" role="tablist">
      ...
    </ul>
  </div>
  ...
</body>

Через JavaScript

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

Опції

Оскільки параметри можна передати через атрибути даних або JavaScript, ви можете додати назву параметра до data-bs-, як у data-bs-animation="{value}". Обов’язково змініть тип регістру назви параметра з « camelCase » на « kebab-case » під час передачі параметрів через атрибути даних. Наприклад, використовуйте data-bs-custom-class="beautifier"замість data-bs-customClass="beautifier".

Починаючи з Bootstrap 5.2.0, усі компоненти підтримують експериментальний зарезервований атрибут даних data-bs-config, який може зберігати просту конфігурацію компонента як рядок JSON. Якщо елемент має атрибути data-bs-config='{"delay":0, "title":123}'і data-bs-title="456", остаточне titleзначення буде таким, 456а окремі атрибути даних замінять значення, надані в data-bs-config. Крім того, наявні атрибути даних можуть містити такі значення JSON, як data-bs-delay='{"show":0,"hide":150}'.

Ім'я	Тип	За замовчуванням	опис
`rootMargin`	рядок	`0px 0px -25%`	Intersection Observer rootMargin дійсні одиниці під час розрахунку положення прокручування.
`smoothScroll`	логічний	`false`	Вмикає плавне прокручування, коли користувач натискає посилання, яке посилається на спостережувані ScrollSpy.
`target`	рядок, елемент DOM	`null`	Визначає елемент для застосування плагіна Scrollspy.
`threshold`	масив	`[0.1, 0.5, 1]`	`IntersectionObserver` порогове значення дійсного введення під час розрахунку положення прокручування.

Застарілі параметри

До версії 5.1.3 ми використовували опції offset& method, які зараз застаріли та замінені на rootMargin. Щоб зберегти зворотну сумісність, ми продовжуватимемо розбирати заданий offsetдля rootMargin, але цю функцію буде видалено у версії 6 .

методи

метод	опис
`dispose`	Знищує scrollspy елемента. (Видаляє збережені дані в елементі DOM)
`getInstance`	Статичний метод отримання екземпляра Scrollspy, пов’язаного з елементом DOM.
`getOrCreateInstance`	Статичний метод для отримання екземпляра scrollspy, пов’язаного з елементом DOM, або для створення нового, якщо він не був ініціалізований.
`refresh`	Додаючи або видаляючи елементи в DOM, вам потрібно буде викликати метод refresh.

Ось приклад використання методу оновлення:

const dataSpyList = document.querySelectorAll('[data-bs-spy="scroll"]')
dataSpyList.forEach(dataSpyEl => {
  bootstrap.ScrollSpy.getInstance(dataSpyEl).refresh()
})

Події

Подія	опис
`activate.bs.scrollspy`	Ця подія спрацьовує на елементі прокрутки щоразу, коли прив’язку активує scrollspy.

const firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', () => {
  // do something...
})

Scrollspy

Як це працює

Приклади

Навігаційна панель

Перший заголовок

Другий заголовок

Третій заголовок

Четвертий заголовок

П'ятий заголовок

Вкладена нав

Пункт 1

Пункт 1-1

Пункт 1-2

Пункт 2

Пункт 3

Пункт 3-1

Пункт 3-2

Список групи

Пункт 1

Пункт 2

Пункт 3

Пункт 4

Прості анкери

Пункт 1

Пункт 2

Пункт 3

Пункт 4

Пункт 5

Невидимі елементи

Використання

Через атрибути даних

Через JavaScript

Опції

методи

Події