in English

Scrollspy

Actualiza automaticamente a navegación de Bootstrap ou os compoñentes do grupo de listas en función da posición de desprazamento para indicar que ligazón está activa actualmente na ventana gráfica.

Nesta páxina

Cómo funciona

Scrollspy alterna a .activeclase nos elementos de áncora ( <a>) cando o elemento ao que idfai referencia a áncora hrefse despraza á vista. Scrollspy úsase mellor xunto cun compoñente de navegación Bootstrap ou un grupo de listas , pero tamén funcionará con calquera elemento de ancoraxe da páxina actual. Aquí tes como funciona.

Para comezar, scrollspy require dúas cousas: unha navegación, un grupo de listas ou un simple conxunto de ligazóns, ademais dun contedor desprazable. O contedor que se pode desprazar pode ser o <body>ou un elemento personalizado cun conxunto heighte overflow-y: scroll.
No contedor desprazable, engade data-bs-spy="scroll"e data-bs-target="#navId"onde navIdestá o único idda navegación asociada. Asegúrate de incluír tamén un tabindex="0"para garantir o acceso ao teclado.
A medida que te desprazas polo contedor "espiado", .activeengádese e elimínase unha clase das ligazóns de ancoraxe dentro da navegación asociada. As ligazóns deben ter idobxectivos resolubles, se non, ignoraranse. Por exemplo, un <a href="#home">home</a>debe corresponder a algo no DOM como<div id="home"></div>
Ignoraranse os elementos obxectivo que non sexan visibles. Consulte a sección Elementos non visibles a continuación.

Exemplos

Desprázate pola área debaixo da barra de navegación e observa o cambio de clase activa. Abre o menú despregable e observa que tamén se destacan os elementos do menú despregable.

Primeiro título

Este é un contido de marcador de posición para a páxina scrollspy. Teña en conta que a medida que se despraza pola páxina, a ligazón de navegación adecuada aparece resaltada. Repítese ao longo do exemplo do compoñente. Seguimos engadindo algunha copia máis de exemplo aquí para enfatizar o desprazamento e o resaltado.

Segundo título

Terceiro epígrafe

Cuarto epígrafe

Quinto epígrafe

<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ón anidada

Scrollspy tamén funciona con .navs anidados. Se un aniñado .navé .active, os seus pais tamén o serán .active. Desprázate pola área situada ao carón da barra de navegación e observa o cambio de clase activa.

Elemento 1

Teña en conta que o complemento de JavaScript tenta escoller o elemento correcto entre todos os que poden ser visibles. Varios obxectivos scrollspy visibles ao mesmo tempo poden causar algúns problemas.

Elemento 1-1

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

Grupo de listas

Scrollspy tamén funciona con .list-groups. Desprácese pola área xunto ao grupo da lista e observa o cambio de clase activa.

Elemento 1 Tema 2 Tema 3 Tema 4

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

áncoras sinxelas

Scrollspy non se limita aos compoñentes de navegación e aos grupos de listas, polo que funcionará en calquera <a>elemento de ancoraxe do documento actual. Desprázate pola zona e observa o .activecambio de clase.

Elemento 1 Tema 2 Tema 3 Tema 4 Tema 5

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

Elementos non visibles

Os elementos de destino que non sexan visibles ignoraranse e os elementos de navegación correspondentes non recibirán unha .activeclase. As instancias de Scrollspy inicializadas nun envoltorio non visible ignorarán todos os elementos de destino. Use o refreshmétodo para comprobar se hai elementos observables unha vez que o envoltorio se faga 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()
  })
})

Uso

A través de atributos de datos

Para engadir facilmente o comportamento scrollspy á túa navegación da barra superior, engádese data-bs-spy="scroll"ao elemento que queres espiar (normalmente este sería o <body>). A continuación, engade o data-bs-targetatributo co idnome ou clase do elemento pai de calquera .navcompoñente 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>

Vía JavaScript

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

Opcións

Como as opcións se poden pasar a través de atributos de datos ou JavaScript, pode engadir un nome de opción a data-bs-, como en data-bs-animation="{value}". Asegúrate de cambiar o tipo de maiúsculas e minúsculas do nome da opción de " camelCase " a " kebab-case " ao pasar as opcións a través dos atributos de datos. Por exemplo, use data-bs-custom-class="beautifier"no canto de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos os compoñentes admiten un atributo de datos reservados experimentaisdata-bs-config que pode albergar unha configuración sinxela de compoñentes como cadea JSON. Cando un elemento ten data-bs-config='{"delay":0, "title":123}'e data-bs-title="456"atributos, o titlevalor final será 456e os atributos de datos separados anularán os valores indicados en data-bs-config. Ademais, os atributos de datos existentes poden albergar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

Nome	Tipo	Por defecto	Descrición
`rootMargin`	corda	`0px 0px -25%`	Intersection Observer rootMargin unidades válidas, ao calcular a posición de desprazamento.
`smoothScroll`	booleano	`false`	Permite o desprazamento suave cando un usuario fai clic nunha ligazón que fai referencia aos observables de ScrollSpy.
`target`	cadea, elemento DOM	`null`	Especifica o elemento para aplicar o complemento Scrollspy.
`threshold`	matriz	`[0.1, 0.5, 1]`	`IntersectionObserver` entrada válida de limiar , ao calcular a posición de desprazamento.

Opcións obsoletas

Ata a versión 5.1.3 usabamos offset& methodopcións, que agora están obsoletas e substituídas por rootMargin. Para manter a compatibilidade con versións anteriores, seguiremos analizando un determinado offseta rootMargin, pero esta función eliminarase na versión 6 .

Métodos

Método	Descrición
`dispose`	Destrúe o scrollspy dun elemento. (Elimina os datos almacenados no elemento DOM)
`getInstance`	Método estático para obter a instancia scrollspy asociada a un elemento DOM.
`getOrCreateInstance`	Método estático para obter a instancia scrollspy asociada a un elemento DOM ou para crear un novo no caso de que non se inicializou.
`refresh`	Ao engadir ou eliminar elementos no DOM, terás que chamar ao método de actualización.

Aquí tes un exemplo usando o método de actualización:

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

Eventos

Evento	Descrición
`activate.bs.scrollspy`	Este evento desenvólvese no elemento scroll sempre que o scrollspy activa unha áncora.

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

Scrollspy

Cómo funciona

Exemplos

Barra de navegación

Primeiro título

Segundo título

Terceiro epígrafe

Cuarto epígrafe

Quinto epígrafe

Navegación anidada

Elemento 1

Elemento 1-1

Elemento 1-2

Tema 2

Tema 3

Tema 3-1

Tema 3-2

Grupo de listas

Elemento 1

Tema 2

Tema 3

Tema 4

áncoras sinxelas

Elemento 1

Tema 2

Tema 3

Tema 4

Tema 5

Elementos non visibles

Uso

A través de atributos de datos

Vía JavaScript

Opcións

Métodos

Eventos