Scrollspy

Actualitzeu automàticament la navegació Bootstrap o els components del grup de llista en funció de la posició de desplaçament per indicar quin enllaç està actiu actualment a la finestra gràfica.

En aquesta pàgina

Com funciona

Scrollspy alterna la .activeclasse als <a>elements d'àncora ( ) quan l'element amb el que idfa referència l'àncora hrefes desplaça a la vista. Scrollspy s'utilitza millor juntament amb un component de navegació Bootstrap o un grup de llista , però també funcionarà amb qualsevol element d'ancoratge de la pàgina actual. Així és com funciona.

Per començar, scrollspy requereix dues coses: una navegació, un grup de llista o un simple conjunt d'enllaços, a més d'un contenidor desplaçable. El contenidor desplaçable pot ser l' <body>element o un element personalitzat amb un conjunt heighti overflow-y: scroll.
Al contenidor desplaçable, afegiu data-bs-spy="scroll"i data-bs-target="#navId"on navIdés l'únic idde la navegació associada. Assegureu-vos d'incloure també un tabindex="0"per garantir l'accés al teclat.
A mesura que us desplaceu pel contenidor "espiat", .actives'afegeix una classe i s'elimina dels enllaços d'ancoratge dins de la navegació associada. Els enllaços han de tenir idobjectius resolubles, en cas contrari s'ignoren. Per exemple, un <a href="#home">home</a>ha de correspondre a alguna cosa semblant al DOM<div id="home"></div>
Els elements objectiu que no són visibles s'ignoraran. Vegeu la secció Elements no visibles a continuació.

Exemples

Desplaceu-vos per l'àrea de sota de la barra de navegació i observeu el canvi de classe activa. Obriu el menú desplegable i observeu que també es destaquen els elements desplegables.

Primer títol

Aquest és un contingut de marcador de posició per a la pàgina scrollspy. Tingueu en compte que a mesura que us desplaceu per la pàgina, es ressalta l'enllaç de navegació adequat. Es repeteix al llarg de l'exemple del component. Continuem afegint una còpia d'exemple més aquí per emfatitzar el desplaçament i el ressaltat.

Segon títol

Tercer títol

Quart títol

Cinquè títol

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

Navegació imbricada

Scrollspy també funciona amb .navs imbricats. Si un imbricat .navés .active, els seus pares també ho seran .active. Desplaceu-vos per l'àrea al costat de la barra de navegació i observeu el canvi de classe activa.

Element 1

Tingueu en compte que el connector de JavaScript intenta escollir l'element correcte entre tots els que poden ser visibles. Diversos objectius scrollspy visibles al mateix temps poden causar alguns problemes.

Tema 1-1

Tema 1-2

Tema 2

Tema 3

Tema 3-1

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

Grup de llista

Scrollspy també funciona amb .list-groups. Desplaceu-vos per l'àrea al costat del grup de llista i observeu el canvi de classe activa.

Element 1 Tema 2 Tema 3 Tema 4

Element 1

Tema 2

Tema 3

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

Ancores senzilles

Scrollspy no es limita als components de navegació i als grups de llista, de manera que funcionarà amb qualsevol <a>element d'ancoratge del document actual. Desplaceu-vos per l'àrea i observeu el .activecanvi de classe.

Element 1 Tema 2 Tema 3 Tema 4 Tema 5

Element 1

Tema 2

Tema 3

Tema 4

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

Elements no visibles

Els elements objectiu que no siguin visibles s'ignoraran i els elements de navegació corresponents no rebran cap .activeclasse. Les instàncies de Scrollspy inicialitzades en un embolcall no visible ignoraran tots els elements de destinació. Utilitzeu el refreshmètode per comprovar si hi ha elements observables un cop l'embolcall es faci visible.

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

Ús

Mitjançant atributs de dades

Per afegir fàcilment un comportament scrollspy a la vostra navegació de la barra superior, afegiu data-bs-spy="scroll"-lo a l'element que voleu espiar (normalment seria el <body>). A continuació, afegiu l' data-bs-targetatribut amb el nom o classe de l'element pare de qualsevol component idBootstrap ..nav

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

Mitjançant JavaScript

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

Opcions

Com que les opcions es poden passar mitjançant atributs de dades o JavaScript, podeu afegir un nom d'opció a data-bs-, com a data-bs-animation="{value}". Assegureu-vos de canviar el tipus de cas del nom de l'opció de " camelCase " a " kebab-case " quan passeu les opcions mitjançant atributs de dades. Per exemple, utilitzeu data-bs-custom-class="beautifier"en comptes de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, tots els components admeten un atribut de dades reservades experimentalsdata-bs-config que pot albergar una configuració senzilla de components com a cadena JSON. Quan un element té data-bs-config='{"delay":0, "title":123}'i data-bs-title="456"atributs, el titlevalor final serà 456i els atributs de dades independents substituiran els valors donats a data-bs-config. A més, els atributs de dades existents poden albergar valors JSON com data-bs-delay='{"show":0,"hide":150}'.

Nom	Tipus	Per defecte	Descripció
`rootMargin`	corda	`0px 0px -25%`	Intersection Observer rootMargin unitats vàlides, quan es calcula la posició de desplaçament.
`smoothScroll`	booleà	`false`	Permet un desplaçament suau quan un usuari fa clic en un enllaç que fa referència als observables de ScrollSpy.
`target`	cadena, element DOM	`null`	Especifica l'element per aplicar el connector Scrollspy.
`threshold`	matriu	`[0.1, 0.5, 1]`	`IntersectionObserver` entrada vàlida del llindar , quan es calcula la posició de desplaçament.

Opcions obsoletes

Fins a la v5.1.3 estàvem utilitzant opcions offset& method, que ara estan obsoletes i substituïdes per rootMargin. Per mantenir la compatibilitat enrere, continuarem analitzant un determinat offseta rootMargin, però aquesta característica s'eliminarà a la v6 .

Mètodes

Mètode	Descripció
`dispose`	Destrueix el scrollspy d'un element. (Elimina les dades emmagatzemades a l'element DOM)
`getInstance`	Mètode estàtic per obtenir la instància scrollspy associada a un element DOM.
`getOrCreateInstance`	Mètode estàtic per obtenir la instància scrollspy associada a un element DOM o per crear-ne un de nou en cas que no s'hagi inicialitzat.
`refresh`	Quan afegiu o suprimiu elements al DOM, haureu de cridar al mètode d'actualització.

Aquí teniu un exemple amb el mètode d'actualització:

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

Esdeveniments

Esdeveniment	Descripció
`activate.bs.scrollspy`	Aquest esdeveniment s'activa a l'element de desplaçament sempre que el scrollspy activa una àncora.

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

Scrollspy

Com funciona

Exemples

Barra de navegació

Primer títol

Segon títol

Tercer títol

Quart títol

Cinquè títol

Navegació imbricada

Element 1

Tema 1-1

Tema 1-2

Tema 2

Tema 3

Tema 3-1

Tema 3-2

Grup de llista

Element 1

Tema 2

Tema 3

Tema 4

Ancores senzilles

Element 1

Tema 2

Tema 3

Tema 4

Tema 5

Elements no visibles

Ús

Mitjançant atributs de dades

Mitjançant JavaScript

Opcions

Mètodes

Esdeveniments