Lumaktaw sa pangunahing nilalaman Lumaktaw sa docs navigation
Check
in English

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 .activeklase sa mga elemento ng anchor ( <a>) kapag ang elementong may idreference ng anchor's hrefay 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 set heightat overflow-y: scroll.

  • Sa na-scroll na lalagyan, idagdag data-bs-spy="scroll"at data-bs-target="#navId"kung saan navIdang natatangi idsa nauugnay na nabigasyon. Tiyaking isama rin ang isang tabindex="0"upang matiyak ang pag-access sa keyboard.

  • Habang nag-ii-scroll ka sa lalagyan na "na-spied", may .activeidinaragdag at inaalis na klase sa mga anchor link sa loob ng nauugnay na nabigasyon. Ang mga link ay dapat na may mga nareresolba na idtarget, 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

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 .navs. Kung ang isang nested .navay .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-groups. 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 .activepagbabago 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 .activeklase. Ang mga instance ng scrollspy na nasimulan sa isang hindi nakikitang wrapper ay babalewalain ang lahat ng target na elemento. Gamitin ang refreshparaan 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-targetattribute na may idpangalan 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-configna 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 titlehalaga ay magiging 456at 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 methodopsyon, na ngayon ay hindi na ginagamit at pinalitan ng rootMargin. Upang mapanatili ang backward compatibility, magpapatuloy kami sa pag-parse ng ibinigay offsetsa 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...
})