Bootstrap/modal

استخدم ملحَق JavaScript الخاصّ بالنوافذ الشرطيّة Modal لإضافة حوارات على شكل صناديق خفيفة إلى موقعك، أو إشعارات أو محتوى مُخصَّص بالكامل.

1. كيفيّة العمل

تأكّد من قراءة الفقرات التاليّة قبل البدء في استخدام مكوِّن النوافذ الشرطيّة في إطار العمل Bootstrap، إذ أنّ خيّارات القوائم عُدِّلت في الإصدارات الأخيرة.

تُنشَأ النوافذ الشرطية باستخدام HTML، وCSS وJavaScript. تتموضع النوافذ الشرطيّة فوق مكوِّنات الصفحة جميعها وتحذف قابليّة التمرير من متن الصفحة (<body>) بحيث يُمرَّر محتوى النافذة الشرطيّة بدلًا من المتن.
تُغلَق النافذة الشرطيّة فور النقر على زر التراجع.
لا يدعم إطار العمل Bootstrap سوى نافذة شرطيّة واحدة في كلّ مرة؛ كما أنّه لا يدعم النوافذ الشرطيّة المتداخلة (نافذة شرطيّة داخل نافذة شرطيّة) ويعدّها تجربة مستخدم سيّئة.
تستخدم النوافذ الشرطيّة الخاصيّة position: fixed التي قد تكون أحيانًا فريدة في طريقة عرضها. حاول قدر المستطاع وضع شفرة HTML الخاصّة بالنافذة الفرعيّة في مستوى علويّ لتفادي التداخل المُحتمل مع العناصر الأخرى. من المحتمل جدًّا أن يتسبّب وضع النافذة الشرطيّة (‎.modal) داخل عنصُر ثابت آخر في مشاكل.
توجد بعض العراقيل في استخدام النوافذ الشرطيّة على الأجهزة الجوّالة، نظرًا - مُجدَّدًا - لاستخدام الخاصيّةposition: fixed. راجع صفحة دعم المتصفّحات والأجهزة للمزيد من التفاصيل.
لا يؤثّر عنصُر autofocus في HTML على النوافذ الشرطيّة في Bootstrap، نظرًا لكون HTML5 يعرّف معنى دلاليًّا له. استخدم شفرة JavaScript مُخصَّصة للحصول على نفس التأثير.

$('#myModal').on('shown.bs.modal', function () {
  $('#myInput').trigger('focus')
})

واصل القراءة للحصول على أمثلة توضيحية وقواعد استخدام مكوِّن النوافذ الشرطيّة في Bootstrap.

أمثلة

مكوِّنات شرطيّة

يوجد أدناه مثال لنافذة شرطيّة ثابتة Static (بمعنى أنّ قيمتيْ الخاصيّتيْن position و display مُبطلتان). تتضمّن هذه النافذة الشرطيّة ترويسة، ومتنًا (مطلوبًا للحاشيّة padding) وتذييلًا (اختيّاري). يقترح مطوّرو Bootstrap تضمين إجراءات تجاهل (إخفاء النافذة) في الترويسة كلّ ما كان ذلك ممكنًا، أو توفير طريقة أخرى صريحة لإجراء التجاهل.

<div class="modal" tabindex="-1" role="dialog">
  <div class="modal-dialog" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title">عنوان النافذة الشرطيّة</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
        <p>يوجد هنا محتوى النافذة الشرطيّة النصّي</p>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-primary">احفظ التغييرات</button>
        <button type="button" class="btn btn-secondary" data-dismiss="modal">أغلق</button>
      </div>
    </div>
  </div>
</div>

مثال عمليّ

جرّب الشفرة التاليّة وستحصُل على زرّ يمكّن النقر عليه من عرض نافذة شرطيّة تنزل من أعلى الصفحة ثم يخفُت التأثير عليها.

<!-- زرّ إظهار النافذة الشرطيّة -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal">
  أظهر النافذة الشرطيّة
</button>

<!-- النافذة الشرطيّة -->
<div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
  <div class="modal-dialog" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalLabel">عنوان النافذة الشرطيّة</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
        نصّ في متن النافذة الشرطيّة
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-dismiss="modal">أغلق</button>
        <button type="button" class="btn btn-primary">احفظ التعديلات</button>
      </div>
    </div>
  </div>
</div>

تمرير محتوى طويل

عندما تصبح النافذة الشرطيّة طويلة جدًّا بالنسبة لإطار العرض أو الجهاز فإنها تكون مستقلّة عن الصفحة في تمرير المحتوى. جرّب المثال التالي لتفهم المقصود.

<!-- زرّ إظهار النافذة الشرطيّة -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModalLong">
  أظهر النافذة الشرطيّة
</button>

<!-- النافذة الشرطيّة -->
<div class="modal fade" id="exampleModalLong" tabindex="-1" role="dialog" aria-labelledby="exampleModalLongTitle" aria-hidden="true">
  <div class="modal-dialog" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalLongTitle">عنوان النافذة الشرطيّة</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-dismiss="modal">أغلق</button>
        <button type="button" class="btn btn-primary">احفظ التعديلات</button>
      </div>
    </div>
  </div>
</div>

توسيط النوافذ الشرطيّة عموديا

أضف الصنف ‎.modal-dialog-centered إلى ‎.modal-dialog لتوسيط النافذة الشرطيّة عموديّا.

<!-- زرّ إظهار النافذة الشرطيّة -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModalCenter">
  أظهر النافذة الشرطيّة
</button>

<!-- النافذة الشرطيّة -->
<div class="modal fade" id="exampleModalCenter" tabindex="-1" role="dialog" aria-labelledby="exampleModalCenterTitle" aria-hidden="true">
  <div class="modal-dialog modal-dialog-centered" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalLongTitle">عنوان النافذة الشرطيّة</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
        <p>
      أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ أبجد هوز حطي كلمن سعفص قرشت ثخذ ضظغ.
      <p/>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-dismiss="modal">أغلق</button>
        <button type="button" class="btn btn-primary">احفظ التغييرات</button>
      </div>
    </div>
  </div>
</div>

التلميحات Tooltips والعناصر المنبثقة Popovers

يمكن وضع التلميحات والعناصر المنبثقة داخل نافذة شرطيّة. تُلغى جميع التلميحات والعناصر المنبثقة تلقائيًّا بعد إغلاق النافذة الشرطيّة.

<!-- زرّ إظهار النافذة الشرطيّة -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModalCenter">
  أظهر النافذة الشرطيّة
</button>

<!-- النافذة الشرطيّة -->
<div class="modal fade" id="exampleModalCenter" tabindex="-1" role="dialog" aria-labelledby="exampleModalCenterTitle" aria-hidden="true">
  <div class="modal-dialog modal-dialog-centered" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalLongTitle">عنوان النافذة الشرطيّة</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
    <div class="modal-body">
    <h5>عنصُر منبثق ضمن نافذة شرطيّة</h5>
    <p>هذا <a href="#" role="button" class="btn btn-secondary popover-test" title="عنوان العنصُر المنبثق" data-content="يُعيَّن محتوى متن العنصُر المنبثق في هذه الخاصيّة">الزرّ</a> يُظهر عنصرًا منبثقا.</p>
    <hr>
    <h5>تلميحات في نافذة شرطيّة</h5>
    <p><a href="#" class="tooltip-test" title="تلميحة">هذا الرابط</a> و <a href="#" class="tooltip-test" title="تلميحة">هذا الرابط</a> تظهر عليهما تلميحات عند الحومان.</p>
    </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-dismiss="modal">أغلق</button>
        <button type="button" class="btn btn-primary">احفظ التغييرات</button>
      </div>
    </div>
  </div>
</div>

استخدام نظام الشبكة

يؤدّي تضمين الصنف ‎.container-fluid داخل نافذة شرطيّة (‎.modal-body) إلى تفعيل نظام الشبكة في Bootstrap على مستوى النافذة الشرطيّة. يمكن بعدها استخدام أصناف نظام الشبكة بالطريقة الاعتيّاديّة.

<div class="modal-body">
  <div class="container-fluid">
    <div class="row">
      <div class="col-md-4">.col-md-4</div>
      <div class="col-md-4 ml-auto">.col-md-4 .ml-auto</div>
    </div>
    <div class="row">
      <div class="col-md-3 ml-auto">.col-md-3 .ml-auto</div>
      <div class="col-md-2 ml-auto">.col-md-2 .ml-auto</div>
    </div>
    <div class="row">
      <div class="col-md-6 ml-auto">.col-md-6 .ml-auto</div>
    </div>
    <div class="row">
      <div class="col-sm-9">
        Level 1: .col-sm-9
        <div class="row">
          <div class="col-8 col-sm-6">
            Level 2: .col-8 .col-sm-6
          </div>
          <div class="col-4 col-sm-6">
            Level 2: .col-4 .col-sm-6
          </div>
        </div>
      </div>
    </div>
  </div>
</div>

تنويع محتوى النافذة الشرطيّة

استخدم الخاصيّة event.relatedTarget وخاصيّات data-‎*‎ في HTML (يمكن استخدام [ https://api.jquery.com/data jQuery لهذا الغرض]) لتنويع محتوى النافذة الشرطيّة حسب الزّر الذي تسبّب في عرض النافذة.

<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@mdo">افتح نافذة الشرطيّة للمستلم @mdo</button>
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@fat">افتح نافذة الشرطيّة للمستلم @fat</button>
<button type="button" class="btn btn-primary" data-toggle="modal" data-target="#exampleModal" data-whatever="@getbootstrap">افتح نافذة الشرطيّة للمستلم @getbootstrap</button>

<div class="modal fade" id="exampleModal" tabindex="-1" role="dialog" aria-labelledby="exampleModalLabel" aria-hidden="true">
  <div class="modal-dialog" role="document">
    <div class="modal-content">
      <div class="modal-header">
        <h5 class="modal-title" id="exampleModalLabel">رسالة جديدة</h5>
        <button type="button" class="close" data-dismiss="modal" aria-label="Close">
          <span aria-hidden="true">&times;</span>
        </button>
      </div>
      <div class="modal-body">
        <form>
          <div class="form-group">
            <label for="recipient-name" class="col-form-label">المستلِم:</label>
            <input type="text" class="form-control" id="recipient-name">
          </div>
          <div class="form-group">
            <label for="message-text" class="col-form-label">الرسالة:</label>
            <textarea class="form-control" id="message-text"></textarea>
          </div>
        </form>
      </div>
      <div class="modal-footer">
        <button type="button" class="btn btn-secondary" data-dismiss="modal">أغلق</button>
        <button type="button" class="btn btn-primary">أرسل الرسالة</button>
      </div>
    </div>
  </div>
</div>

$('#exampleModal').on('show.bs.modal', function (event) {
  var button = $(event.relatedTarget) // الزرّ الذي أظهر النافذة الشرطيّة
  var recipient = button.data('whatever') // استخراج المعلومات من الخاصيّات data-* 
  // يمكن إنْ اقتضت الحاجة بدْء طلب AJAX هنا (ثم تحديث المحتوى عبر تابع الرد Callback).
  // تحديث محتوى النافذة الشرطيّة. نستخدم jQuery هنا، إلّا أنه يمكن استخدام مكتبة ربط من طرف ثالث أو توابع أخرى 
  var modal = $(this)
  modal.find('.modal-title').text('رسالة جديدة إلى ' + recipient)
  modal.find('.modal-body input').val(recipient)
})

حذف التحريكات

تحصُل بحذف ‎.fade الصنف على نافذة شرطيّة تظهر دون تأثير الخفوت والنزول من أعلى الشاشة.

<div class="modal" tabindex="-1" role="dialog" aria-labelledby="..." aria-hidden="true">
  ...
</div>

ارتفاعات ديناميكيّة

يؤدّي استخدام التابع ‎$('#myModal').modal('handleUpdate') عند تغيّر ارتفاع النافذة الشرطيّة إلى إعادة تموضعها في حال ظهور شريط التمرير.

سهولة الوصول

تأكّد من إضافة الخاصيّتين role="dialog"‎ و aria-labelledby="..."‎ (قيمة الخاصيّة الأخيرة هي عنوان النافذة الشرطيّة) إلى ‎.modal والخاصيّة role="document"‎ إلى ‎.modal-dialog. يمكن علاوة على ذلك إضافة وصف للنافذة الشرطيّة ضمن الخاصيّة aria-describedby في الصنف ‎.modal.

تضمين فيديوهات من YouTube

يحتاج تضمين فيديوهات من YouTube في نوافذ شرطيّة إلى شفرة JavaScript إضافيّة - لا تتوفّر في Bootstrap - بهدف التوفّر على وظائف مثل إيقاف الفيديو وغيرها. راجع هذا المنشور المفيد على موقع Stack Overflow للمزيد من المعلومات.

الأبعاد الاختيّاريّة

يوجد قيّاسان اختيّاريّان متوفّران عبر صنفيْن مُعدِّليْن يوضعان مع الصنف ‎.modal-dialog. يرتدّ هذان القيّاسان في بعض النقاط الحديّة للحيلولة دون ظهور شريط تمرير أفقيّ في الأجهزة ذات الشاشات الضيّقة.

<!-- نافذة شرطيّة كبيرة -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-lg">نافذة شرطيّة كبيرة</button>

<div class="modal fade bd-example-modal-lg" tabindex="-1" role="dialog" aria-labelledby="myLargeModalLabel" aria-hidden="true">
  <div class="modal-dialog modal-lg">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

<!-- نافذة شرطيّة صغيرة -->
<button type="button" class="btn btn-primary" data-toggle="modal" data-target=".bd-example-modal-sm">نافذة شرطيّة صغيرة</button>

<div class="modal fade bd-example-modal-sm" tabindex="-1" role="dialog" aria-labelledby="mySmallModalLabel" aria-hidden="true">
  <div class="modal-dialog modal-sm">
    <div class="modal-content">
      ...
    </div>
  </div>
</div>

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

يبدّل مُلحَق JavaScript المحتوى المخفي حسب الحاجة، باستخدام خاصيّات البيانات أو شفرة JavaScript مُخصَّصة. كما يضيف هذا المُلحَق الصنف ‎.modal-open إلى متن الصفحة (<body>) لإبطال إمكانيّة التمرير المبدئيّة عليه عند عرض النافذة الشرطيّة ويولّد الصنف ‎.modal-backdrop لتوفير مساحة نقر لتجاهل النوافذ الشرطيّة عند النقر خارج النافذة الشرطيّة.

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

يمكن تفعيل نافذة شرطيّة بدون كتابة شفرة JavaScript مُخصَّصة بتعيين الخاصيّة data-toggle="modal"‎ على عنصُر تحكّم - زرّ مثلًا - مع تعيين الخاصيّة data-target="#foo"‎ أو href="#foo"‎ لاستهداف نافذة شرطيّة مُعيَّنة لإظهارها (أو إخفائها).

<button type="button" data-toggle="modal" data-target="#myModal">افتح النافذة الشرطيّة</button>

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

يكفي سطرُ JavaScript واحد لاستدعاء نافذة شرطيّة ذات المُعرِّف myModal:

$('#myModal').modal(options)

الخيّارات

يمكن تمرير الخيّارات عبر خاصيّات البيانات أو باستخدام شفرة JavaScript مُخصَّصة. ألصق اسم الخيّار بـ ‎data-‎ (data-backdrop="") لتمريره باستخدام خاصيّات البيانات.

التوابع

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

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

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

`‎.modal(options)`

ينشئ نافذة شرطيّة اعتمادًا على المحتوى الذي يُطبَّق عليه. يقبل كائن خيّارات اختيّاري.

$('#myModal').modal({
  keyboard: false
})

`‎.modal('toggle')`

يُظهر - أو يخفي - النافذة شرطيّة. يعود إلى المستدعِي قبل أن تُعرَض النافذة الشرطيّة أو تُخفَى (أي قبل وقوع الحدث shown.bs.modal أو hidden.bs.modal).

$('#myModal').modal('toggle')

`‎.modal('show')`

يُظهر نافذة شرطيّة. يعود إلى المستدعِي قبل أن تُعرَض النافذة الشرطيّة (أي قبل وقوع الحدث shown.bs.modal).

$('#myModal').modal('show')

`‎.modal('hide')`

يعود إلى المستدعِي قبل أن تُخفَى النافذة الشرطيّة (أي قبل وقوع الحدث hidden.bs.modal).

$('#myModal').modal('hide')

`‎.modal('handleUpdate')`

يعدّل موضع النافذة الشرطيّة عند تغيّر ارتفاعها أثناء عرضها (بمعنى عند ظهور شريط التمرير).

$('#myModal').modal('handleUpdate')

`‎.modal('dispose')`

يحذف عنصُر النافذة الشرطيّة.

الأحداث

يعرض صنف النوافذ الشرطيّة في إطار العمل Bootstrap بضعة أحداث للتعامل مع النافذة. تُطلَق جميع أحداث الدوّار ضمن الدوّار نفسه (بمعنى أنّها على العنصُر <div class="modal">)

$('#myModal').on('hidden.bs.modal', function (e) {
  // افعل شيئًا هنا ...
})

مصادر

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