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 пры разліку пазіцыі пракруткі.
`smoothScroll`	лагічны	`false`	Дазваляе плыўную пракрутку, калі карыстальнік націскае на спасылку, якая спасылаецца на назіраныя ScrollSpy.
`target`	радок, элемент DOM	`null`	Вызначае элемент для прымянення плагіна Scrollspy.
`threshold`	масіў	`[0.1, 0.5, 1]`	`IntersectionObserver` парогавае значэнне дапушчальнага ўводу пры разліку пазіцыі пракруткі.

Састарэлыя параметры

Да версіі 5.1.3 мы выкарыстоўвалі offset& methodoptions, якія цяпер састарэлі і заменены на rootMargin. Каб захаваць зваротную сумяшчальнасць, мы будзем працягваць разбіраць дадзены offsetў rootMargin, але гэтая функцыя будзе выдалена ў v6 .

Метады

Метад	Апісанне
`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

Параметры

Метады

Падзеі