القوائم المنسدلة Dropdowns في إطار العمل Bootstrap

أظهر تراكيب سياقيّة لعرض قوائم روابط أو غيرها من العناصر باستخدام مُلحَق القوائم المنسدلة Dropdowns في إطار العمل Bootstrap.

نظرة عامّة

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

تُبنَى القوائم المنسدلة على مكتبة Popper.js التي توفّر تموضعًا ديناميكيًّا للعناصر واكتشاف إطار العرض Viewport. تأكّد من إضافة popper.min.js قبل شفرة JavaScript الخاصّة بإطار العمل Bootstrap أو استخدم bootstrap.bundle.min.js أو bootstrap.bundle.js اللذين يتضمّنان Popper.js. لا تُستخدَم مكتبة Popper.js لتموضع القوائم المنسدلة ضمن شريط التصفّح، إذ أنّ التموضع الديناميكي ليس مطلوبًا في هذه الحالة.

انتبه إنْ كنت تبني JavaScript من المصدر إلى أنّ مُلحَق القوائم المنسدلة يتطلّب مكتبة util.js.

سهولة الوصول

يعرّف معيار WAI ARIA مربّعًا جانبيًّا بالخاصيّة role="menu"‎، إلّا أنّها خاصّة القوائم الشبيهة بالتطبيقات والتي تتسبّب في إجراءات أو في تنفيذ دوالّ. لا يمكن أن تتضمّن القوائم التي تستجيب للمعيار ARIA سوى عناصر القائمة، وصناديق التأشير، وأزرار الانتقاء، ومجموعات الانتقاء والقوائم الفرعيّة.

صُمِّمت القوائم المنسدلة في إطار العمل Bootstrap لتكون عامّة ويمكن استخدامها في حالات متعدّدة وفي هياكل وسوم مختلفة. يمكن - على سبيل المثال - إنشاء قوائم منسدلة تحتوي على مُدخَلات إضافيّة وعناصر تحكّم في الاستمارات، مثل حقول البحث واستمارات تسجيل الدخول. لهذا السبب لا يفترض إطار العمل Bootstrap (ولا يضيف تلقائيًّا) أيًّا من الخاصيّات role و aria-‎ المطلوبة في القوائم المتوافقة تمامًا مع المعيار ARIA. سيحتاج المطوّرون ومعدّو المحتوى لإضافة الخاصيّات المذكورة الأكثر تخصيصًا بأنفسهم.

رغم ذلك، يضيف إطار العمل Bootstrap مبدئيًّا دعمَ معظم التفاعلات الاعتياديّة بين لوحة المفاتيح والقوائم، مثل إمكانيّة التنقّل بين عناصر القائمة المنسدلة باستخدام الأسهُم في لوحة المفاتيح وإغلاقها بمفتاح الهروب <kbd>ESC</kbd>.

أمثلة

غلِّف الرابط - أو الزرّ - الذي يفتح القائمة المنسدلة والقائمة المنسدلة نفسها ضمن الصنف ‎.dropdown، أو أيّ عنصُر آخر يعرّف الخاصيّة position: relative;‎. يمكن فتح القوائم المنسدلة بالعنصُر <a> أو <button> حسب ما يلائم احتيّاجاتك.

قوائم منسدلة ذات زر مُجمَّع

يمكن - ببعض التغييرات - تحويل زرّ واحد (‎.btn) إلى عنصُر لعرض قائمة منسدلة. في ما يلي كيف تجعلها تعمل مع الأزرار:

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenuButton" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    زرّ لقائمة منسدلة
  </button>
  <div class="dropdown-menu" aria-labelledby="dropdownMenuButton">
    <a class="dropdown-item" href="#">إجراء</a>
    <a class="dropdown-item" href="#">إجراء آخر</a>
    <a class="dropdown-item" href="#">أمر آخر</a>
  </div>
</div>

كما يمكن استخدام عناصر <a> :

<div class="dropdown show">
  <a class="btn btn-secondary dropdown-toggle" href="#" role="button" id="dropdownMenuLink" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    رابط لقائمة منسدلة
  </a>

  <div class="dropdown-menu" aria-labelledby="dropdownMenuLink">
    <a class="dropdown-item" href="#">إجراء</a>
    <a class="dropdown-item" href="#">إجراء آخر</a>
    <a class="dropdown-item" href="#">أمر آخر</a>
  </div>
</div>

كما يمكن استخدام أيّ من تنويعات الأزرار:

<!-- مثال على استخدام زرّ خطر لعرض قائمة منسدلة -->
<div class="btn-group">
  <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    إجراء
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">إجراء</a>
    <a class="dropdown-item" href="#">إجراء آخر</a>
    <a class="dropdown-item" href="#">أمر آخر</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">رابط منفصل</a>
  </div>
</div>

قوائم منسدلة بزر مُجتَزَأ

يمكن على نحو مشابه إنشاء زرّ مُجتَزَأ (السهم لوحده، دون النصّ) باستخدام نفس الشفرة المستخدمة لزرّ مُجمَّع تقريبًا، مع إضافة الصنف ‎.dropdown-toggle-split لترك مساحة مناسبة حول السهم في الزرّ.

يُستخدَم هذا الصنف لخفض الحاشيّات (padding) الأفقيّة حول السهم بنسبة 25% وحذف الهامش الأيسر (margin-left) الذي يُضاف إلى زرّ القائمة المنسدلة الاعتيّاديّ. تحافظ هذه التعديلات على السهم في وسط الزرّ المُجتَزّأ وتُوفّر مساحة ذات قياس مناسب للنقر إلى جانب الزرّ الرئيسي.

<!-- مثال على استخدام زرّ خطر مُجتَزَأ لعرض قائمة منسدلة -->
<div class="btn-group">
  <button type="button" class="btn btn-danger">إجراء</button>
  <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">فتح القائمة المنسدلة</span>
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">إجراء</a>
    <a class="dropdown-item" href="#">إجراء آخر</a>
    <a class="dropdown-item" href="#">أمر آخر</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">رابط منفصل</a>
  </div>
</div>

تحديد الأبعاد

تعمل القوائم المنسدلة مع الأزرار من جميع القيّاسات، سواء تعلّق الأمر بأزرار مُجمَّعة أو مُجتَزَأة.

<!-- أزرار عريضة (مُجمَّعة ومُجتَزَأة) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    زرّ عريض
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-lg" type="button">
    زرّ مُجتَزَأ عريض
  </button>
  <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">فتح القائمة المنسدلة</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

<!-- أزرار صغيرة (مُجمَّعة ومُجتَزَأة) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    زرّ صغير
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-sm" type="button">
    زرّ صغير مُجتَزَأ
  </button>
  <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">فتح القائمة المنسدلة</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

القوائم المنسدلة إلى الأعلى

يجعل الصنف ‎.dropup عند إضافته للعنصُر الأب القائمة تتّجه إلى الأعلى عند النقر على الزرّ أو الرابط.

<!-- زرّ مُجمَّع لعرض القائمة -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    فتح القائمة إلى الأعلى
  </button>
  <div class="dropdown-menu">
    <!-- روابط القائمة المنسدلة -->
  </div>
</div>

<!-- زرّ مُجزَّأ لعرض القائمة في الأعلى -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary">
    فتح القائمة إلى الأعلى
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">فتح القائمة المنسدلة</span>
  </button>
  <div class="dropdown-menu">
    <!-- روابط القائمة المنسدلة -->
  </div>
</div>

القوائم المنسدلة إلى اليمين

اجعل عناصر القائمة تُفتَح يمين الزرّ بإضافة الصنف ‎.dropright إلى العنصُر الأب.

<!-- الزرّ المبدئي لعرض القائمة إلى اليمين -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    فتح القائمة باتجاه اليمين
  </button>
  <div class="dropdown-menu">
    <!-- روابط القائمة المنسدلة -->
  </div>
</div>

<!-- زرّ مُجتَزأ لعرض القائمة إلى اليمين -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary">
    فتح القائمة باتجاه اليمين
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    <span class="sr-only">فتح القائمة باتجاه اليمين</span>
  </button>
  <div class="dropdown-menu">
    <!-- روابط القائمة المنسدلة -->
  </div>
</div>

القوائم المنسدلة إلى اليسار

اجعل عناصر القائمة تُفتَح يمين الزرّ بإضافة الصنف ‎.dropleft إلى العنصُر الأب.

<!-- الزرّ المبدئيّ لعرض القائمة إلى اليسار -->
<div class="btn-group dropleft">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    فتح القائمة باتجاه اليسار
  </button>
  <div class="dropdown-menu">
    <!-- روابط القائمة المنسدلة -->
  </div>
</div>

<!-- زرّ مُجتَزَأ لعرض القائمة إلى اليسار -->
<div class="btn-group">
  <div class="btn-group dropleft" role="group">
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
      <span class="sr-only">فتح القائمة باتجاه اليسار</span>
    </button>
    <div class="dropdown-menu">
      <!-- روابط القائمة المنسدلة -->
    </div>
  </div>
  <button type="button" class="btn btn-secondary">
    فتح القائمة باتجاه اليسار
  </button>
</div>

عناصر القائمة

كان مطلوبًا في الماضي أن تكون محتويات القوائم المنسدلة روابط، إلّا أنّ الأمر تغيّر مع الإصدار 4 من إطار العمل Bootstrap. يمكن الآن استخدام عناصر <button> في القوائم المنسدلة بدلًا من الروابط (<a>) لوحدها.

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" id="dropdownMenu2" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    قائمة منسدلة
  </button>
  <div class="dropdown-menu" aria-labelledby="dropdownMenu2">
    <button class="dropdown-item" type="button">إجراء</button>
    <button class="dropdown-item" type="button">إجراء آخر</button>
    <button class="dropdown-item" type="button">أمر آخر</button>
  </div>
</div>

محاذاة القائمة

توضَع القوائم المنسدلة مبدئيًّا على مسافة 100% من أعلى العنصُر الأب، باتّجاه اليسار. أضف الصنف ‎.dropdown-menu-right إلى القائمة المنسدلة (‎.dropdown-menu) لمحاذاتها إلى اليمين.

تنبيه: تُحدَّد وضعيّة القوائم المنسدلة بفضل Popper.js (باستثناء عندما تكون في شريط التنقّل ‎.navbar).

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    قائمة محاذاة إلى اليمين
  </button>
  <div class="dropdown-menu dropdown-menu-right">
    <button class="dropdown-item" type="button">إجراء</button>
    <button class="dropdown-item" type="button">إجراء آخر</button>
    <button class="dropdown-item" type="button">أمر آخر</button>
  </div>
</div>

ترويسات القائمة

أضف ترويسة لعنونة مجموعات إجراءات في أي قائمة منسدلة.

<div class="dropdown-menu">
  <h6 class="dropdown-header">ترويسة قائمة منسدلة</h6>
  <a class="dropdown-item" href="#">إجراء</a>
  <a class="dropdown-item" href="#">إجراء آخر</a>
</div>

الفواصل بين عناصر القوائم

استخدم فاصلًا للفصل بين عناصر القائمة المترابطة.

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">إجراء</a>
  <a class="dropdown-item" href="#">إجراء آخر</a>
  <a class="dropdown-item" href="#">أمر آخر</a>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">رابط منفصل</a>
</div>

الاستمارات في القوائم المنفصلة

ضع استمارةً داخل قائمة منسدلة أو أنشئها داخلها ثم استخدم أدوات الحاشيّات أو الهوامش لإعطائها التباعد التي تريد.

<div class="dropdown-menu">
  <form class="px-4 py-3">
    <div class="form-group">
      <label for="exampleDropdownFormEmail1">البريد الإلكتروني</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="email@example.com">
    </div>
    <div class="form-group">
      <label for="exampleDropdownFormPassword1">كلمة السرّ</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="كلمة السرّ">
    </div>
    <div class="form-check">
      <input type="checkbox" class="form-check-input" id="dropdownCheck">
      <label class="form-check-label" for="dropdownCheck">
        تذكّرني
      </label>
    </div>
    <button type="submit" class="btn btn-primary">سجّل الدخول</button>
  </form>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">جديد على الموقع؟ سجّل هنا</a>
  <a class="dropdown-item" href="#">نسيت كلمة السرّ؟</a>
</div>

<form class="dropdown-menu p-4">
  <div class="form-group">
    <label for="exampleDropdownFormEmail2">البريد الإلكترونيّ</label>
    <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="email@example.com">
  </div>
  <div class="form-group">
    <label for="exampleDropdownFormPassword2">كلمة السرّ</label>
    <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="كلمة السرّ">
  </div>
  <div class="form-check">
    <input type="checkbox" class="form-check-input" id="dropdownCheck2">
    <label class="form-check-label" for="dropdownCheck2">
      تذكّرني
    </label>
  </div>
  <button type="submit" class="btn btn-primary">سجّل الدخول</button>
</form>

العناصر النشطة في القائمة

أضف الصنف ‎.active إلى العناصر في قائمة منسدلة لتنسيقها بالنمط النشط.

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">رابط عاديّ</a>
  <a class="dropdown-item active" href="#">رابط نشط</a>
  <a class="dropdown-item" href="#">رابط آخر</a>
</div>

العناصر المُعطَّلة في القائمة

أضف الصنف ‎.disabled إلى العناصر في قائمة منسدلة لتنسيقها بالنمط الخامل (عنصُر مُعطَّل).

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">رابط اعتيّاديّ</a>
  <a class="dropdown-item disabled" href="#">رابط خامل</a>
  <a class="dropdown-item" href="#">رابط آخر</a>
</div>

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

يبدّل مُلحَق JavaScript - عن طريق شفرة JavaScript أو بخاصيّات البيانات (data attributes) - حالة المحتوى المخفيّ (القوائم المنسدلة) بتطبيق - أو حذف - الصنف ‎.show على عنصُر القائمة الأب. يُعتمَد على الخاصيّة data-toggle="dropdown"‎ لإغلاق القائمة المنسدلة على مستوى التطبيق، لذا من الجيّد استخدامها دومًا.

تنبيه حول شاشات اللّمس:

ينتُج عن فتح قائمة منسدلة على أجهزة بشاشات لمس إضافةُ معالجات الأحداث ‎(‎$.noop)‎ mouseover ‎إلى العناصر الأبناء المباشرين للعنصُر <body>. هذا الترقيع (التعيس) ضروريّ للحيلولة دون مشكلة في تفويض الأحداث (event delegation) على iOS تتسبّب في منع أي ضغطة خارج القائمة المنسدلة من تشغيل الشيفرة التي تُغلق القائمة المنسدلة. تُحذَف هذه المعالجات الفارغة الإضافيّة بعد إغلاق القائمة المنسدلة.

استخدام المُلحَق عن طريق خاصيّات البيانات

أضف الخاصيّة data-toggle="dropdown"‎ إلى زرّ أو رابط لجعله يظهر أو يخفي قائمة منسدلة.

<div class="dropdown">
  <button id="dLabel" type="button" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">
    زرّ القائمة المنسدلة
  </button>
  <div class="dropdown-menu" aria-labelledby="dLabel">
    ...
  </div>
</div>

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

استدعاء القوائم المنسدلة بشفرة JavaScript:

$('.dropdown-toggle').dropdown()

`data-toggle="dropdown"‎` ما تزال مطلوبةً

بغضّ النظر عن طريقة استدعاء القوائم المنسدلة - خاصيّات البيانات أو شفرة JavaScript - فإنّ وجود الخاصيّة data-toggle="dropdown"‎ على عنصُر الإظهار والإخفاء مطلوب دائمًا.

الخيارات

يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق JavaScript. ألحق اسم الخيّار بالكلمة data-‎ (مثلًا data-offset=""‎ للخيّار offset) عند التمرير عبر خاصيّات البيانات.

الاسم	النوع	لقيمة المبدئيّة	الوصف
`offset` (الإزاحة)	سلسلة محارف \| دالّة	`0`	انزياح القائمة المنسدلة بالنسبة إلى هدفها. راجع توثيق Popper.js للمزيد من المعلومات.
`flip` (القلب)	قيمة منطقيّة	`true`	يسمح للقائمة المنسدلة بالانقلاب في حال التراكب مع العنصُر المرجع. راجع توثيق Popper.js للمزيد من المعلومات.
`boundary` (الحدود)	عنصُر	`'scrollParent'`	تجاوز قيد الحدود المفروض على القائمة المنسدلة. يقبل القيّم `'viewport'`، و `'window'`، و `'scrollParent'`, أو مرجعًا لعنصُر HTML (في شفرة JavaScript فقط). راجع راجع توثيق Popper.js للمزيد من المعلومات.

يُرجى الانتباه إلى أنّ النمط position: static يُطبَّق على حاويّة القائمة المنسدلة عند تعيين أي قيمة ما عدا 'scrollParent' للخاصيّة boundary.

التوابع

التابع	الوصف
`‎$().dropdown('toggle')‎`	يُظهر أو يخفي القائمة المنسدلة في شريط تنقّل أو عناصر تنقّل مُبوَّبة.
`‎$().dropdown('update')‎`	يحدّث وضعيّة القائمة المنسدلة في عنصُر
`‎$().dropdown('dispose')‎`	يحذف القائمة المنسدلة.

الأحداث

تُطلَق جميع الأحداث المرتبطة بالقوائم المنسدلة على مستوى عنصُر ‎.dropdown-menu الأب ولديها الخاصيّة relatedTarget التي تكون قيمتها وسم العنصُر الذي تسبّب في الحدث.

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

$('#myDropdown').on('show.bs.dropdown', function () {
  // افعل شيئًا هنا …
})

مصادر

صفحة Dropdowns في توثيق Bootstrap.