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

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

نظرة عامّة

في ما يلي أمور ينبغي إدراكها قبل البدء في استخدام مكوِّن التلميحات الذي يوفّره 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="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)

الوسوم

لا تتطلّب التلميحات سوى الخاصيّتيْن 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>زرّ مُعطَّل</button>
</span>

الخيّارات

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

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

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

التوابع

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

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

‎$().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('disable')

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

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

‎.tooltip('toggleEnabled')

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

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

‎.tooltip('update')

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

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

مصادر

• صفحة Tooltips في توثيق Bootstrap.