Scrollspy

Mettez automatiquement à jour la navigation Bootstrap ou répertoriez les composants de groupe en fonction de la position de défilement pour indiquer quel lien est actuellement actif dans la fenêtre d'affichage.

Sur cette page

Comment ça fonctionne

Scrollspy bascule la .activeclasse sur les <a>éléments d'ancrage ( ) lorsque l'élément idréférencé par l'ancre hrefdéfile dans la vue. Scrollspy est mieux utilisé en conjonction avec un composant de navigation Bootstrap ou un groupe de liste , mais il fonctionnera également avec tous les éléments d'ancrage de la page actuelle. Voici comment ça fonctionne.

Pour commencer, scrollspy nécessite deux choses : une navigation, un groupe de listes ou un simple ensemble de liens, plus un conteneur déroulant. Le conteneur déroulant peut être le <body>ou un élément personnalisé avec un ensemble heightet overflow-y: scroll.
Sur le conteneur déroulant, ajoutez data-bs-spy="scroll"et data-bs-target="#navId"où navIdest l'unique idde la navigation associée. Assurez-vous d'inclure également un tabindex="0"pour garantir l'accès au clavier.
Lorsque vous faites défiler le conteneur "espionné", une .activeclasse est ajoutée et supprimée des liens d'ancrage dans la navigation associée. Les liens doivent avoir des idcibles résolubles, sinon ils sont ignorés. Par exemple, un <a href="#home">home</a>must correspond à quelque chose dans le DOM comme<div id="home"></div>
Les éléments cibles qui ne sont pas visibles seront ignorés. Voir la section Éléments non visibles ci-dessous.

Exemples

Faites défiler la zone sous la barre de navigation et regardez la classe active changer. Ouvrez le menu déroulant et regardez les éléments déroulants être également mis en surbrillance.

Premier titre

Il s'agit d'un contenu d'espace réservé pour la page scrollspy. Notez que lorsque vous faites défiler la page, le lien de navigation approprié est mis en surbrillance. Il est répété tout au long de l'exemple de composant. Nous continuons à ajouter d'autres exemples de copie ici pour souligner le défilement et la mise en surbrillance.

Deuxième rubrique

Troisième rubrique

Quatrième rubrique

Cinquième titre

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

Navigation imbriquée

Scrollspy fonctionne également avec les .navs imbriqués. Si un imbriqué .navest .active, ses parents le seront également .active. Faites défiler la zone à côté de la barre de navigation et regardez la classe active changer.

Objet 1

Gardez à l'esprit que le plugin JavaScript essaie de choisir le bon élément parmi tous ceux qui peuvent être visibles. Plusieurs cibles scrollspy visibles en même temps peuvent causer des problèmes.

Point 1-1

Article 1-2

Point 2

Point 3

Article 3-1

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

Groupe de liste

Scrollspy fonctionne également avec .list-groups. Faites défiler la zone à côté du groupe de la liste et regardez la classe active changer.

Objet 1 Point 2 Point 3 Point 4

Objet 1

Point 2

Point 3

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

Ancrages simples

Scrollspy n'est pas limité aux composants de navigation et aux groupes de listes, il fonctionnera donc sur tous les <a>éléments d'ancrage du document actuel. Faites défiler la zone et regardez le .activechangement de classe.

Objet 1 Point 2 Point 3 Point 4 Point 5

Objet 1

Point 2

Point 3

Point 4

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

Éléments non visibles

Les éléments cibles qui ne sont pas visibles seront ignorés et leurs éléments de navigation correspondants ne recevront pas de .activeclasse. Les instances Scrollspy initialisées dans un wrapper non visible ignoreront tous les éléments cibles. Utilisez la refreshméthode pour vérifier les éléments observables une fois que le wrapper devient visible.

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

Usage

Via les attributs de données

Pour ajouter facilement un comportement scrollspy à votre navigation dans la barre supérieure, ajoutez data-bs-spy="scroll"à l'élément que vous souhaitez espionner (le plus souvent, ce serait le <body>). Ajoutez ensuite l' data-bs-targetattribut avec le idnom de classe ou de l'élément parent de tout .navcomposant 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>

Via Javascript

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

Choix

Comme les options peuvent être transmises via des attributs de données ou JavaScript, vous pouvez ajouter un nom d'option à data-bs-, comme dans data-bs-animation="{value}". Assurez-vous de changer le type de casse du nom de l'option de " camelCase " à " kebab-case " lors du passage des options via les attributs de données. Par exemple, utilisez à la data-bs-custom-class="beautifier"place de data-bs-customClass="beautifier".

Depuis Bootstrap 5.2.0, tous les composants prennent en charge un attribut de données expérimentaldata-bs-config réservé pouvant héberger une configuration de composant simple sous forme de chaîne JSON. Lorsqu'un élément a des attributs data-bs-config='{"delay":0, "title":123}'et , la valeur finale sera et les attributs de données séparés remplaceront les valeurs données sur . De plus, les attributs de données existants peuvent héberger des valeurs JSON telles que .data-bs-title="456"title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

Nom	Taper	Défaut	La description
`rootMargin`	chaîne de caractères	`0px 0px -25%`	Intersection Observer rootMargin unités valides, lors du calcul de la position de défilement.
`smoothScroll`	booléen	`false`	Permet un défilement fluide lorsqu'un utilisateur clique sur un lien faisant référence aux observables ScrollSpy.
`target`	chaîne, élément DOM	`null`	Spécifie l'élément pour appliquer le plugin Scrollspy.
`threshold`	déployer	`[0.1, 0.5, 1]`	`IntersectionObserver` entrée valide de seuil , lors du calcul de la position de défilement.

Options obsolètes

Jusqu'à la v5.1.3, nous utilisions les options offset& method, qui sont désormais obsolètes et remplacées par rootMargin. Pour conserver la rétrocompatibilité, nous continuerons à analyser un donné offsetà rootMargin, mais cette fonctionnalité sera supprimée dans la v6 .

Méthodes

Méthode	La description
`dispose`	Détruit le scrollspy d'un élément. (Supprime les données stockées sur l'élément DOM)
`getInstance`	Méthode statique pour obtenir l'instance scrollspy associée à un élément DOM.
`getOrCreateInstance`	Méthode statique pour obtenir l'instance scrollspy associée à un élément DOM, ou pour en créer une nouvelle au cas où elle n'aurait pas été initialisée.
`refresh`	Lors de l'ajout ou de la suppression d'éléments dans le DOM, vous devrez appeler la méthode refresh.

Voici un exemple utilisant la méthode refresh :

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

Événements

Événement	La description
`activate.bs.scrollspy`	Cet événement se déclenche sur l'élément de défilement chaque fois qu'une ancre est activée par le scrollspy.

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

Scrollspy

Comment ça fonctionne

Exemples

Barre de navigation

Premier titre

Deuxième rubrique

Troisième rubrique

Quatrième rubrique

Cinquième titre

Navigation imbriquée

Objet 1

Point 1-1

Article 1-2

Point 2

Point 3

Article 3-1

Point 3-2

Groupe de liste

Objet 1

Point 2

Point 3

Point 4

Ancrages simples

Objet 1

Point 2

Point 3

Point 4

Point 5

Éléments non visibles

Usage

Via les attributs de données

Via Javascript

Choix

Méthodes

Événements