رفتن به محتوای اصلی به پیمایش اسناد بروید
Check
in English

Scrollspy

به طور خودکار ناوبری بوت استرپ یا اجزای گروه لیست را بر اساس موقعیت اسکرول به روز کنید تا مشخص کنید کدام پیوند در حال حاضر در نمای نمایش فعال است.

چگونه کار می کند

Scrollspy .activeکلاس را روی <a>عناصر لنگر ( ) تغییر می دهد زمانی که عنصری که idتوسط انکر ارجاع داده شده hrefاست به نمای پیمایش می شود. Scrollspy بهتر است همراه با یک مؤلفه ناوبری بوت استرپ یا گروه لیست استفاده شود ، اما با هر عنصر لنگر در صفحه فعلی نیز کار می کند. در اینجا نحوه عملکرد آن آمده است.

  • برای شروع، Scrollspy به دو چیز نیاز دارد: یک ناوبری، گروه لیست، یا مجموعه ای ساده از پیوندها، به علاوه یک ظرف قابل پیمایش. ظرف قابل پیمایش می تواند <body>یک عنصر سفارشی یا یک مجموعه با مجموعه heightو overflow-y: scroll.

  • در ظرف قابل پیمایش، ویژگی منحصربه‌فرد پیمایش مرتبط را data-bs-spy="scroll"اضافه کنید. برای اطمینان از دسترسی به صفحه کلید ، حتماً یک علامت را نیز وارد کنید.data-bs-target="#navId"navIdidtabindex="0"

  • با اسکرول کردن کانتینر "جاسوسی"، یک .activeکلاس از پیوندهای لنگر در ناوبری مرتبط اضافه و حذف می شود. پیوندها باید دارای idاهداف قابل حل باشند، در غیر این صورت نادیده گرفته می شوند. به عنوان مثال، یک <a href="#home">home</a>must با چیزی در DOM مانند مطابقت دارد<div id="home"></div>

  • عناصر هدف که قابل مشاهده نیستند نادیده گرفته می شوند. بخش عناصر غیر قابل مشاهده را در زیر ببینید.

مثال ها

ناحیه زیر نوار ناوبری را اسکرول کنید و تغییر کلاس فعال را تماشا کنید. منوی کشویی را باز کنید و ببینید که آیتم های کشویی نیز برجسته می شوند.

عنوان اول

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

عنوان دوم

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

عنوان سوم

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

عنوان چهارم

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

عنوان پنجم

این برخی از محتوای نگهدارنده مکان برای صفحه 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

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

به خاطر داشته باشید که افزونه جاوا اسکریپت سعی می کند عنصر مناسب را از بین همه مواردی که ممکن است قابل مشاهده باشد انتخاب کند. چندین هدف پیمایش قابل مشاهده به طور همزمان ممکن است باعث ایجاد برخی مشکلات شود.

مورد 1-1

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

به خاطر داشته باشید که افزونه جاوا اسکریپت سعی می کند عنصر مناسب را از بین همه مواردی که ممکن است قابل مشاهده باشد انتخاب کند. چندین هدف پیمایش قابل مشاهده به طور همزمان ممکن است باعث ایجاد برخی مشکلات شود.

مورد 1-2

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

به خاطر داشته باشید که افزونه جاوا اسکریپت سعی می کند عنصر مناسب را از بین همه مواردی که ممکن است قابل مشاهده باشد انتخاب کند. چندین هدف پیمایش قابل مشاهده به طور همزمان ممکن است باعث ایجاد برخی مشکلات شود.

مورد 2

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

به خاطر داشته باشید که افزونه جاوا اسکریپت سعی می کند عنصر مناسب را از بین همه مواردی که ممکن است قابل مشاهده باشد انتخاب کند. چندین هدف پیمایش قابل مشاهده به طور همزمان ممکن است باعث ایجاد برخی مشکلات شود.

مورد 3

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

به خاطر داشته باشید که افزونه جاوا اسکریپت سعی می کند عنصر مناسب را از بین همه مواردی که ممکن است قابل مشاهده باشد انتخاب کند. چندین هدف پیمایش قابل مشاهده به طور همزمان ممکن است باعث ایجاد برخی مشکلات شود.

مورد 3-1

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

به خاطر داشته باشید که افزونه جاوا اسکریپت سعی می کند عنصر مناسب را از بین همه مواردی که ممکن است قابل مشاهده باشد انتخاب کند. چندین هدف پیمایش قابل مشاهده به طور همزمان ممکن است باعث ایجاد برخی مشکلات شود.

مورد 3-2

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

به خاطر داشته باشید که افزونه جاوا اسکریپت سعی می کند عنصر مناسب را از بین همه مواردی که ممکن است قابل مشاهده باشد انتخاب کند. چندین هدف پیمایش قابل مشاهده به طور همزمان ممکن است باعث ایجاد برخی مشکلات شود.

<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

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

مورد 2

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

مورد 3

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

مورد 4

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

<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

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

مورد 2

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

مورد 3

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

مورد 4

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

مورد 5

این برخی از محتوای نگهدارنده مکان برای صفحه scrollspy است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجسته‌سازی، چند نسخه نمونه دیگر را در اینجا اضافه می‌کنیم.

<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جزء بوت استرپ اضافه کنید.

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

گزینه ها

از آنجایی که گزینه‌ها می‌توانند از طریق ویژگی‌های داده یا جاوا اسکریپت ارسال شوند، می‌توانید یک نام گزینه را 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 بولی 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، باید روش refresh را فراخوانی کنید.

در اینجا یک مثال با استفاده از روش refresh آورده شده است:

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