in English

Scrollspy

Tự động cập nhật điều hướng Bootstrap hoặc các thành phần nhóm danh sách dựa trên vị trí cuộn để cho biết liên kết nào hiện đang hoạt động trong khung nhìn.

Trên trang này

Làm thế nào nó hoạt động

Scrollspy chuyển đổi .activelớp trên các phần tử anchor ( <a>) khi phần tử có idtham chiếu bởi anchor's hrefđược cuộn vào chế độ xem. Scrollspy được sử dụng tốt nhất cùng với thành phần hoặc nhóm danh sách Bootstrap nav , nhưng nó cũng sẽ hoạt động với bất kỳ phần tử neo nào trong trang hiện tại. Đây là cách nó hoạt động.

Để bắt đầu, scrollspy yêu cầu hai thứ: điều hướng, nhóm danh sách hoặc một tập hợp các liên kết đơn giản, cộng với một vùng chứa có thể cuộn. Vùng chứa có thể cuộn có thể là <body>hoặc một phần tử tùy chỉnh với một tập hợp heightvà overflow-y: scroll.
Trên vùng chứa có thể cuộn, hãy thêm data-bs-spy="scroll"và data-bs-target="#navId"đâu navIdlà điểm duy nhất idcủa điều hướng được liên kết. Hãy chắc chắn bao gồm một tabindex="0"để đảm bảo quyền truy cập bàn phím.
Khi bạn cuộn vùng chứa "do thám", một .activelớp được thêm vào và xóa khỏi các liên kết neo trong điều hướng được liên kết. Các liên kết phải có idcác mục tiêu có thể giải quyết được, nếu không chúng sẽ bị bỏ qua. Ví dụ: một <a href="#home">home</a>phải tương ứng với một cái gì đó trong DOM như<div id="home"></div>
Các phần tử mục tiêu không hiển thị sẽ bị bỏ qua. Xem phần Các phần tử không hiển thị bên dưới.

Các ví dụ

Cuộn khu vực bên dưới thanh điều hướng và xem thay đổi lớp đang hoạt động. Mở menu thả xuống và xem các mục thả xuống cũng được đánh dấu.

Tiêu đề đầu tiên

Đây là một số nội dung giữ chỗ cho trang cuộn giấy. Lưu ý rằng khi bạn cuộn xuống trang, liên kết điều hướng thích hợp sẽ được tô sáng. Nó được lặp lại trong suốt ví dụ thành phần. Chúng tôi tiếp tục thêm một số bản sao ví dụ khác ở đây để nhấn mạnh việc cuộn và làm nổi bật.

Tiêu đề thứ hai

Tiêu đề thứ ba

Tiêu đề thứ tư

Tiêu đề thứ năm

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

Điều hướng lồng nhau

Scrollspy cũng hoạt động với các .navs lồng nhau. Nếu một con .navđược làm .activetổ, bố mẹ của nó cũng sẽ như vậy .active. Cuộn khu vực bên cạnh thanh điều hướng và xem sự thay đổi lớp đang hoạt động.

Mục 1

Hãy nhớ rằng plugin JavaScript cố gắng chọn đúng phần tử trong số tất cả những phần tử có thể hiển thị. Nhiều mục tiêu cuộn chuột có thể nhìn thấy cùng một lúc có thể gây ra một số vấn đề.

Mục 1-1

Mục 1-2

Mặt hàng 2

Mặt hàng 3

Mục 3-1

Mục 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>

Danh sách nhóm

Scrollspy cũng hoạt động với .list-groups. Cuộn khu vực bên cạnh nhóm danh sách và xem sự thay đổi lớp đang hoạt động.

Mục 1 Mặt hàng 2 Mặt hàng 3 Mặt hàng 4

Mục 1

Mặt hàng 2

Mặt hàng 3

Mặt hàng 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>

Neo đơn giản

Scrollspy không giới hạn ở các thành phần điều hướng và nhóm danh sách, vì vậy nó sẽ hoạt động trên bất kỳ <a>phần tử neo nào trong tài liệu hiện tại. Di chuyển khu vực và xem sự .activethay đổi của lớp.

Mục 1 Mặt hàng 2 Mặt hàng 3 Mặt hàng 4 Mặt hàng 5

Mục 1

Mặt hàng 2

Mặt hàng 3

Mặt hàng 4

Mặt hàng 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>

Các phần tử không hiển thị

Các phần tử mục tiêu không hiển thị sẽ bị bỏ qua và các mục điều hướng tương ứng của chúng sẽ không nhận được một .activelớp. Các trường hợp cuộn giấy được khởi tạo trong một trình bao bọc không hiển thị sẽ bỏ qua tất cả các phần tử đích. Sử dụng refreshphương pháp này để kiểm tra các phần tử có thể quan sát được khi trình bao bọc trở nên hiển thị.

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

Cách sử dụng

Qua các thuộc tính dữ liệu

Để dễ dàng thêm hành vi cuộn tròn vào điều hướng thanh trên cùng của bạn, hãy thêm data-bs-spy="scroll"vào phần tử bạn muốn theo dõi (thông thường nhất sẽ là phần tử này <body>). Sau đó, thêm data-bs-targetthuộc tính có tên idhoặc tên lớp của phần tử mẹ của bất kỳ thành phần Bootstrap nào .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>

Qua JavaScript

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

Tùy chọn

Vì các tùy chọn có thể được chuyển qua thuộc tính dữ liệu hoặc JavaScript, bạn có thể thêm tên tùy chọn vào data-bs-, như trong data-bs-animation="{value}". Đảm bảo thay đổi kiểu chữ hoa của tên tùy chọn từ “ camelCase ” thành “ kebab-case ” khi chuyển các tùy chọn qua thuộc tính dữ liệu. Ví dụ, sử dụng data-bs-custom-class="beautifier"thay vì data-bs-customClass="beautifier".

Kể từ Bootstrap 5.2.0, tất cả các thành phần đều hỗ trợ thuộc tính dữ liệu dành riêng thử nghiệmdata-bs-config có thể chứa cấu hình thành phần đơn giản dưới dạng chuỗi JSON. Khi một phần tử có data-bs-config='{"delay":0, "title":123}'và data-bs-title="456"các thuộc tính, titlegiá trị cuối cùng sẽ là 456và các thuộc tính dữ liệu riêng biệt sẽ ghi đè các giá trị được cho trên data-bs-config. Ngoài ra, các thuộc tính dữ liệu hiện có có thể chứa các giá trị JSON như data-bs-delay='{"show":0,"hide":150}'.

Tên	Loại hình	Mặc định	Sự mô tả
`rootMargin`	sợi dây	`0px 0px -25%`	Intersection Observer rootMargin đơn vị hợp lệ, khi tính toán vị trí cuộn.
`smoothScroll`	boolean	`false`	Cho phép cuộn trơn tru khi người dùng nhấp vào liên kết đề cập đến các khả năng quan sát của ScrollSpy.
`target`	chuỗi, phần tử DOM	`null`	Chỉ định phần tử để áp dụng plugin Scrollspy.
`threshold`	mảng	`[0.1, 0.5, 1]`	`IntersectionObserver` ngưỡng đầu vào hợp lệ, khi tính toán vị trí cuộn.

Tùy chọn không được chấp nhận

Cho đến v5.1.3, chúng tôi đã sử dụng offset& methodtùy chọn, hiện không được dùng nữa và được thay thế bằng rootMargin. Để giữ khả năng tương thích ngược, chúng tôi sẽ tiếp tục phân tích cú pháp đã cho offset, rootMarginnhưng tính năng này sẽ bị xóa trong phiên bản 6 .

Phương pháp

Phương pháp	Sự mô tả
`dispose`	Hủy bỏ cuộn giấy của một phần tử. (Xóa dữ liệu được lưu trữ trên phần tử DOM)
`getInstance`	Phương thức static để lấy phiên bản scrollspy được liên kết với một phần tử DOM.
`getOrCreateInstance`	Phương thức static để lấy phiên bản scrollspy được liên kết với một phần tử DOM hoặc để tạo một phiên bản mới trong trường hợp nó chưa được khởi tạo.
`refresh`	Khi thêm hoặc xóa các phần tử trong DOM, bạn sẽ cần gọi phương thức làm mới.

Dưới đây là một ví dụ sử dụng phương pháp làm mới:

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

Sự kiện

Biến cố	Sự mô tả
`activate.bs.scrollspy`	Sự kiện này kích hoạt trên phần tử cuộn bất cứ khi nào một anchor được kích hoạt bởi scrollspy.

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

Scrollspy

Làm thế nào nó hoạt động

Các ví dụ

Thanh điều hướng

Tiêu đề đầu tiên

Tiêu đề thứ hai

Tiêu đề thứ ba

Tiêu đề thứ tư

Tiêu đề thứ năm

Điều hướng lồng nhau

Mục 1

Mục 1-1

Mục 1-2

Mặt hàng 2

Mặt hàng 3

Mục 3-1

Mục 3-2

Danh sách nhóm

Mục 1

Mặt hàng 2

Mặt hàng 3

Mặt hàng 4

Neo đơn giản

Mục 1

Mặt hàng 2

Mặt hàng 3

Mặt hàng 4

Mặt hàng 5

Các phần tử không hiển thị

Cách sử dụng

Qua các thuộc tính dữ liệu

Qua JavaScript

Tùy chọn

Phương pháp

Sự kiện