التلميحات (Popovers)

نظرة عامة

أشياء يجب معرفتها عند استخدام إضافة الـ popover plugin:

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

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

أمثلة

تفعيل الـ popovers

كما ذكرنا أعلاه، يجب عليك تهيئة الـ popovers قبل أن تتمكن من استخدامها. إحدى الطرق لتهيئة جميع الـ popovers في الصفحة هي اختيارها عن طريق سمة data-bs-toggle الخاصة بها، على النحو التالي:

const popoverTriggerList = document.querySelectorAll('[data-bs-toggle="popover"]')
const popoverList = [...popoverTriggerList].map(popoverTriggerEl => new bootstrap.Popover(popoverTriggerEl))

عرض توضيحي مباشر

نستخدم JavaScript مشابهة للمقتطف أعلاه لعرض الـ popover المباشر التالي. يتم تعيين العناوين عبر data-bs-title ومحتوى الجسم عبر data-bs-content.

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

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

تتوفر أربعة خيارات: الأعلى (top)، واليمين (right)، والأسفل (bottom)، واليسار (left). يتم عكس الاتجاهات عند استخدام Bootstrap في وضع RTL. قم بتعيين data-bs-placement لتغيير الاتجاه.

<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>

حاوية container مخصصة

عندما يكون لديك بعض الأنماط في عنصر أب تتداخل مع الـ popover، فستحتاج إلى تحديد container مخصص بحيث يظهر الـ HTML الخاص بالـ popover داخل هذا العنصر بدلاً من ذلك. هذا أمر شائع في الجداول المتوافقة مع الشاشات (Responsive)، ومجموعات الإدخال، وما شابه ذلك.

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

هناك حالة أخرى قد ترغب فيها في تعيين container مخصص صريح وهي الـ popovers الموجودة داخل modal dialog، للتأكد من أن الـ popover نفسه يتم إلحاقه بالـ modal. هذا أمر مهم بشكل خاص للـ popovers التي تحتوي على عناصر تفاعلية – حيث ستقوم الـ modal dialogs بحجز التركيز (trap focus)، لذا ما لم يكن الـ popover عنصراً فرعياً من الـ modal، لن يتمكن المستخدمون من التركيز على هذه العناصر التفاعلية أو تفعيلها.

const popover = new bootstrap.Popover('.example-popover', {
  container: '.modal-body'
})

تلميحات مخصصة

يمكنك تخصيص مظهر الـ popovers باستخدام متغيرات CSS. نقوم بتعيين فئة (class) مخصصة باستخدام data-bs-custom-class="custom-popover" لتحديد نطاق مظهرنا المخصص واستخدامها لتجاوز بعض متغيرات CSS المحلية.

.custom-popover {
  --bs-popover-max-width: 200px;
  --bs-popover-border-color: var(--bd-violet-bg);
  --bs-popover-header-bg: var(--bd-violet-bg);
  --bs-popover-header-color: var(--bs-white);
  --bs-popover-body-padding-x: 1rem;
  --bs-popover-body-padding-y: .5rem;
}

<button type="button" class="btn btn-secondary"
        data-bs-toggle="popover" data-bs-placement="right"
        data-bs-custom-class="custom-popover"
        data-bs-title="Custom popover"
        data-bs-content="This popover is themed via CSS variables.">
  Custom popover
</button>

الإغلاق عند النقر التالي

استخدم مشغل focus لإغلاق الـ popovers عند نقرة المستخدم التالية على عنصر آخر غير عنصر التفعيل.

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

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

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

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

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

<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>

الـ (CSS)

المتغيرات (Variables)

كجزء من نهج الـ Bootstrap المتطور لمتغيرات CSS، تستخدم الـ popovers الآن متغيرات CSS محلية على popover. لتعزيز التخصيص في الوقت الفعلي. يتم تعيين قيم متغيرات CSS عبر الـ Sass، لذا لا يزال تخصيص الـ Sass مدعوماً أيضاً.

--#{$prefix}popover-zindex: #{$zindex-popover};
--#{$prefix}popover-max-width: #{$popover-max-width};
@include rfs($popover-font-size, --#{$prefix}popover-font-size);
--#{$prefix}popover-bg: #{$popover-bg};
--#{$prefix}popover-border-width: #{$popover-border-width};
--#{$prefix}popover-border-color: #{$popover-border-color};
--#{$prefix}popover-border-radius: #{$popover-border-radius};
--#{$prefix}popover-inner-border-radius: #{$popover-inner-border-radius};
--#{$prefix}popover-box-shadow: #{$popover-box-shadow};
--#{$prefix}popover-header-padding-x: #{$popover-header-padding-x};
--#{$prefix}popover-header-padding-y: #{$popover-header-padding-y};
@include rfs($popover-header-font-size, --#{$prefix}popover-header-font-size);
--#{$prefix}popover-header-color: #{$popover-header-color};
--#{$prefix}popover-header-bg: #{$popover-header-bg};
--#{$prefix}popover-body-padding-x: #{$popover-body-padding-x};
--#{$prefix}popover-body-padding-y: #{$popover-body-padding-y};
--#{$prefix}popover-body-color: #{$popover-body-color};
--#{$prefix}popover-arrow-width: #{$popover-arrow-width};
--#{$prefix}popover-arrow-height: #{$popover-arrow-height};
--#{$prefix}popover-arrow-border: var(--#{$prefix}popover-border-color);

متغيرات الـ (Sass)

$popover-font-size:                 $font-size-sm;
$popover-bg:                        var(--#{$prefix}body-bg);
$popover-max-width:                 276px;
$popover-border-width:              var(--#{$prefix}border-width);
$popover-border-color:              var(--#{$prefix}border-color-translucent);
$popover-border-radius:             var(--#{$prefix}border-radius-lg);
$popover-inner-border-radius:       calc(#{$popover-border-radius} - #{$popover-border-width}); // stylelint-disable-line function-disallowed-list
$popover-box-shadow:                var(--#{$prefix}box-shadow);

$popover-header-font-size:          $font-size-base;
$popover-header-bg:                 var(--#{$prefix}secondary-bg);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                var(--#{$prefix}body-color);
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

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

الإستخدام

تمكين التلميحات (popovers) عبر الـ JavaScript:

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

خيارات

بما أنه يمكن تمرير الخيارات عبر سمات البيانات (data attributes) أو الـ JavaScript، يمكنك إضافة اسم الخيار إلى -data-bs ، كما في "data-bs-animation="{value}. تأكد من تغيير نوع حالة اسم الخيار من “camelCase” إلى “kebab-case” عند تمرير الخيارات عبر سمات البيانات. على سبيل المثال، استخدم "data-bs-custom-class="beautifier بدلاً من "data-bs-customClass="beautifier.

بدءاً من Bootstrap 5.2.0، تدعم جميع المكونات سمة بيانات محجوزة تجريبية وهي data-bs-config والتي يمكن أن تحتوي على تكوين بسيط للمكون كسلسلة JSON. عندما يحتوي العنصر على سمات 'data-bs-config='{"delay":0, "title":123} و "data-bs-title="456، ستكون قيمة title النهائية هي 456 وستقوم سمات البيانات المنفصلة بتجاوز القيم المعطاة في data-bs-config. بالإضافة إلى ذلك، يمكن لسمات البيانات الموجودة أن تحتوي على قيم JSON مثل 'data-bs-delay='{"show":0,"hide":150}.

كائن التكوين النهائي هو النتيجة المدمجة لـ data-bs-config و -data-bs و js object حيث يقوم آخر مفتاح-قيمة مُعطى بتجاوز القيم الأخرى.

استخدام الدالة مع popperConfig

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

الطرق، الأساليب (Methods)

// getOrCreateInstance example
const popover = bootstrap.Popover.getOrCreateInstance('#example') // Returns a Bootstrap popover instance

// setContent example
popover.setContent({
  '.popover-header': 'another title',
  '.popover-body': 'another content'
})

الأحداث (Events)

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