Ir para o conteúdo principal Pular para a navegação de documentos
in English

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.

Como funciona

Scrollspy tem alguns requisitos para funcionar corretamente:

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.

Exemplo na barra de navegação

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

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.

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

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

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

<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

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.

Item 1-1

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.

Item 1-2

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.

Item 2

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.

Item 3

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.

Item 3-1

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.

Item 3-2

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.

<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

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.

Item 2

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.

Item 3

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.

Item 4

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.

<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á. autoescolherá o melhor método para obter as coordenadas de rolagem. offsetusará o Element.getBoundingClientRect()método para obter as coordenadas de rolagem. positionusará as propriedades HTMLElement.offsetTope HTMLElement.offsetLeftpara 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...
})