بوبوفرز

وثائق وأمثلة لإضافة Bootstrap popovers ، مثل تلك الموجودة في iOS ، إلى أي عنصر على موقعك.

على هذه الصفحة

ملخص

أشياء يجب معرفتها عند استخدام المكون الإضافي Popover:

تعتمد العناصر المنبثقة على مكتبة Popper التابعة لجهة خارجية لتحديد المواقع. يجب عليك تضمين popper.min.js قبل bootstrap.js أو استخدام bootstrap.bundle.min.js/ bootstrap.bundle.jsالذي يحتوي على Popper حتى يعمل popovers!
تتطلب العناصر المنبثقة إضافة تلميح الأدوات كتبعية.
يتم تمكين العناصر المنبثقة لأسباب تتعلق بالأداء ، لذا يجب عليك تهيئتها بنفسك .
الطول الصفري titleوالقيم contentلن تظهر أبدًا نافذة منبثقة.
حدد container: 'body'لتجنب مشاكل العرض في المكونات الأكثر تعقيدًا (مثل مجموعات الإدخال ومجموعات الأزرار وما إلى ذلك).
لن يعمل تشغيل العناصر المنبثقة على العناصر المخفية.
يجب تشغيل العناصر المنبثقة لـ .disabledأو disabledالعناصر على عنصر مجمّع.
عند التشغيل من المراسي التي تلتف عبر خطوط متعددة ، سيتم توسيط العناصر المنبثقة بين العرض الإجمالي للمراسي. استخدمه لتجنب هذا السلوك .text-nowrap.<a>
يجب إخفاء العناصر المنبثقة قبل إزالة العناصر المقابلة لها من DOM.
يمكن تشغيل النوافذ المنبثقة بفضل عنصر داخل ظل DOM.

بشكل افتراضي ، يستخدم هذا المكون معقم المحتوى المدمج ، والذي يزيل أي عناصر HTML غير مسموح بها بشكل صريح. راجع قسم المطهر في وثائق JavaScript لمزيد من التفاصيل.

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

استمر في القراءة لترى كيف يعمل popovers مع بعض الأمثلة.

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

تتمثل إحدى طرق تهيئة جميع العناصر المنبثقة على الصفحة في تحديدها حسب data-bs-toggleالسمة الخاصة بها:

var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
  return new bootstrap.Popover(popoverTriggerEl)
})

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

عندما يكون لديك بعض الأنماط على عنصر أصلي تتداخل مع نافذة منبثقة ، سترغب في تحديد مخصص containerبحيث يظهر HTML المنبثق داخل هذا العنصر بدلاً من ذلك.

var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
  container: 'body'
})

مثال

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

أربعة اتجاهات

تتوفر أربعة خيارات: محاذاة لأعلى ولليمين ولأسفل ولليسار. يتم عكس الاتجاهات عند استخدام Bootstrap في RTL.

<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
  Popover on top
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover">
  Popover on right
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover">
  Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover">
  Popover on left
</button>

رفض عند النقر التالي

استخدم focusالمشغل لتجاهل العناصر المنبثقة عند نقرة المستخدم التالية على عنصر مختلف عن عنصر التبديل.

مطلوب ترميز محدد للرفض عند النقرة التالية

للحصول على سلوك سليم عبر المتصفحات وعبر الأنظمة الأساسية ، يجب عليك استخدام <a>العلامة ، وليس العلامة <button>، كما يجب تضمين tabindexسمة.

popover غير مقبول

<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>

var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
  trigger: 'focus'
})

العناصر المعطلة

العناصر التي تحتوي على disabledالسمة ليست تفاعلية ، مما يعني أنه لا يمكن للمستخدمين المرور فوقها أو النقر فوقها لتشغيل نافذة منبثقة (أو تلميح أداة). كحل بديل ، سترغب في تشغيل العنصر المنبثق من غلاف <div>أو <span>جعله بشكل مثالي للتركيز على لوحة المفاتيح باستخدام tabindex="0".

بالنسبة لمشغلات popover المعطلة ، قد تفضل أيضًا data-bs-trigger="hover focus"أن تظهر النافذة المنبثقة كتعليقات مرئية فورية للمستخدمين حيث قد لا يتوقعون النقر فوق عنصر معطل.

<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

ساس

المتغيرات

$popover-font-size:                 $font-size-sm;
$popover-bg:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              rgba($black, .2);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$popover-header-bg:                 shade-color($popover-bg, 6%);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                $body-color;
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

$popover-arrow-width:               1rem;
$popover-arrow-height:              .5rem;
$popover-arrow-color:               $popover-bg;

$popover-arrow-outer-color:         fade-in($popover-border-color, .05);

إستعمال

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

var exampleEl = document.getElementById('example')
var popover = new bootstrap.Popover(exampleEl, options)

جعل popovers تعمل مع لوحة المفاتيح ومستخدمي التكنولوجيا المساعدة

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

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

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

خيارات

يمكن تمرير الخيارات عبر سمات البيانات أو JavaScript. لسمات البيانات ، قم بإلحاق اسم الخيار بـ data-bs-، كما في data-bs-animation="". تأكد من تغيير نوع حالة اسم الخيار من camelCase إلى kebab-case عند تمرير الخيارات عبر سمات البيانات. على سبيل المثال ، بدلاً من استخدام data-bs-customClass="beautifier"، استخدم data-bs-custom-class="beautifier".

لاحظ أنه لأسباب تتعلق بالأمان sanitize، لا يمكن توفير الخيارات sanitizeFn، و ، باستخدام سمات البيانات.allowList

اسم	يكتب	تقصير	وصف
`animation`	قيمة منطقية	`true`	تطبيق انتقال تلاشي CSS إلى العنصر المنبثق
`container`	سلسلة \| عنصر \| خاطئة	`false`	لإلحاق العنصر المنبثق بعنصر معين. مثال `container: 'body'`:. هذا الخيار مفيد بشكل خاص لأنه يسمح لك بوضع النافذة المنبثقة في تدفق المستند بالقرب من عنصر التشغيل - مما سيمنع العنصر المنبثق من الطفو بعيدًا عن عنصر التشغيل أثناء تغيير حجم النافذة.
`content`	سلسلة \| عنصر \| وظيفة	`''`	قيمة المحتوى الافتراضية إذا `data-bs-content`لم تكن السمة موجودة. إذا تم توفير وظيفة ، فسيتم استدعاؤها مع `this`مجموعة مرجعية لها إلى العنصر الذي يتم إرفاق العنصر المنبثق به.
`delay`	رقم \| هدف	`0`	التأخير في إظهار وإخفاء النافذة المنبثقة (بالمللي ثانية) - لا ينطبق على نوع المشغل اليدوي إذا تم توفير رقم ، فسيتم تطبيق التأخير على كل من الإخفاء / العرض هيكل الكائن هو:`delay: { "show": 500, "hide": 100 }`
`html`	قيمة منطقية	`false`	أدخل HTML في النافذة المنبثقة. إذا كان خطأ ، `innerText`فسيتم استخدام الخاصية لإدراج محتوى في DOM. استخدم النص إذا كنت قلقًا بشأن هجمات XSS.
`placement`	سلسلة \| وظيفة	`'right'`	كيفية وضع المنبثقة - تلقائي \| أعلى \| أسفل \| غادر \| حقا. عند `auto`تحديده ، سيعيد توجيه النافذة المنبثقة ديناميكيًا. عند استخدام دالة لتحديد الموضع ، يتم استدعاؤها باستخدام عقدة DOM المنبثقة باعتبارها الوسيطة الأولى لها وعقدة DOM المشغلة كعقدة ثانية لها. يتم `this`تعيين السياق على مثيل popover.
`selector`	سلسلة \| خاطئة	`false`	إذا تم توفير محدد ، فسيتم تفويض الكائنات المنبثقة إلى الأهداف المحددة. في الممارسة العملية ، يتم استخدام هذا لتمكين محتوى HTML الديناميكي لإضافة العناصر المنبثقة. انظر إلى هذا ومثال إعلامي .
`template`	سلسلة	`'<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'`	قاعدة HTML لاستخدامها عند إنشاء العنصر المنبثق. `title`سيتم حقن العناصر المنبثقة في ملف `.popover-header`. `content`سيتم حقن العناصر المنبثقة في ملف `.popover-body`. `.popover-arrow`سيصبح سهم المنبثقة. يجب أن يحتوي عنصر الغلاف الخارجي على `.popover`الفئة.
`title`	سلسلة \| عنصر \| وظيفة	`''`	قيمة العنوان الافتراضية إذا `title`لم تكن السمة موجودة. إذا تم توفير وظيفة ، فسيتم استدعاؤها مع `this`مجموعة مرجعية لها إلى العنصر الذي يتم إرفاق العنصر المنبثق به.
`trigger`	سلسلة	`'click'`	كيف يتم تشغيل المنبثقة - انقر فوق \| تحوم \| التركيز \| كتيب. يمكنك تمرير عدة مشغلات ؛ افصلهم بمسافة. `manual`لا يمكن دمجها مع أي مشغل آخر.
`fallbackPlacements`	مجموعة مصفوفة	`['top', 'right', 'bottom', 'left']`	حدد المواضع الاحتياطية من خلال توفير قائمة بالمواضع في مصفوفة (بترتيب التفضيل). لمزيد من المعلومات ، راجع مستندات سلوك Popper
`boundary`	سلسلة \| عنصر	`'clippingParents'`	حدود قيد تجاوز السعة المنبثقة (تنطبق فقط على معدل منع تجاوز تدفق Popper). بشكل افتراضي `'clippingParents'`، يمكن قبول مرجع HTMLElement (عبر JavaScript فقط). لمزيد من المعلومات ، راجع مستندات DiscoverOverflow الخاصة بـ Popper .
`customClass`	سلسلة \| وظيفة	`''`	أضف فئات إلى النافذة المنبثقة عند عرضها. لاحظ أنه ستتم إضافة هذه الفئات بالإضافة إلى أي فئات محددة في النموذج. لإضافة عدة فئات ، افصل بينها بمسافات `'class-1 class-2'`:. يمكنك أيضًا تمرير دالة يجب أن تُرجع سلسلة واحدة تحتوي على أسماء فئات إضافية.
`sanitize`	قيمة منطقية	`true`	تمكين أو تعطيل التطهير. في حالة التنشيط `'template'`، سيتم تعقيم الخيارات `'content'`. `'title'`راجع قسم المطهر في وثائق JavaScript الخاصة بنا .
`allowList`	هدف	القيمة الافتراضية	الكائن الذي يحتوي على السمات والعلامات المسموح بها
`sanitizeFn`	فارغ \| وظيفة	`null`	هنا يمكنك توفير وظيفة التعقيم الخاصة بك. يمكن أن يكون هذا مفيدًا إذا كنت تفضل استخدام مكتبة مخصصة لإجراء التعقيم.
`offset`	مجموعة \| سلسلة \| وظيفة	`[0, 8]`	إزاحة العنصر المنبثق بالنسبة إلى هدفه. يمكنك تمرير سلسلة في سمات البيانات بقيم مفصولة بفواصل مثل:`data-bs-offset="10,20"` عندما يتم استخدام دالة لتحديد الإزاحة ، يتم استدعاؤها بكائن يحتوي على موضع بوبر ، والمرجع ، ومستقيم بوبر كوسيطة أولى لها. يتم تمرير عقدة DOM المشغلة كوسيطة ثانية. يجب أن تُرجع الدالة مصفوفة تحتوي على رقمين :.`[skidding, distance]` لمزيد من المعلومات راجع مستندات تعويض Popper .
`popperConfig`	فارغ \| كائن \| وظيفة	`null`	لتغيير تكوين Popper الافتراضي الخاص بـ Bootstrap ، راجع تكوين Popper . عند استخدام وظيفة لإنشاء تكوين Popper ، يتم استدعاؤها بكائن يحتوي على تكوين Popper الافتراضي الخاص بـ Bootstrap. يساعدك على استخدام ودمج الافتراضي مع التكوين الخاص بك. يجب أن تقوم الوظيفة بإرجاع كائن تكوين لـ Popper.

سمات البيانات للأفراد المنبثقين

يمكن بدلاً من ذلك تحديد خيارات العناصر المنبثقة الفردية من خلال استخدام سمات البيانات ، كما هو موضح أعلاه.

استخدام وظيفة مع`popperConfig`

var popover = new bootstrap.Popover(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

طُرق

الطرق غير المتزامنة والانتقالات

جميع طرق API غير متزامنة وتبدأ في الانتقال . يعودون إلى المتصل بمجرد بدء الانتقال ولكن قبل أن ينتهي . بالإضافة إلى ذلك ، سيتم تجاهل استدعاء طريقة على مكون انتقالي .

راجع وثائق JavaScript الخاصة بنا للحصول على مزيد من المعلومات .

تبين

يكشف عن العنصر المنبثق. يعود إلى المتصل قبل أن يتم عرض العنصر المنبثق بالفعل (أي قبل shown.bs.popoverوقوع الحدث). يعتبر هذا بمثابة تشغيل "يدوي" للقافزة المنبثقة. لا يتم أبدًا عرض العناصر المنبثقة التي يكون عنوانها ومحتواها صفريًا.

myPopover.show()

يخفي

يخفي العنصر المنبثق. يعود إلى المتصل قبل إخفاء العنصر المنبثق بالفعل (أي قبل hidden.bs.popoverوقوع الحدث). يعتبر هذا بمثابة تشغيل "يدوي" للقافزة المنبثقة.

myPopover.hide()

تبديل

يبدل العنصر المنبثق. يعود إلى المتصل قبل إظهار أو إخفاء العنصر المنبثق بالفعل (أي قبل وقوع الحدث shown.bs.popoverأو ). hidden.bs.popoverيعتبر هذا بمثابة تشغيل "يدوي" للقافزة المنبثقة.

myPopover.toggle()

تخلص

يخفي العنصر المنبثق ويدمره (يزيل البيانات المخزنة على عنصر DOM). العناصر المنبثقة التي تستخدم التفويض (التي تم إنشاؤها باستخدام الخيارselector ) لا يمكن إتلافها بشكل فردي على عناصر المشغل التابعة .

myPopover.dispose()

يُمكَِن

يمنح العنصر المنبثق القدرة على الظهور. يتم تمكين العناصر المنبثقة افتراضيًا.

myPopover.enable()

تعطيل

يزيل إمكانية إظهار العنصر المنبثق. لن يتم عرض النافذة المنبثقة إلا إذا تمت إعادة تمكينها.

myPopover.disable()

toggleEnabled

يبدل إمكانية إظهار أو إخفاء العنصر المنبثق.

myPopover.toggleEnabled()

تحديث

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

myPopover.update()

getInstance

طريقة ثابتة تتيح لك الحصول على مثيل منبثق مرتبط بعنصر DOM

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

getOrCreateInstance

طريقة ثابتة تتيح لك الحصول على مثيل منبثق مرتبط بعنصر DOM ، أو إنشاء مثيل جديد في حالة عدم تهيئته

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

الأحداث

نوع الحدث	وصف
show.bs.popover	يتم تشغيل هذا الحدث فورًا عند `show`استدعاء أسلوب المثيل.
معروض. bs.popover	يتم تشغيل هذا الحدث عندما يصبح العنصر المنبثق مرئيًا للمستخدم (سينتظر حتى تكتمل انتقالات CSS).
إخفاء. bs.popover	يتم تشغيل هذا الحدث فورًا عند `hide`استدعاء أسلوب المثيل.
مخفي. bs.popover	يتم تشغيل هذا الحدث عند انتهاء إخفاء العنصر المنبثق عن المستخدم (سينتظر حتى تكتمل انتقالات CSS).
المدرجة. bs.popover	يتم تشغيل هذا الحدث بعد `show.bs.popover`الحدث عند إضافة القالب المنبثق إلى DOM.

var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
  // do something...
})