Scrollspy
Uppdatera automatiskt Bootstrap-navigering eller listgruppskomponenter baserat på rullningsposition för att indikera vilken länk som för närvarande är aktiv i visningsporten.
Hur det fungerar
Scrollspy växlar .activeklassen på ankarelement ( <a>) när elementet med det som idrefereras av ankaret hrefrullas fram. Scrollspy används bäst i kombination med en Bootstrap nav-komponent eller listgrupp , men det fungerar också med alla ankarelement på den aktuella sidan. Så här fungerar det.
-
För att börja, kräver scrollspy två saker: en navigering, listgrupp eller en enkel uppsättning länkar, plus en rullningsbar behållare. Den rullningsbara behållaren kan vara
<body>eller ett anpassat element med en uppsättningheightochoverflow-y: scroll. -
På den rullningsbara behållaren, lägg till
data-bs-spy="scroll"ochdata-bs-target="#navId"varnavIdär det unikaidför den associerade navigeringen. Se till att även inkludera etttabindex="0"för att säkerställa tangentbordsåtkomst. -
När du rullar den "spionerade" behållaren läggs en
.activeklass till och tas bort från ankarlänkar i den associerade navigeringen. Länkar måste ha lösbaraidmål, annars ignoreras de. Till exempel måste ett<a href="#home">home</a>måste motsvara något i DOM som<div id="home"></div> -
Målelement som inte är synliga kommer att ignoreras. Se avsnittet Icke-synliga element nedan.
Exempel
Navbar
Bläddra i området under navigeringsfältet och se hur den aktiva klassen ändras. Öppna rullgardinsmenyn och se hur rullgardinsmenyn också markeras.
Första rubriken
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Andra rubriken
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Tredje rubriken
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Fjärde rubriken
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Femte rubriken
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
<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>
Kapslad nav
Scrollspy fungerar också med kapslade .navs. Om en kapslad .navär .activekommer dess föräldrar också att vara .active. Bläddra i området bredvid navigeringsfältet och se hur den aktiva klassen ändras.
Punkt 1
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Tänk på att JavaScript-pluginen försöker välja rätt element bland allt som kan vara synligt. Flera synliga scrollspy-mål samtidigt kan orsaka vissa problem.
Punkt 1-1
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Tänk på att JavaScript-pluginen försöker välja rätt element bland allt som kan vara synligt. Flera synliga scrollspy-mål samtidigt kan orsaka vissa problem.
Punkt 1-2
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Tänk på att JavaScript-pluginen försöker välja rätt element bland allt som kan vara synligt. Flera synliga scrollspy-mål samtidigt kan orsaka vissa problem.
Punkt 2
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Tänk på att JavaScript-pluginen försöker välja rätt element bland allt som kan vara synligt. Flera synliga scrollspy-mål samtidigt kan orsaka vissa problem.
Punkt 3
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Tänk på att JavaScript-pluginen försöker välja rätt element bland allt som kan vara synligt. Flera synliga scrollspy-mål samtidigt kan orsaka vissa problem.
Punkt 3-1
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Tänk på att JavaScript-pluginen försöker välja rätt element bland allt som kan vara synligt. Flera synliga scrollspy-mål samtidigt kan orsaka vissa problem.
Punkt 3-2
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Tänk på att JavaScript-pluginen försöker välja rätt element bland allt som kan vara synligt. Flera synliga scrollspy-mål samtidigt kan orsaka vissa problem.
<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>
Listgrupp
Scrollspy fungerar också med .list-groups. Bläddra i området bredvid listgruppen och se hur den aktiva klassen ändras.
Punkt 1
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Punkt 2
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Punkt 3
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Punkt 4
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
<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>
Enkla ankare
Scrollspy är inte begränsat till nav-komponenter och listgrupper, så det fungerar på alla <a>ankarelement i det aktuella dokumentet. Bläddra i området och se hur .activeklassen förändras.
Punkt 1
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Punkt 2
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Punkt 3
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Punkt 4
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
Punkt 5
Detta är en del platshållarinnehåll för scrollspy-sidan. Observera att när du rullar nedåt på sidan markeras lämplig navigeringslänk. Det upprepas genom hela komponentexemplet. Vi fortsätter att lägga till ytterligare några exemplar här för att betona rullningen och markeringen.
<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>
Ej synliga element
Målelement som inte är synliga kommer att ignoreras och deras motsvarande nav-objekt kommer inte att få en .activeklass. Scrollspy-instanser som initierats i ett icke-synligt omslag kommer att ignorera alla målelement. Använd refreshmetoden för att kontrollera om det finns observerbara element när omslaget blir synligt.
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()
})
})
Användande
Via dataattribut
För att enkelt lägga till scrollspy-beteende till din toppfältsnavigering, lägg data-bs-spy="scroll"till elementet du vill spionera på (vanligtvis skulle detta vara <body>). Lägg sedan till data-bs-targetattributet med ideller klassnamnet för det överordnade elementet för någon Bootstrap- .navkomponent.
<body data-bs-spy="scroll" data-bs-target="#navbar-example">
...
<div id="navbar-example">
<ul class="nav nav-tabs" role="tablist">
...
</ul>
</div>
...
</body>
Via JavaScript
const scrollSpy = new bootstrap.ScrollSpy(document.body, {
target: '#navbar-example'
})
alternativ
Eftersom alternativ kan skickas via dataattribut eller JavaScript kan du lägga till ett alternativnamn till data-bs-, som i data-bs-animation="{value}". Se till att ändra fallets typ av alternativnamnet från " camelCase " till " kebab-case " när du skickar alternativen via dataattribut. Använd till exempel data-bs-custom-class="beautifier"istället för data-bs-customClass="beautifier".
Från och med Bootstrap 5.2.0 stöder alla komponenter ett experimentellt reserverat dataattribut data-bs-configsom kan hysa enkel komponentkonfiguration som en JSON-sträng. När ett element har data-bs-config='{"delay":0, "title":123}'och data-bs-title="456"attribut kommer det slutliga titlevärdet att vara 456och de separata dataattributen kommer att åsidosätta värden som ges på data-bs-config. Dessutom kan befintliga dataattribut innehålla JSON-värden som data-bs-delay='{"show":0,"hide":150}'.
| namn | Typ | Standard | Beskrivning |
|---|---|---|---|
rootMargin |
sträng | 0px 0px -25% |
Intersection Observer rootMargin giltiga enheter, vid beräkning av rullningsposition. |
smoothScroll |
booleskt | false |
Möjliggör smidig rullning när en användare klickar på en länk som hänvisar till ScrollSpy observerbara. |
target |
sträng, DOM-element | null |
Anger element för att tillämpa Scrollspy-plugin. |
threshold |
array | [0.1, 0.5, 1] |
IntersectionObserver tröskel giltig inmatning, vid beräkning av rullningsposition. |
Utfasade alternativ
Fram till v5.1.3 använde vi offset& methodalternativ, som nu är utfasade och ersatta av rootMargin. För att behålla bakåtkompatibiliteten kommer vi att fortsätta att analysera en given offsettill rootMargin, men den här funktionen kommer att tas bort i v6 .
Metoder
| Metod | Beskrivning |
|---|---|
dispose |
Förstör ett elements scrollspy. (Tar bort lagrad data på DOM-elementet) |
getInstance |
Statisk metod för att få scrollspy-instansen associerad med ett DOM-element. |
getOrCreateInstance |
Statisk metod för att få scrollspy-instansen associerad med ett DOM-element, eller för att skapa en ny om den inte initierades. |
refresh |
När du lägger till eller tar bort element i DOM, måste du anropa uppdateringsmetoden. |
Här är ett exempel med uppdateringsmetoden:
const dataSpyList = document.querySelectorAll('[data-bs-spy="scroll"]')
dataSpyList.forEach(dataSpyEl => {
bootstrap.ScrollSpy.getInstance(dataSpyEl).refresh()
})
evenemang
| Händelse | Beskrivning |
|---|---|
activate.bs.scrollspy |
Denna händelse utlöses på rullningselementet närhelst ett ankare aktiveras av scrollspionen. |
const firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', () => {
// do something...
})