Bootstrap/list group

مجموعات القوائم هي مكوِّن مرن وفعّال لعرض سلاسل من المحتوى؛ يمكن التعديل عليها وتمديدها لدعم أي نوع من المحتوى داخلها.

مثال قاعديّ

أبسط مثال على استخدام مجموعات القوائم هو قائمة غير مُرتَّبة تحوي عناصر القائمة والأصناف المناسبة. أسِّس على هذه اللوائح بالخيّارات المشروحة أدناه أو باستخدام CSS خاصّ بك حسب الحاجة.

<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>

العناصر النشطة

أضف الصنف ‎.active إلى عنصُر في القائمة (‎.list-group-item) للإشارة إلى أنّ العنصُر نشط.

<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>

العناصر المُعطَّلة

أضف الصنف ‎.disabled إلى عنصُر في القائمة (‎.list-group-item) لجعله يظهر مُعطّلا. تُرجى ملاحظة أنّ بعض العناصر (الروابط مثلًا) تحتاج لشفرة JavaScript إضافيّة لتعطيل أحداث النقر عليها تمامًا.

<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>

الروابط والأزرار

طبّق الصنف ‎.list-group-item-action على العناصر <a> أو <button> لإنشاء عناصر يمكن تنفيذ إجراءات بالنقر عليها ضمن القائمة. تتوفّر عناصر القائمة في عند تطبيق الصنف على حالات الحومان (hover)، والتعطيل والنشاط. يفصل إطار العمل Bootstrap بين الأصناف الزائفة للحالات المذكورة لضمان أنّ أعضاء اللائحة المُنشئين باستخدام عناصر غير تفاعليّة (مثل <li> و <div>) لا توفّر قابليّة النقر أو الضغط.

تأكّد من عدم استخدام الأصناف المعياريّة ‎.btn هنا.

<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>

يمكن بالنسبة للأزرار (<button>) استخدام الخاصيّة disabled بدلًا من الصنف ‎.disabled للأسف لا تدعم الروابط (<a>) الخاصيّة disabled.

<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>

تسطيح القائمة

أضف الصنف ‎.list-group-flush إلى القائمة لحذف بعضٍ من الحدود والحوافّ المُدوَّرة لجعل عناصر القائمة متراصّة ضمن حاويّة (مثل البطاقات).

<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>

الأصناف السياقيّة (Contextual classes)

استخدم الأصناف السياقيّة لتنسيق عناصر القائمة بخلفيّة ولون يوضّحان حالتها.

<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>

تعمل الأصناف السياقيّة كذلك مع الصنف ‎.list-group-item-action. لاحظ أنّ تأثيرات الحومان غير حاضرة في المثال السابق. يُدعَم كذلك الصنف ‎.active الذي يؤدّي تطبيقه إلى الإشارة إلى العنصُر النشط ضمن قائمة بأصناف سياقيّة.

<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>

تنبيه: توصيل المعنى إلى التقنيّات المساعدة

يقتصر المعنى - عند الاقتصار على استخدام اللّون لنقله – على الدّلالة البصريّة، وبالتالي لن يصل المعنى المطلوب إلى التقنيّات المساعدة للزوّار (مثل قارئات الشاشة). تأكّد من أنّ المعلومة التي يشير إليها اللّون إمّا بديهيّة من المحتوى نفسِه (أيّ النصّ المرئي) أو أنّها أُضيفت بوسائل بديلة مثل نصّ مخفيّ بالصّنف ‎.sr-only.

استخدام الشارات (Badges)

استخدم الشارات بالتعاون مع أدوات Flex على أيّ عنصُر في اللائحة لعرض عدّاد للرسائل غير المقروءة، النشاط أو ما شابه.

<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>

المُحتوى المُخصَّص

أضف شفرة HTML داخل عناصر القوائم بمساعدة أدوات Flex كما في المثال التالي.

<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>

كتابة شفرة JavaScript مخصّصة

استخدم ملحق JavaScript - بتضمينه منفردًا أو عبر الملف المُجمَّع bootstrap.js - لتمديد مكوِن مجموعة عناصر القوائم في إطار العمل Bootstrap وإنشاء لوحات محتوى مُبوَّب (tabbable panes).

<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>

استخدام خاصيّات البيانات

يمكن تفعيل التنقّل بين مجموعة العناصر دون كتابة شفرة JavaScript بسهولة عن طريق الخاصيّة ‎data-toggle="list"‎ أو عنصُر. استخدم خاصيّات البيانات على العناصر ‎.list-group-item.

<!-- مجموعة العناصر -->
<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>

كتابة شفرات JavaScript

استخدم JavaScript لتفعيل إنشاء التبويبات (tabs) عبر مجموعات العناصر (يجب تفعيل كل عنصُر في اللائحة):

$('#myList a').on('click', function (e) {
  e.preventDefault()
  $(this).tab('show')
})

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

$('#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') // اختيّار التبويب الثالث

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

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

<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>

التوابع

‎ $().tab

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

<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>

‎‎.tab('show')‎‎

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

$('#someListItem').tab('show')

الأحداث

تقع الأحداث عند عرض تبويب وفق الترتيب التالي:

1. hide.bs.tab (على التبويب النشط حاليًا).
2. show.bs.tab (على التبويب المستهدَف).
3. hidden.bs.tab (على التبويب النشط سابقا، نفس التبويب الذي يقع عليه الحدث hide.bs.tab).
4. shown.bs.tab (على التبويب النشط الجديد، نفس التبويب الذي وقع عليه الحدث show.bs.tab).

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

نوع الحدث	الوصف
show.bs.tab	يقع هذا الحدث عند طلب عرض التبويب، ولكن قبل أن يُعرَض. استخدم event.target وevent.relatedTarget لاستهداف التبويب النشط الجديد والتبويب النشط السابق (إنْ وُجد) على التوالي .
shown.bs.tab	يقع هذا الحدث بعد عرض التبويب. استخدم event.target وevent.relatedTarget لاستهداف التبويب النشط الجديد والتبويب النشط السابق (إنْ وُجد) على التوالي .
hide.bs.tab	يقع هذا الحدث عندما يوجد تبويب يُراد عرضُه (وبالتالي يُراد إخفاء التبويب النشط السابق). استخدم event.target وevent.relatedTarget لاستهداف التبويب النشط حاليًّا والتبويب الذي سيكون نشطًا قريبًا على التوالي.
hidden.bs.tab	يقع هذا الحدث بعد عرض التبويب الجديد (وبالتالي بعد إخفاء التبويب النشط السابق). استخدم event.target وevent.relatedTarget لاستهداف التبويب النشط سابقًا والتبويب النشط حاليًّا على التوالي.

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

مصادر

• صفحة List group على توثيق Bootstrap.