Slaan oor na hoofinhoud Slaan oor na dokumentnavigasie
Check
in English

Scrollspy

Dateer Bootstrap-navigasie of lys groepkomponente outomaties op gebaseer op rolposisie om aan te dui watter skakel tans aktief is in die viewport.

Hoe dit werk

Scrollspy skakel die .activeklas op anker ( <a>) elemente wanneer die element met die idverwysing deur die anker s'n hrefin sig gerol word. Scrollspy word die beste gebruik in samewerking met 'n Bootstrap nav-komponent of lysgroep , maar dit sal ook met enige ankerelemente in die huidige bladsy werk. Hier is hoe dit werk.

  • Om te begin, benodig scrollspy twee dinge: 'n navigasie, lysgroep of 'n eenvoudige stel skakels, plus 'n blaaibare houer. Die blaaibare houer kan die <body>of 'n pasgemaakte element wees met 'n stel heighten overflow-y: scroll.

  • Op die blaaibare houer, voeg by data-bs-spy="scroll"en data-bs-target="#navId"waar navIdis die unieke idvan die gepaardgaande navigasie. Maak seker dat jy ook 'n insluit tabindex="0"om sleutelbordtoegang te verseker.

  • Soos jy die "gespioeneer" houer blaai, word 'n .activeklas bygevoeg en verwyder van ankerskakels binne die gepaardgaande navigasie. Skakels moet oplosbare idteikens hê, anders word hulle geïgnoreer. Byvoorbeeld, 'n <a href="#home">home</a>moet ooreenstem met iets in die DOM soos<div id="home"></div>

  • Teikenelemente wat nie sigbaar is nie, sal geïgnoreer word. Sien die Nie-sigbare elemente afdeling hieronder.

Voorbeelde

Blaai deur die area onder die navigasiebalk en kyk hoe die aktiewe klas verander. Maak die aftreklys oop en kyk hoe die aftrekitems ook uitgelig word.

Eerste opskrif

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Tweede opskrif

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Derde opskrif

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Vierde opskrif

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Vyfde opskrif

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

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

Geneste nav

Scrollspy werk ook met geneste .navs. As 'n geneste .navis .active, sal sy ouers ook wees .active. Blaai deur die area langs die navigasiebalk en kyk hoe die aktiewe klas verander.

Item 1

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Hou in gedagte dat die JavaScript-inprop probeer om die regte element te kies uit alles wat sigbaar mag wees. Verskeie sigbare scrollspy-teikens op dieselfde tyd kan sekere probleme veroorsaak.

Item 1-1

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Hou in gedagte dat die JavaScript-inprop probeer om die regte element te kies uit alles wat sigbaar mag wees. Verskeie sigbare scrollspy-teikens op dieselfde tyd kan sekere probleme veroorsaak.

Item 1-2

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Hou in gedagte dat die JavaScript-inprop probeer om die regte element te kies uit alles wat sigbaar mag wees. Verskeie sigbare scrollspy-teikens op dieselfde tyd kan sekere probleme veroorsaak.

Item 2

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Hou in gedagte dat die JavaScript-inprop probeer om die regte element te kies uit alles wat sigbaar mag wees. Verskeie sigbare scrollspy-teikens op dieselfde tyd kan sekere probleme veroorsaak.

Item 3

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Hou in gedagte dat die JavaScript-inprop probeer om die regte element te kies uit alles wat sigbaar mag wees. Verskeie sigbare scrollspy-teikens op dieselfde tyd kan sekere probleme veroorsaak.

Item 3-1

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Hou in gedagte dat die JavaScript-inprop probeer om die regte element te kies uit alles wat sigbaar mag wees. Verskeie sigbare scrollspy-teikens op dieselfde tyd kan sekere probleme veroorsaak.

Item 3-2

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Hou in gedagte dat die JavaScript-inprop probeer om die regte element te kies uit alles wat sigbaar mag wees. Verskeie sigbare scrollspy-teikens op dieselfde tyd kan sekere probleme veroorsaak.

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

Lys groep

Scrollspy werk ook met .list-groups. Blaai deur die area langs die lysgroep en kyk hoe die aktiewe klas verander.

Item 1

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Item 2

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Item 3

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Item 4

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

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

Eenvoudige ankers

Scrollspy is nie beperk tot nav-komponente en lysgroepe nie, so dit sal op enige <a>ankerelemente in die huidige dokument werk. Blaai deur die area en kyk hoe die .activeklas verander.

Item 1

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Item 2

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Item 3

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Item 4

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

Item 5

Dit is 'n paar plekhouer-inhoud vir die scrollspy-bladsy. Let daarop dat die toepaslike navigasieskakel uitgelig word terwyl jy op die bladsy blaai. Dit word deur die komponentvoorbeeld herhaal. Ons hou aan om nog 'n voorbeeldkopie hier by te voeg om die blaai en uitlig te beklemtoon.

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

Nie-sigbare elemente

Teikenelemente wat nie sigbaar is nie, sal geïgnoreer word en hul ooreenstemmende navigasie-items sal nie 'n .activeklas ontvang nie. Scrollspy-gevalle wat in 'n nie-sigbare omhulsel geïnisialiseer is, sal alle teikenelemente ignoreer. Gebruik die refreshmetode om te kyk vir waarneembare elemente sodra die omhulsel sigbaar word.

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

Gebruik

Via data-eienskappe

Om maklik scrollspy-gedrag by jou bobalknavigasie te voeg, voeg data-bs-spy="scroll"by die element waarop jy wil spioeneer (meestal sal dit die <body>). Voeg dan die data-bs-targetkenmerk by met die idof klasnaam van die ouerelement van enige Bootstrap- .navkomponent.

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

Via JavaScript

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

Opsies

Aangesien opsies deur data-kenmerke of JavaScript deurgegee kan word, kan jy 'n opsienaam byvoeg data-bs-, soos in data-bs-animation="{value}". Maak seker dat jy die kastipe van die opsienaam verander van " camelCase " na " kebab-case " wanneer die opsies deur data-kenmerke deurgegee word. Gebruik byvoorbeeld in data-bs-custom-class="beautifier"plaas van data-bs-customClass="beautifier".

Vanaf Bootstrap 5.2.0 ondersteun alle komponente 'n eksperimentele gereserveerde data-kenmerk data-bs-configwat eenvoudige komponentkonfigurasie as 'n JSON-string kan huisves. Wanneer 'n element data-bs-config='{"delay":0, "title":123}'en data-bs-title="456"kenmerke het, sal die finale titlewaarde wees 456en die afsonderlike data-kenmerke sal waardes wat op gegee word, ignoreer data-bs-config. Daarbenewens kan bestaande data-kenmerke JSON-waardes soos data-bs-delay='{"show":0,"hide":150}'.

Naam Tik Verstek Beskrywing
rootMargin string 0px 0px -25% Interseksie Observer rootMargin geldige eenhede, wanneer die rolposisie bereken word.
smoothScroll boolean false Maak gladde blaai moontlik wanneer 'n gebruiker op 'n skakel klik wat na ScrollSpy waarneembares verwys.
target string, DOM-element null Spesifiseer element om Scrollspy-inprop toe te pas.
threshold skikking [0.1, 0.5, 1] IntersectionObserver drempel geldige invoer, wanneer die rolposisie bereken word.

Verouderde opsies

Tot v5.1.3 het ons offset& methodopsies gebruik, wat nou afgekeur is en vervang word deur rootMargin. Om terugwaartse versoenbaarheid te behou, sal ons voortgaan om 'n gegewe offsetna te ontleed rootMargin, maar hierdie kenmerk sal in v6 verwyder word .

Metodes

Metode Beskrywing
dispose Vernietig 'n element se scrollspy. (Verwyder gestoorde data op die DOM-element)
getInstance Statiese metode om die scrollspy-instansie te kry wat met 'n DOM-element geassosieer word.
getOrCreateInstance Statiese metode om die scrollspy-instansie te kry wat met 'n DOM-element geassosieer word, of om 'n nuwe een te skep ingeval dit nie geïnisialiseer is nie.
refresh Wanneer jy elemente in die DOM byvoeg of verwyder, moet jy die herlaaimetode aanroep.

Hier is 'n voorbeeld wat die herlaaimetode gebruik:

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

Gebeurtenisse

Gebeurtenis Beskrywing
activate.bs.scrollspy Hierdie gebeurtenis brand op die rolelement wanneer 'n anker deur die rolspioen geaktiveer word.
const firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', () => {
  // do something...
})