прокрутка

Автоматически обновляйте компоненты навигации или группы списка 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

Это некоторый заполнитель для страницы scrollspy. Обратите внимание, что при прокрутке страницы соответствующая навигационная ссылка выделяется. Это повторяется во всем примере компонента. Мы продолжаем добавлять сюда еще несколько примеров, чтобы подчер��нуть прокрутку и выделение.

Пункт 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 вам необходимо вызвать метод обновления.

Вот пример использования метода обновления:

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...
})

прокрутка

Как это работает

Примеры

Навбар

Первый заголовок

Второй заголовок

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

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

Пятый заголовок

Вложенная навигация

Пункт 1

Пункт 1-1

Пункт 1-2

Пункт 2

Пункт 3

Пункт 3-1

Пункт 3-2

Группа списка

Пункт 1

Пункт 2

Пункт 3

Пункт 4

Простые якоря

Пункт 1

Пункт 2

Пункт 3

Пункт 4

Пункт 5

Невидимые элементы

Применение

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

Через JavaScript

Опции

Методы

События