Scrollspy

Kemas kini navigasi Bootstrap secara automatik atau senaraikan komponen kumpulan berdasarkan kedudukan tatal untuk menunjukkan pautan yang sedang aktif dalam port pandang.

Pada halaman ini

Bagaimana ia berfungsi

Scrollspy menogol .activekelas pada elemen anchor ( <a>) apabila elemen yang iddirujuk oleh anchor hrefditatal ke paparan. Scrollspy paling sesuai digunakan bersama dengan komponen nav Bootstrap atau kumpulan senarai , tetapi ia juga akan berfungsi dengan mana-mana elemen utama dalam halaman semasa. Begini cara ia berfungsi.

Untuk bermula, scrollspy memerlukan dua perkara: navigasi, kumpulan senarai atau set pautan ringkas, serta bekas boleh ditatal. Bekas boleh tatal boleh menjadi <body>atau elemen tersuai dengan set heightdan overflow-y: scroll.
Pada bekas boleh tatal, tambahkan data-bs-spy="scroll"dan data-bs-target="#navId"di manakah navIdkeunikan idnavigasi yang berkaitan. Pastikan anda turut sertakan a tabindex="0"untuk memastikan akses papan kekunci.
Semasa anda menatal bekas "diintip", .activekelas ditambah dan dialih keluar daripada pautan sauh dalam navigasi yang berkaitan. Pautan mesti mempunyai idsasaran yang boleh diselesaikan, jika tidak ia diabaikan. Sebagai contoh, <a href="#home">home</a>mesti sepadan dengan sesuatu dalam DOM seperti<div id="home"></div>
Elemen sasaran yang tidak kelihatan akan diabaikan. Lihat bahagian Unsur tidak kelihatan di bawah.

Contoh

Tatal kawasan di bawah bar navigasi dan lihat perubahan kelas aktif. Buka menu lungsur turun dan tonton item lungsur turun juga diserlahkan.

Tajuk pertama

Ini ialah beberapa kandungan pemegang tempat untuk halaman scrollspy. Ambil perhatian bahawa semasa anda menatal ke bawah halaman, pautan navigasi yang sesuai diserlahkan. Ia diulang sepanjang contoh komponen. Kami terus menambah beberapa lagi contoh salinan di sini untuk menekankan penatalan dan penyerlahan.

Tajuk kedua

Tajuk ketiga

Tajuk keempat

Tajuk kelima

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

Nav bersarang

Scrollspy juga berfungsi dengan .navs bersarang. Jika bersarang , .navibu .activebapanya juga .active. Tatal kawasan di sebelah bar navigasi dan lihat perubahan kelas aktif.

Perkara 1

Perlu diingat bahawa pemalam JavaScript cuba memilih elemen yang betul antara semua yang mungkin kelihatan. Berbilang sasaran scrollspy yang boleh dilihat pada masa yang sama boleh menyebabkan beberapa isu.

Perkara 1-1

Perkara 1-2

Perkara 2

Perkara 3

Perkara 3-1

Perkara 3-2

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

Senaraikan kumpulan

Scrollspy juga berfungsi dengan .list-groups. Tatal kawasan di sebelah kumpulan senarai dan tonton perubahan kelas aktif.

Perkara 1 Perkara 2 Perkara 3 Perkara 4

Perkara 1

Perkara 2

Perkara 3

Perkara 4

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

sauh mudah

Scrollspy tidak terhad kepada komponen nav dan kumpulan senarai, jadi ia akan berfungsi pada mana-mana <a>elemen utama dalam dokumen semasa. Tatal kawasan dan lihat .activeperubahan kelas.

Perkara 1 Perkara 2 Perkara 3 Perkara 4 Perkara 5

Perkara 1

Perkara 2

Perkara 3

Perkara 4

Perkara 5

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

Unsur yang tidak kelihatan

Elemen sasaran yang tidak kelihatan akan diabaikan dan item nav yang sepadan tidak akan menerima .activekelas. Kejadian Scrollspy yang dimulakan dalam pembungkus yang tidak kelihatan akan mengabaikan semua elemen sasaran. Gunakan refreshkaedah untuk menyemak unsur yang boleh diperhatikan sebaik sahaja pembalut kelihatan.

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()
  })
})

Penggunaan

Melalui atribut data

Untuk menambahkan gelagat scrollspy dengan mudah pada navigasi bar atas anda, tambahkan data-bs-spy="scroll"pada elemen yang anda ingin mengintip (kebiasaannya ini ialah <body>). Kemudian tambahkan data-bs-targetatribut dengan idatau nama kelas bagi elemen induk bagi mana-mana .navkomponen Bootstrap.

<body data-bs-spy="scroll" data-bs-target="#navbar-example">
  ...
  <div id="navbar-example">
    <ul class="nav nav-tabs" role="tablist">
      ...
    </ul>
  </div>
  ...
</body>

Melalui JavaScript

const scrollSpy = new bootstrap.ScrollSpy(document.body, {
  target: '#navbar-example'
})

Pilihan

Memandangkan pilihan boleh dihantar melalui atribut data atau JavaScript, anda boleh menambahkan nama pilihan pada data-bs-, seperti dalam data-bs-animation="{value}". Pastikan anda menukar jenis kes bagi nama pilihan daripada " camelCase " kepada " kebab-case " apabila menghantar pilihan melalui atribut data. Sebagai contoh, gunakan data-bs-custom-class="beautifier"bukannya data-bs-customClass="beautifier".

Mulai Bootstrap 5.2.0, semua komponen menyokong atribut data simpanan percubaandata-bs-config yang boleh menempatkan konfigurasi komponen ringkas sebagai rentetan JSON. Apabila elemen mempunyai data-bs-config='{"delay":0, "title":123}'dan data-bs-title="456"atribut, nilai akhir titleakan menjadi 456dan atribut data yang berasingan akan mengatasi nilai yang diberikan pada data-bs-config. Selain itu, atribut data sedia ada dapat menempatkan nilai JSON seperti data-bs-delay='{"show":0,"hide":150}'.

Nama	taip	Lalai	Penerangan
`rootMargin`	tali	`0px 0px -25%`	Unit sah rootMargin Pemerhati Persimpangan , apabila mengira kedudukan tatal.
`smoothScroll`	boolean	`false`	Membolehkan penatalan lancar apabila pengguna mengklik pada pautan yang merujuk kepada ScrollSpy observables.
`target`	rentetan, elemen DOM	`null`	Menentukan elemen untuk menggunakan pemalam Scrollspy.
`threshold`	tatasusunan	`[0.1, 0.5, 1]`	`IntersectionObserver` ambang input yang sah, apabila mengira kedudukan tatal.

Pilihan Dihentikan

Sehingga v5.1.3 kami menggunakan offset& methodpilihan, yang kini ditamatkan dan digantikan dengan rootMargin. Untuk mengekalkan keserasian ke belakang, kami akan terus menghuraikan yang diberikan offsetkepada rootMargin, tetapi ciri ini akan dialih keluar dalam v6 .

Kaedah

Kaedah	Penerangan
`dispose`	Memusnahkan scrollspy elemen. (Mengalih keluar data yang disimpan pada elemen DOM)
`getInstance`	Kaedah statik untuk mendapatkan contoh scrollspy yang dikaitkan dengan elemen DOM.
`getOrCreateInstance`	Kaedah statik untuk mendapatkan contoh scrollspy yang dikaitkan dengan elemen DOM, atau untuk mencipta yang baharu sekiranya ia tidak dimulakan.
`refresh`	Apabila menambah atau mengalih keluar elemen dalam DOM, anda perlu memanggil kaedah muat semula.

Berikut ialah contoh menggunakan kaedah muat semula:

const dataSpyList = document.querySelectorAll('[data-bs-spy="scroll"]')
dataSpyList.forEach(dataSpyEl => {
  bootstrap.ScrollSpy.getInstance(dataSpyEl).refresh()
})

Peristiwa

Peristiwa	Penerangan
`activate.bs.scrollspy`	Peristiwa ini menyala pada elemen skrol apabila sauh diaktifkan oleh scrollspy.

const firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', () => {
  // do something...
})