דלג לתוכן הראשי דלג לניווט במסמכים
Check
in English

Scrollspy

עדכן אוטומטית את רכיבי הניווט של Bootstrap או רשימת קבוצות בהתבסס על מיקום הגלילה כדי לציין איזה קישור פעיל כעת בנקודת התצוגה.

איך זה עובד

Scrollspy מחליפה את .activeהמחלקה על <a>רכיבי עוגן ( ) כאשר האלמנט עם idההתייחסות של העוגן hrefנגלל לתצוגה. Scrollspy עדיף להשתמש בשילוב עם רכיב Bootstrap nav או קבוצת רשימה , אך הוא יעבוד גם עם כל רכיבי עוגן בעמוד הנוכחי. ככה זה עובד.

  • כדי להתחיל, 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>חובה להתאים למשהו כמו ב-DOM<div id="home"></div>

  • תתעלם ממרכיבי יעד שאינם גלויים. עיין בסעיף רכיבים לא גלויים למטה.

דוגמאות

גלול באזור שמתחת לסרגל הניווט וצפה בשינוי הכיתה הפעילה. פתח את התפריט הנפתח וצפה בפריטים הנפתחים מודגשים גם כן.

כותרת ראשונה

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

כותרת שניה

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

כותרת שלישית

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

כותרת רביעית

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

כותרת חמישית

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

<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 מנסה לבחור את האלמנט הנכון מבין כל מה שעשוי להיות גלוי. מספר יעדים גלויים גלויים בו-זמנית עלולים לגרום לבעיות מסוימות.

פריט 1-1

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

זכור שהתוסף של JavaScript מנסה לבחור את האלמנט הנכון מבין כל מה שעשוי להיות גלוי. מספר יעדים גלויים גלויים בו-זמנית עלולים לגרום לבעיות מסוימות.

פריט 1-2

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

זכור שהתוסף של JavaScript מנסה לבחור את האלמנט הנכון מבין כל מה שעשוי להיות גלוי. מספר יעדים גלויים גלויים בו-זמנית עלולים לגרום לבעיות מסוימות.

פריט 2

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

זכור שהתוסף של JavaScript מנסה לבחור את האלמנט הנכון מבין כל מה שעשוי להיות גלוי. מספר יעדים גלויים גלויים בו-זמנית עלולים לגרום לבעיות מסוימות.

פריט 3

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

זכור שהתוסף של JavaScript מנסה לבחור את האלמנט הנכון מבין כל מה שעשוי להיות גלוי. מספר יעדים גלויים גלויים בו-זמנית עלולים לגרום לבעיות מסוימות.

פריט 3-1

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

זכור שהתוסף של JavaScript מנסה לבחור את האלמנט הנכון מבין כל מה שעשוי להיות גלוי. מספר יעדים גלויים גלויים בו-זמנית עלולים לגרום לבעיות מסוימות.

פריט 3-2

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

זכור שהתוסף של JavaScript מנסה לבחור את האלמנט הנכון מבין כל מה שעשוי להיות גלוי. מספר יעדים גלויים גלויים בו-זמנית עלולים לגרום לבעיות מסוימות.

<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

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

<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

זהו חלק מהתוכן של מציין מיקום עבור דף הגלילה. שימו לב שכאשר אתם גוללים למטה בעמוד, קישור הניווט המתאים מודגש. זה חוזר על עצמו בכל דוגמה של הרכיב. אנחנו ממשיכים להוסיף כאן עוד עותק לדוגמה כדי להדגיש את הגלילה וההדגשה.

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

נוֹהָג

באמצעות תכונות נתונים

כדי להוסיף בקלות התנהגות גלילית לניווט בסרגל העליון שלך, הוסף 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% צומת Observer rootMargin יחידות חוקיות, בעת חישוב מיקום הגלילה.
smoothScroll בוליאני false מאפשר גלילה חלקה כאשר משתמש לוחץ על קישור המתייחס ל-ScrollSpy הניתנים לצפייה.
target מחרוזת, רכיב DOM null מציין רכיב להחלת הפלאגין Scrollspy.
threshold מַעֲרָך [0.1, 0.5, 1] IntersectionObserver קלט חוקי לסף , בעת חישוב מיקום הגלילה.

אפשרויות שהוצאו משימוש

עד לגרסה 5.1.3 השתמשנו ב- offset& methodoptions, שכעת הוצאו משימוש ומוחלפים ב- rootMargin. כדי לשמור על תאימות לאחור, נמשיך לנתח נתון offsetל- rootMargin, אך תכונה זו תוסר ב- v6 .

שיטות

שיטה תיאור
dispose הורס את הגלגול של אלמנט. (מסיר נתונים מאוחסנים ברכיב ה-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 אירוע זה יורה על אלמנט הגלילה בכל פעם שעוגן מופעל על ידי הגלילה.
const firstScrollSpyEl = document.querySelector('[data-bs-spy="scroll"]')
firstScrollSpyEl.addEventListener('activate.bs.scrollspy', () => {
  // do something...
})