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:
- 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 aquelaid
.
Quando implementado com sucesso, seu grupo de navegação ou lista será atualizado de acordo, movendo a .active
classe 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 height
conjunto 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 .nav
s aninhados. Se um aninhado .nav
for .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-group
s. 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-target
atributo com o ID ou classe do elemento pai de qualquer .nav
componente 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...
})