تلميحات الأدوات (Tooltips)

نظرة عامة

أشياء يجب معرفتها عند استخدام إضافة تلميحات الأدوات (tooltip plugin):

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

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

أمثلة

تفعيل تلميحات الأدوات

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

const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))

تلميحات الأدوات على الروابط

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

<p class="muted">Placeholder text to demonstrate some <a href="#" data-bs-toggle="tooltip" data-bs-title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-bs-toggle="tooltip" data-bs-title="Another tooltip">real text</a>. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you’ve now seen how <a href="#" data-bs-toggle="tooltip" data-bs-title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-bs-toggle="tooltip" data-bs-title="The last tip!">your own</a> site or project.</p>

تلميحات أدوات مخصصة

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

.custom-tooltip {
  --bs-tooltip-bg: var(--bd-violet-bg);
  --bs-tooltip-color: var(--bs-white);
}

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

الإتجاهات

مرر مؤشر الماوس فوق الأزرار أدناه لرؤية اتجاهات تلميحات الأدوات الأربعة: الأعلى، واليمين، والأسفل، واليسار. يتم عكس الاتجاهات عند استخدام الـ Bootstrap في وضع RTL.

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

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

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

بإستخدام الـ (SVG):

الـ (CSS)

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

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

--#{$prefix}tooltip-zindex: #{$zindex-tooltip};
--#{$prefix}tooltip-max-width: #{$tooltip-max-width};
--#{$prefix}tooltip-padding-x: #{$tooltip-padding-x};
--#{$prefix}tooltip-padding-y: #{$tooltip-padding-y};
--#{$prefix}tooltip-margin: #{$tooltip-margin};
@include rfs($tooltip-font-size, --#{$prefix}tooltip-font-size);
--#{$prefix}tooltip-color: #{$tooltip-color};
--#{$prefix}tooltip-bg: #{$tooltip-bg};
--#{$prefix}tooltip-border-radius: #{$tooltip-border-radius};
--#{$prefix}tooltip-opacity: #{$tooltip-opacity};
--#{$prefix}tooltip-arrow-width: #{$tooltip-arrow-width};
--#{$prefix}tooltip-arrow-height: #{$tooltip-arrow-height};

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

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     var(--#{$prefix}body-bg);
$tooltip-bg:                        var(--#{$prefix}emphasis-color);
$tooltip-border-radius:             var(--#{$prefix}border-radius);
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    null; // TODO: remove this in v6

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
// fusv-disable
$tooltip-arrow-color:               null; // Deprecated in Bootstrap 5.2.0 for CSS variables
// fusv-enable

الإستخدام

تقوم إضافة تلميحات الأدوات (tooltip plugin) بتوليد المحتوى والتنسيق عند الطلب، وتضع تلميحات الأدوات افتراضياً بعد العنصر الذي يقوم بتشغيلها. قم بتشغيل تلميح الأداة عبر الـ JavaScript:

const exampleEl = document.getElementById('example')
const tooltip = new bootstrap.Tooltip(exampleEl, options)

const tooltip = new bootstrap.Tooltip('#example', {
  boundary: document.body // or document.querySelector('#boundary')
})

التوصيف (Markup)

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

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

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

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

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

<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" data-bs-title="Disabled tooltip">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

خيارات

بما أنه يمكن تمرير الخيارات عبر سمات البيانات (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 حيث يقوم آخر مفتاح-قيمة مُعطى بتجاوز القيم الأخرى.

استخدام الدالة (function) مع popperConfig

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

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

const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })

الأحداث (Events)

const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', () => {
  // do something...
})

tooltip.hide()