Scrollspy
قم تلقائيًا بتحديث تنقل Bootstrap أو سرد مكونات المجموعة استنادًا إلى موضع التمرير للإشارة إلى الرابط النشط حاليًا في منفذ العرض.
كيف تعمل
يقوم Scrollspy بتبديل .active
الفئة على عناصر anchor ( <a>
) عندما يتم تمرير العنصر الذي id
تمت الإشارة إليه بواسطة المرساة href
إلى العرض. من الأفضل استخدام Scrollspy مع مكون Bootstrap nav أو مجموعة القوائم ، ولكنه سيعمل أيضًا مع أي عناصر ربط في الصفحة الحالية. وإليك كيف يعمل.
-
للبدء ، يتطلب scrollspy شيئين: التنقل ، أو مجموعة القائمة ، أو مجموعة بسيطة من الروابط ، بالإضافة إلى حاوية قابلة للتمرير. يمكن أن تكون الحاوية القابلة للتمرير
<body>
عبارة عن عنصر مخصص مع مجموعةheight
وoverflow-y: scroll
. -
في الحاوية القابلة للتمرير ، أضف
data-bs-spy="scroll"
وأينdata-bs-target="#navId"
يكون التنقلnavId
الفريدid
المرتبط به. تأكد أيضًا من تضمين atabindex="0"
لضمان الوصول إلى لوحة المفاتيح. -
أثناء التمرير في حاوية "التجسس" ،
.active
تتم إضافة فئة وإزالتها من روابط الارتساء داخل التنقل المرتبط. يجب أن تحتوي الروابط علىid
أهداف قابلة للحل ، وإلا سيتم تجاهلها. على سبيل المثال ،<a href="#home">home</a>
يجب أن يتوافق a مع شيء ما في 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. لاحظ أنه أثناء التمرير لأسفل الصفحة ، يتم تمييز ارتباط التنقل المناسب. يتم تكرارها في المثال المكون. نستمر في إضافة بعض الأمثلة الأخرى هنا للتأكيد على التمرير والتمييز.
ضع في اعتبارك أن مكون JavaScript الإضافي يحاول اختيار العنصر الصحيح من بين كل ما قد يكون مرئيًا. قد تتسبب العديد من أهداف scrollspy المرئية في نفس الوقت في حدوث بعض المشكلات.
البند 1-1
هذا هو بعض محتوى العنصر النائب لصفحة scrollspy. لاحظ أنه أثناء التمرير لأسفل الصفحة ، يتم تمييز ارتباط التنقل المناسب. يتم تكرارها في المثال المكون. نستمر في إضافة بعض الأمثلة الأخرى هنا للتأكيد على التمرير والتمييز.
ضع في اعتبارك أن مكون JavaScript الإضافي يحاول اختيار العنصر الصحيح من بين كل ما قد يكون مرئيًا. قد تتسبب العديد من أهداف scrollspy المرئية في نفس الوقت في حدوث بعض المشكلات.
البند 1-2
هذا هو بعض محتوى العنصر النائب لصفحة scrollspy. لاحظ أنه أثناء التمرير لأسفل الصفحة ، يتم تمييز ارتباط التنقل المناسب. يتم تكرارها في المثال المكون. نستمر في إضافة بعض الأمثلة الأخرى هنا للتأكيد على التمرير والتمييز.
ضع في اعتبارك أن مكون JavaScript الإضافي يحاول اختيار العنصر الصحيح من بين كل ما قد يكون مرئيًا. قد تتسبب العديد من أهداف scrollspy المرئية في نفس الوقت في حدوث بعض المشكلات.
البند 2
هذا هو بعض محتوى العنصر النائب لصفحة scrollspy. لاحظ أنه أثناء التمرير لأسفل الصفحة ، يتم تمييز ارتباط التنقل المناسب. يتم تكرارها في المثال المكون. نستمر في إضافة بعض الأمثلة الأخرى هنا للتأكيد على التمرير والتمييز.
ضع في اعتبارك أن مكون JavaScript الإضافي يحاول اختيار العنصر الصحيح من بين كل ما قد يكون مرئيًا. قد تتسبب العديد من أهداف scrollspy المرئية في نفس الوقت في حدوث بعض المشكلات.
البند 3
هذا هو بعض محتوى العنصر النائب لصفحة scrollspy. لاحظ أنه أثناء التمرير لأسفل الصفحة ، يتم تمييز ارتباط التنقل المناسب. يتم تكرارها في المثال المكون. نستمر في إضافة بعض الأمثلة الأخرى هنا للتأكيد على التمرير والتمييز.
ضع في اعتبارك أن مكون JavaScript الإضافي يحاول اختيار العنصر الصحيح من بين كل ما قد يكون مرئيًا. قد تتسبب العديد من أهداف scrollspy المرئية في نفس الوقت في حدوث بعض المشكلات.
البند 3-1
هذا هو بعض محتوى العنصر النائب لصفحة scrollspy. لاحظ أنه أثناء التمرير لأسفل الصفحة ، يتم تمييز ارتباط التنقل المناسب. يتم تكرارها في المثال المكون. نستمر في إضافة بعض الأمثلة الأخرى هنا للتأكيد على التمرير والتمييز.
ضع في اعتبارك أن مكون JavaScript الإضافي يحاول اختيار العنصر الصحيح من بين كل ما قد يكون مرئيًا. قد تتسبب العديد من أهداف scrollspy المرئية في نفس الوقت في حدوث بعض المشكلات.
البند 3-2
هذا هو بعض محتوى العنصر النائب لصفحة scrollspy. لاحظ أنه أثناء التمرير لأسفل الصفحة ، يتم تمييز ارتباط التنقل المناسب. يتم تكرارها في المثال المكون. نستمر في إضافة بعض الأمثلة الأخرى هنا للتأكيد على التمرير والتمييز.
ضع في اعتبارك أن مكون JavaScript الإضافي يحاول اختيار العنصر الصحيح من بين كل ما قد يكون مرئيًا. قد تتسبب العديد من أهداف 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
فصلًا دراسيًا. ستتجاهل مثيلات التمرير التي تمت تهيئتها في غلاف غير مرئي جميع العناصر المستهدفة. استخدم 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"
النهائية وستتجاوز سمات البيانات المنفصلة القيم المعطاة . بالإضافة إلى ذلك ، يمكن لسمات البيانات الحالية استيعاب قيم JSON مثل .title
456
data-bs-config
data-bs-delay='{"show":0,"hide":150}'
اسم | يكتب | تقصير | وصف |
---|---|---|---|
rootMargin |
سلسلة | 0px 0px -25% |
وحدات Intersection Observer rootMargin صالحة ، عند حساب موضع التمرير. |
smoothScroll |
قيمة منطقية | false |
لتمكين التمرير السلس عند نقر المستخدم على ارتباط يشير إلى عناصر ScrollSpy التي يمكن ملاحظتها. |
target |
سلسلة ، عنصر DOM | null |
يحدد عنصرًا لتطبيق البرنامج المساعد Scrollspy. |
threshold |
مجموعة مصفوفة | [0.1, 0.5, 1] |
IntersectionObserver عتبة الإدخال الصحيح ، عند حساب موضع التمرير. |
خيارات موقوفة
حتى الإصدار 5.1.3 ، كنا نستخدم offset
& method
options ، والتي تم إهمالها الآن واستبدالها بـ rootMargin
. للحفاظ على التوافق مع الإصدارات السابقة ، سنستمر في تحليل المعطى offset
لـ rootMargin
، ولكن ستتم إزالة هذه الميزة في الإصدار السادس .
طُرق
طريقة | وصف |
---|---|
dispose |
يدمر التمرير لعنصر. (يزيل البيانات المخزنة على عنصر DOM) |
getInstance |
طريقة Static للحصول على مثيل 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...
})