Scrollspy

Automaticky aktualizujte navigáciu Bootstrap alebo zoznam komponentov skupiny na základe pozície posúvania, aby ste označili, ktoré prepojenie je momentálne aktívne vo výreze.

Na tejto stránke

Ako to funguje

Scrollspy prepína .activetriedu na <a>prvkoch kotvy ( ), keď sa prvok, na idktorý odkazuje kotva, hrefposunie do zobrazenia. Scrollspy sa najlepšie používa v spojení s komponentom Bootstrap nav alebo skupinou zoznamu , ale bude fungovať aj s akýmikoľvek prvkami kotvy na aktuálnej stránke. Tu je návod, ako to funguje.

Na začiatok vyžaduje scrollspy dve veci: navigáciu, skupinu zoznamov alebo jednoduchú sadu odkazov a rolovateľný kontajner. Posúvateľný kontajner môže byť <body>alebo vlastný prvok so sadou heighta overflow-y: scroll.
Na posúvateľnom kontajneri pridajte data-bs-spy="scroll"a data-bs-target="#navId"kde navIdje jedinečná idpriradená navigácia. Nezabudnite uviesť aj symbol, tabindex="0"ktorý zabezpečí prístup ku klávesnici.
Pri posúvaní „špionážneho“ kontajnera sa .activetrieda pridáva a odstraňuje z kotviacich odkazov v rámci súvisiacej navigácie. Odkazy musia mať rozlíšiteľné idciele, inak sú ignorované. Napríklad, <a href="#home">home</a>musí zodpovedať niečomu v DOM, ako je<div id="home"></div>
Cieľové prvky, ktoré nie sú viditeľné, budú ignorované. Pozrite si časť Neviditeľné prvky nižšie.

Príklady

Prejdite oblasťou pod navigačnou lištou a sledujte, ako sa aktívna trieda mení. Otvorte rozbaľovaciu ponuku a sledujte, ako sú zvýraznené aj položky rozbaľovacej ponuky.

Prvý nadpis

Toto je nejaký zástupný obsah pre stránku scrollspy. Upozorňujeme, že pri posúvaní stránky nadol sa zvýrazní príslušný navigačný odkaz. Opakuje sa v celom príklade komponentu. Stále pridávame niekoľko ďalších vzorových kópií, aby sme zdôraznili posúvanie a zvýrazňovanie.

Druhý nadpis

Tretí nadpis

Štvrtý nadpis

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

Vnorená navig

Scrollspy funguje aj s vnorenými .navs. .navAk je vnorený .active, jeho rodičia budú tiež .active. Prejdite oblasťou vedľa navigačného panela a sledujte, ako sa aktívna trieda mení.

Položka 1

Majte na pamäti, že doplnok JavaScript sa snaží vybrať správny prvok spomedzi všetkých, ktoré môžu byť viditeľné. Viacero viditeľných scrollspy cieľov súčasne môže spôsobiť určité problémy.

Položka 1-1

Položka 1-2

Položka 2

Bod 3

Položka 3-1

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

Zoznam skupiny

Scrollspy funguje aj so .list-groups. Prejdite oblasťou vedľa skupiny zoznamov a sledujte, ako sa aktívna trieda mení.

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

Položka 1

Položka 2

Bod 3

Bod 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 sa neobmedzuje len na komponenty navigácie a skupiny zoznamov, takže bude fungovať na akýchkoľvek <a>kotviacich prvkoch v aktuálnom dokumente. Posúvajte oblasť a sledujte, ako sa .activetrieda mení.

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

Položka 1

Položka 2

Bod 3

Bod 4

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

Neviditeľné prvky

Cieľové prvky, ktoré nie sú viditeľné, budú ignorované a ich zodpovedajúce navigačné položky nedostanú .activetriedu. Scrollspy inštancie inicializované v neviditeľnom obale budú ignorovať všetky cieľové prvky. Túto metódu použite refreshna kontrolu pozorovateľných prvkov, keď sa obal stane viditeľný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žitie

Cez dátové atribúty

Ak chcete jednoducho pridať rolovacie správanie do navigácie v hornej lište, pridajte data-bs-spy="scroll"prvok, ktorý chcete špehovať (najčastejšie to bude <body>). Potom pridajte data-bs-targetatribút s idnázvom triedy alebo rodičovského prvku ľubovoľného .navkomponentu 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>

Cez JavaScript

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

možnosti

Keďže možnosti možno odovzdať prostredníctvom atribútov údajov alebo jazyka JavaScript, môžete pridať názov možnosti k data-bs-, ako v data-bs-animation="{value}". Pri odovzdávaní možností cez atribúty údajov nezabudnite zmeniť typ prípadu názvu možnosti z „ camelCase “ na „ kebab-case “. Napríklad použite data-bs-custom-class="beautifier"namiesto data-bs-customClass="beautifier".

Od Bootstrapu 5.2.0 všetky komponenty podporujú experimentálny atribút rezervovaných údajov data-bs-config, ktorý môže obsahovať jednoduchú konfiguráciu komponentu ako reťazec JSON. Ak má prvok atribúty data-bs-config='{"delay":0, "title":123}'a data-bs-title="456", konečná titlehodnota bude 456a samostatné atribúty údajov prepíšu hodnoty uvedené na data-bs-config. Existujúce dátové atribúty môžu navyše obsahovať hodnoty JSON ako data-bs-delay='{"show":0,"hide":150}'.

názov	Typ	Predvolené	Popis
`rootMargin`	reťazec	`0px 0px -25%`	Intersection Observer rootMargin platné jednotky pri výpočte pozície rolovania.
`smoothScroll`	boolovská hodnota	`false`	Umožňuje plynulé posúvanie, keď používateľ klikne na odkaz, ktorý odkazuje na pozorovateľné položky ScrollSpy.
`target`	reťazec, prvok DOM	`null`	Určuje prvok, na ktorý sa má použiť doplnok Scrollspy.
`threshold`	pole	`[0.1, 0.5, 1]`	`IntersectionObserver` prahový platný vstup pri výpočte polohy rolovania.

Možnosti s ukončenou podporou

Až do verzie 5.1.3 sme používali možnosti offset& method, ktoré sú teraz zastarané a nahradené rootMargin. Aby sme zachovali spätnú kompatibilitu, budeme pokračovať v analýze daného offsetdo rootMargin, ale táto funkcia bude vo verzii 6 odstránená .

Metódy

Metóda	Popis
`dispose`	Zničí scrollspy prvku. (Odstráni uložené údaje v prvku DOM)
`getInstance`	Statická metóda na získanie inštancie scrollspy priradenej k prvku DOM.
`getOrCreateInstance`	Statická metóda na priradenie scrollspy inštancie k prvku DOM alebo na vytvorenie novej v prípade, že nebola inicializovaná.
`refresh`	Pri pridávaní alebo odstraňovaní prvkov v DOM budete musieť zavolať metódu obnovenia.

Tu je príklad použitia metódy obnovenia:

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

Diania

Udalosť	Popis
`activate.bs.scrollspy`	Táto udalosť sa spustí na rolovacom prvku vždy, keď scrollspy aktivuje kotvu.

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