Scrollspy

Aktualisieren Sie automatisch die Bootstrap-Navigation oder listen Sie Gruppenkomponenten basierend auf der Bildlaufposition auf, um anzuzeigen, welcher Link derzeit im Ansichtsfenster aktiv ist.

Auf dieser Seite

Wie es funktioniert

Scrollspy schaltet die .activeKlasse auf Anker ( <a>)-Elemente um, wenn das Element, auf das iddurch den Anker verwiesen hrefwird, in die Ansicht gescrollt wird. Scrollspy wird am besten in Verbindung mit einer Bootstrap - Navigationskomponente oder einer Listengruppe verwendet , funktioniert aber auch mit allen Ankerelementen auf der aktuellen Seite. So funktioniert das.

Scrollspy benötigt zu Beginn zwei Dinge: eine Navigation, eine Listengruppe oder einen einfachen Satz von Links sowie einen scrollbaren Container. Der scrollbare Container kann das <body>oder ein benutzerdefiniertes Element mit einem Satz heightund sein overflow-y: scroll.
Fügen Sie auf dem scrollbaren Container hinzu data-bs-spy="scroll"und data-bs-target="#navId"wo navIdist die eindeutige idder zugehörigen Navigation. Stellen Sie sicher, dass Sie auch ein einfügen tabindex="0", um den Zugriff auf die Tastatur zu gewährleisten.
Wenn Sie durch den „ausspionierten“ Container scrollen, wird eine .activeKlasse hinzugefügt und von Ankerlinks innerhalb der zugehörigen Navigation entfernt. Links müssen auflösbare idZiele haben, andernfalls werden sie ignoriert. Zum Beispiel <a href="#home">home</a>muss a etwas im DOM wie entsprechen<div id="home"></div>
Nicht sichtbare Zielelemente werden ignoriert. Siehe Abschnitt Nicht sichtbare Elemente weiter unten.

Beispiele

Scrollen Sie im Bereich unterhalb der Navigationsleiste und beobachten Sie, wie sich die aktive Klasse ändert. Öffnen Sie das Dropdown-Menü und beobachten Sie, wie die Dropdown-Elemente ebenfalls hervorgehoben werden.

Erste Überschrift

Dies ist ein Platzhalterinhalt für die Scrollspy-Seite. Beachten Sie, dass beim Herunterscrollen der Seite der entsprechende Navigationslink hervorgehoben wird. Es wird im gesamten Komponentenbeispiel wiederholt. Wir fügen hier immer wieder weitere Beispieltexte hinzu, um das Scrollen und Hervorheben hervorzuheben.

Zweite Überschrift

Dritte Überschrift

Vierte Überschrift

Fünfte Überschrift

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

Verschachtelte Navigation

Scrollspy funktioniert auch mit verschachtelten .navs. Wenn eine verschachtelt .navist .active, sind auch ihre Eltern .active. Scrollen Sie im Bereich neben der Navigationsleiste und beobachten Sie, wie sich die aktive Klasse ändert.

Gegenstand 1

Denken Sie daran, dass das JavaScript-Plug-in versucht, das richtige Element unter allen sichtbaren Elementen auszuwählen. Mehrere gleichzeitig sichtbare Scrollspy-Ziele können einige Probleme verursachen.

Punkt 1-1

Punkt 1-2

Punkt 2

Punkt 3

Punkt 3-1

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

Gruppe auflisten

Scrollspy funktioniert auch mit .list-groups. Scrollen Sie im Bereich neben der Listengruppe und beobachten Sie, wie sich die aktive Klasse ändert.

Gegenstand 1 Punkt 2 Punkt 3 Punkt 4

Gegenstand 1

Punkt 2

Punkt 3

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

Einfache Anker

Scrollspy ist nicht auf Navigationskomponenten und Listengruppen beschränkt, daher funktioniert es mit allen Ankerelementen <a>im aktuellen Dokument. Scrollen Sie durch den Bereich und beobachten Sie, wie sich die .activeKlasse ändert.

Gegenstand 1 Punkt 2 Punkt 3 Punkt 4 Punkt 5

Gegenstand 1

Punkt 2

Punkt 3

Punkt 4

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

Nicht sichtbare Elemente

Nicht sichtbare Zielelemente werden ignoriert und ihre entsprechenden Navigationselemente erhalten keine .activeKlasse. Scrollspy-Instanzen, die in einem nicht sichtbaren Wrapper initialisiert werden, ignorieren alle Zielelemente. Verwenden Sie die refreshMethode, um nach beobachtbaren Elementen zu suchen, sobald der Wrapper sichtbar wird.

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

Verwendungszweck

Über Datenattribute

Um ganz einfach Scrollspy-Verhalten zu Ihrer Topbar-Navigation hinzuzufügen, fügen data-bs-spy="scroll"Sie das Element hinzu, das Sie ausspionieren möchten (normalerweise wäre dies das <body>). Fügen Sie dann das data-bs-targetAttribut mit dem idKlassennamen oder des übergeordneten Elements einer beliebigen Bootstrap- .navKomponente hinzu.

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

Über JavaScript

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

Optionen

Da Optionen über Datenattribute oder JavaScript übergeben werden können, können Sie einen Optionsnamen data-bs-wie in anhängen data-bs-animation="{value}". Stellen Sie sicher, dass Sie den Falltyp des Optionsnamens von " camelCase " in " kebab -case " ändern, wenn Sie die Optionen über Datenattribute übergeben. Verwenden Sie beispielsweise data-bs-custom-class="beautifier"anstelle von data-bs-customClass="beautifier".

Ab Bootstrap 5.2.0 unterstützen alle Komponenten ein experimentelles reserviertes Datenattribut, das eine data-bs-configeinfache Komponentenkonfiguration als JSON-String enthalten kann. Wenn ein Element über data-bs-config='{"delay":0, "title":123}'und data-bs-title="456"-Attribute verfügt, ist der endgültige titleWert 456und die separaten Datenattribute überschreiben die auf angegebenen Werte data-bs-config. Darüber hinaus können vorhandene Datenattribute JSON-Werte wie data-bs-delay='{"show":0,"hide":150}'.

Name	Typ	Standard	Beschreibung
`rootMargin`	Schnur	`0px 0px -25%`	Intersection Observer rootMargin gültige Einheiten bei der Berechnung der Bildlaufposition.
`smoothScroll`	boolesch	`false`	Ermöglicht reibungsloses Scrollen, wenn ein Benutzer auf einen Link klickt, der auf Observables von ScrollSpy verweist.
`target`	Zeichenfolge, DOM-Element	`null`	Gibt das Element zum Anwenden des Scrollspy-Plugins an.
`threshold`	Reihe	`[0.1, 0.5, 1]`	`IntersectionObserver` Schwellwert gültige Eingabe, wenn die Bildlaufposition berechnet wird.

Veraltete Optionen

Bis v5.1.3 haben wir offset& -Optionen verwendet method, die jetzt veraltet sind und durch ersetzt wurden rootMargin. Um die Abwärtskompatibilität zu wahren, werden wir weiterhin eine bestimmte bis analysieren offset, rootMarginaber diese Funktion wird in v6 entfernt .

Methoden

Methode	Beschreibung
`dispose`	Zerstört den Scrollspy eines Elements. (Entfernt gespeicherte Daten auf dem DOM-Element)
`getInstance`	Statische Methode zum Abrufen der Scrollspy-Instanz, die einem DOM-Element zugeordnet ist.
`getOrCreateInstance`	Statische Methode, um die mit einem DOM-Element verknüpfte Scrollspy-Instanz abzurufen oder eine neue zu erstellen, falls sie nicht initialisiert wurde.
`refresh`	Wenn Sie Elemente im DOM hinzufügen oder entfernen, müssen Sie die Aktualisierungsmethode aufrufen.

Hier ist ein Beispiel für die Verwendung der Aktualisierungsmethode:

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

Veranstaltungen

Vorfall	Beschreibung
`activate.bs.scrollspy`	Dieses Ereignis wird auf dem Scroll-Element ausgelöst, wenn ein Anker vom Scrollspy aktiviert wird.

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