Scrollspy
Awtomatikong i-update ang Bootstrap navigation o ilista ang mga bahagi ng pangkat batay sa posisyon ng pag-scroll upang isaad kung aling link ang kasalukuyang aktibo sa viewport.
Paano ito gumagana
I-toggle ng Scrollspy ang .active
klase sa mga elemento ng anchor ( <a>
) kapag ang elementong may id
reference ng anchor's href
ay na-scroll sa view. Ang Scrollspy ay pinakamahusay na ginagamit kasabay ng isang Bootstrap nav component o list group , ngunit gagana rin ito sa anumang mga elemento ng anchor sa kasalukuyang pahina. Narito kung paano ito gumagana.
-
Upang magsimula, ang scrollspy ay nangangailangan ng dalawang bagay: isang nabigasyon, pangkat ng listahan, o isang simpleng hanay ng mga link, kasama ang isang na-scroll na lalagyan. Ang na-scroll na lalagyan ay maaaring ang
<body>
o isang custom na elemento na may setheight
atoverflow-y: scroll
. -
Sa na-scroll na lalagyan, idagdag
data-bs-spy="scroll"
atdata-bs-target="#navId"
kung saannavId
ang natatangiid
sa nauugnay na nabigasyon. Tiyaking isama rin ang isangtabindex="0"
upang matiyak ang pag-access sa keyboard. -
Habang nag-ii-scroll ka sa lalagyan na "na-spied", may
.active
idinaragdag at inaalis na klase sa mga anchor link sa loob ng nauugnay na nabigasyon. Ang mga link ay dapat na may mga nareresolba naid
target, kung hindi, mababalewala ang mga ito. Halimbawa, ang isang ay<a href="#home">home</a>
dapat na tumutugma sa isang bagay sa DOM tulad ng<div id="home"></div>
-
Ang mga target na elemento na hindi nakikita ay hindi papansinin. Tingnan ang seksyong Hindi nakikitang mga elemento sa ibaba.
Mga halimbawa
Navbar
Mag-scroll sa lugar sa ibaba ng navbar at panoorin ang aktibong pagbabago ng klase. Buksan ang dropdown na menu at panoorin ang mga dropdown na item na naka-highlight din.
Unang heading
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
Pangalawang heading
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
Pangatlong heading
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
Pang-apat na heading
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
Ikalimang heading
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
<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>
Nested nav
Gumagana rin ang Scrollspy sa nested .nav
s. Kung ang isang nested .nav
ay .active
, ang mga magulang nito ay magiging .active
. Mag-scroll sa lugar sa tabi ng navbar at panoorin ang aktibong pagbabago ng klase.
aytem 1
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
Tandaan na sinusubukan ng JavaScript plugin na piliin ang tamang elemento sa lahat ng maaaring makita. Maramihang nakikitang scrollspy target sa parehong oras ay maaaring magdulot ng ilang mga isyu.
Aytem 1-1
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
Tandaan na sinusubukan ng JavaScript plugin na piliin ang tamang elemento sa lahat ng maaaring makita. Maramihang nakikitang scrollspy target sa parehong oras ay maaaring magdulot ng ilang mga isyu.
Aytem 1-2
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
Tandaan na sinusubukan ng JavaScript plugin na piliin ang tamang elemento sa lahat ng maaaring makita. Maramihang nakikitang scrollspy target sa parehong oras ay maaaring magdulot ng ilang mga isyu.
aytem 2
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
Tandaan na sinusubukan ng JavaScript plugin na piliin ang tamang elemento sa lahat ng maaaring makita. Maramihang nakikitang scrollspy target sa parehong oras ay maaaring magdulot ng ilang mga isyu.
aytem 3
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
Tandaan na sinusubukan ng JavaScript plugin na piliin ang tamang elemento sa lahat ng maaaring makita. Maramihang nakikitang scrollspy target sa parehong oras ay maaaring magdulot ng ilang mga isyu.
Aytem 3-1
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
Tandaan na sinusubukan ng JavaScript plugin na piliin ang tamang elemento sa lahat ng maaaring makita. Maramihang nakikitang scrollspy target sa parehong oras ay maaaring magdulot ng ilang mga isyu.
Aytem 3-2
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
Tandaan na sinusubukan ng JavaScript plugin na piliin ang tamang elemento sa lahat ng maaaring makita. Maramihang nakikitang scrollspy target sa parehong oras ay maaaring magdulot ng ilang mga isyu.
<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>
Listahan ng pangkat
Gumagana rin ang Scrollspy sa .list-group
s. Mag-scroll sa lugar sa tabi ng listahan ng pangkat at panoorin ang aktibong pagbabago ng klase.
aytem 1
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
aytem 2
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
aytem 3
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
aytem 4
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
<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>
Mga simpleng anchor
Ang Scrollspy ay hindi limitado sa mga bahagi ng nav at mga pangkat ng listahan, kaya gagana ito sa anumang <a>
mga elemento ng anchor sa kasalukuyang dokumento. Mag-scroll sa lugar at panoorin ang .active
pagbabago ng klase.
aytem 1
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
aytem 2
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
aytem 3
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
aytem 4
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
aytem 5
Ito ay ilang placeholder na nilalaman para sa scrollspy page. Tandaan na habang nag-i-scroll ka pababa sa pahina, naka-highlight ang naaangkop na link sa pag-navigate. Ito ay paulit-ulit sa buong halimbawa ng bahagi. Patuloy kaming nagdaragdag ng ilang halimbawang kopya dito upang bigyang-diin ang pag-scroll at pag-highlight.
<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>
Mga elementong hindi nakikita
Ang mga target na elemento na hindi nakikita ay hindi papansinin at ang kanilang mga katumbas na nav item ay hindi makakatanggap ng .active
klase. Ang mga instance ng scrollspy na nasimulan sa isang hindi nakikitang wrapper ay babalewalain ang lahat ng target na elemento. Gamitin ang refresh
paraan upang suriin kung may mga nakikitang elemento kapag nakita na ang wrapper.
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()
})
})
Paggamit
Sa pamamagitan ng mga katangian ng data
Upang madaling magdagdag ng scrollspy na gawi sa iyong topbar navigation, idagdag data-bs-spy="scroll"
sa elementong gusto mong tiktikan (kadalasan ay ito ang <body>
). Pagkatapos ay idagdag ang data-bs-target
attribute na may id
pangalan ng or class ng parent element ng anumang bahagi ng Bootstrap .nav
.
<body data-bs-spy="scroll" data-bs-target="#navbar-example">
...
<div id="navbar-example">
<ul class="nav nav-tabs" role="tablist">
...
</ul>
</div>
...
</body>
Sa pamamagitan ng JavaScript
const scrollSpy = new bootstrap.ScrollSpy(document.body, {
target: '#navbar-example'
})
Mga pagpipilian
Dahil maaaring maipasa ang mga opsyon sa pamamagitan ng mga katangian ng data o JavaScript, maaari kang magdagdag ng pangalan ng opsyon sa data-bs-
, tulad ng sa data-bs-animation="{value}"
. Siguraduhing baguhin ang uri ng case ng pangalan ng opsyon mula sa " camelCase " sa " kebab-case " kapag ipinapasa ang mga opsyon sa pamamagitan ng mga katangian ng data. Halimbawa, gamitin data-bs-custom-class="beautifier"
sa halip na data-bs-customClass="beautifier"
.
Mula sa Bootstrap 5.2.0, sinusuportahan ng lahat ng mga bahagi ang isang pang- eksperimentong nakalaan na katangian ng data data-bs-config
na maaaring maglagay ng simpleng configuration ng bahagi bilang isang string ng JSON. Kapag ang isang elemento ay may data-bs-config='{"delay":0, "title":123}'
at data-bs-title="456"
mga katangian, ang huling title
halaga ay magiging 456
at ang hiwalay na mga katangian ng data ay mag-o-override sa mga halagang ibinigay sa data-bs-config
. Bilang karagdagan, ang mga kasalukuyang katangian ng data ay nakakapaglagay ng mga halaga ng JSON tulad ng data-bs-delay='{"show":0,"hide":150}'
.
Pangalan | Uri | Default | Paglalarawan |
---|---|---|---|
rootMargin |
string | 0px 0px -25% |
Intersection Observer rootMargin valid units, kapag kinakalkula ang posisyon ng scroll. |
smoothScroll |
boolean | false |
Pinapagana ang maayos na pag-scroll kapag nag-click ang isang user sa isang link na tumutukoy sa mga naoobserbahang ScrollSpy. |
target |
string, elemento ng DOM | null |
Tinutukoy ang elementong ilalapat ng Scrollspy plugin. |
threshold |
array | [0.1, 0.5, 1] |
IntersectionObserver threshold valid input, kapag kinakalkula ang posisyon ng scroll. |
Hindi na ginagamit na mga Opsyon
Hanggang sa v5.1.3 kami ay gumagamit ng offset
& mga method
opsyon, na ngayon ay hindi na ginagamit at pinalitan ng rootMargin
. Upang mapanatili ang backward compatibility, magpapatuloy kami sa pag-parse ng ibinigay offset
sa rootMargin
, ngunit ang feature na ito ay aalisin sa v6 .
Paraan
Pamamaraan | Paglalarawan |
---|---|
dispose |
Sinisira ang scrollspy ng isang elemento. (Aalisin ang nakaimbak na data sa elemento ng DOM) |
getInstance |
Static na paraan upang makuha ang scrollspy instance na nauugnay sa isang elemento ng DOM. |
getOrCreateInstance |
Static na paraan para makuha ang scrollspy instance na nauugnay sa isang elemento ng DOM, o gumawa ng bago kung sakaling hindi ito nasimulan. |
refresh |
Kapag nagdaragdag o nag-aalis ng mga elemento sa DOM, kakailanganin mong tawagan ang paraan ng pag-refresh. |
Narito ang isang halimbawa gamit ang paraan ng pag-refresh:
const dataSpyList = document.querySelectorAll('[data-bs-spy="scroll"]')
dataSpyList.forEach(dataSpyEl => {
bootstrap.ScrollSpy.getInstance(dataSpyEl).refresh()
})
Mga kaganapan
Kaganapan | Paglalarawan |
---|---|
activate.bs.scrollspy |
Ang kaganapang ito ay gumagana sa elemento ng scroll sa tuwing ang isang anchor ay ina-activate ng scrollspy. |
const firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', () => {
// do something...
})