Scrollspy

Automaticky aktualizujte navigaci Bootstrap nebo seznam součástí skupiny na základě pozice posouvání, abyste označili, který odkaz je aktuálně aktivní ve výřezu.

Na této straně

Jak to funguje

Scrollspy přepíná .activetřídu na <a>prvcích kotvy ( ), když je prvek s idodkazem na kotvu hrefposunut do pohledu. Scrollspy se nejlépe používá ve spojení s komponentou Bootstrap nav nebo skupinou seznamů , ale bude fungovat také s libovolnými kotevními prvky na aktuální stránce. Zde je návod, jak to funguje.

Pro začátek vyžaduje scrollspy dvě věci: navigaci, skupinu seznamů nebo jednoduchou sadu odkazů a navíc rolovací kontejner. Posouvatelným kontejnerem může být <body>prvek nebo vlastní prvek se sadou heighta overflow-y: scroll.
Na rolovatelném kontejneru přidejte data-bs-spy="scroll"a data-bs-target="#navId"kde navIdje jedinečnost idpřidružené navigace. Nezapomeňte také uvést a tabindex="0"zajistit přístup ke klávesnici.
Při posouvání „špionovaného“ kontejneru se .activetřída přidává a odebírá z odkazů ukotvení v přidružené navigaci. Odkazy musí mít řešitelné idcíle, jinak jsou ignorovány. Například <a href="#home">home</a>musí odpovídat něčemu v DOM, jako je<div id="home"></div>
Cílové prvky, které nejsou viditelné, budou ignorovány. Viz část Neviditelné prvky níže.

Příklady

Posouvejte oblast pod navigační lištou a sledujte, jak se aktivní třída mění. Otevřete rozevírací nabídku a sledujte, jak jsou také zvýrazněny položky rozevíracího seznamu.

První nadpis

Toto je nějaký zástupný obsah pro scrollspy stránku. Všimněte si, že při posouvání stránky dolů se zvýrazní příslušný navigační odkaz. Opakuje se v celém příkladu komponenty. Stále přidáváme další ukázkové kopie, abychom zdůraznili posouvání a zvýrazňování.

Druhý nadpis

Třetí nadpis

Čtvrtý nadpis

Pátý nadpis

<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>

Vnořená navigace

Scrollspy funguje také s vnořenými .navs. Pokud je vnořený objekt .nav, .activejeho rodiče budou také .active. Posouvejte oblast vedle navigačního panelu a sledujte, jak se aktivní třída mění.

Položka 1

Nezapomeňte, že plugin JavaScript se snaží vybrat ten správný prvek ze všech, které mohou být viditelné. Několik viditelných scrollspy cílů současně může způsobit určité problémy.

Bod 1-1

Položka 1-2

Položka 2

Položka 3

Bod 3-1

Bod 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>

Seznam skupiny

Scrollspy také pracuje s .list-groups. Posouvejte oblast vedle skupiny seznamu a sledujte, jak se aktivní třída mění.

Položka 1 Položka 2 Položka 3 Položka 4

Položka 1

Položka 2

Položka 3

Položka 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>

Jednoduché kotvy

Scrollspy se neomezuje na komponenty navigace a skupiny seznamů, takže bude fungovat na všech <a>kotevních prvcích v aktuálním dokumentu. Posouvejte oblast a sledujte, jak se .activetřída mění.

Položka 1 Položka 2 Položka 3 Položka 4 Položka 5

Položka 1

Položka 2

Položka 3

Položka 4

Položka 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>

Neviditelné prvky

Cílové prvky, které nejsou viditelné, budou ignorovány a jejich odpovídající navigační položky nedostanou .activetřídu. Scrollspy instance inicializované v neviditelném obalu budou ignorovat všechny cílové prvky. Tuto metodu použijte refreshke kontrole pozorovatelných prvků, jakmile se obal stane viditelným.

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

Používání

Prostřednictvím datových atributů

Chcete-li do navigace v horní liště snadno přidat scrollspy chování, přidejte data-bs-spy="scroll"k prvku, který chcete špehovat (nejčastěji by to byl <body>). Potom přidejte data-bs-targetatribut s názvem idnebo třídou nadřazeného prvku libovolné .navkomponenty 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>

Prostřednictvím JavaScriptu

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

Možnosti

Protože volby lze předávat prostřednictvím datových atributů nebo JavaScriptu, můžete přidat název volby k data-bs-, jako v data-bs-animation="{value}". Při předávání možností prostřednictvím datových atributů se ujistěte, že jste změnili typ případu názvu možnosti z „ camelCase “ na „ kebab-case “. Použijte například data-bs-custom-class="beautifier"místo data-bs-customClass="beautifier".

Od Bootstrapu 5.2.0 všechny komponenty podporují experimentální atribut vyhrazených dat data-bs-config, který může obsahovat jednoduchou konfiguraci komponenty jako řetězec JSON. Když má prvek atributy data-bs-config='{"delay":0, "title":123}'a data-bs-title="456", konečná titlehodnota bude 456a samostatné datové atributy přepíší hodnoty uvedené na data-bs-config. Kromě toho mohou existující datové atributy obsahovat hodnoty JSON, jako je data-bs-delay='{"show":0,"hide":150}'.

název	Typ	Výchozí	Popis
`rootMargin`	tětiva	`0px 0px -25%`	Intersection Observer rootMargin platné jednotky při výpočtu pozice rolování.
`smoothScroll`	booleovský	`false`	Umožňuje plynulé posouvání, když uživatel klikne na odkaz, který odkazuje na pozorovatele ScrollSpy.
`target`	řetězec, prvek DOM	`null`	Určuje prvek, na který se má použít plugin Scrollspy.
`threshold`	pole	`[0.1, 0.5, 1]`	`IntersectionObserver` prahový platný vstup při výpočtu pozice rolování.

Zastaralé možnosti

Do verze 5.1.3 jsme používali možnosti offset& method, které jsou nyní zastaralé a nahrazeny rootMargin. Abychom zachovali zpětnou kompatibilitu, budeme pokračovat v analýze daného offsetdo rootMargin, ale tato funkce bude ve verzi 6 odstraněna .

Metody

Metoda	Popis
`dispose`	Zničí scrollspy prvku. (Odstraní uložená data v prvku DOM)
`getInstance`	Statická metoda pro získání instance scrollspy přidružené k prvku DOM.
`getOrCreateInstance`	Statická metoda k získání instance scrollspy přidružené k prvku DOM nebo k vytvoření nové v případě, že nebyla inicializována.
`refresh`	Při přidávání nebo odebírání prvků v DOM budete muset zavolat metodu refresh.

Zde je příklad použití metody aktualizace:

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

Události

událost	Popis
`activate.bs.scrollspy`	Tato událost se spustí na prvku scroll vždy, když bude scrollspy aktivována kotva.

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