التلميحات Tooltips في إطار العمل Bootstrap

من موسوعة حسوب

أضف تلميحات Bootstrap المُخصَّصة إلى صفحات الويب باستخدام التأثيرات في انتقالات CSS وخاصيّات البيانات لتخزين العناوين محليًّا.

نظرة عامة

في ما يلي أمور ينبغي إدراكها قبل البدء في استخدام مكوِّن التلميحات الذي يوفّره 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;‎ على الرابط لتفادي هذا الأمر.
  • يجب إخفاء التلميحات حتى يتسنّى حذفُ العناصر المتعلّقة بها من كائن المستند DOM.
  • يمكن ابتداء التلميحات عبر عنصر داخل شجرة DOM.

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

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

مثال: تفعيل التلميحات في كلّ مكان

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

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

أمثلة

توجد في المثال التالي أربعة أزرار يؤدّي الحومان فوق كل واحدة منها إلى إظهار تلميحة أعلى، أو يمين، أو أسفل أو يسار الزرّ.

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">
  تلمحية في الأعلى
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">
  تلميحة على اليمين
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">
  تلميحة في الأسفل
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">
  تلميحة إلى اليسار
</button>

تمكن إضافة شفرة HTML داخل التلميحة.

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>تلميحة</em> <u>توجد بها</u> شفرة <b>HTML</b>">
  تلميحة توجد بها شفرة HTML
</button>

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

يولّد مُلحَق JavaScript الخاصّ بالتلميحات المحتوى والوسوم حسب الطلب. توضَع التلميحات مبدئيًّا بعد العنصُر المتسبّب في إظهارها.

في ما يلي كيفيّة إظهار تلميحة بشفرة JavaScript:

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

ملحوظة: يحاول bootstrap تغيير موضع التلميحات تلقائيا إن كان للحاوية الخاصيتان overflow: auto و overflow: scroll، كما في الصنف ‎.table-responsive. مع الحفاظ على التموضع الأصلي. لحل هذه المشكلة، عين قيمة الخيار boundary إلى أي قيمة خلا القيمة الافتراضية 'scrollParent'، مثل 'window'.

$('#example').tooltip({ boundary: 'window' })

الوسوم

لا تتطلّب التلميحات سوى الخاصيّتيْن data وtitle على عنصُر HTML المرغوب في التلميح إليه. يولّد المُلحَق وسوم HTML بسيطةً لإظهار التلميحة، ولا تحتاج سوى لوضعيّة (تأخذ مبدئيًّا القيمة top، أي أنّها تتموضع في الأعلى).

جعل التلميحات تعمل بلوحة المفاتيح ولمستخدمي التقنيّات المساعدة

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

لا تعتمد كليًّا على الحومان (hover) لإظهار التلميحات، إذ سيلغي ذلك إمكانيّة عرض التلميحات لمستخدمي لوحات المفاتيح.

<!-- وسوم HTML مكتوبة يدويّا -->
<a href="#" data-toggle="tooltip" title="نصّ في تلميحة!">أشّر عليّ</a>

<!-- وسوم يولّدها المُلحَق -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="arrow"></div>
  <div class="tooltip-inner">
   نصّ في تلميحة!
  </div>
</div>

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

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

<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="تلمحية على زرّ معطّل">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

الخيّارات

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

الاسم النوع القيمة المبدئيّة الوصف
animation (التحريك) قيمة منطقيّة true تطبيق تأثير الخفوت في CSS على التلميحة.
container (الحاويّة) عنصُر | false false

إلحاق التلميحة بالعنصُر المخصوص. مثال: container: 'body'. هذا الخيّار مفيد جدًّا، إذ يمكّنك من وضع التلميحة قرب العنصُر الذي تشير إليه، ممّا يمنع التلميحة من الابتعاد أثناء تغيير قياس النافذة.

delay (تأخير) كائن 0

تأخير إظهار أو إخفاء االتلميحة (بالميلّي ثانيّة). لا ينطبق على التلميحات المُظهرة يدويّا.

عند تمرير عدد فإنّ التأخير يُطبَّق على الإظهار (show) والإخفاء (hide) كليهما.

بنية الكائن هي كالتالي

delay: { "show": 500, "hide": 100 }‎

html قيمة منطقيّة false

يسمح بكتابة شفرات HTML داخل نصّ التلميحة.

إنْ كانت قيمة الخيار true فستُعرَض وسوم HTML داخل عنوان التلميحة (الخاصيّة title)؛ وإلّا فإنّ التابع text في jQuery سيُستخدَم لإدراج المحتوى في كائن المستند DOM.

استخدم نصًّا بسيطًا إنْ كنت تخشى من هجمات XSS.

placement (التموضع) دالّة 'top'

تموضع التلميحة: auto (تلقائي) | top (أعلى) | bottom (أسفل) | left (يسار) | right (يمين).
يُعاد توجيه التلميحة تلقائيَّا عند اختيّار التموضع التلقائي (auto).

عند استخدام دالّة لتحديد التموضع فإنّ المُعطَى الأوّل الذي يُمرّر لها أثناء استدعائها هو موقع التلميحة في كائن المستنَد والمُعطَى الثاني هو مكان العنصُر الذي تتبع له التلميحة. يُعيَّن سياق المتغيّر this إلى التلميحة.

selector (المُحدِّد) false false تُفوّض كائنات العناصر المنبثقة إلى الأهداف المُحدّدة إذا كان هناك مُحدِد مُمرّر. يُستخدَم هذا الخيّار عمليًّا لتفعيل محتوى HTML ديناميكيّ لإضافة عناصر منبثقة. انظر هنا وهذا المثال المفيد
template (قالب) سلسلة محارف ‎'<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'‎

شفرة HTML قاعديّة للاستخدام أثناء إنشاء التلميحة.

يُحقَن عنوان التلميحة (title) في الصنف (‎.tooltip-inner).

تصبح قيمة ‎.arrow قيمة الخاصيّة arrow في التلميحة.

يجب أن يحوي العنصُر المغلِّف الأعلى الصنف ‎.tooltip والخاصيّة role="tooltip"‎.

title (العنوان) عنصُر | دالّة سلسلة محارف فارغة

قيمة العنوان المبدئيّة إنْ لم تكن الخاصيّة title موجودة في التلميحة.

عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي تحيل إليه التلميحة إلى المتغيّر this.

trigger (التفعيل) سلسلة محارف 'hover focus'

كيفيّة إظهار التلميحة: click (النقر) | hover (الحومان)| focus (تركيز المؤشّر)| manual (يدوي). يمكن تمرير طرق عدّة، افصل بينها بمسافة.

تشير القيمة 'manual' إلى أنّ التلميحة ستُفعَّل برمجيّا بالتوابع .tooltip('show')‎، و .tooltip('hide')‎ و .tooltip('toggle')‎. لا يمكن استعمال أيّ قيمة أخرى إلى جانب هذه القيمة.

ينتُج عن استخدام القيمة 'hover' وحدها تلميحات لا يمكن تفعيلها بلوحة المفاتيح، ويجب ألّا تُستخدَم وحدها إلّا إذا كانت هناك طريقة أخرى لتوصيل المعنى لمستخدمي لوحة المفاتيح.

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 الافتراضية. راجع هذه الصفحة لمزيد من التفاصيل

خاصيّات البيانات لتلميحات منفردة

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

التوابع

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

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

‎$().tooltip(options)‎

يربط معالج تلميحات بمجموعة عناصر.

‎.tooltip('show')‎

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

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

‎.tooltip('hide')‎

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

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

‎.tooltip('toggle')‎

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

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

‎.tooltip('dispose')‎

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

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

‎.tooltip('enable')‎

يمنح عنصر تلميحة قابليّة العرض. وهو الخيار الافتراضي.

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

‎.tooltip('disable')‎

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

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

‎.tooltip('toggleEnabled')‎

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

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

‎.tooltip('update')‎

يحدّث موضع تلميحة على عنصُر.

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

الأحداث

نوع الحدث الوصف
show.bs.tooltip يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع show.
shown.bs.tooltip يُطلَق هذا الحدث عندما تُصبح التلميحة ظاهرةً للزائر (ينتظر اكتمال انتقالات CSS).
hide.bs.tooltip يُطلَق هذا الحدث مباشرةً بعد استدعاء التابع hide .
hidden.bs.tooltip يُطلَق هذا الحدث عندما يكتمل إخفاء التلميحة عن الزائر ((ينتظر اكتمال انتقالات CSS).
inserted.bs.tooltip يُطلَق هذا الحدث بعد الحدث show.bs.tooltip عندما يُضاف قالب التلميحة إلى كائن المستند. when the popover template 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // افعل شيئا هنا …
})

مصادر

مجلوبة من «https://wiki.hsoub.com/index.php?title=Bootstrap/tooltips&oldid=29703»