تخطي إلى المحتوى الرئيسي انتقل إلى ملاحة المستندات
Check
in English

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المرتبط به. تأكد أيضًا من تضمين a tabindex="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 أيضًا مع ملفات .navs المتداخلة. إذا كانت متداخلة .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-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فصلًا دراسيًا. ستتجاهل مثيلات التمرير التي تمت تهيئتها في غلاف غير مرئي جميع العناصر المستهدفة. استخدم 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 مثل .title456data-bs-configdata-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& methodoptions ، والتي تم إهمالها الآن واستبدالها بـ 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...
})