Bootstrap/popovers

استخدم العناصر المنبثقّة Popovers التي يوفّرها إطار العمل Bootstrap لإضافة تنسيقات وتأثيرات مماثلة لتلك الموجودة في iOS إلى صفحات ويب.

نظرة عامّة

في ما يلي أمور ينبغي إدراكها قبل البدء في استخدام مكوِّن العناصر المنبثقة الذي يوفّره Bootstrap:

• تعتمد العناصر المنبثقة على مكتبة Popper.js في تموضعها. لذا يجب - من أجل أن تعمل هذه العناصر - تضمين popper.min.js قبل bootstrap.js أو استخدام bootstrap.bundle.min.js أو bootstrap.bundle.js الذين يتضمّنان Popper.js.
• تعتمد العناصر المنبثقة على مُلحَق التلميحات.
• انتبه إنْ كنت تبني JavaScript من الملفّات المصدريّة لإطار العمل Bootstrap إلى أنّه يتطلّب الملف util.js
• العناصر المنبثقة اختيّاريّة - لأسباب تتعلّق بالأداء، ويجب بالتالي تمهيدها يدويّا.
• لا تظهر عناصر منبثقة أبدًا في قيم title وcontent الفارغة.
• حدّد القيمة container: 'body' لتجنّب مشاكل في العرض في المكوِّنات الأكثر تعقيدًا (مثل مجموعات الإدخال، مجموعات الأزرار، ...إلخ).
• لن تعمل العناصر المنبثقة على العناصر المخفيّة.
• يجب ابتداء العناصر المنبثقة على العنصُر المُغلِّف عند استهداف عناصر تطبِّق الخاصيّة disabled أو الصنف ‎.disabled.
• تتوسّط العناصر المنبثقة عند ابتدائها من روابط تلتفّ على أسطر متعدّدة تتوسّط العرض الكامل للرابط. استخدم الخاصيّة white-space: nowrap;‎ على الرابط <a> لتفادي هذا الأمر.
• يجب إخفاء العناصر المنبثقة حتى يتسنّى حذفُ العناصر المتعلّقة بها من كائن المستند DOM.

واصل القراءة لأمثلة عن كيفيّة عمل العناصر المنبثقة.

مثال: تفعيل العناصر المنبثقة في كلّ مكان

إحدى طرق تمهيد Initialization جميع العناصر المنبثقة في صفحة هي تحديدها باستخدام قيمة data-toggle الخاصّة بها (data-toggle="popover"‎).

$(function () {
  $('[data-toggle="popover"]').popover()
})

مثال: استخدام الخيّار container

عندما تكون هناك أنماط على عنصُر أب تتداخل مع عنصُر منبثق فستحتاج لتحديد حاويّة (container) مُخصَّصة بحيث تظهر شفرة HTML الخاصّة بالعنصُر المنبثق داخل الحاويّة.

$(function () {
  $('.example-popover').popover({
    container: 'body'
  })
})

مثال

<button type="button" class="btn btn-lg btn-danger" data-toggle="popover" title="Popover title" data-content="وصف محتوى العنصُر">انقر لإظهار العنصُر المنبثق أو إخفائه</button>

الاتّجاهات الأربع

تتوفّر أربع خيّارات لمحاذاة العنصُر المبثق: في الأعلى، وإلى اليمين، وفي الأسفل وإلى اليسار.

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="top" data-content="وصف العنصُر">
  عنصُر منبثق إلى الأعلى
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="right" data-content="وصف العنصُر">
  عنصُر منبثق إلى اليمين
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="bottom" data-content="وصف العنصُر">
  عنصُر منبثق إلى الأسفل
</button>

<button type="button" class="btn btn-secondary" data-container="body" data-toggle="popover" data-placement="left" data-content="وصف العنصُر">
  عنصُر منبثق إلى اليسار
</button>

الإخفاء عند النقر خارج العنصُر

استخدم الخاصيّة focus لإخفاء العنصُر المنبثق عند نقر المستخدم على عنصُر مغاير للذي تسبّب في إظهار العنصُر المنبثق. تنبيه: تتطلّب هذه الميزة لكي تعمل على مختلف المنصّات والمتصفّحات استخدام الوسم <a> _لا_ الوسم <button>، كما يجب أن تضمِّن الخاصيّة tabindex.

<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-toggle="popover" data-trigger="focus" title="Dismissible popover" data-content="وصف العنصُر">عنصُر منبثق يمكن إخفاؤه</a>

$('.popover-dismiss').popover({
  trigger: 'focus'
})

العناصر المُعطَّلة

لا تعدّ العناصر التي تُطبَّق عليها الخاصيّة disabled تفاعليّة، ممّا يعني أنّ المستخدمين لا يستطيعون الحومان فوقها أو النقر عليها لإظهار عنصُر منبثق (أو تلميح). الحلّ البديل هو إظهار عنصُر منبثق من عنصُر مغلِّف (<div> أو <span>) وإبطال أحداث المؤشِّر (pointer-events) على العنصُر المُعطَّل. يمكن كذلك استخدام الخاصيّة data-trigger="hover"‎ لابتداء العنصُر المنبثق مباشرةً إذْ قد لا يتوقّع الزائر أنّ بإمكانه النقر على عنصُر مُعطَّل.

<span class="d-inline-block" data-toggle="popover" data-content="عنصُر منبثق">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>زرّ مُعطَّل</button>
</span>

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

تفعيل العناصر المنبثقة باستخدام شفرة JavaScript:

$('#example').popover(options)

الخيّارات

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

الاسم	النوع	القيمة المبدئيّة	الوصف
animation (التحريك)	قيمة منطقيّة	true	تطبيق تأثير الخفوت في CSS على العنصُر المنبثق
container (الحاويّة)	عنصُر | false	false	إلحاق العنصُر المنبثق بالعنصُر المخصوص. مثال: container: 'body'‎. هذا الخيّار مفيد جدًّا، إذ يمكّنك من وضع العنصُر المنبثق قرب العنصُر الذي يتعلّق به، ممّا يمنع العنصُر المنبثق من الابتعاد أثناء تغيير قياس النافذة.
content (المحتوى)	عنصُر | دالّة	سلسلة محارف فارغة	تأخذ القيمة المبدئيّة إن لم تكن الخاصيّة data-content موجودة على العنصُر المنبثق. عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي يتعلّق به العنصُر المنبثق إلى المتغيّر this.
delay (تأخير)	كائن	0	تأخير إظهار أو إخفاء العنصُر المنبثق (بالميلّي ثانيّة). لا ينطبق على العناصر المنبثقة المُظهرة يدويّا. عند تمرير عدد فإنّ التأخير يُطبَّق على الإظهار (show) والإخفاء (hide) كليهما. بنية الكائن هي كالتالي: delay: { "show": 500, "hide": 100 }
html	قيمة منطقيّة	false	إدراج وسوم HTML ضمن العنصُر المنبثق. تُستخدَم الدالّة text في jQuery لإدراج المحتوى في كائن المستند إذا كانت قيمة الخيّار false. استخدم نصّا إنْ كنت نصا بسيطًا إنْ كنت تخشى من هجمات XSS.
placement (التموضع)	دالّة	'right'	تموضع العنصُر المنبثق: - auto (تلقائي) | top (أعلى) | bottom (أسفل) | left (يسار) | right (يمين). يُعاد توجيه العنصُر المنبثق تلقائيَّا عند اختيّار التموضع التلقائي (auto). عند استخدام دالّة لتحديد التموضع فإنّ المُعطَى الأوّل الذي يُمرّر لها أثناء استدعائها هو مكان العنصُر المنبثق في كائن المستنَد والمُعطَى الثاني هو مكان العنصُر الذي تسبّب في إظهار العنصُر المنبثق. يُعيَّن سياق المتغيّر this إلى العنصُر المنبثق.
selector (المُحدِّد)	false	false	تُفوّض كائنات العناصر المنبثقة إلى الأهداف المُحدّدة إذا كان هناك مُحدِد مُمرّر. يُستخدَم هذا الخيّار عمليًّا لتفعيل محتوى HTML ديناميكيّ لإضافة عناصر منبثقة. انظر هنا وهذا المثال المفيد.
template (قالب)	سلسلة محارف	'‎<div class="popover" role="tooltip"><div class="arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>‎'	شفرة HTML قاعديّة للاستخدام أثناء إنشاء العنصُر المنبثق يُحقَن عنوان العنصُر المنبثق (title) في الصنف (‎.popover-header). يُحقَ مُحتوى العنصُر المنبثق (content) في الصنف .popover-body. تصبح قيمة .arrow قيمة الخاصيّة arrow في العنصُر المنبثق. يجب أن يحوي العنصُر المغلِّف الأعلى الصنف .popover .
title (العنوان)	عنصُر | دالّة		قيمة العنوان المبدئيّة إنْ لم تكن الخاصيّة title موجودة في العنصُر المنبثق عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي يتعلّق به العنصُر المنبثق إلى المتغيّر this.
trigger (التفعيل)	سلسلة محارف	'click'	hover (الحومان) | focus (تركيز المؤشّر) | manual (يدويًّا). يمكن تعيين أكثر من طريقة، افصل بينها بمسافة. لا يمكن الجمع بين التفعيل يدويًّا manual وأي طريقة أخرى.
offset (الانزياح)	سلسلة محارف	0	انزيّاح العنصُر المنبثق عن العنصُر المستهدَف. راجع توثيق Offset في Popper.js.
fallbackPlacement (موضع التراجع)	مصفوفة	'flip'	يسمح بتحديد الموضع الذي سيختاره Popper.js عند التراجع Fallback. راجع توثيق Popper.js للمزيد من المعلومات.
boundary (حدود)	عنصُر	'scrollParent'	حدود قيد طفح Overflow العنصُر المنبثق. يقبل القيم 'viewport' (إطار العرض)، أو'window' (نافذة)، أو 'scrollParent' (عنصُر أب يقبل التمرير) أو عنصُر HTML (فقط عند استخدام JavaScript). راجع توثيق Popper.js للمزيد من المعلومات.

خاصيّات البيانات لعناصر منبثقة منفردة

يمكن تعيين خيّارات بديلة لعناصر منبثقة على انفراد باستخدام خاصيّات البيانات كما هو محدَّد أعلاه.

التوابع

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

‎$().popover(options)

يمهِّد العناصر المنبثقة المتعلّقة بمجموعة من العناصر.

‎.popover('show')

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

$('#element').popover('show')

‎.popover('hide')

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

$('#element').popover('hide')

‎.popover('toggle')

يبدّل حالة العنصُر المنبثق المتعلِّق بعنصُر (يُخفيه عندما ما يكون ظاهرًا، والعكس). يعود إلى المُستدعِي قبل أن يُظهَر العنصُر المنبثق أو يُخفَى فعليًّا (أي قبل وقوع الحدث hidden.bs.popover أو shown.bs.popover). يُعدّ استخدام هذا التابع إخفاءً يدويًّا للعنصُر المنبثق.

$('#element').popover('toggle')

‎.popover('dispose')

يخفي العنصُر المنبثق ويحذفه. لا يمكن حذف العناصر المنبثقة التي تستخدم التفويض (أي التي أُنشِئت باستخدام المُحدِّد selector) فرديًّا من العناصر الأبناء.

$('#element').popover('dispose')

‎.popover('enable')

يمنح العنصُر المنبثق المتعلِّق بعنصُر قابليّة العرض. تُفعَّل العناصر المنبثقة مبدئيّا.

$('#element').popover('enable')

‎.popover('disable')

يحذف قابليّة العرض من العنصُر المنبثق المتعلِّق بعنصُر. لن يمكن عرض العنصُر المنبثق بعدها إلّا إذا أعيد تفعيل قابليّة عرضه.

$('#element').popover('disable')

‎.popover('toggleEnabled')

يبدّل حالة قابليّة العرض الخاصّة بالعنصُر المنبثق المتعلِّق بعنصُر.

$('#element').popover('toggleEnabled')

‎.popover('update')

يحدّث موضع العنصُر المنبثق المتعلِّق بعنصُر

$('#element').popover('update')

الأحداث

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

$('#myPopover').on('hidden.bs.popover', function () {
  // افعل شيئا هنا …
})