Spia pergamena

Aggiorna automaticamente la navigazione Bootstrap o elenca i componenti del gruppo in base alla posizione di scorrimento per indicare quale collegamento è attualmente attivo nella finestra.

Su questa pagina

Come funziona

Scrollspy attiva o disattiva la .activeclasse sugli <a>elementi anchor ( ) quando l'elemento a cui idfa riferimento l'ancora hrefviene visualizzato. Scrollspy è meglio utilizzato in combinazione con un componente di navigazione Bootstrap o un gruppo di elenchi , ma funzionerà anche con qualsiasi elemento di ancoraggio nella pagina corrente. Ecco come funziona.

Per iniziare, scrollspy richiede due cose: una navigazione, un gruppo di elenchi o un semplice insieme di collegamenti, oltre a un contenitore scorrevole. Il contenitore scorrevole può essere <body>o un elemento personalizzato con un set heighte overflow-y: scroll.
Sul contenitore scorrevole, aggiungi data-bs-spy="scroll"e data-bs-target="#navId"dove navIdè l'univoca iddella navigazione associata. Assicurati di includere anche un tabindex="0"per garantire l'accesso alla tastiera.
Mentre scorri il contenitore "spiato", una .activeclasse viene aggiunta e rimossa dai link di ancoraggio all'interno della navigazione associata. I link devono avere idobiettivi risolvibili, altrimenti vengono ignorati. Ad esempio, un <a href="#home">home</a>must corrisponde a qualcosa nel DOM come<div id="home"></div>
Gli elementi di destinazione che non sono visibili verranno ignorati. Vedere la sezione Elementi non visibili di seguito.

Esempi

Scorri l'area sotto la barra di navigazione e osserva il cambio di classe attivo. Apri il menu a discesa e osserva anche gli elementi a discesa evidenziati.

Prima intestazione

Questo è un contenuto segnaposto per la pagina scrollspy. Tieni presente che mentre scorri la pagina verso il basso, viene evidenziato il collegamento di navigazione appropriato. Viene ripetuto in tutto l'esempio del componente. Continuiamo ad aggiungere un altro esempio di copia qui per enfatizzare lo scorrimento e l'evidenziazione.

Secondo titolo

Terzo titolo

Quarto titolo

Quinto titolo

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

nav nidificato

Scrollspy funziona anche con nidificati .navs. Se un nidificato .navlo è .active, lo saranno anche i suoi genitori .active. Scorri l'area accanto alla barra di navigazione e osserva il cambio di classe attivo.

Articolo 1

Tieni presente che il plug-in JavaScript cerca di selezionare l'elemento giusto tra tutto ciò che potrebbe essere visibile. Più bersagli scrollspy visibili contemporaneamente possono causare alcuni problemi.

Voce 1-1

Voce 1-2

Articolo 2

Voce 3

Articolo 3-1

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

Gruppo elenco

Scrollspy funziona anche con .list-groups. Scorri l'area accanto al gruppo dell'elenco e osserva il cambio di classe attiva.

Articolo 1 Articolo 2 Voce 3 Articolo 4

Articolo 1

Articolo 2

Voce 3

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

Ancoraggi semplici

Scrollspy non è limitato ai componenti di navigazione e ai gruppi di elenchi, quindi funzionerà su qualsiasi <a>elemento di ancoraggio nel documento corrente. Scorri l'area e guarda il .activecambio di classe.

Articolo 1 Articolo 2 Voce 3 Articolo 4 Voce 5

Articolo 1

Articolo 2

Voce 3

Articolo 4

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

Elementi non visibili

Gli elementi di destinazione che non sono visibili verranno ignorati e gli elementi di navigazione corrispondenti non riceveranno una .activeclasse. Le istanze di Scrollspy inizializzate in un wrapper non visibile ignoreranno tutti gli elementi di destinazione. Utilizzare il refreshmetodo per verificare la presenza di elementi osservabili una volta che il wrapper diventa visibile.

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

Utilizzo

Tramite attributi di dati

Per aggiungere facilmente il comportamento scrollspy alla tua navigazione nella barra in alto, aggiungi data-bs-spy="scroll"l'elemento che vuoi spiare (di solito questo sarebbe il <body>). Quindi aggiungi l' data-bs-targetattributo con il idnome della classe o dell'elemento padre di qualsiasi .navcomponente 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>

Tramite JavaScript

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

Opzioni

Poiché le opzioni possono essere passate tramite attributi di dati o JavaScript, puoi aggiungere un nome di opzione a data-bs-, come in data-bs-animation="{value}". Assicurati di cambiare il tipo di caso del nome dell'opzione da " camelCase " a " kebab-case " quando passi le opzioni tramite attributi di dati. Ad esempio, utilizzare data-bs-custom-class="beautifier"invece di data-bs-customClass="beautifier".

A partire da Bootstrap 5.2.0, tutti i componenti supportano un attributo di dati riservato sperimentaledata-bs-config che può ospitare una semplice configurazione del componente come una stringa JSON. Quando un elemento ha data-bs-config='{"delay":0, "title":123}'e data-bs-title="456"attributi, il titlevalore finale sarà 456e gli attributi di dati separati sovrascriveranno i valori forniti su data-bs-config. Inoltre, gli attributi di dati esistenti sono in grado di ospitare valori JSON come data-bs-delay='{"show":0,"hide":150}'.

Nome	Tipo	Predefinito	Descrizione
`rootMargin`	corda	`0px 0px -25%`	Intersection Observer rootMargin unità valide, quando si calcola la posizione di scorrimento.
`smoothScroll`	booleano	`false`	Consente lo scorrimento fluido quando un utente fa clic su un collegamento che fa riferimento agli osservabili ScrollSpy.
`target`	stringa, elemento DOM	`null`	Specifica l'elemento per applicare il plug-in Scrollspy.
`threshold`	Vettore	`[0.1, 0.5, 1]`	`IntersectionObserver` ingresso valido di soglia , durante il calcolo della posizione di scorrimento.

Opzioni deprecate

Fino alla v5.1.3 utilizzavamo le opzioni offset& method, che ora sono deprecate e sostituite da rootMargin. Per mantenere la compatibilità con le versioni precedenti, continueremo ad analizzare un dato offseta rootMargin, ma questa funzionalità verrà rimossa nella v6 .

Metodi

Metodo	Descrizione
`dispose`	Distrugge lo scrollspy di un elemento. (Rimuove i dati memorizzati sull'elemento DOM)
`getInstance`	Metodo statico per ottenere l'istanza scrollspy associata a un elemento DOM.
`getOrCreateInstance`	Metodo statico per ottenere l'istanza scrollspy associata a un elemento DOM o per crearne uno nuovo nel caso non sia stato inizializzato.
`refresh`	Quando aggiungi o rimuovi elementi nel DOM, dovrai chiamare il metodo refresh.

Ecco un esempio utilizzando il metodo di aggiornamento:

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

Eventi

Evento	Descrizione
`activate.bs.scrollspy`	Questo evento si attiva sull'elemento scroll ogni volta che un'ancora viene attivata da scrollspy.

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