스크롤스파이

뷰포트에서 현재 활성화된 링크를 나타내기 위해 스크롤 위치를 기반으로 부트스트랩 탐색 또는 목록 그룹 구성 요소를 자동으로 업데이트합니다.

이 페이지에서

작동 방식

Scrollspy 는 앵커에서 참조 하는 요소 가 보기로 스크롤될 때 앵커( ) 요소 의 .active클래스를 토글합니다. Scrollspy는 Bootstrap 탐색 구성 요소 또는 목록 그룹 과 함께 사용하는 것이 가장 좋지만 현재 페이지의 모든 앵커 요소에서도 작동합니다. 작동 방식은 다음과 같습니다.<a>idhref

시작하려면 scrollspy에는 탐색, 목록 그룹 또는 간단한 링크 집합과 스크롤 가능한 컨테이너의 두 가지가 필요합니다. 스크롤 가능한 컨테이너는 또는 세트 및 <body>가 있는 사용자 정의 요소 일 수 있습니다 .heightoverflow-y: scroll
스크롤 가능한 컨테이너 에서 관련 탐색 의 고유한 위치를 data-bs-spy="scroll"추가 data-bs-target="#navId"합니다 . 또한 키보드 액세스를 보장하기 위해 포함해야 합니다.navIdidtabindex="0"
"스파이" 컨테이너를 스크롤하면 .active연결된 탐색 내의 앵커 링크에서 클래스가 추가 및 제거됩니다. 링크에는 확인 가능한 대상이 있어야 id하며 그렇지 않으면 무시됩니다. 예를 들어, a <a href="#home">home</a>는 다음과 같은 DOM에 있는 것과 일치해야 합니다.<div id="home"></div>
보이지 않는 대상 요소는 무시됩니다. 아래의 보이지 않는 요소 섹션 을 참조하십시오 .

예

탐색 모음 아래 영역을 스크롤하여 활성 클래스 변경을 확인합니다. 드롭다운 메뉴를 열고 드롭다운 항목도 강조 표시되는지 확인합니다.

첫 번째 제목

이것은 scrollspy 페이지에 대한 일부 자리 표시자 콘텐츠입니다. 페이지를 아래로 스크롤하면 해당 탐색 링크가 강조 표시됩니다. 구성 요소 예제 전체에서 반복됩니다. 스크롤 및 강조 표시를 강조하기 위해 여기에 예제 사본을 계속 추가합니다.

두 번째 제목

세 번째 제목

네 번째 제목

다섯 번째 제목

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

중첩된 탐색

Scrollspy는 중첩된 .navs에서도 작동합니다. 중첩 .nav이 .active이면 부모도 됩니다 .active. 탐색 모음 옆의 영역을 스크롤하여 활성 클래스 변경을 확인합니다.

항목 1

JavaScript 플러그인은 표시될 수 있는 모든 요소 중에서 올바른 요소를 선택하려고 시도합니다. 동시에 여러 개의 scrollspy 대상이 표시되면 몇 가지 문제가 발생할 수 있습니다.

항목 1-1

항목 1-2

항목 2

항목 3

항목 3-1

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

목록 그룹

Scrollspy는 s와도 작동합니다 .list-group. 목록 그룹 옆의 영역을 스크롤하여 활성 클래스 변경 사항을 확인합니다.

항목 1 항목 2 항목 3 항목 4

항목 1

항목 2

항목 3

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

간단한 앵커

Scrollspy는 탐색 구성 요소 및 목록 그룹에 국한되지 않으므로 <a>현재 문서의 모든 앵커 요소에서 작동합니다. 영역을 스크롤하여 .active클래스 변경 사항을 확인하십시오.

항목 1 항목 2 항목 3 항목 4 항목 5

항목 1

항목 2

항목 3

항목 4

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

보이지 않는 요소

표시되지 않는 대상 요소는 무시되고 해당 탐색 항목은 .active클래스를 수신하지 않습니다. 보이지 않는 래퍼에서 초기화된 Scrollspy 인스턴스는 모든 대상 요소를 무시합니다. refresh래퍼가 표시되면 메서드를 사용하여 관찰 가능한 요소를 확인합니다.

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

용법

데이터 속성을 통해

scrollspy 동작을 상단 표시줄 탐색에 쉽게 추가하려면 data-bs-spy="scroll"감시하려는 요소에 추가합니다(대부분의 경우 <body>). 그런 다음 Bootstrap 구성 요소의 상위 요소에 대한 또는 클래스 이름으로 data-bs-target속성을 추가합니다 .id.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>

자바스크립트를 통해

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

옵션

옵션은 데이터 속성이나 JavaScript를 통해 전달할 수 있으므로 에서 data-bs-와 같이 옵션 이름을 에 추가할 수 있습니다 data-bs-animation="{value}". 데이터 속성을 통해 옵션을 전달할 때 옵션 이름의 대소문자 유형을 " camelCase "에서 " kebab-case "로 변경해야 합니다. 예를 들어, data-bs-custom-class="beautifier"대신 를 사용 data-bs-customClass="beautifier"하십시오.

Bootstrap 5.2.0부터 모든 구성 요소 는 JSON 문자열로 간단한 구성 요소 구성을 수용할 수 있는 실험적 으로 예약된 데이터 속성 을 지원합니다. data-bs-config요소에 data-bs-config='{"delay":0, "title":123}'및 data-bs-title="456"속성이 있는 경우 최종 title값은 456이고 별도의 데이터 속성은 에 제공된 값을 재정의합니다 data-bs-config. 또한 기존 데이터 속성은 와 같은 JSON 값을 저장할 수 data-bs-delay='{"show":0,"hide":150}'있습니다.

이름	유형	기본	설명
`rootMargin`	끈	`0px 0px -25%`	교차 관찰자 rootMargin 은 스크롤 위치를 계산할 때 유효한 단위입니다.
`smoothScroll`	부울	`false`	사용자가 ScrollSpy 관찰 가능 항목을 참조하는 링크를 클릭할 때 부드러운 스크롤을 활성화합니다.
`target`	문자열, DOM 요소	`null`	Scrollspy 플러그인을 적용할 요소를 지정합니다.
`threshold`	정렬	`[0.1, 0.5, 1]`	`IntersectionObserver` 스크롤 위치를 계산할 때 임계값 유효 입력.

사용되지 않는 옵션

v5.1.3까지 우리는 offset& method옵션을 사용했는데 이제는 더 이상 사용되지 않으며 rootMargin. 이전 버전과의 호환성을 유지하기 위해 주어진 offset에 대한 구문 분석을 계속할 rootMargin것이지만 이 기능은 v6 에서 제거됩니다 .

행동 양식

방법	설명
`dispose`	요소의 scrollspy를 파괴합니다. (DOM 요소에 저장된 데이터 제거)
`getInstance`	DOM 요소와 연결된 scrollspy 인스턴스를 가져오는 정적 메서드입니다.
`getOrCreateInstance`	DOM 요소와 연결된 scrollspy 인스턴스를 가져오거나 초기화되지 않은 경우 새 인스턴스를 만드는 정적 메서드입니다.
`refresh`	DOM에서 요소를 추가하거나 제거할 때 새로 고침 메서드를 호출해야 합니다.

다음은 새로 고침 방법을 사용하는 예입니다.

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

이벤트

이벤트	설명
`activate.bs.scrollspy`	이 이벤트는 scrollspy에 의해 앵커가 활성화될 때마다 스크롤 요소에서 발생합니다.

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

스크롤스파이

작동 방식

예

나브바

첫 번째 제목

두 번째 제목

세 번째 제목

네 번째 제목

다섯 번째 제목

중첩된 탐색

항목 1

항목 1-1

항목 1-2

항목 2

항목 3

항목 3-1

항목 3-2

목록 그룹

항목 1

항목 2

항목 3

항목 4

간단한 앵커

항목 1

항목 2

항목 3

항목 4

항목 5

보이지 않는 요소

용법

데이터 속성을 통해

자바스크립트를 통해

옵션

행동 양식

이벤트