Espião de rolagem

Atualize automaticamente a navegação do Bootstrap ou os componentes do grupo de lista com base na posição de rolagem para indicar qual link está atualmente ativo na viewport.

Nesta página

Como funciona

Scrollspy tem alguns requisitos para funcionar corretamente:

Ele deve ser usado em um componente de navegação Bootstrap ou grupo de listas .
O Scrollspy requer position: relative;o elemento que você está espionando, geralmente o <body>.
Âncoras ( <a>) são obrigatórias e devem apontar para um elemento com aquela id.

Quando implementado com sucesso, seu grupo de navegação ou lista será atualizado de acordo, movendo a .activeclasse de um item para o próximo com base em seus destinos associados.

Contêineres roláveis e acesso por teclado

Se você estiver criando um contêiner rolável (diferente do <body>), certifique-se de ter um heightconjunto e overflow-y: scroll;aplicado a ele - junto com um tabindex="0"para garantir o acesso ao teclado.

Role a área abaixo da barra de navegação e observe a mudança de classe ativa. Os itens suspensos também serão destacados.

Primeiro título

Este é um conteúdo de espaço reservado para a página do scrollspy. Observe que, à medida que você rola a página, o link de navegação apropriado é realçado. É repetido em todo o exemplo do componente. Continuamos adicionando mais alguns exemplos de cópia aqui para enfatizar a rolagem e o realce.

Segundo título

Terceiro título

Quarto título

Quinto título

<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 com navegação aninhada

Scrollspy também funciona com .navs aninhados. Se um aninhado .navfor .active, seus pais também serão .active. Role a área ao lado da barra de navegação e observe a mudança de classe ativa.

Item 1

Item 1-1

Item 1-2

Item 2

Item 3

Item 3-1

Item 3-2

<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 com grupo de listas

Scrollspy também funciona com .list-groups. Role a área ao lado do grupo de lista e observe a mudança de classe ativa.

Item 1 Item 2 Item 3 Item 4

Item 1

Item 2

Item 3

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

Por atributos de dados

Para adicionar facilmente o comportamento do scrollspy à sua navegação na barra superior, adicione data-bs-spy="scroll"ao elemento que você deseja espionar (geralmente, isso seria o <body>). Em seguida, adicione o data-bs-targetatributo com o ID ou classe do elemento pai de qualquer .navcomponente do 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>

Por JavaScript

Depois position: relative;de adicionar seu CSS, chame o scrollspy via JavaScript:

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

Destinos de ID resolúvel obrigatórios

Os links da barra de navegação devem ter destinos de ID que podem ser resolvidos. Por exemplo, a <a href="#home">home</a>deve corresponder a algo no DOM como <div id="home"></div>.

Elementos de destino não visíveis ignorados

Os elementos de destino que não estiverem visíveis serão ignorados e seus itens de navegação correspondentes nunca serão destacados.

Métodos

atualizar

Ao usar o scrollspy em conjunto com a adição ou remoção de elementos do DOM, você precisará chamar o método de atualização da seguinte forma:

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

dispor

Destrói o scrollspy de um elemento. (Remove os dados armazenados no elemento DOM)

getInstance

Método estático que permite obter a instância scrollspy associada a um elemento DOM

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

getOrCreateInstance

Método estático que permite obter a instância scrollspy associada a um elemento DOM ou criar uma nova caso não tenha sido inicializada

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

Opções

As opções podem ser passadas por meio de atributos de dados ou JavaScript. Para atributos de dados, anexe o nome da opção a data-bs-, como em data-bs-offset="".

Nome	Modelo	Predefinição	Descrição
`offset`	número	`10`	Pixels para compensar a partir do topo ao calcular a posição de rolagem.
`method`	corda	`auto`	Localiza em qual seção o elemento espiado está. `auto`escolherá o melhor método para obter as coordenadas de rolagem. `offset`usará o `Element.getBoundingClientRect()`método para obter as coordenadas de rolagem. `position`usará as propriedades `HTMLElement.offsetTop`e `HTMLElement.offsetLeft`para obter as coordenadas de rolagem.
`target`	seqüência \| objeto jQuery \| Elemento DOM		Especifica o elemento para aplicar o plugin Scrollspy.

Eventos

Tipo de evento	Descrição
`activate.bs.scrollspy`	Este evento é acionado no elemento scroll sempre que um novo item é ativado pelo scrollspy.

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

Espião de rolagem

Como funciona

Contêineres roláveis ​​e acesso por teclado

Exemplo na barra de navegação

Primeiro título

Segundo título

Terceiro título

Quarto título

Quinto título

Exemplo com navegação aninhada

Item 1

Item 1-1

Item 1-2

Item 2

Item 3

Item 3-1

Item 3-2

Exemplo com grupo de listas

Item 1

Item 2

Item 3

Item 4

Uso

Por atributos de dados

Por JavaScript

Destinos de ID resolúvel obrigatórios

Elementos de destino não visíveis ignorados

Métodos

atualizar

dispor

getInstance

getOrCreateInstance

Opções

Eventos

Contêineres roláveis e acesso por teclado