Scrollspy
به طور خودکار ناوبری بوت استرپ یا اجزای گروه لیست را بر اساس موقعیت اسکرول به روز کنید تا مشخص کنید کدام پیوند در حال حاضر در نمای نمایش فعال است.
چگونه کار می کند
Scrollspy .active
کلاس را روی <a>
عناصر لنگر ( ) تغییر می دهد زمانی که عنصری که id
توسط انکر ارجاع داده شده href
است به نمای پیمایش می شود. Scrollspy بهتر است همراه با یک مؤلفه ناوبری بوت استرپ یا گروه لیست استفاده شود ، اما با هر عنصر لنگر در صفحه فعلی نیز کار می کند. در اینجا نحوه عملکرد آن آمده است.
-
برای شروع، 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 است. توجه داشته باشید که با اسکرول کردن صفحه به پایین، پیوند ناوبری مناسب برجسته می شود. در سراسر مثال جزء تکرار شده است. برای تأکید بر پیمایش و برجستهسازی، چند نسخه نمونه دیگر را در اینجا اضافه میکنیم.
عنوان دوم
این برخی از محتوای نگهدارنده مکان برای صفحه 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 همچنین با .nav
s های تودرتو کار می کند. اگر تو در تو .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-group
s کار می کند. ناحیه کنار گروه لیست را اسکرول کنید و تغییر کلاس فعال را تماشا کنید.
مورد 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...
})