عرض مصدر Bootstrap/scrollspy

<noinclude>{{DISPLAYTITLE:متتبّع التمرير Scrollspy في إطار العمل Bootstrap}}</noinclude>
حدِّث مكوِّنات التنقّل أو مجموعات القوائم في إطار العمل Bootstrap بناءً على وضعيّة شريط التمرير للإشارة إلى الرابط الموجود حاليًّا في إطار العرض.

== آليّة العمل ==
يتطلّب متتبّع التمرير Scrollspy الأمور التاليّة حتى يعمل على النحو المرغوب:
* ملفّ util.js. انتبه له عند بناء ملفّات JavaScript من المصدر.
* يجب أن يكون مستخدمًا على مكوِّن تنقّل أو مجموعة قوائم.
* يتطلّب شريط التمرير وجود الخاصيّة <code>position: relative;‎</code> على العنصُر الذي تتتبّعه (متن الصفحة <code><body></code> في العادة).
* تأكّد عند تتبّع عناصر أخرى غير <code><body></code> من تعيين ارتفاع العنصُر (<code>height</code> ) وتطبيق الخاصيّة <code>overflow-y: scroll;‎</code>.
* الروابط (<code><a></code>) مطلوبة، ويجب أن تشير إلى العنصُر بمعرِّفه (<code>id</code>).
تُحدَّث عناصر التنقّل ومجموعة القوائم - عند تنفيذ متتبّع التمرير بطريقة صحيحة - تلقائيًّا حسب مرور المحتوى، وسينتقل الصنف من عنصُر إلى آخر في القائمة حسب العناصر المستهدفة المتعلّقة بها.

== مثال على تتبّع شريط تنقّل ==
يوضّح المثال التالي تمييز عناصر شريط التنقّل حسب المحتوى الذي يمرّ عليه الزائر. يتغيّر الزرّ النشط تلقائيًّا ليوافق الجزء المعروض من المحتوى. ينطبق الأمر كذلك على عناصر القائمة المنسدلة.<syntaxhighlight lang="html">
<nav id="navbar-example2" class="navbar navbar-light bg-light">
  <a class="navbar-brand" href="#">Navbar</a>
  <ul class="nav nav-pills">
    <li class="nav-item">
      <a class="nav-link" href="#fat">@fat</a>
    </li>
    <li class="nav-item">
      <a class="nav-link" href="#mdo">@mdo</a>
    </li>
    <li class="nav-item dropdown">
      <a class="nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">Dropdown</a>
      <div class="dropdown-menu">
        <a class="dropdown-item" href="#one">one</a>
        <a class="dropdown-item" href="#two">two</a>
        <div role="separator" class="dropdown-divider"></div>
        <a class="dropdown-item" href="#three">three</a>
      </div>
    </li>
  </ul>
</nav>
<div data-spy="scroll" data-target="#navbar-example2" data-offset="0">
  <h4 id="fat">@fat</h4>
  <p>...</p>
  <h4 id="mdo">@mdo</h4>
  <p>...</p>
  <h4 id="one">one</h4>
  <p>...</p>
  <h4 id="two">two</h4>
  <p>...</p>
  <h4 id="three">three</h4>
  <p>...</p>
</div>
</syntaxhighlight>

== مثال على تتبّع عناصر تنقّل متداخلة ==
يعمل متتبّع التمرير كذلك عند تداخل أصناف <code>‎.nav</code> عدّة.  عندما يكون عنصُر <code>‎.nav</code> نشطًا فإنّ عنصُر <code>‎.nav</code> الأب يظهر نشطًا كذلك.<syntaxhighlight lang="html">
<nav id="navbar-example3" class="navbar navbar-light bg-light">
  <a class="navbar-brand" href="#">Navbar</a>
  <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 ml-3 my-1" href="#item-1-1">Item 1-1</a>
      <a class="nav-link ml-3 my-1" href="#item-1-2">Item 1-2</a>
    </nav>
    <a class="nav-link" href="#item-2">Item2</a>
    <a class="nav-link" href="#item-3">Item3</a>
    <nav class="nav nav-pills flex-column">
      <a class="nav-link ml-3 my-1" href="#item-3-1">Item 3-1</a>
      <a class="nav-link ml-3 my-1" href="#item-3-2">Item 3-2</a>
    </nav>
  </nav>
</nav>

<div data-spy="scroll" data-target="#navbar-example3" data-offset="0">
  <h4 id="item-1">Item 1</h4>
  <p>...</p>
  <h5 id="item-1-1">Item 1-1</h5>
  <p>...</p>
  <h5 id="item-1-2">Item 2-2</h5>
  <p>...</p>
  <h4 id="item-2">Item 2</h4>
  <p>...</p>
  <h4 id="item-3">Item 3</h4>
  <p>...</p>
  <h5 id="item-3-1">Item 3-1</h5>
  <p>...</p>
  <h5 id="item-3-2">Item 3-2</h5>
  <p>...</p>
</div>


</syntaxhighlight>

== مثال مع مجموعة قوائم ==
يعمل متتبّع التمرير على نحو مشابه على مجموعات القوائم ( <code>‎.list-group</code>).<syntaxhighlight lang="html">
<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">Item2</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 data-spy="scroll" data-target="#list-example" data-offset="0" class="scrollspy-example">
  <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>
</syntaxhighlight>

== استخدام مُلحَق JavaScript ==

=== باستخدام خاصيّات البيانات ===
أضف الخاصيّة <code>data-spy="scroll"‎</code>  إلى العنصُر الذي تريد تتبّعه (عادةً <code><body></code>) في شريط التنقّل العلويّ ثم الخاصيّة <code>data-target</code> مع تحديد قيمتها بمعرِّف - أو صنف - العنصُر الأب لأي مكوِّن <code>‎.nav</code> في Bootstrap.<syntaxhighlight lang="css">
body {
  position: relative;
}
</syntaxhighlight><syntaxhighlight lang="html">
<body data-spy="scroll" data-target="#navbar-example">
  ...
  <div id="navbar-example">
    <ul class="nav nav-tabs" role="tablist">
      ...
    </ul>
  </div>
  ...
</body>


</syntaxhighlight>

=== كتابة شفرة JavaScript مُخصَّصة ===
استدع متتبّع التمرير - بعد إضافة الخاصيّة <code>position: relative;‎</code> إلى العنصُر قيد التتبّع - بشفرة JavaScript على النحو التالي:<syntaxhighlight lang="javascript">
$('body').scrollspy({ target: '#navbar-example' })
</syntaxhighlight>'''تنبيه:''' يجب أن تتضمَّن روابط شريط التنقّل معرِّفات موجودة فعلا. على سبيل المثال، إذا كان يوجد الرابط <code>‎<a href="#home">‎‎‎الرئيسيّة‎</a>‎‎</code> في شريط التنقل فيجب أن يوجد عنصُر لديه المعرِّف <code>home</code> في كائن المستنَد (مثلًا <code><nowiki><div id="home"></div></nowiki></code>).

'''ملحوظة:''' تُتجاهل العناصر المستهدَفة [https://api.jquery.com/visible-selector/ غير المرئيّة لمحدِّد <code>‎:visible</code> في  jQuery]، ولا تُميَّز عناصر التنقّل المتعلّقة بها في شريط التنقّل.

=== التوابع ===

==== <code>‎.scrollspy('refresh')</code> ====
يجب استدعاء التابع <code>‎.scrollspy('refresh')</code> عند استخدام متبّع التمرير بالتزامن مع إضافة العناصر وحذفها من كائن المستنَد DOM، وذلك على النحو التالي:<syntaxhighlight lang="javascript">
$('[data-spy="scroll"]').each(function () {
  var $spy = $(this).scrollspy('refresh')
})
</syntaxhighlight>

==== <code>.scrollspy('dispose')</code> ====
يحذف متتبّع التمرير من العنصُر.

=== الخيّارات ===
يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق JavaScript. ألحق اسم الخيّار بالكلمة <code>data-‎</code> (مثلًا <code>data-offset=""‎</code> للخيّار <code>offset</code>) عند التمرير عبر خاصيّات البيانات.
{| class="wikitable"
|الاسم
|النوع
|القيمة المبدئيّة
|الوصف
|-
|offset (الإزاحة)
|عدد
|10
|عدد بكسلات الإزاحة من الأعلى عند حساب موضع التمرير.
|}

=== الأحداث ===
{| class="wikitable"
!نوع الحدث
!الوصف
|-
|<code>activate.bs.scrollspy</code>
|ينطلق هذا الحدث من العنصُر المُتتبَّع ي كلّ مرة ينشِّط فيها متتبّع التمرير عنصُرًا جديدًا في شريط التنقّل.
|}
<syntaxhighlight lang="javascript">
$('[data-spy="scroll"]').on('activate.bs.scrollspy', function () {
  // افعل شيئًا هنا …
})
</syntaxhighlight>

== مصادر ==
* [https://getbootstrap.com/docs/4.0/components/scrollspy/ صفحة Scrollspy في توثيق Bootstrap].