in English

تلميحات

وثائق وأمثلة لإضافة تلميحات أدوات Bootstrap مخصصة مع CSS و JavaScript باستخدام CSS3 للرسوم المتحركة وسمات البيانات لتخزين العنوان المحلي.

ملخص

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

  • تعتمد تلميحات الأدوات على مكتبة Popper التابعة لجهة خارجية لتحديد المواقع. يجب عليك تضمين popper.min.js قبل bootstrap.js أو استخدام bootstrap.bundle.min.js/ bootstrap.bundle.jsالذي يحتوي على Popper حتى تعمل التلميحات!
  • إذا كنت تقوم ببناء JavaScript من المصدر ، فهذا يتطلبutil.js .
  • يتم الاشتراك في تلميحات الأدوات لأسباب تتعلق بالأداء ، لذا يجب عليك تهيئتها بنفسك .
  • لا يتم أبدًا عرض تلميحات الأدوات ذات العناوين ذات الطول الصفري.
  • حدد container: 'body'لتجنب مشاكل العرض في المكونات الأكثر تعقيدًا (مثل مجموعات الإدخال ومجموعات الأزرار وما إلى ذلك).
  • تشغيل تلميحات الأدوات على العناصر المخفية لن يعمل.
  • يجب تشغيل تلميحات الأدوات .disabledأو disabledالعناصر على عنصر غلاف.
  • عند التشغيل من ارتباطات تشعبية تمتد عبر عدة أسطر ، سيتم توسيط تلميحات الأدوات. استخدمه لتجنب هذا السلوك white-space: nowrap;.<a>
  • يجب إخفاء تلميحات الأدوات قبل إزالة العناصر المقابلة لها من DOM.
  • يمكن تشغيل تلميحات الأدوات بفضل عنصر داخل ظل DOM.
بشكل افتراضي ، يستخدم هذا المكون معقم المحتوى المدمج ، والذي يزيل أي عناصر HTML غير مسموح بها بشكل صريح. راجع قسم المطهر في وثائق JavaScript لمزيد من التفاصيل.
يعتمد تأثير الرسوم المتحركة لهذا المكون على prefers-reduced-motionالاستعلام عن الوسائط. راجع قسم الحركة المخفضة في وثائق إمكانية الوصول الخاصة بنا .

حصلت على كل هذا؟ رائع ، دعنا نرى كيف يعملون مع بعض الأمثلة.

مثال: قم بتمكين التلميحات في كل مكان

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

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

أمثلة

مرر مؤشر الماوس فوق الروابط أدناه لمشاهدة تلميحات الأدوات:

نص العنصر النائب لتوضيح بعض الروابط المضمنة مع تلميحات الأدوات. هذا الآن مجرد حشو ، لا قاتل. تم وضع المحتوى هنا فقط لتقليد وجود نص حقيقي . وكل ذلك فقط لإعطائك فكرة عن كيفية ظهور تلميحات الأدوات عند استخدامها في مواقف العالم الحقيقي. لذلك نأمل أن تكون قد رأيت الآن كيف يمكن أن تعمل تلميحات الأدوات هذه على الروابط عمليًا ، بمجرد استخدامها على موقعك أو مشروعك.

قم بالمرور فوق الأزرار أدناه لمشاهدة اتجاهات تلميحات الأدوات الأربعة: أعلى ، ويمين ، وأسفل ، ويسار.

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">
  Tooltip on left
</button>

وبعد إضافة HTML المخصص:

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

إستعمال

يُنشئ المكون الإضافي لتلميح الأدوات المحتوى والترميز عند الطلب ، ويضع بشكل افتراضي تلميحات الأدوات بعد عنصر المشغل الخاص بهم.

تشغيل تلميح الأداة عبر JavaScript:

$('#example').tooltip(options)
تجاوز autoوscroll

يحاول موضع تلميح الأدوات أن يتغير تلقائيًا عندما يكون للحاوية الرئيسية overflow: autoأو overflow: scrollتشبهنا .table-responsive، لكنها تحافظ على موضع الموضع الأصلي. لحل المشكلة ، اضبط boundaryالخيار على أي شيء بخلاف القيمة الافتراضية 'scrollParent'، مثل 'window':

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

وضع علامة على

الترميز المطلوب لتلميح الأداة هو dataسمة فقط وعلى titleعنصر HTML الذي ترغب في الحصول عليه تلميح أداة. الترميز الذي تم إنشاؤه لتلميح الأداة بسيط نوعًا ما ، على الرغم من أنه يتطلب موضعًا (افتراضيًا ، يتم تعيينه topبواسطة المكون الإضافي).

عمل تلميحات الأدوات لمستخدمي لوحة المفاتيح والتقنيات المساعدة

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

<!-- HTML to write -->
<a href="#" data-toggle="tooltip" title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

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

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

<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="Disabled tooltip">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

خيارات

يمكن تمرير الخيارات عبر سمات البيانات أو JavaScript. لسمات البيانات ، قم بإلحاق اسم الخيار بـ data-، كما في data-animation="".

لاحظ أنه لأسباب تتعلق بالأمان sanitize، لا يمكن توفير الخيارات باستخدام سمات البيانات sanitizeFn. whiteList
اسم يكتب تقصير وصف
الرسوم المتحركة قيمة منطقية حقيقي تطبيق انتقال الخبو في CSS إلى تلميح الأداة
وعاء سلسلة | عنصر | خاطئة خاطئة

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

التأخير في إظهار تلميح الأداة وإخفائه (بالمللي ثانية) - لا ينطبق على نوع المشغل اليدوي

إذا تم توفير رقم ، فسيتم تطبيق التأخير على كل من الإخفاء / العرض

هيكل الكائن هو:delay: { "show": 500, "hide": 100 }
لغة البرمجة قيمة منطقية خاطئة

اسمح بتنسيق HTML في تلميح الأداة.

titleإذا كان هذا صحيحًا ، فسيتم تقديم علامات HTML في تلميح الأدوات في تلميح الأداة. textإذا كانت القيمة false ، فسيتم استخدام طريقة jQuery لإدراج المحتوى في DOM.

استخدم النص إذا كنت قلقًا بشأن هجمات XSS.
تحديد مستوى سلسلة | وظيفة 'أعلى'

كيفية وضع تلميح الأدوات - تلقائي | أعلى | أسفل | غادر | حقا.
عندما autoيتم تحديده ، فإنه سيعيد توجيه تلميح الأداة ديناميكيًا.

عندما يتم استخدام دالة لتحديد الموضع ، يتم استدعاؤها باستخدام عقدة DOM تلميح كأول وسيط لها وعقدة DOM المشغلة كعقدة ثانية لها. يتم thisتعيين السياق على مثيل تلميح الأدوات.
محدد سلسلة | خاطئة خاطئة إذا تم توفير محدد ، فسيتم تفويض كائنات تلميح الأدوات إلى الأهداف المحددة. في الممارسة العملية ، يتم استخدام هذا أيضًا لتطبيق تلميحات الأدوات على عناصر DOM المضافة ديناميكيًا ( jQuery.onالدعم). انظر إلى هذا ومثال إعلامي .
قالب سلسلة '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

قاعدة HTML لاستخدامها عند إنشاء التلميح.

titleسيتم إدخال تلميح الأدوات في ملف .tooltip-inner.

.arrowسيصبح سهم تلميح الأداة.

يجب أن يحتوي عنصر الغلاف الخارجي على .tooltipالفئة و role="tooltip".
لقب سلسلة | عنصر | وظيفة "

قيمة العنوان الافتراضية إذا titleلم تكن السمة موجودة.

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

كيف يتم تشغيل التلميح - انقر فوق | تحوم | التركيز | كتيب. يمكنك تمرير عدة مشغلات ؛ افصلهم بمسافة.

'manual'يشير إلى أن تلميح الأداة سيتم تشغيله برمجيًا عبر .tooltip('show')، .tooltip('hide')و .tooltip('toggle')الطرق ؛ لا يمكن دمج هذه القيمة مع أي مشغل آخر.

'hover'من تلقاء نفسه سينتج عن تلميحات أدوات لا يمكن تشغيلها عبر لوحة المفاتيح ، ويجب استخدامها فقط في حالة وجود طرق بديلة لنقل نفس المعلومات لمستخدمي لوحة المفاتيح.
عوض رقم | سلسلة | وظيفة 0

إزاحة تلميح الأداة بالنسبة إلى هدفه.

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

لمزيد من المعلومات راجع مستندات تعويض Popper .
احتياطي سلسلة | مجموعة مصفوفة 'يواجه' السماح بتحديد الموضع الذي سيستخدمه بوبر عند الرجوع. لمزيد من المعلومات ، راجع مستندات سلوك Popper
CustomClass سلسلة | وظيفة "

أضف فئات إلى تلميح الأداة عندما يتم عرضها. لاحظ أنه ستتم إضافة هذه الفئات بالإضافة إلى أي فئات محددة في النموذج. لإضافة عدة فئات ، افصل بينها بمسافات 'a b':.

يمكنك أيضًا تمرير دالة يجب أن تُرجع سلسلة واحدة تحتوي على أسماء فئات إضافية.
الحدود سلسلة | عنصر "scrollParent" تجاوز حدود القيد لتلميح الأداة. يقبل قيم 'viewport'، 'window'أو 'scrollParent'، أو مرجع HTMLElement (JavaScript فقط). لمزيد من المعلومات ، راجع مستندات Popper 's PreventionOverflow .
عقم قيمة منطقية حقيقي تمكين أو تعطيل التطهير. إذا تم تنشيطه 'template'وسيتم 'title'تعقيم الخيارات. راجع قسم المطهر في وثائق JavaScript الخاصة بنا .
القائمة البيضاء هدف القيمة الافتراضية الكائن الذي يحتوي على السمات والعلامات المسموح بها
تعقيم فارغ | وظيفة لا شيء هنا يمكنك توفير وظيفة التعقيم الخاصة بك. يمكن أن يكون هذا مفيدًا إذا كنت تفضل استخدام مكتبة مخصصة لإجراء التعقيم.
popperConfig فارغ | هدف لا شيء لتغيير تكوين Popper الافتراضي الخاص بـ Bootstrap ، راجع تكوين Popper

سمات البيانات لتلميحات الأدوات الفردية

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

طُرق

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

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

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

$().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استدعاء أسلوب المثيل.
معروض .bs.tooltip يتم تشغيل هذا الحدث عندما يصبح التلميح مرئيًا للمستخدم (سينتظر حتى تكتمل انتقالات CSS).
hide.bs.tooltip يتم تشغيل هذا الحدث فورًا عند hideاستدعاء أسلوب المثيل.
hidden.bs.tooltip يتم تشغيل هذا الحدث عند انتهاء إخفاء التلميح عن المستخدم (سينتظر حتى تكتمل انتقالات CSS).
المدرجة. bs.tooltip يتم تشغيل هذا الحدث بعد show.bs.tooltipالحدث عند إضافة قالب تلميح الأدوات إلى DOM. 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})