الطي (Collapse)

كيف يعمل ؟

تُستخدم إضافة الـ JavaScript الخاصة بالطي (collapse) لإظهار وإخفاء المحتوى. تُستخدم الأزرار أو الروابط كمشغلات يتم ربطها بعناصر محددة تقوم بتبديلها. سيؤدي طي العنصر إلى تحريك الـ height من قيمته الحالية إلى 0. ونظراً لكيفية تعامل الـ CSS مع الرسوم المتحركة، لا يمكنك استخدام الـ padding على عنصر collapse.. بدلاً من ذلك، استخدم الفئة (class) كعنصر تغليف مستقل.

مثال

انقر على الأزرار أدناه لإظهار وإخفاء عنصر آخر عبر تغييرات الفئات (classes):

• .collapse تخفي المحتوى
• .collapsing يتم تطبيقها أثناء الانتقالات
• .collapse.show تظهر المحتوى

بشكل عام، نوصي باستخدام عنصر <button> مع سمة data-bs-target. ورغم أنها غير موصى بها من وجهة نظر دلالية، يمكنك أيضاً استخدام رابط <a> مع سمة href (و role="button"). في كلتا الحالتين، فإن سمة data-bs-toggle="collapse" مطلوبة.

<p class="d-inline-flex gap-1">
  <a class="btn btn-primary" data-bs-toggle="collapse" href="#collapseExample" role="button" aria-expanded="false" aria-controls="collapseExample">
    Link with href
  </a>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseExample" aria-expanded="false" aria-controls="collapseExample">
    Button with data-bs-target
  </button>
</p>
<div class="collapse" id="collapseExample">
  <div class="card card-body">
    Some placeholder content for the collapse component. This panel is hidden by default but revealed when the user activates the relevant trigger.
  </div>
</div>

أفقي (Horizontal)

تدعم إضافة الـ collapse الطي الأفقي. أضف الفئة (class) المعدلة .collapse-horizontal لتحريك الـ width بدلاً من الـ height وقم بتعيين width على العنصر الابن المباشر. لا تتردد في كتابة الـ Sass الخاص بك، أو استخدام الأنماط المضمنة (inline styles)، أو استخدام أدوات العرض (width utilities).

<p>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#collapseWidthExample" aria-expanded="false" aria-controls="collapseWidthExample">
    Toggle width collapse
  </button>
</p>
<div style="min-height: 120px;">
  <div class="collapse collapse-horizontal" id="collapseWidthExample">
    <div class="card card-body" style="width: 300px;">
      This is some placeholder content for a horizontal collapse. It’s hidden by default and shown when triggered.
    </div>
  </div>
</div>

مشغلات وأهداف متعددة

يمكن لعنصر <button> أو <a> إظهار وإخفاء عناصر متعددة من خلال الإشارة إليها باستخدام محدد (selector) في سمة data-bs-target أو href. وبالمقابل، يمكن لعناصر <button> أو <a> متعددة إظهار وإخفاء نفس العنصر إذا كانت كل منها تشير إليه عبر سمة data-bs-target أو href.

<p class="d-inline-flex gap-1">
  <a class="btn btn-primary" data-bs-toggle="collapse" href="#multiCollapseExample1" role="button" aria-expanded="false" aria-controls="multiCollapseExample1">Toggle first element</a>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target="#multiCollapseExample2" aria-expanded="false" aria-controls="multiCollapseExample2">Toggle second element</button>
  <button class="btn btn-primary" type="button" data-bs-toggle="collapse" data-bs-target=".multi-collapse" aria-expanded="false" aria-controls="multiCollapseExample1 multiCollapseExample2">Toggle both elements</button>
</p>
<div class="row">
  <div class="col">
    <div class="collapse multi-collapse" id="multiCollapseExample1">
      <div class="card card-body">
        Some placeholder content for the first collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger.
      </div>
    </div>
  </div>
  <div class="col">
    <div class="collapse multi-collapse" id="multiCollapseExample2">
      <div class="card card-body">
        Some placeholder content for the second collapse component of this multi-collapse example. This panel is hidden by default but revealed when the user activates the relevant trigger.
      </div>
    </div>
  </div>
</div>

إمكانية الوصول

تأكد من إضافة aria-expanded إلى عنصر التحكم. تنقل هذه السمة بوضوح الحالة الحالية للعنصر القابل للطي المرتبط بعنصر التحكم إلى قارئات الشاشة والتقنيات المساعدة المماثلة. إذا كان العنصر القابل للطي مغلقاً بشكل افتراضي، فيجب أن تكون قيمة السمة في عنصر التحكم aria-expanded="false". إذا قمت بتعيين العنصر القابل للطي ليكون مفتوحاً بشكل افتراضي باستخدام الفئة show، فقم بتعيين aria-expanded="true" في عنصر التحكم بدلاً من ذلك. ستقوم الإضافة تلقائياً بتبديل هذه السمة في عنصر التحكم بناءً على ما إذا كان العنصر القابل للطي قد تم فتحه أو إغلاقه (عبر الـ JavaScript، أو لأن المستخدم قام بتفعيل عنصر تحكم آخر مرتبط بنفس العنصر القابل للطي). إذا لم يكن عنصر HTML الخاص بعنصر التحكم زراً (على سبيل المثال، <a> أو <div>)، فيجب إضافة السمة role="button" إلى العنصر.

إذا كان عنصر التحكم الخاص بك يستهدف عنصراً واحداً قابلاً للطي - أي أن سمة data-bs-target تشير إلى محدد id - فيجب إضافة سمة aria-controls إلى عنصر التحكم، بحيث تحتوي على الـ id الخاص بالعنصر القابل للطي. تستخدم قارئات الشاشة الحديثة والتقنيات المساعدة المماثلة هذه السمة لتزويد المستخدمين باختصارات إضافية للتنقل مباشرة إلى العنصر القابل للطي نفسه.

لاحظ أن تنفيذ Bootstrap الحالي لا يغطي مختلف تفاعلات لوحة المفاتيح الاختيارية الموضحة في نمط القوائم المطوية (accordion) في دليل ممارسات تأليف ARIA - ستحتاج إلى تضمين هذه التفاعلات بنفسك باستخدام JavaScript مخصص.

الـ (CSS)

متغيرات الـ (Sass)

$transition-collapse:         height .35s ease;
$transition-collapse-width:   width .35s ease;

الفئات (Classes)

يمكن العثور على الفئات (classes) الخاصة بانتقالات الطي في scss/_transitions.scss حيث أنها مشتركة عبر مكونات متعددة (الطي والقوائم المطوية (accordion)).

.collapse {
  &:not(.show) {
    display: none;
  }
}

.collapsing {
  height: 0;
  overflow: hidden;
  @include transition($transition-collapse);

  &.collapse-horizontal {
    width: 0;
    height: auto;
    @include transition($transition-collapse-width);
  }
}

الإستخدام

تستخدم إضافة الـ collapse بعض الفئات (classes) للقيام بالمهام الأساسية:

• .collapse تخفي المحتوى
• .collapse.show تظهر المحتوى
• .collapsing يتم إضافتها عند بدء الانتقال، وتُزال عند انتهائه

يمكن العثور على هذه الفئات في _transitions.scss.

عبر سمات البيانات (Via data attributes)

فقط أضف data-bs-toggle="collapse" و data-bs-target إلى العنصر لتعيين التحكم تلقائياً في عنصر واحد أو أكثر من العناصر القابلة للطي. تقبل سمة data-bs-target محدد CSS لتطبيق الطي عليه. تأكد من إضافة الفئة collapse إلى العنصر القابل للطي. إذا كنت تريد أن يكون مفتوحاً بشكل افتراضي، فأضف الفئة الإضافية show.

لإضافة إدارة مجموعات تشبه القوائم المطوية (accordion) إلى منطقة قابلة للطي، أضف سمة البيانات data-bs-parent="#selector". راجع صفحة القوائم المطوية لمزيد من المعلومات.

عبر الـ (JavaScript)

قم بتفعيله يدوياً باستخدام:

const collapseElementList = document.querySelectorAll('.collapse')
const collapseList = [...collapseElementList].map(collapseEl => new bootstrap.Collapse(collapseEl))

خيارات

بما أنه يمكن تمرير الخيارات عبر سمات البيانات (data attributes) أو الـ JavaScript، يمكنك إضافة اسم الخيار إلى -data-bs ، كما في "data-bs-animation="{value}. تأكد من تغيير نوع حالة اسم الخيار من “camelCase” إلى “kebab-case” عند تمرير الخيارات عبر سمات البيانات. على سبيل المثال، استخدم "data-bs-custom-class="beautifier بدلاً من "data-bs-customClass="beautifier.

بدءاً من Bootstrap 5.2.0، تدعم جميع المكونات سمة بيانات محجوزة تجريبية وهي data-bs-config والتي يمكن أن تحتوي على تكوين بسيط للمكون كسلسلة JSON. عندما يحتوي العنصر على سمات 'data-bs-config='{"delay":0, "title":123} و "data-bs-title="456، ستكون قيمة title النهائية هي 456 وستقوم سمات البيانات المنفصلة بتجاوز القيم المعطاة في data-bs-config. بالإضافة إلى ذلك، يمكن لسمات البيانات الموجودة أن تحتوي على قيم JSON مثل 'data-bs-delay='{"show":0,"hide":150}.

كائن التكوين النهائي هو النتيجة المدمجة لـ data-bs-config و -data-bs و js object حيث يقوم آخر مفتاح-قيمة مُعطى بتجاوز القيم الأخرى.

الطرق، الأساليب (Methods)

يقوم بتفعيل المحتوى الخاص بك كعنصر قابل للطي. يقبل كائن object خيارات اختيارية.

يمكنك إنشاء مثيل (instance) للطي باستخدام المنشئ (constructor)، على سبيل المثال:

const bsCollapse = new bootstrap.Collapse('#myCollapse', {
  toggle: false
})

الأحداث (Events)

توفر الفئة (class) الخاصة بالطي (collapse) في الـ Bootstrap بعض الأحداث للربط مع وظائف الطي.

const myCollapsible = document.getElementById('myCollapsible')
myCollapsible.addEventListener('hidden.bs.collapse', event => {
  // do something...
})