عرض مصدر Bootstrap/list group

<noinclude>{{DISPLAYTITLE:مجموعات القوائم List group في إطار العمل Bootstrap}}</noinclude>
مجموعات القوائم هي مكوِّن مرن وفعّال لعرض سلاسل من المحتوى؛ يمكن التعديل عليها وتمديدها لدعم أي نوع من المحتوى داخلها.
== مثال قاعديّ ==
أبسط مثال على استخدام مجموعات القوائم هو قائمة غير مُرتَّبة تحوي عناصر القائمة والأصناف المناسبة. أسِّس على هذه اللوائح بالخيّارات المشروحة أدناه أو باستخدام CSS خاصّ بك حسب الحاجة.
<syntaxhighlight lang="html">
<ul class="list-group">
  <li class="list-group-item">Cras justo odio</li>
  <li class="list-group-item">Dapibus ac facilisis in</li>
  <li class="list-group-item">Morbi leo risus</li>
  <li class="list-group-item">Porta ac consectetur ac</li>
  <li class="list-group-item">Vestibulum at eros</li>
</ul>
</syntaxhighlight>
== العناصر النشطة ==
أضف الصنف <code>‎.active</code> إلى عنصُر في القائمة  (<code>‎.list-group-item</code>) للإشارة إلى أنّ العنصُر نشط.
<syntaxhighlight lang="html">
<ul class="list-group">
  <li class="list-group-item active">Cras justo odio</li>
  <li class="list-group-item">Dapibus ac facilisis in</li>
  <li class="list-group-item">Morbi leo risus</li>
  <li class="list-group-item">Porta ac consectetur ac</li>
  <li class="list-group-item">Vestibulum at eros</li>
</ul>
</syntaxhighlight>
== العناصر المُعطَّلة ==
أضف الصنف <code>‎.disabled</code> إلى عنصُر في القائمة (<code>‎.list-group-item</code>) لجعله ''يظهر'' مُعطّلا. تُرجى ملاحظة أنّ بعض العناصر (الروابط مثلًا) تحتاج لشفرة [[JavaScript]] إضافيّة لتعطيل أحداث النقر عليها تمامًا.
<syntaxhighlight lang="html">
<ul class="list-group">
  <li class="list-group-item disabled">Cras justo odio</li>
  <li class="list-group-item">Dapibus ac facilisis in</li>
  <li class="list-group-item">Morbi leo risus</li>
  <li class="list-group-item">Porta ac consectetur ac</li>
  <li class="list-group-item">Vestibulum at eros</li>
</ul>
</syntaxhighlight>
== الروابط والأزرار ==
طبّق الصنف <code>‎.list-group-item-action</code> على العناصر <code>[[HTML/a|&lt;a>]]</code> أو <code>[[HTML/button|&lt;button>]]</code> لإنشاء عناصر يمكن تنفيذ إجراءات بالنقر عليها ضمن القائمة. تتوفّر عناصر القائمة في عند تطبيق الصنف على حالات الحومان (hover)، والتعطيل والنشاط. يفصل إطار العمل Bootstrap بين الأصناف الزائفة للحالات المذكورة لضمان أنّ أعضاء اللائحة المُنشئين باستخدام عناصر غير تفاعليّة (مثل <code>[[HTML/li|&lt;li>]]</code> و <code>[[HTML/div|&lt;div>]]</code>) لا توفّر قابليّة النقر أو الضغط.

تأكّد من '''عدم استخدام الأصناف المعياريّة <code>‎.btn</code> هنا.'''
<syntaxhighlight lang="html">
<div class="list-group">
  <a href="#" class="list-group-item list-group-item-action active">
    Cras justo odio
  </a>
  <a href="#" class="list-group-item list-group-item-action">Dapibus ac facilisis in</a>
  <a href="#" class="list-group-item list-group-item-action">Morbi leo risus</a>
  <a href="#" class="list-group-item list-group-item-action">Porta ac consectetur ac</a>
  <a href="#" class="list-group-item list-group-item-action disabled">Vestibulum at eros</a>
</div>
</syntaxhighlight>

يمكن بالنسبة للأزرار (<code>[[HTML/button|&lt;button>]]</code>) استخدام الخاصيّة <code>disabled</code> بدلًا من الصنف <code>‎.disabled</code> للأسف لا  تدعم الروابط (<code>[[HTML/a|&lt;a>]]</code>) الخاصيّة <code>disabled</code>.

<syntaxhighlight lang="html">
<div class="list-group">
  <button type="button" class="list-group-item list-group-item-action active">
    Cras justo odio
  </button>
  <button type="button" class="list-group-item list-group-item-action">Dapibus ac facilisis in</button>
  <button type="button" class="list-group-item list-group-item-action">Morbi leo risus</button>
  <button type="button" class="list-group-item list-group-item-action">Porta ac consectetur ac</button>
  <button type="button" class="list-group-item list-group-item-action" disabled>Vestibulum at eros</button>
</div>
</syntaxhighlight>
== تسطيح القائمة ==
أضف الصنف  <code>‎.list-group-flush</code> إلى القائمة لحذف بعضٍ من الحدود والحوافّ المُدوَّرة لجعل عناصر القائمة متراصّة ضمن حاويّة (مثل البطاقات).
<syntaxhighlight lang="html">
<ul class="list-group list-group-flush">
  <li class="list-group-item">Cras justo odio</li>
  <li class="list-group-item">Dapibus ac facilisis in</li>
  <li class="list-group-item">Morbi leo risus</li>
  <li class="list-group-item">Porta ac consectetur ac</li>
  <li class="list-group-item">Vestibulum at eros</li>
</ul>
</syntaxhighlight>
== الأصناف السياقيّة (Contextual classes) ==
استخدم الأصناف السياقيّة لتنسيق عناصر القائمة بخلفيّة ولون يوضّحان حالتها.
<syntaxhighlight lang="html">
<ul class="list-group">
  <li class="list-group-item">عنصُر بدون صنف سيّاقيّ</li>
  <li class="list-group-item list-group-item-primary">عنصُر بصنف سيّاقيّ أوّلي</li>
  <li class="list-group-item list-group-item-secondary">عنصُر بصنف سيّاقيّ ثانويّ</li>
  <li class="list-group-item list-group-item-success">عنصُر بصنف سيّاقيّ للنجاح</li>
  <li class="list-group-item list-group-item-danger">عنصُر بصنف سيّاقيّ للخطر</li>
  <li class="list-group-item list-group-item-warning">عنصُر بصنف سيّاقيّ للتحذير</li>
  <li class="list-group-item list-group-item-info">عنصُر بصنف سيّاقيّ للمعلومات</li>
  <li class="list-group-item list-group-item-light">عنصُر بصنف سيّاقيّ خفيف</li>
  <li class="list-group-item list-group-item-dark">عنصُر بصنف سيّاقيّ غامق</li>
</ul>
</syntaxhighlight>
تعمل الأصناف السياقيّة كذلك مع الصنف <code>‎.list-group-item-action</code>. لاحظ أنّ تأثيرات الحومان غير حاضرة في المثال السابق. يُدعَم كذلك الصنف <code>‎.active</code> الذي يؤدّي تطبيقه إلى الإشارة إلى العنصُر النشط ضمن قائمة بأصناف سياقيّة.
<syntaxhighlight lang="html">
<ul class="list-group">
  <li class="list-group-item list-group-item-action">عنصُر بدون صنف سيّاقيّ</li>
  <li class="list-group-item list-group-item-action list-group-item-primary">عنصُر بصنف سيّاقيّ أوّلي</li>
  <li class="list-group-item list-group-item-action list-group-item-secondary">عنصُر بصنف سيّاقيّ ثانويّ</li>
  <li class="list-group-item list-group-item-action list-group-item-success">عنصُر بصنف سيّاقيّ للنجاح</li>
  <li class="list-group-item list-group-item-action list-group-item-danger">عنصُر بصنف سيّاقيّ للخطر</li>
  <li class="list-group-item list-group-item-action list-group-item-warning">عنصُر بصنف سيّاقيّ للتحذير</li>
  <li class="list-group-item list-group-item-action list-group-item-info">عنصُر بصنف سيّاقيّ للمعلومات</li>
  <li class="list-group-item list-group-item-action list-group-item-light">عنصُر بصنف سيّاقيّ خفيف</li>
  <li class="list-group-item list-group-item-action list-group-item-dark">عنصُر بصنف سيّاقيّ غامق</li>
</ul>
</syntaxhighlight>تنبيه: توصيل المعنى إلى التقنيّات المساعدة

يقتصر المعنى - عند الاقتصار على استخدام اللّون لنقله – على الدّلالة البصريّة، وبالتالي لن يصل  المعنى المطلوب إلى التقنيّات المساعدة للزوّار (مثل قارئات الشاشة). تأكّد من أنّ المعلومة التي يشير إليها اللّون إمّا بديهيّة من المحتوى نفسِه (أيّ النصّ المرئي) أو أنّها أُضيفت بوسائل بديلة مثل نصّ  مخفيّ بالصّنف <code>‎.sr-only</code>.
== استخدام الشارات (Badges) ==
استخدم الشارات بالتعاون مع [[Bootstrap/flex|أدوات Flex]] على أيّ عنصُر في اللائحة لعرض عدّاد للرسائل غير المقروءة، النشاط أو ما شابه.
<syntaxhighlight lang="html">
<ul class="list-group">
  <li class="list-group-item d-flex justify-content-between align-items-center">
    Cras justo odio
    <span class="badge badge-primary badge-pill">14</span>
  </li>
  <li class="list-group-item d-flex justify-content-between align-items-center">
    Dapibus ac facilisis in
    <span class="badge badge-primary badge-pill">2</span>
  </li>
  <li class="list-group-item d-flex justify-content-between align-items-center">
    Morbi leo risus
    <span class="badge badge-primary badge-pill">1</span>
  </li>
</ul>
</syntaxhighlight>
== المُحتوى المُخصَّص ==
أضف شفرة [[HTML]] داخل عناصر القوائم بمساعدة [[Bootstrap/flex|أدوات Flex]] كما في المثال التالي.
<syntaxhighlight lang="html">
<div class="list-group">
  <a href="#" class="list-group-item list-group-item-action flex-column align-items-start active">
    <div class="d-flex w-100 justify-content-between">
      <h5 class="mb-1">ترويسة عنصُر في قائمة عناصر</h5>
      <small>قبل ثلاثة أيّام</small>
    </div>
    <p class="mb-1">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p>
    <small>Donec id elit non mi porta.</small>
  </a>
  <a href="#" class="list-group-item list-group-item-action flex-column align-items-start">
    <div class="d-flex w-100 justify-content-between">
      <h5 class="mb-1">ترويسة عنصُر في قائمة عناصر</h5>
      <small class="text-muted">قبل ثلاثة أيّام</small>
    </div>
    <p class="mb-1">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p>
    <small class="text-muted">Donec id elit non mi porta.</small>
  </a>
  <a href="#" class="list-group-item list-group-item-action flex-column align-items-start">
    <div class="d-flex w-100 justify-content-between">
      <h5 class="mb-1">ترويسة عنصُر في قائمة عناصر</h5>
      <small class="text-muted">قبل ثلاثة أيّام</small>
    </div>
    <p class="mb-1">Donec id elit non mi porta gravida at eget metus. Maecenas sed diam eget risus varius blandit.</p>
    <small class="text-muted">Donec id elit non mi porta.</small>
  </a>
</div>
</syntaxhighlight>
== كتابة شفرة JavaScript مخصّصة ==
استخدم ملحق JavaScript - بتضمينه منفردًا أو عبر الملف المُجمَّع <code>bootstrap.js</code> - لتمديد مكوِن مجموعة عناصر القوائم في إطار العمل Bootstrap وإنشاء لوحات محتوى مُبوَّب (tabbable panes). 
<syntaxhighlight lang="html">
<div class="row">
  <div class="col-4">
    <div class="list-group" id="list-tab" role="tablist">
      <a class="list-group-item list-group-item-action active" id="list-home-list" data-toggle="list" href="#list-home" role="tab" aria-controls="home">الرئيسيّة</a>
      <a class="list-group-item list-group-item-action" id="list-profile-list" data-toggle="list" href="#list-profile" role="tab" aria-controls="profile">الملف الشخصيّ</a>
      <a class="list-group-item list-group-item-action" id="list-messages-list" data-toggle="list" href="#list-messages" role="tab" aria-controls="messages">الرسائل</a>
      <a class="list-group-item list-group-item-action" id="list-settings-list" data-toggle="list" href="#list-settings" role="tab" aria-controls="settings">الإعدادات</a>
    </div>
  </div>
  <div class="col-8">
    <div class="tab-content" id="nav-tabContent">
      <div class="tab-pane fade show active" id="list-home" role="tabpanel" aria-labelledby="list-home-list">محتوى تبويب الرئيسية</div>
      <div class="tab-pane fade" id="list-profile" role="tabpanel" aria-labelledby="list-profile-list">محتوى تبويب الملف الشخصيّ</div>
      <div class="tab-pane fade" id="list-messages" role="tabpanel" aria-labelledby="list-messages-list">محتوى تبويب الرسائل</div>
      <div class="tab-pane fade" id="list-settings" role="tabpanel" aria-labelledby="list-settings-list">محتوى تبويب الإعدادات</div>
    </div>
  </div>
</div>
</syntaxhighlight>
=== استخدام خاصيّات البيانات ===
يمكن تفعيل التنقّل بين مجموعة العناصر دون كتابة شفرة JavaScript بسهولة عن طريق الخاصيّة ‎<code>data-toggle="list"‎</code> أو عنصُر. استخدم خاصيّات البيانات على العناصر <code>‎.list-group-item</code>.
<syntaxhighlight lang="html">
<!-- مجموعة العناصر -->
<div class="list-group" id="myList" role="tablist">
  <a class="list-group-item list-group-item-action active" data-toggle="list" href="#home" role="tab">الرئيسيّة</a>
  <a class="list-group-item list-group-item-action" data-toggle="list" href="#profile" role="tab">الملفّ الشخصيّ</a>
  <a class="list-group-item list-group-item-action" data-toggle="list" href="#messages" role="tab">الرسائل</a>
  <a class="list-group-item list-group-item-action" data-toggle="list" href="#settings" role="tab">الإعدادات</a>
</div>

<!-- محتوى التبويبات -->
<div class="tab-content">
  <div class="tab-pane active" id="home" role="tabpanel">محتوى تبويب الرئيسية</div>
  <div class="tab-pane" id="profile" role="tabpanel">محتوى تبويب الملف الشخصيّ</div>
  <div class="tab-pane" id="messages" role="tabpanel">محتوى تبويب الرسائل</div>
  <div class="tab-pane" id="settings" role="tabpanel">محتوى تبويب الإعدادات</div>
</div>
</syntaxhighlight>
=== كتابة شفرات JavaScript ===
استخدم JavaScript لتفعيل إنشاء التبويبات (tabs) عبر مجموعات العناصر (يجب تفعيل كل عنصُر في اللائحة):
<syntaxhighlight lang="javascript">
$('#myList a').on('click', function (e) {
  e.preventDefault()
  $(this).tab('show')
})
</syntaxhighlight>

توجد أكثر من طريقة لتفعيل عناصر اللائحة فرادى:

<syntaxhighlight lang="javascript">
$('#myList a[href="#profile"]').tab('show') // الاختيّار حسب اسم التبويب
$('#myList a:first-child').tab('show') // اختيّار التبويب الأوّل
$('#myList a:last-child').tab('show') // اختيّار التبويب الأخير
$('#myList a:nth-child(3)').tab('show') // اختيّار التبويب الثالث
</syntaxhighlight>

=== تأثير الخفوت (Fade) ===

أضف الصنف <code>‎.fade</code> إلى كلّ تبويب <code>‎.tab-pane</code> لجعل التبويبات تخفُت عند الانتقال إلى غيرها. يجب أن يُطبَّق الصنف <code>‎.show</code> على التبويب الأوّل لجعل المحتوى الابتدائيّ مرئيًّا.

<syntaxhighlight lang="html">
<div class="tab-content">
  <div class="tab-pane fade show active" id="home" role="tabpanel">...</div>
  <div class="tab-pane fade" id="profile" role="tabpanel">...</div>
  <div class="tab-pane fade" id="messages" role="tabpanel">...</div>
  <div class="tab-pane fade" id="settings" role="tabpanel">...</div>
</div>
</syntaxhighlight>

== التوابع ==

=== <code>‎ $().tab</code> ===

يفعّل عنصُر من عناصر القائمة وحاويّة محتوى. يجب أن يُطبَّق التابع <code>tab</code> على خاصيّة <code>data-target</code> أو رابط (<code>href</code>) يستهدف حاويّة في كائن المستند.

<syntaxhighlight lang="html">
<div class="list-group" id="myList" role="tablist">
  <a class="list-group-item list-group-item-action active" data-toggle="list" href="#home" role="tab">الرئيسيّة</a>
  <a class="list-group-item list-group-item-action" data-toggle="list" href="#profile" role="tab">الملفّ الشخصيّ</a>
  <a class="list-group-item list-group-item-action" data-toggle="list" href="#messages" role="tab">الرسائل</a>
  <a class="list-group-item list-group-item-action" data-toggle="list" href="#settings" role="tab">الإعدادات</a>
</div>

<div class="tab-content">
  <div class="tab-pane active" id="home" role="tabpanel">...</div>
  <div class="tab-pane" id="profile" role="tabpanel">...</div>
  <div class="tab-pane" id="messages" role="tabpanel">...</div>
  <div class="tab-pane" id="settings" role="tabpanel">...</div>
</div>

<script>
  $(function () {
    $('#myList a:last-child').tab('show')
  })
</script>
</syntaxhighlight>

=== ‎<code>‎.tab('show')‎‎</code> ===
يحدّد عنصُر القائمة المُمرَّر ويعرض التبويب الموافق له. يُلغى تحديد أيّ عنصُر آخر غير العنصُر المُمرَّر ويُخفَى التبويب الموافق له. '''يعود إلى شفرة الاستدعاء قبل عرض التبويب''' (على سبيل المثال قبل وقوع الحدث <code>shown.bs.tab</code>)

<syntaxhighlight lang="javascript">
$('#someListItem').tab('show')
</syntaxhighlight>
=== الأحداث ===
تقع الأحداث عند عرض تبويب وفق الترتيب التالي:

# <code>hide.bs.tab</code> (على التبويب النشط حاليًا).
# <code>show.bs.tab</code> (على التبويب المستهدَف).
# <code>hidden.bs.tab</code> (على التبويب النشط سابقا، نفس التبويب الذي يقع عليه الحدث <code>hide.bs.tab</code>).
# <code>shown.bs.tab</code> (على التبويب النشط الجديد، نفس التبويب الذي وقع عليه الحدث <code>show.bs.tab</code>).

لا يقع الحدثان<code>hide.bs.tab</code> و <code>hidden.bs.tab</code> عندما لا يوجد تبويب نشط مسبقًا.

{| class="wikitable"
!نوع الحدث
!الوصف
|-
|<code>show.bs.tab</code>
|يقع هذا الحدث عند طلب عرض التبويب، ولكن قبل أن يُعرَض. استخدم <code>event.target</code> و<code>event.relatedTarget</code> لاستهداف التبويب النشط الجديد والتبويب النشط السابق (إنْ وُجد) على التوالي .
|-
|<code>shown.bs.tab</code>
|يقع هذا الحدث بعد عرض التبويب.  استخدم <code>event.target</code> و<code>event.relatedTarget</code> لاستهداف التبويب النشط الجديد والتبويب النشط السابق (إنْ وُجد) على التوالي .
|-
|<code>hide.bs.tab</code>
|يقع هذا الحدث عندما يوجد تبويب يُراد عرضُه (وبالتالي يُراد إخفاء التبويب النشط السابق). استخدم <code>event.target</code> و<code>event.relatedTarget</code> لاستهداف التبويب النشط حاليًّا والتبويب الذي سيكون نشطًا قريبًا على التوالي.
|-
|<code>hidden.bs.tab</code>
|يقع هذا الحدث بعد عرض التبويب الجديد (وبالتالي بعد إخفاء التبويب النشط السابق). استخدم <code>event.target</code> و<code>event.relatedTarget</code> لاستهداف التبويب النشط سابقًا والتبويب النشط حاليًّا على التوالي.
|}

<syntaxhighlight lang="javascript">
$('a[data-toggle="list"]').on('shown.bs.tab', function (e) {
  e.target // التبويب النشط الجديد
  e.relatedTarget // التبويب النشط السابق
})
</syntaxhighlight>

== مصادر ==
* [https://getbootstrap.com/docs/4.0/components/list-group صفحة List group على توثيق Bootstrap].

[[تصنيف:Bootstrap]]
[[تصنيف:Bootstrap components]]