Ir ao contido principal Ir á navegación de documentos
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 ten algúns requisitos para funcionar correctamente:

  • Debe usarse nun compoñente de navegación de Bootstrap ou nun grupo de listas .
  • Scrollspy require position: relative;o elemento que estás espiando, normalmente o <body>.
  • As áncoras ( <a>) son necesarias e deben apuntar a un elemento con iso id.

Cando se implemente correctamente, o teu grupo de navegación ou lista actualizarase en consecuencia, movendo a .activeclase dun elemento a outro en función dos seus obxectivos asociados.

Contenedores desprazables e acceso ao teclado

Se estás a crear un contedor que se pode desprazar (que non sexa <body>), asegúrate de ter un heightconxunto e overflow-y: scroll;aplicalo xunto a un tabindex="0"para garantir o acceso ao teclado.

Exemplo na barra de navegación

Desprázate pola área debaixo da barra de navegación e observa o cambio de clase activa. Tamén se destacarán 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

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.

Terceiro epígrafe

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.

Cuarto epígrafe

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.

Quinto epígrafe

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.

<nav id="navbar-example2" class="navbar navbar-light bg-light px-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-offset="0" class="scrollspy-example" 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>

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

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.

Elemento 1-1

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.

Elemento 1-2

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.

Tema 2

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.

Tema 3

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.

Tema 3-1

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.

Tema 3-2

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.

<nav id="navbar-example3" class="navbar navbar-light bg-light flex-column align-items-stretch p-3">
  <a class="navbar-brand" href="#">Navbar</a>
  <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 data-bs-spy="scroll" data-bs-target="#navbar-example3" data-bs-offset="0" tabindex="0">
  <h4 id="item-1">Item 1</h4>
  <p>...</p>
  <h5 id="item-1-1">Item 1-1</h5>
  <p>...</p>
  <h5 id="item-1-2">Item 1-2</h5>
  <p>...</p>
  <h4 id="item-2">Item 2</h4>
  <p>...</p>
  <h4 id="item-3">Item 3</h4>
  <p>...</p>
  <h5 id="item-3-1">Item 3-1</h5>
  <p>...</p>
  <h5 id="item-3-2">Item 3-2</h5>
  <p>...</p>
</div>

Exemplo con lista-grupo

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

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.

Tema 2

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.

Tema 3

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.

Tema 4

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.

<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 data-bs-spy="scroll" data-bs-target="#list-example" data-bs-offset="0" 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>

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 ID ou clase do elemento pai de calquera .navcompoñente Bootstrap.

body {
  position: relative;
}

<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

Despois de engadir position: relative;o teu CSS, chama ao scrollspy mediante JavaScript:

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

Requírense obxectivos de identificación resolubles

As ligazóns da barra de navegación deben ter obxectivos de identificación resolubles. Por exemplo, un <a href="#home">home</a>debe corresponder a algo no DOM como <div id="home"></div>.

Ignoráronse os elementos de destino non visibles

Os elementos de destino que non sexan visibles ignoraranse e os seus correspondentes elementos de navegación nunca se resaltarán.

Métodos

refrescar

Ao usar scrollspy xunto coa engade ou eliminación de elementos do DOM, terás que chamar ao método de actualización deste xeito:

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

dispor

Destrúe o scrollspy dun elemento. (Elimina os datos almacenados no elemento DOM)

getInstance

Método estático que che permite obter a instancia scrollspy asociada a un elemento DOM

var scrollSpyContentEl = document.getElementById('content')
var scrollSpy = bootstrap.ScrollSpy.getInstance(scrollSpyContentEl) // Returns a Bootstrap scrollspy instance

getOrCreateInstance

Método estático que che permite obter a instancia scrollspy asociada a un elemento DOM ou crear un novo no caso de que non se inicializou

var scrollSpyContentEl = document.getElementById('content')
var scrollSpy = bootstrap.ScrollSpy.getOrCreateInstance(scrollSpyContentEl) // Returns a Bootstrap scrollspy instance

Opcións

As opcións pódense pasar a través de atributos de datos ou JavaScript. Para os atributos de datos, engada o nome da opción a data-bs-, como en data-bs-offset="".

Nome Tipo Por defecto Descrición
offset número 10 Píxeles para compensar desde arriba ao calcular a posición do desprazamento.
method corda auto Busca en que sección se atopa o elemento espiado. autoElixirá o mellor método para obter as coordenadas de desprazamento. offsetusará o Element.getBoundingClientRect()método para obter as coordenadas de desprazamento. positionusará as propiedades HTMLElement.offsetTope HTMLElement.offsetLeftpara obter as coordenadas de desprazamento.
target cadea | obxecto jQuery | Elemento DOM Especifica o elemento para aplicar o complemento Scrollspy.

Eventos

Tipo de evento Descrición
activate.bs.scrollspy Este evento desenvólvese no elemento scroll sempre que o scrollspy activa un novo elemento. 
var firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', function () {
  // do something...
})