Scrollspy

Αυτόματη ενημέρωση της πλοήγησης Bootstrap ή των στοιχείων ομάδας λίστας με βάση τη θέση κύλισης για να υποδείξει ποιος σύνδεσμος είναι ενεργός αυτήν τη στιγμή στη θύρα προβολής.

Σε αυτήν την σελίδα

Πως δουλεύει

Το Scrollspy εναλλάσσει την .activeκλάση στα <a>στοιχεία αγκύρωσης ( ) όταν το στοιχείο στο οποίο idαναφέρονται τα στοιχεία αγκύρωσης hrefμετακινείται σε προβολή. Το Scrollspy χρησιμοποιείται καλύτερα σε συνδυασμό με ένα στοιχείο πλοήγησης Bootstrap ή μια ομάδα λίστας , αλλά θα λειτουργήσει επίσης με τυχόν στοιχεία αγκύρωσης στην τρέχουσα σελίδα. Ετσι δουλευει.

Για να ξεκινήσετε, το scrollspy απαιτεί δύο πράγματα: μια πλοήγηση, μια ομάδα λίστας ή ένα απλό σύνολο συνδέσμων, συν ένα κοντέινερ με δυνατότητα κύλισης. Το κοντέινερ με δυνατότητα κύλισης μπορεί να είναι το <body>ή ένα προσαρμοσμένο στοιχείο με ένα σύνολο heightκαι overflow-y: scroll.
Στο κοντέινερ με δυνατότητα κύλισης, προσθέστε data-bs-spy="scroll"και data-bs-target="#navId"πού navIdείναι το μοναδικό idτης συσχετισμένης πλοήγησης. Φροντίστε να συμπεριλάβετε επίσης ένα tabindex="0"για να εξασφαλίσετε πρόσβαση στο πληκτρολόγιο.
Καθώς κάνετε κύλιση στο "κατασκοπευμένο" κοντέινερ, .activeπροστίθεται και αφαιρείται μια κλάση από συνδέσμους αγκύρωσης στη σχετική πλοήγηση. Οι σύνδεσμοι πρέπει να έχουν επιλύσιμους idστόχους, διαφορετικά αγνοούνται. Για παράδειγμα, το <a href="#home">home</a>must αντιστοιχεί σε κάτι στο 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 λειτουργεί επίσης με .list-groups. Κάντε κύλιση στην περιοχή δίπλα στην ομάδα λίστας και παρακολουθήστε την αλλαγή της ενεργής τάξης.

Στοιχείο 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>). Στη συνέχεια, προσθέστε το data-bs-targetχαρακτηριστικό με το idόνομα ή την κλάση του γονικού στοιχείου οποιουδήποτε .navστοιχείου 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>

Μέσω JavaScript

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, όλα τα στοιχεία υποστηρίζουν ένα πειραματικό χαρακτηριστικό δεσμευμένων δεδομένων data-bs-configπου μπορεί να φιλοξενήσει απλή διαμόρφωση στοιχείων ως συμβολοσειρά JSON. Όταν ένα στοιχείο έχει 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`	boolean	`false`	Επιτρέπει την ομαλή κύλιση όταν ένας χρήστης κάνει κλικ σε έναν σύνδεσμο που αναφέρεται σε παρατηρήσιμα στοιχεία ScrollSpy.
`target`	συμβολοσειρά, στοιχείο DOM	`null`	Καθορίζει το στοιχείο για την εφαρμογή της προσθήκης Scrollspy.
`threshold`	πίνακας	`[0.1, 0.5, 1]`	`IntersectionObserver` έγκυρη είσοδο κατωφλίου , κατά τον υπολογισμό της θέσης κύλισης.

Επιλογές που έχουν καταργηθεί

Μέχρι την έκδοση 5.1.3 χρησιμοποιούσαμε offset& methodεπιλογές, οι οποίες πλέον έχουν καταργηθεί και αντικαθίστανται από rootMargin. Για να διατηρήσουμε τη συμβατότητα προς τα πίσω, θα συνεχίσουμε να αναλύουμε ένα δεδομένο offsetστο rootMargin, αλλά αυτή η δυνατότητα θα καταργηθεί στην έκδοση 6 .

Μέθοδοι

Μέθοδος	Περιγραφή
`dispose`	Καταστρέφει το scrollspy ενός στοιχείου. (Καταργεί τα αποθηκευμένα δεδομένα στο στοιχείο DOM)
`getInstance`	Στατική μέθοδος για τη λήψη της παρουσίας scrollspy που σχετίζεται με ένα στοιχείο DOM.
`getOrCreateInstance`	Στατική μέθοδος για τη λήψη της παρουσίας scrollspy που σχετίζεται με ένα στοιχείο DOM ή για τη δημιουργία μιας νέας σε περίπτωση που δεν είχε αρχικοποιηθεί.
`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...
})