الفرق بين المراجعتين ل"Bootstrap/scrollspy"
(مراجعتان متوسطتان بواسطة مستخدم واحد آخر غير معروضتين) | |||
سطر 3: | سطر 3: | ||
== آليّة العمل == | == آليّة العمل == | ||
− | يتطلّب متتبّع التمرير | + | يتطلّب متتبّع التمرير (scrollspy) الأمور التاليّة حتى يعمل على النحو المرغوب: |
− | * ملفّ util.js. انتبه له عند بناء ملفّات JavaScript من المصدر. | + | * [[Bootstrap/javascript#Util|ملفّ util.js]]. انتبه له عند بناء ملفّات JavaScript من المصدر. |
* يجب أن يكون مستخدمًا على مكوِّن تنقّل أو مجموعة قوائم. | * يجب أن يكون مستخدمًا على مكوِّن تنقّل أو مجموعة قوائم. | ||
− | * يتطلّب شريط التمرير وجود الخاصيّة <code>position: relative;</code> على العنصُر الذي تتتبّعه (متن الصفحة <code><body></code> في العادة). | + | * يتطلّب شريط التمرير وجود الخاصيّة <code>position: relative;</code> على العنصُر الذي تتتبّعه (متن الصفحة <code>[[HTML/body|<body>]]</code> في العادة). |
− | * تأكّد عند تتبّع عناصر أخرى غير <code><body></code> من تعيين ارتفاع العنصُر (<code>height</code> ) وتطبيق الخاصيّة <code>overflow-y: scroll;</code>. | + | * تأكّد عند تتبّع عناصر أخرى غير <code>[[HTML/body|<body>]]</code> من تعيين ارتفاع العنصُر (<code>[[CSS/height|height]]</code>) وتطبيق الخاصيّة <code>[[CSS/overflow-y|overflow-y]]: scroll;</code>. |
− | * الروابط (<code | + | * الروابط (<code></code>) مطلوبة، ويجب أن تشير إلى العنصُر بمعرِّفه (<code>id</code>). |
تُحدَّث عناصر التنقّل ومجموعة القوائم - عند تنفيذ متتبّع التمرير بطريقة صحيحة - تلقائيًّا حسب مرور المحتوى، وسينتقل الصنف من عنصُر إلى آخر في القائمة حسب العناصر المستهدفة المتعلّقة بها. | تُحدَّث عناصر التنقّل ومجموعة القوائم - عند تنفيذ متتبّع التمرير بطريقة صحيحة - تلقائيًّا حسب مرور المحتوى، وسينتقل الصنف من عنصُر إلى آخر في القائمة حسب العناصر المستهدفة المتعلّقة بها. | ||
سطر 14: | سطر 14: | ||
يوضّح المثال التالي تمييز عناصر شريط التنقّل حسب المحتوى الذي يمرّ عليه الزائر. يتغيّر الزرّ النشط تلقائيًّا ليوافق الجزء المعروض من المحتوى. ينطبق الأمر كذلك على عناصر القائمة المنسدلة.<syntaxhighlight lang="html"> | يوضّح المثال التالي تمييز عناصر شريط التنقّل حسب المحتوى الذي يمرّ عليه الزائر. يتغيّر الزرّ النشط تلقائيًّا ليوافق الجزء المعروض من المحتوى. ينطبق الأمر كذلك على عناصر القائمة المنسدلة.<syntaxhighlight lang="html"> | ||
<nav id="navbar-example2" class="navbar navbar-light bg-light"> | <nav id="navbar-example2" class="navbar navbar-light bg-light"> | ||
− | <a class="navbar-brand" href="#"> | + | <a class="navbar-brand" href="#">شريط التصفح</a> |
<ul class="nav nav-pills"> | <ul class="nav nav-pills"> | ||
<li class="nav-item"> | <li class="nav-item"> | ||
سطر 25: | سطر 25: | ||
<a class="nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">Dropdown</a> | <a class="nav-link dropdown-toggle" data-toggle="dropdown" href="#" role="button" aria-haspopup="true" aria-expanded="false">Dropdown</a> | ||
<div class="dropdown-menu"> | <div class="dropdown-menu"> | ||
− | <a class="dropdown-item" href="#one"> | + | <a class="dropdown-item" href="#one">واحد</a> |
− | <a class="dropdown-item" href="#two"> | + | <a class="dropdown-item" href="#two">اثنان</a> |
<div role="separator" class="dropdown-divider"></div> | <div role="separator" class="dropdown-divider"></div> | ||
− | <a class="dropdown-item" href="#three"> | + | <a class="dropdown-item" href="#three">ثلاثة</a> |
</div> | </div> | ||
</li> | </li> | ||
سطر 38: | سطر 38: | ||
<h4 id="mdo">@mdo</h4> | <h4 id="mdo">@mdo</h4> | ||
<p>...</p> | <p>...</p> | ||
− | <h4 id="one"> | + | <h4 id="one">واحد</h4> |
<p>...</p> | <p>...</p> | ||
− | <h4 id="two"> | + | <h4 id="two">اثنان</h4> |
<p>...</p> | <p>...</p> | ||
− | <h4 id="three"> | + | <h4 id="three">ثلاثة</h4> |
<p>...</p> | <p>...</p> | ||
</div> | </div> | ||
سطر 57: | سطر 57: | ||
<a class="nav-link ml-3 my-1" href="#item-1-2">Item 1-2</a> | <a class="nav-link ml-3 my-1" href="#item-1-2">Item 1-2</a> | ||
</nav> | </nav> | ||
− | <a class="nav-link" href="#item-2"> | + | <a class="nav-link" href="#item-2">Item 2</a> |
− | <a class="nav-link" href="#item-3"> | + | <a class="nav-link" href="#item-3">Item 3</a> |
<nav class="nav nav-pills flex-column"> | <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-1">Item 3-1</a> | ||
سطر 71: | سطر 71: | ||
<h5 id="item-1-1">Item 1-1</h5> | <h5 id="item-1-1">Item 1-1</h5> | ||
<p>...</p> | <p>...</p> | ||
− | <h5 id="item-1-2">Item | + | <h5 id="item-1-2">Item 1-2</h5> |
<p>...</p> | <p>...</p> | ||
<h4 id="item-2">Item 2</h4> | <h4 id="item-2">Item 2</h4> | ||
سطر 82: | سطر 82: | ||
<p>...</p> | <p>...</p> | ||
</div> | </div> | ||
− | |||
− | |||
</syntaxhighlight> | </syntaxhighlight> | ||
سطر 90: | سطر 88: | ||
<div id="list-example" class="list-group"> | <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-1">Item 1</a> | ||
− | <a class="list-group-item list-group-item-action" href="#list-item-2"> | + | <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-3">Item 3</a> | ||
<a class="list-group-item list-group-item-action" href="#list-item-4">Item 4</a> | <a class="list-group-item list-group-item-action" href="#list-item-4">Item 4</a> | ||
سطر 109: | سطر 107: | ||
=== باستخدام خاصيّات البيانات === | === باستخدام خاصيّات البيانات === | ||
− | أضف الخاصيّة <code>data-spy="scroll"</code> إلى العنصُر الذي تريد تتبّعه (عادةً <code><body></code>) في شريط التنقّل العلويّ ثم الخاصيّة <code>data-target</code> مع تحديد قيمتها بمعرِّف - أو صنف - العنصُر الأب لأي مكوِّن <code>.nav</code> في Bootstrap.<syntaxhighlight lang="css"> | + | أضف الخاصيّة <code>data-spy="scroll"</code> إلى العنصُر الذي تريد تتبّعه (عادةً <code>[[HTML/body|<body>]]</code>) في شريط التنقّل العلويّ ثم الخاصيّة <code>data-target</code> مع تحديد قيمتها بمعرِّف - أو صنف - العنصُر الأب لأي مكوِّن <code>.nav</code> في Bootstrap.<syntaxhighlight lang="css"> |
body { | body { | ||
position: relative; | position: relative; | ||
سطر 127: | سطر 125: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | === كتابة شفرة JavaScript | + | === كتابة شفرة JavaScript مخصصة === |
استدع متتبّع التمرير - بعد إضافة الخاصيّة <code>position: relative;</code> إلى العنصُر قيد التتبّع - بشفرة JavaScript على النحو التالي:<syntaxhighlight lang="javascript"> | استدع متتبّع التمرير - بعد إضافة الخاصيّة <code>position: relative;</code> إلى العنصُر قيد التتبّع - بشفرة JavaScript على النحو التالي:<syntaxhighlight lang="javascript"> | ||
$('body').scrollspy({ target: '#navbar-example' }) | $('body').scrollspy({ target: '#navbar-example' }) | ||
− | </syntaxhighlight>'''تنبيه:''' يجب أن تتضمَّن روابط شريط التنقّل معرِّفات موجودة فعلا. على سبيل المثال، إذا كان يوجد الرابط <code> | + | </syntaxhighlight>'''تنبيه:''' يجب أن تتضمَّن روابط شريط التنقّل معرِّفات موجودة فعلا. على سبيل المثال، إذا كان يوجد الرابط <code><a href="#home">home</a></code> في شريط التنقل فيجب أن يوجد عنصُر لديه المعرِّف <code>home</code> في كائن المستنَد (مثلًا <code><nowiki><div id="home"></div></nowiki></code>). |
'''ملحوظة:''' تُتجاهل العناصر المستهدَفة [https://api.jquery.com/visible-selector/ غير المرئيّة لمحدِّد <code>:visible</code> في jQuery]، ولا تُميَّز عناصر التنقّل المتعلّقة بها في شريط التنقّل. | '''ملحوظة:''' تُتجاهل العناصر المستهدَفة [https://api.jquery.com/visible-selector/ غير المرئيّة لمحدِّد <code>:visible</code> في jQuery]، ولا تُميَّز عناصر التنقّل المتعلّقة بها في شريط التنقّل. | ||
سطر 136: | سطر 134: | ||
=== التوابع === | === التوابع === | ||
− | ==== <code>.scrollspy('refresh')</code> ==== | + | ==== <code>.scrollspy('refresh')</code> ==== |
− | يجب استدعاء التابع <code>.scrollspy('refresh')</code> عند استخدام متبّع التمرير بالتزامن مع إضافة العناصر وحذفها من كائن المستنَد DOM، وذلك على النحو التالي:<syntaxhighlight lang="javascript"> | + | يجب استدعاء التابع <code>.scrollspy('refresh')</code> عند استخدام متبّع التمرير بالتزامن مع إضافة العناصر وحذفها من كائن المستنَد DOM، وذلك على النحو التالي:<syntaxhighlight lang="javascript"> |
$('[data-spy="scroll"]').each(function () { | $('[data-spy="scroll"]').each(function () { | ||
var $spy = $(this).scrollspy('refresh') | var $spy = $(this).scrollspy('refresh') | ||
سطر 143: | سطر 141: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
− | ==== <code>.scrollspy('dispose')</code> ==== | + | ==== <code>.scrollspy('dispose')</code> ==== |
يحذف متتبّع التمرير من العنصُر. | يحذف متتبّع التمرير من العنصُر. | ||
− | === | + | === الخيارات === |
يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق JavaScript. ألحق اسم الخيّار بالكلمة <code>data-</code> (مثلًا <code>data-offset=""</code> للخيّار <code>offset</code>) عند التمرير عبر خاصيّات البيانات. | يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق JavaScript. ألحق اسم الخيّار بالكلمة <code>data-</code> (مثلًا <code>data-offset=""</code> للخيّار <code>offset</code>) عند التمرير عبر خاصيّات البيانات. | ||
{| class="wikitable" | {| class="wikitable" | ||
− | + | !الاسم | |
− | + | !النوع | |
− | + | !القيمة المبدئيّة | |
− | + | !الوصف | |
|- | |- | ||
− | |offset (الإزاحة) | + | |<code>offset</code> (الإزاحة) |
|عدد | |عدد | ||
− | |10 | + | |<code>10</code> |
|عدد بكسلات الإزاحة من الأعلى عند حساب موضع التمرير. | |عدد بكسلات الإزاحة من الأعلى عند حساب موضع التمرير. | ||
+ | |- | ||
+ | |<code>method</code> | ||
+ | |سلسلة نصية | ||
+ | |<code>auto</code> | ||
+ | |تبحث عن الفقرة التي يوجد العنصر فيها. تختار القيمة <code>auto</code> أفضل طريقة للحصول على إحداثيات التمرير. فيما تستخدم <code>offset</code> تابع الإزاحة <code>offset</code> الخاص بـ jQuery للحصول على تلك الإحداثيات. تستخدم <code>position</code> تابع الموضع position الخاص بـ jQuery للحصول على إحداثيات التمرير. | ||
+ | |- | ||
+ | |<code>target</code> | ||
+ | |<nowiki>سلسلة نصية | كائن jQuery | عنصر DOM</nowiki> | ||
+ | |<code>10</code> | ||
+ | |تعيين العنصر الذي سيُطبق عليه الملحق Scrollspy. | ||
|} | |} | ||
سطر 175: | سطر 183: | ||
== مصادر == | == مصادر == | ||
− | * [https://getbootstrap.com/docs/4. | + | * [https://getbootstrap.com/docs/4.5/components/scrollspy/ صفحة Scrollspy في توثيق Bootstrap]. |
− | [[تصنيف:Bootstrap]] | + | [[تصنيف:Bootstrap|{{SUBPAGENAME}}]] |
− | [[تصنيف:Bootstrap components]] | + | [[تصنيف:Bootstrap components|{{SUBPAGENAME}}]] |
المراجعة الحالية بتاريخ 08:49، 13 يوليو 2020
حدِّث مكوِّنات التنقّل أو مجموعات القوائم في إطار العمل Bootstrap بناءً على وضعيّة شريط التمرير للإشارة إلى الرابط الموجود حاليًّا في إطار العرض.
آليّة العمل
يتطلّب متتبّع التمرير (scrollspy) الأمور التاليّة حتى يعمل على النحو المرغوب:
- ملفّ util.js. انتبه له عند بناء ملفّات JavaScript من المصدر.
- يجب أن يكون مستخدمًا على مكوِّن تنقّل أو مجموعة قوائم.
- يتطلّب شريط التمرير وجود الخاصيّة
position: relative;
على العنصُر الذي تتتبّعه (متن الصفحة<body>
في العادة). - تأكّد عند تتبّع عناصر أخرى غير
<body>
من تعيين ارتفاع العنصُر (height
) وتطبيق الخاصيّةoverflow-y: scroll;
. - الروابط (
) مطلوبة، ويجب أن تشير إلى العنصُر بمعرِّفه (
id
).
تُحدَّث عناصر التنقّل ومجموعة القوائم - عند تنفيذ متتبّع التمرير بطريقة صحيحة - تلقائيًّا حسب مرور المحتوى، وسينتقل الصنف من عنصُر إلى آخر في القائمة حسب العناصر المستهدفة المتعلّقة بها.
مثال على تتبّع شريط تنقّل
يوضّح المثال التالي تمييز عناصر شريط التنقّل حسب المحتوى الذي يمرّ عليه الزائر. يتغيّر الزرّ النشط تلقائيًّا ليوافق الجزء المعروض من المحتوى. ينطبق الأمر كذلك على عناصر القائمة المنسدلة.
<nav id="navbar-example2" class="navbar navbar-light bg-light">
<a class="navbar-brand" href="#">شريط التصفح</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">واحد</a>
<a class="dropdown-item" href="#two">اثنان</a>
<div role="separator" class="dropdown-divider"></div>
<a class="dropdown-item" href="#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">واحد</h4>
<p>...</p>
<h4 id="two">اثنان</h4>
<p>...</p>
<h4 id="three">ثلاثة</h4>
<p>...</p>
</div>
مثال على تتبّع عناصر تنقّل متداخلة
يعمل متتبّع التمرير كذلك عند تداخل أصناف .nav
عدّة. عندما يكون عنصُر .nav
نشطًا فإنّ عنصُر .nav
الأب يظهر نشطًا كذلك.
<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">Item 2</a>
<a class="nav-link" href="#item-3">Item 3</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 1-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>
مثال مع مجموعة قوائم
يعمل متتبّع التمرير على نحو مشابه على مجموعات القوائم ( .list-group
).
<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 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>
استخدام مُلحَق JavaScript
باستخدام خاصيّات البيانات
أضف الخاصيّة data-spy="scroll"
إلى العنصُر الذي تريد تتبّعه (عادةً <body>
) في شريط التنقّل العلويّ ثم الخاصيّة data-target
مع تحديد قيمتها بمعرِّف - أو صنف - العنصُر الأب لأي مكوِّن .nav
في Bootstrap.
body {
position: relative;
}
<body data-spy="scroll" data-target="#navbar-example">
...
<div id="navbar-example">
<ul class="nav nav-tabs" role="tablist">
...
</ul>
</div>
...
</body>
كتابة شفرة JavaScript مخصصة
استدع متتبّع التمرير - بعد إضافة الخاصيّة position: relative;
إلى العنصُر قيد التتبّع - بشفرة JavaScript على النحو التالي:
$('body').scrollspy({ target: '#navbar-example' })
تنبيه: يجب أن تتضمَّن روابط شريط التنقّل معرِّفات موجودة فعلا. على سبيل المثال، إذا كان يوجد الرابط <a href="#home">home</a>
في شريط التنقل فيجب أن يوجد عنصُر لديه المعرِّف home
في كائن المستنَد (مثلًا <div id="home"></div>
).
ملحوظة: تُتجاهل العناصر المستهدَفة غير المرئيّة لمحدِّد :visible
في jQuery، ولا تُميَّز عناصر التنقّل المتعلّقة بها في شريط التنقّل.
التوابع
.scrollspy('refresh')
يجب استدعاء التابع .scrollspy('refresh')
عند استخدام متبّع التمرير بالتزامن مع إضافة العناصر وحذفها من كائن المستنَد DOM، وذلك على النحو التالي:
$('[data-spy="scroll"]').each(function () {
var $spy = $(this).scrollspy('refresh')
})
.scrollspy('dispose')
يحذف متتبّع التمرير من العنصُر.
الخيارات
يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق JavaScript. ألحق اسم الخيّار بالكلمة data-
(مثلًا data-offset=""
للخيّار offset
) عند التمرير عبر خاصيّات البيانات.
الاسم | النوع | القيمة المبدئيّة | الوصف |
---|---|---|---|
offset (الإزاحة)
|
عدد | 10
|
عدد بكسلات الإزاحة من الأعلى عند حساب موضع التمرير. |
method
|
سلسلة نصية | auto
|
تبحث عن الفقرة التي يوجد العنصر فيها. تختار القيمة auto أفضل طريقة للحصول على إحداثيات التمرير. فيما تستخدم offset تابع الإزاحة offset الخاص بـ jQuery للحصول على تلك الإحداثيات. تستخدم position تابع الموضع position الخاص بـ jQuery للحصول على إحداثيات التمرير.
|
target
|
سلسلة نصية | كائن jQuery | عنصر DOM | 10
|
تعيين العنصر الذي سيُطبق عليه الملحق Scrollspy. |
الأحداث
نوع الحدث | الوصف |
---|---|
activate.bs.scrollspy
|
ينطلق هذا الحدث من العنصُر المُتتبَّع ي كلّ مرة ينشِّط فيها متتبّع التمرير عنصُرًا جديدًا في شريط التنقّل. |
$('[data-spy="scroll"]').on('activate.bs.scrollspy', function () {
// افعل شيئًا هنا …
})