Bootstrap/collapse

استخدِم أصناف مكوِّن الطيّ ومُلحقات JavaScript في إطار العمل Bootstrap لإظهار المحتوى أو إخفائه حسب الحاجة.

نظرة عامة

يُستخدم مكوِّن الطيّ لإظهار وإخفاء المحتوى. تُستخدم الأزرار أو المنقورات كمنشّطات لإظهار أو إخفاء عنصر معين ترتبط به. سيؤدي تصغير عنصر إلى تحريك الارتفاع من قيمته الحالية إلى 0. ونظرًا للطريقة التي تتعامل بها CSS مع الحركات، لا يمكنك استخدام الحواشي على عنصر .collapse. استخدم بدلاً من ذلك الصنف كعنصر مغلِّف مستقل.

ملحوظة: تأثير الحركة الخاص بهذه المكونة يعتمد على استعلام الوسائط prefers-reduced-motion. راجع صفحة سهولة الوصول لمزيد من المعلومات.

مثال

تتوفّر الأصناف التاليّة لإظخار المحتوى أو إخفائه:

• ‎.collapse تخفي المحتوى،
• ‎.collapsing يُطبَّق هذا الصنف أثناء الانتقال بين إظهار المحتوى وإخفائه،
• ‎.collapse.show يُظهر المحتوى.

يمكن استخدام رابط وتعيين الخاصيّة href أو زرّ بخاصيّة data-target. الخاصيّة data-toggle="collapse"‎مطلوبة في كلتا الحالتيْن.

جرّب المثال التالي.

<p>
  <a class="btn btn-primary" data-toggle="collapse" href="#collapseExample" role="button" aria-expanded="false" aria-controls="collapseExample">
    رابط بخاصيّة href
  </a>
  <button class="btn btn-primary" type="button" data-toggle="collapse" data-target="#collapseExample" aria-expanded="false" aria-controls="collapseExample">
    زرّ بخاصيّة data-target
  </button>
</p>
<div class="collapse" id="collapseExample">
  <div class="card card-body">مثال لفقرة يظهر محتواها أو يختفي بالنقر على الرابط أو الزرّ السابقيْن.
  </div>
</div>

أهداف متعدّدة

يمكن لزرّ (<button>) أو رابط () إظهار عناصر عدّة أو إخفاؤها بالإحالة إلى محدِّد jQuery في الخاصيّة href أو data-target حسب الحالة.

يمكن لأزرار أو روابط عدّة إظهار أو إخفاء نفس العنصُر إن كانت كلّها تحيل إلى خاصيّة href أو data-target في العنصُر المذكور.

<p>
  <a class="btn btn-primary" data-toggle="collapse" href="#multiCollapseExample1" role="button" aria-expanded="false" aria-controls="multiCollapseExample1">بدّل حالة العنصُر الأوّل</a>
  <button class="btn btn-primary" type="button" data-toggle="collapse" data-target="#multiCollapseExample2" aria-expanded="false" aria-controls="multiCollapseExample2">بدّل حالة العنصُر الثاني</button>
  <button class="btn btn-primary" type="button" data-toggle="collapse" data-target=".multi-collapse" aria-expanded="false" aria-controls="multiCollapseExample1 multiCollapseExample2">بدّل حالة العنصُريْن</button>
</p>
<div class="row">
  <div class="col">
    <div class="collapse multi-collapse" id="multiCollapseExample1">
      <div class="card card-body">
      مثال لفقرة يظهر محتواها (أو يختفي) عند النقر على الزرّ <strong>الأوّل</strong> أو على الزرّ <strong>الأخير</strong>. 
      </div>
    </div>
  </div>
  <div class="col">
    <div class="collapse multi-collapse" id="multiCollapseExample2">
      <div class="card card-body">
        مثال لفقرة يظهر محتواها (أو يختفي) عند النقر على الزرّ <strong>الثاني</strong> أو على الزرّ <strong>الأخير</strong>.
      </div>
    </div>
  </div>
</div>

تأثير الأكورديون

يمكن باستخدام مكوِّن البطاقات في إطار العمل Bootstrap تمديد سلوك الطيّ المبدئي لإنشاء تأثير يشبه حركة آلة الأكورديون الموسيقية.

<div class="accordion" id="accordionExample">
  <div class="card">
    <div class="card-header" id="headingOne">
      <h2 class="mb-0">
        <button class="btn btn-link btn-block text-left" type="button" data-toggle="collapse" data-target="#collapseOne" aria-expanded="true" aria-controls="collapseOne">
          العنصُر الأوّل القابل للطيّ
        </button>
      </h2>
    </div>

    <div id="collapseOne" class="collapse show" aria-labelledby="headingOne" data-parent="#accordionExample">
      <div class="card-body">
        تأثير الأكورديون - يتمدّد هذا العنصُر ويظهر محتواه عند النقر على ترويسة البطاقة، في نفس الوقت تُطوى البطاقات الأخرى ويُخفى محتواها.
      </div>
    </div>
  </div>
  <div class="card">
    <div class="card-header" id="headingTwo">
      <h2 class="mb-0">
        <button class="btn btn-link btn-block text-left collapsed" type="button" data-toggle="collapse" data-target="#collapseTwo" aria-expanded="false" aria-controls="collapseTwo">
          العنصُر الثاني القابل للطيّ
        </button>
      </h2>
    </div>
    <div id="collapseTwo" class="collapse" aria-labelledby="headingTwo" data-parent="#accordionExample">
      <div class="card-body">
        تأثير الأكورديون - يتمدّد هذا العنصُر ويظهر محتواه عند النقر على ترويسة البطاقة، في نفس الوقت تُطوى البطاقات الأخرى ويُخفى محتواها.
      </div>
    </div>
  </div>
  <div class="card">
    <div class="card-header" id="headingThree">
      <h2 class="mb-0">
        <button class="btn btn-link btn-block text-left collapsed" type="button" data-toggle="collapse" data-target="#collapseThree" aria-expanded="false" aria-controls="collapseThree">
          العنصُر الثالث القابل للطيّ
        </button>
      </h2>
    </div>
    <div id="collapseThree" class="collapse" aria-labelledby="headingThree" data-parent="#accordionExample">
      <div class="card-body">        تأثير الأكورديون - يتمدّد هذا العنصُر ويظهر محتواه عند النقر على ترويسة البطاقة، في نفس الوقت تُطوى البطاقات الأخرى ويُخفى محتواها.
      </div>
    </div>
  </div>
</div>

سهولة الوصول

تأكّد من إضافة الخاصيّة aria-expanded إلى عنصُر التحكّم. تنقُل هذه الخاصيّة الحالة الراهنة للعنصُر القابل للطيّ تنقُلها إلى قارئات الشاشة والتقنيّات المساعدة المشابهة. يجب أن تكون قيمة الخاصيّة هي aria-expanded="false"‎ إنْ كان العنصُر القابل للطيّ مغلقًا مبدئيّا. عيّن القيمة true للخاصيّة aria-expanded إنْ كان العنصُر القابل للطيّ ظاهرًا مبدئيًّا نتيجة لاستخدام الصنف show. يبدّل المُلحَق قيمة الخاصيّة تلقائيًّا في عنصُر التحكّم اعتمادًا على ما إذا كان العنصُر القابل للطيّ مُظهَرًا أم مخفيًّا (عن طريق JavaScript أو عندما يستخدم الزائر عنصُر تحكّم آخر مربوطًا بنفس العنصُر القابل للطيّ). إنْ لم يكن عنصُر التحكم زرًّا (<button>) فتجب إضافة الخاصيّة role="button"‎ إليه.

تجب إضافة خاصيّة aria-controls تحتوي معرِّف العنصُر القابل للطيّ إلى عنصُر التحكّم إنْ كان يستهدف عنصُرًا واحدًا قابلًا للطيّ (مثلًا عندما تشير الخاصيّة data-target إلى معرِّف [id]). تستخدم قارئات الشاشة الحديثة والتقنيّات المساعدة المشابهة لها هذه الخاصيّة لتوفير اختصارات إضافيّة للمستخدمين للتنقّل إلى العنصُر القابل للطيّ مباشرة.

يُرجى ملاحظة أنّ إصدارات Bootstrap حاليًّا لا تغطّي التفاعلات المختلفة مع لوحة المفاتيح المشروحة ضمن فقرة معيار WAI-ARIA الخاصّة بتأثير الأكورديون؛ لذا ستحتاج لتضمين هذه التفاعلات المختلفة بنفسك عن طريق شفرة JavaScript مُخصَّصة.

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

يستخدم مُلحَق الطيّ في إطار العمل Bootstrap بضعة أصناف للتعامل مع الانتقال بين حالة الطيّ (الإخفاء) والسدل (الإظهار):

• ‎.collapse يخفي المحتوى،
• ‎.collapse.show يظهر المحتوى،
• ‎.collapsing يُضاف هذا الصنف عند بدء الانتقال ويُحذَف بعد اكتماله.

توجد هذه الأصناف ضمن الملفّ ‎_transitions.scss.

خاصيّات البيانات (Data attributes)

أضف الخاصيّةdata-toggle="collapse"‎ و data-target إلى العنصُر ليُسند إليه تلقائيًّا التحكّم في عنصُر قابل للطيّ أو أكثر. تستقبل الخاصيّة data-target محدِّد CSS لتطبيق الطيّ عليه. تأكّد من إضافة الصنف collapse إلى العنصُر القابل للطيّ. أضف الصنف show إليه إنْ كنت تريد أن يظهر مبدئيّا.

لإضافة إمكانية إدارة مجموعة تشبه الأكورديون إلى منطقة قابلة للطي، أضف السمة data-parent="#selector"‎.

شفرة JavaScript مُخصَّصة

يُفعَّل تأثير الطيّ يدويًّا على النحو التالي:

$('.collapse').collapse();

الخيّارات

يمكن تمرير الخيارات عبر سمات البيانات أو جافا سكربت. بالنسبة لسمات البيانات، ألحق اسم الخيار إلى data-‎ كما في data-parent=""‎.

الاسم	النوع	القيمة المبدئيّة	الوصف
parent (العنصُر الأب)	مُحدِّد Selector| كائن jQuery | عنصُر DOM	false	تُخفى جميع العناصر القابلة للطيّ عند إظهار العنصُر الأب - في حالة تمريره - الذي ترتبط به تلك العناصر (شبيه بتأثير الأكورديون. يعتمد على الصنف card). يجب أن تُعيَّن الخاصيّة على المنطقة القابلة للطيّ المستهدَفة.
toggle (تبديل)	قيمة منطقيّة	true	يُبدِّل حالة العنصُر القابل للطيّ.

التوابع

تنبيه: التوابع غير المتزامنة والانتقالات

توابع واجهة التطبيقات جميعها غير متزامنة وتشغّل انتقالا. تعود هذه التوابع لشفرة الاستدعاء مباشرةً بعد بدء الانتقال، لكن قبل أن ينتهي. علاوةً على ذلك، يُتجاهل استدعاء تابع على مكوِّن في طور الانتقال.

راجع توثيق JavaScript في Bootstrap للمزيد من المعلومات.

‎.collapse(options)‎‎

يجعل المحتوى قابلًا للطيّ. يقبل كائن خيّارات اختيّاري.

$('#myCollapsible').collapse({
  toggle: false
})

.collapse('toggle')‎‎

يبدّل بين حالتيْ العنصُر القابل للطيّ (إخفاء أو إظهار). يعود إلى المستدعِي قبل أن يُظهَر أو يُخفَى العنصُر المستهدَف (أي قبل وقوع الحدث shown.bs.collapse أو hidden.bs.collapse )

‎.collapse('show')‎‎

يُظهر عنصُرًا قابلًا للطيّ. يعود إلى المستدعِي قبل أن يُظهَر العنصُر المستهدَف فعليًّا (أي قبل وقوع الحدث shown.bs.collapse).

‎.collapse('hide')‎‎

يُخفي عنصُرًا قابلًا للطيّ. يعود إلى المستدعِي قبل أن يُخفَى العنصُر المستهدَف فعليًّا (أي قبل وقوع الحدث hidden.bs.collapse).

‎.collapse('dispose')‎‎

يحذف قابليّة الطيّ من العنصُر.

الأحداث

يعرض الصنف collapse في إطار العمل Bootstrap بضعة أحداث للتعامل مع وظيفة الطيّ.

نوع الحدث	الوصف
show.bs.collapse	ينطلق هذا الحدث مباشرةً بعد استدعاء التابع show.
shown.bs.collapse	ينطلق هذا الحدث عندما يصبح العنصُر القابل للطيّ ظاهرًا للمستخدم (سينتظر حتى اكتمال انتقالات CSS).
hide.bs.collapse	ينطلق هذا الحدث مباشرةً بعد استدعاء التابع hide.
hidden.bs.collapse	ينطلق هذا الحدث عندما يصبح العنصُر القابل للطيّ مخفيًّا عن المستخدم (سينتظر حتى اكتمال انتقالات CSS).

$('#myCollapsible').on('hidden.bs.collapse', function () {
  // افعل شيئا …
})

مصادر

• صفحة Collapse في توثيق Bootstrap.