العناصر المنبثقة Popovers في إطار العمل Bootstrap

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

نظرة عامّة

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

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

ملحوظة: تأثير الحركة الخاص بهذه المكونة يعتمد على استعلام الوسائط prefers-reduced-motion. راجع صفحة سهولة الوصول لمزيد من المعلومات.

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

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

إحدى طرائق تمهيد (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 لإخفاء العنصُر المنبثق عند نقر المستخدم على عنصُر مغاير للذي تسبّب في إظهار العنصُر المنبثق.

تنبيه: تتطلّب هذه الميزة لكي تعمل على مختلف المنصّات والمتصفّحات استخدام الوسم وليس العنصر <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)

جعل العناصر المنبثقة تعمل مع لوحة المفاتيح والتقنيات المساعدة

إن أردت السماح لمستخدمي لوحة المفاتيح بتنشيط العناصر المنبثقة، فلا ينبغي أن تضيفها إلّا إلى عناصر HTML التي تتفاعل مع لوحة المفاتيح (مثل الروابط أو عناصر النموذج). ورغم أنّه يمكن جعل عناصر HTML الأخرى (مثل <span>) قابلة لاستقبال التركيز عن طريق إضافة السمة tabindex = "0"‎ ، إلا أنّ ذلك سيضيف مواضع توقف مربكة على العناصر غير التفاعلية. معظم التقنيات المساعدة حاليًا لا تعلن المحتوى المنبثق في هذه الحالة. علاوة على ذلك، لا ينبغي أن تعتمد حصرَا على الحومان لجعل العنصر ينبثق، ذلك أنّ هذا سيمنع مستخدمي لوحة المفاتيح من إطلاقها.

رغم أنه يمكنك إدراج ترميز لغة HTML في العناصر المنبثقة باستخدام خيار html، فإننا نوصي بشدة بتجنب إضافة الكثير من المحتوى. بمجرد عرض العنصر المنبثق popovers، يرتبط محتواه بعنصر الإطلاق في السمة aria-describedby. ونتيجةً لذلك سيُعرَض كل محتوى العنصر المنبثق لمستخدمي التكنولوجيا المساعدة عرضًا واحدا طويلا غير متقطع.

في حين أنه يجوز أيضًا تضمين عناصر تحكم تفاعلية (مثل عناصر النموذج أو الروابط) في العنصر المنبثق (عن طريق إضافة هذه العناصر إلى القائمة البيضاء أو السمات والوسوم المسموح بها) ، تذكر أنّ العناصر المنبثقة حاليًا لا تنظم ترتيب تركيز لوحة المفاتيح. عندما يفتح مستخدم لوحة المفاتيح عنصرا منبثقًا ، يظل التركيز على العنصر الذي أطلق العنصر المنبثق، وبما أنّ العناصر المنبثقة لا تتبع عادةً عنصر الإطلاق في بنية المستند ، فلا يوجد ضمان بأنّ الانتقال إلى الأمام أو النقر على TAB سينقل مستخدم لوحة المفاتيح إلى العنصر المنبثق نفسه. باختصار ، إنّ إضافة عناصر تحكم تفاعلية إلى العنصر المنبثق سيجعلها على الأرجح غير قابلة للاستخدام / الوصول لمستخدمي لوحة المفاتيح ومستخدمي التقنيات المساعدة، أو على الأقل سيجعل ترتيب التركيز غير منطقي عمومًا. قد يكون الأفضل في هذه الحالات استخدام مربع حوار شرطي.

الخيارات

يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق 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'`	`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 للمزيد من المعلومات.
`sanitize`	قيمة منطقية	`true`	يتيح أو يعطل التصحيح. في حال تفعيلها، ستُصحّح كلّ من `'template'`و `'content'` و `'title'`
`whiteList`	كائن	القيمة الافتراضية	كائن يحتوي السمات والوسوم المسموح بها
`sanitizeFn`	قيمة معدومة أو دالة	قيمة معدومة	يمكنك هنا تخصيص دالة التصحيح. هذا مفيد في حال كنت تفضل استخدام مكتبة خاصة لإجراء التصحيح
`popperConfig`	قيمة معدومة أو كائن	قيمة معدومة	لتغيير إعدادات 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 () {
  // افعل شيئا هنا …
})

مصادر

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

نظرة عامّة

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

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