in English

هبوط قطرة

قم بتبديل التراكبات السياقية لعرض قوائم الروابط والمزيد باستخدام البرنامج الإضافي المنسدل Bootstrap.

ملخص

القوائم المنسدلة هي تراكبات سياقية قابلة للتبديل لعرض قوائم الروابط والمزيد. لقد تم جعلها تفاعلية مع البرنامج المساعد JavaScript لقائمة Bootstrap المنسدلة. يتم تبديلهم عن طريق النقر وليس بالمرور ؛ هذا قرار تصميم مقصود .

القوائم المنسدلة مبنية على مكتبة طرف ثالث ، Popper ، والتي توفر تحديد المواقع الديناميكي واكتشاف منفذ العرض. تأكد من تضمين popper.min.js قبل JavaScript في Bootstrap أو استخدم bootstrap.bundle.min.js/ bootstrap.bundle.jsالذي يحتوي على Popper. لا يتم استخدام Popper لوضع القوائم المنسدلة في أشرطة التنقل على الرغم من أن تحديد المواقع الديناميكي غير مطلوب.

إذا كنت تقوم ببناء JavaScript من المصدر ، فهذا يتطلبutil.js .

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

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

من ناحية أخرى ، تم تصميم القوائم المنسدلة لـ Bootstrap لتكون عامة وقابلة للتطبيق على مجموعة متنوعة من المواقف وهياكل العلامات. على سبيل المثال ، من الممكن إنشاء قوائم منسدلة تحتوي على مدخلات إضافية وعناصر تحكم في النموذج ، مثل حقول البحث أو نماذج تسجيل الدخول. لهذا السبب ، لا يتوقع Bootstrap (ولا يضيف تلقائيًا) أيًا من السمات والسمات roleالمطلوبة لقوائم ARIAaria- الحقيقية . سيتعين على المؤلفين تضمين هذه السمات الأكثر تحديدًا بأنفسهم.

ومع ذلك ، يضيف Bootstrap دعمًا مضمنًا لمعظم تفاعلات قائمة لوحة المفاتيح القياسية ، مثل القدرة على التنقل عبر .dropdown-itemالعناصر الفردية باستخدام مفاتيح المؤشر وإغلاق القائمة باستخدام ESCالمفتاح.

أمثلة

قم بلف مفتاح تبديل القائمة المنسدلة (الزر أو الارتباط الخاص بك) والقائمة المنسدلة بداخله .dropdown، أو بداخله أي عنصر آخر يتم الإعلان عنه position: relative;. يمكن تشغيل القوائم المنسدلة <a>أو <button>العناصر لتناسب احتياجاتك المحتملة بشكل أفضل.

زر واحد

.btnيمكن تحويل أي منفردة إلى قائمة منسدلة للتبديل مع بعض التغييرات في الترميز. إليك كيف يمكنك وضعها للعمل مع أي من <button>العناصر:

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Dropdown button
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
  </div>
</div>

ومع <a>العناصر:

<div class="dropdown">
  <a class="btn btn-secondary dropdown-toggle" href="#" role="button" data-toggle="dropdown" aria-expanded="false">
    Dropdown link
  </a>

  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
  </div>
</div>

أفضل جزء هو أنه يمكنك القيام بذلك باستخدام أي متغير للأزرار أيضًا:

<!-- Example single danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Action
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Separated link</a>
  </div>
</div>

زر الانقسام

وبالمثل ، قم بإنشاء قوائم منسدلة لأزرار الانقسام بنفس الترميز تقريبًا مثل القوائم المنسدلة ذات الزر الفردي ، ولكن مع إضافة .dropdown-toggle-splitالتباعد المناسب حول علامة الإقحام المنسدلة.

نستخدم هذه الفئة الإضافية لتقليل الأفقي paddingعلى جانبي علامة الإقحام بنسبة 25٪ وإزالة margin-leftما تمت إضافته من أجل القوائم المنسدلة للأزرار العادية. هذه التغييرات الإضافية تحافظ على مركز علامة الإقحام في زر الانقسام وتوفر مساحة ضغط أكثر ملاءمة بجوار الزر الرئيسي.

<!-- Example split danger button -->
<div class="btn-group">
  <button type="button" class="btn btn-danger">Action</button>
  <button type="button" class="btn btn-danger dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    <a class="dropdown-item" href="#">Action</a>
    <a class="dropdown-item" href="#">Another action</a>
    <a class="dropdown-item" href="#">Something else here</a>
    <div class="dropdown-divider"></div>
    <a class="dropdown-item" href="#">Separated link</a>
  </div>
</div>

تحجيم

تعمل القوائم المنسدلة للأزرار مع الأزرار من جميع الأحجام ، بما في ذلك الأزرار المنسدلة الافتراضية والمقسمة.

<!-- Large button groups (default and split) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-lg dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Large button
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-lg" type="button">
    Large split button
  </button>
  <button type="button" class="btn btn-lg btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<!-- Small button groups (default and split) -->
<div class="btn-group">
  <button class="btn btn-secondary btn-sm dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Small button
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>
<div class="btn-group">
  <button class="btn btn-secondary btn-sm" type="button">
    Small split button
  </button>
  <button type="button" class="btn btn-sm btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

الاتجاهات

إسقاط ما يصل

تشغيل القوائم المنسدلة فوق العناصر عن طريق الإضافة .dropupإلى العنصر الأصلي.

<!-- Default dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Dropup
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

<!-- Split dropup button -->
<div class="btn-group dropup">
  <button type="button" class="btn btn-secondary">
    Split dropup
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Toggle Dropdown</span>
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

إسقاط

تشغيل القوائم المنسدلة على يمين العناصر من خلال إضافتها .droprightإلى العنصر الرئيسي.

<!-- Default dropright button -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Dropright
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

<!-- Split dropright button -->
<div class="btn-group dropright">
  <button type="button" class="btn btn-secondary">
    Split dropright
  </button>
  <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
    <span class="sr-only">Toggle Dropright</span>
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

Dropleft

تشغيل القوائم المنسدلة على يسار العناصر من خلال إضافتها .dropleftإلى العنصر الرئيسي.

<!-- Default dropleft button -->
<div class="btn-group dropleft">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Dropleft
  </button>
  <div class="dropdown-menu">
    <!-- Dropdown menu links -->
  </div>
</div>

<!-- Split dropleft button -->
<div class="btn-group">
  <div class="btn-group dropleft">
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false">
      <span class="sr-only">Toggle Dropleft</span>
    </button>
    <div class="dropdown-menu">
      <!-- Dropdown menu links -->
    </div>
  </div>
  <button type="button" class="btn btn-secondary">
    Split dropleft
  </button>
</div>

تاريخيًا ، يجب أن تكون محتويات القائمة المنسدلة عبارة عن روابط ، ولكن لم يعد هذا هو الحال مع الإصدار 4. الآن يمكنك اختياريا استخدام <button>العناصر في القوائم المنسدلة بدلاً من <a>s فقط.

<div class="dropdown">
  <button class="btn btn-secondary dropdown-toggle" type="button" data-toggle="dropdown" aria-expanded="false">
    Dropdown
  </button>
  <div class="dropdown-menu">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

يمكنك أيضًا إنشاء عناصر قائمة منسدلة غير تفاعلية باستخدام .dropdown-item-text. لا تتردد في التصميم بشكل أكبر باستخدام CSS المخصص أو الأدوات المساعدة النصية.

<div class="dropdown-menu">
  <span class="dropdown-item-text">Dropdown item text</span>
  <a class="dropdown-item" href="#">Action</a>
  <a class="dropdown-item" href="#">Another action</a>
  <a class="dropdown-item" href="#">Something else here</a>
</div>

نشيط

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

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Regular link</a>
  <a class="dropdown-item active" href="#">Active link</a>
  <a class="dropdown-item" href="#">Another link</a>
</div>

عاجز

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

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Regular link</a>
  <a class="dropdown-item disabled">Disabled link</a>
  <a class="dropdown-item" href="#">Another link</a>
</div>

بشكل افتراضي ، يتم وضع القائمة المنسدلة تلقائيًا بنسبة 100٪ من أعلى وعلى طول الجانب الأيسر من القائمة الرئيسية. أضف .dropdown-menu-rightإلى .dropdown-menuاليمين محاذاة القائمة المنسدلة.

انتباه! يتم وضع القوائم المنسدلة بفضل Popper (إلا عندما تكون موجودة في شريط التنقل).
<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false">
    Right-aligned menu
  </button>
  <div class="dropdown-menu dropdown-menu-right">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

محاذاة مستجيبة

إذا كنت تريد استخدام محاذاة سريعة الاستجابة ، فقم بتعطيل تحديد المواقع الديناميكي عن طريق إضافة data-display="static"السمة واستخدام فئات التباينات سريعة الاستجابة.

لمحاذاة القائمة المنسدلة بشكل صحيح.dropdown-menu{-sm|-md|-lg|-xl}-right مع نقطة التوقف المحددة أو الأكبر ، أضف .

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-expanded="false">
    Left-aligned but right aligned when large screen
  </button>
  <div class="dropdown-menu dropdown-menu-lg-right">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

لمحاذاة القائمة المنسدلة اليسرى.dropdown-menu-right مع نقطة التوقف المحددة أو أكبر ، قم بإضافة و .dropdown-menu{-sm|-md|-lg|-xl}-left.

<div class="btn-group">
  <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" data-display="static" aria-expanded="false">
    Right-aligned but left aligned when large screen
  </button>
  <div class="dropdown-menu dropdown-menu-right dropdown-menu-lg-left">
    <button class="dropdown-item" type="button">Action</button>
    <button class="dropdown-item" type="button">Another action</button>
    <button class="dropdown-item" type="button">Something else here</button>
  </div>
</div>

لاحظ أنك لست بحاجة إلى إضافة data-display="static"سمة إلى أزرار القائمة المنسدلة في أشرطة التنقل ، حيث لا يتم استخدام Popper في أشرطة التنقل.

الرؤوس

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

<div class="dropdown-menu">
  <h6 class="dropdown-header">Dropdown header</h6>
  <a class="dropdown-item" href="#">Action</a>
  <a class="dropdown-item" href="#">Another action</a>
</div>

المقسمات

مجموعات منفصلة من عناصر القائمة ذات الصلة بفاصل.

<div class="dropdown-menu">
  <a class="dropdown-item" href="#">Action</a>
  <a class="dropdown-item" href="#">Another action</a>
  <a class="dropdown-item" href="#">Something else here</a>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">Separated link</a>
</div>

نص

ضع أي نص حر في القائمة المنسدلة مع النص واستخدم أدوات التباعد . لاحظ أنك ستحتاج على الأرجح إلى أنماط تغيير حجم إضافية لتقييد عرض القائمة.

<div class="dropdown-menu p-4 text-muted" style="max-width: 200px;">
  <p>
    Some example text that's free-flowing within the dropdown menu.
  </p>
  <p class="mb-0">
    And this is more example text.
  </p>
</div>

نماذج

ضع نموذجًا في قائمة منسدلة ، أو اجعله في قائمة منسدلة ، واستخدم أدوات الهامش أو الحشو لمنحه المساحة السلبية التي تحتاجها.

<div class="dropdown-menu">
  <form class="px-4 py-3">
    <div class="form-group">
      <label for="exampleDropdownFormEmail1">Email address</label>
      <input type="email" class="form-control" id="exampleDropdownFormEmail1" placeholder="[email protected]">
    </div>
    <div class="form-group">
      <label for="exampleDropdownFormPassword1">Password</label>
      <input type="password" class="form-control" id="exampleDropdownFormPassword1" placeholder="Password">
    </div>
    <div class="form-group">
      <div class="form-check">
        <input type="checkbox" class="form-check-input" id="dropdownCheck">
        <label class="form-check-label" for="dropdownCheck">
          Remember me
        </label>
      </div>
    </div>
    <button type="submit" class="btn btn-primary">Sign in</button>
  </form>
  <div class="dropdown-divider"></div>
  <a class="dropdown-item" href="#">New around here? Sign up</a>
  <a class="dropdown-item" href="#">Forgot password?</a>
</div>
<form class="dropdown-menu p-4">
  <div class="form-group">
    <label for="exampleDropdownFormEmail2">Email address</label>
    <input type="email" class="form-control" id="exampleDropdownFormEmail2" placeholder="[email protected]">
  </div>
  <div class="form-group">
    <label for="exampleDropdownFormPassword2">Password</label>
    <input type="password" class="form-control" id="exampleDropdownFormPassword2" placeholder="Password">
  </div>
  <div class="form-group">
    <div class="form-check">
      <input type="checkbox" class="form-check-input" id="dropdownCheck2">
      <label class="form-check-label" for="dropdownCheck2">
        Remember me
      </label>
    </div>
  </div>
  <button type="submit" class="btn btn-primary">Sign in</button>
</form>

استخدم data-offsetأو data-referenceلتغيير موقع القائمة المنسدلة.

<div class="d-flex">
  <div class="dropdown mr-1">
    <button type="button" class="btn btn-secondary dropdown-toggle" data-toggle="dropdown" aria-expanded="false" data-offset="10,20">
      Offset
    </button>
    <div class="dropdown-menu">
      <a class="dropdown-item" href="#">Action</a>
      <a class="dropdown-item" href="#">Another action</a>
      <a class="dropdown-item" href="#">Something else here</a>
    </div>
  </div>
  <div class="btn-group">
    <button type="button" class="btn btn-secondary">Reference</button>
    <button type="button" class="btn btn-secondary dropdown-toggle dropdown-toggle-split" data-toggle="dropdown" aria-expanded="false" data-reference="parent">
      <span class="sr-only">Toggle Dropdown</span>
    </button>
    <div class="dropdown-menu">
      <a class="dropdown-item" href="#">Action</a>
      <a class="dropdown-item" href="#">Another action</a>
      <a class="dropdown-item" href="#">Something else here</a>
      <div class="dropdown-divider"></div>
      <a class="dropdown-item" href="#">Separated link</a>
    </div>
  </div>
</div>

إستعمال

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

في الأجهزة التي تعمل باللمس ، يؤدي فتح قائمة منسدلة إلى إضافة معالجات ( $.noop) فارغة mouseoverإلى العناصر الفرعية المباشرة <body>للعنصر. يعد هذا الاختراق القبيح ضروريًا للتغلب على مشكلة في تفويض حدث iOS ، والتي من شأنها أن تمنع النقر في أي مكان خارج القائمة المنسدلة من تشغيل الكود الذي يغلق القائمة المنسدلة. بمجرد إغلاق القائمة المنسدلة ، mouseoverتتم إزالة هذه المعالجات الفارغة الإضافية.

عبر سمات البيانات

أضف data-toggle="dropdown"إلى ارتباط أو زر لتبديل القائمة المنسدلة.

<div class="dropdown">
  <button type="button" data-toggle="dropdown" aria-expanded="false">
    Dropdown trigger
  </button>
  <div class="dropdown-menu">
    ...
  </div>
</div>

عبر JavaScript

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

$('.dropdown-toggle').dropdown()
data-toggle="dropdown"لا يزال مطلوبًا

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

خيارات

يمكن تمرير الخيارات عبر سمات البيانات أو JavaScript. لسمات البيانات ، قم بإلحاق اسم الخيار بـ data-، كما في data-offset="".

اسم يكتب تقصير وصف
عوض رقم | سلسلة | وظيفة 0

إزاحة القائمة المنسدلة بالنسبة إلى هدفها.

عند استخدام دالة لتحديد الإزاحة ، يتم استدعاؤها بكائن يحتوي على بيانات الإزاحة كوسيطة أولى لها. يجب أن تقوم الوظيفة بإرجاع كائن بنفس البنية. يتم تمرير عقدة DOM المشغلة كوسيطة ثانية.

لمزيد من المعلومات راجع مستندات تعويض Popper .

يواجه قيمة منطقية حقيقي اسمح لقلب القائمة المنسدلة في حالة تداخل العنصر المرجعي. لمزيد من المعلومات ، راجع مستندات Popper's flip .
الحدود سلسلة | عنصر "scrollParent" تجاوز حدود القيد من القائمة المنسدلة. يقبل قيم 'viewport'، 'window'أو 'scrollParent'، أو مرجع HTMLElement (JavaScript فقط). لمزيد من المعلومات ، راجع مستندات Popper 's PreventionOverflow .
المرجعي سلسلة | عنصر "تبديل" عنصر مرجعي من القائمة المنسدلة. يقبل قيم 'toggle'، 'parent'أو مرجع HTMLElement. لمزيد من المعلومات ، راجع مستندات Popper's referenceObject .
عرض سلسلة 'متحرك' بشكل افتراضي ، نستخدم Popper لتحديد المواقع الديناميكي. تعطيل هذا باستخدام static.
popperConfig فارغ | هدف لا شيء لتغيير تكوين Popper الافتراضي الخاص بـ Bootstrap ، راجع تكوين Popper

لاحظ boundaryأنه عند التعيين على أي قيمة بخلاف ، يتم تطبيق 'scrollParent'النمط على الحاوية.position: static.dropdown

طُرق

طريقة وصف
$().dropdown('toggle') لتبديل القائمة المنسدلة لشريط تنقل محدد أو التنقل المبوب.
$().dropdown('show') يعرض القائمة المنسدلة لشريط التنقل المحدد أو التنقل المبوب.
$().dropdown('hide') يخفي القائمة المنسدلة لشريط تنقل معين أو تنقل مبوب.
$().dropdown('update') يحدّث موضع القائمة المنسدلة للعنصر.
$().dropdown('dispose') يدمر القائمة المنسدلة لعنصر.

الأحداث

يتم تشغيل جميع أحداث القائمة المنسدلة على .dropdown-menuالعنصر الرئيسي للعنصر ولها relatedTargetخاصية قيمتها عنصر الربط. hide.bs.dropdownوالأحداث hidden.bs.dropdownلها clickEventخاصية (فقط عندما يكون نوع الحدث الأصلي click) تحتوي على كائن حدث لحدث النقر.

حدث وصف
show.bs.dropdown يتم تشغيل هذا الحدث فورًا عند استدعاء طريقة إظهار المثيل.
shown.bs.dropdown يتم تشغيل هذا الحدث عندما تصبح القائمة المنسدلة مرئية للمستخدم (سينتظر حتى تكتمل انتقالات CSS).
hide.bs.dropdown يتم تشغيل هذا الحدث فورًا عند استدعاء طريقة إخفاء المثيل.
hidden.bs.dropdown يتم تشغيل هذا الحدث عندما تنتهي القائمة المنسدلة من إخفاء المستخدم (سينتظر حتى تكتمل انتقالات CSS).
$('#myDropdown').on('show.bs.dropdown', function () {
  // do something...
})