تلميحات

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

على هذه الصفحة

ملخص

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

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

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

بشكل افتراضي ، يستخدم هذا المكون معقم المحتوى المدمج ، والذي يزيل أي عناصر HTML غير مسموح بها بشكل صريح. راجع قسم المطهر في وثائق JavaScript لمزيد من التفاصيل.

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

أمثلة

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

كما ذكر أعلاه ، يجب تهيئة تلميحات الأدوات قبل استخدامها. تتمثل إحدى طرق تهيئة جميع تلميحات الأدوات على الصفحة في تحديدها حسب 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>

لا تتردد في استخدام أي من titleأو data-bs-titleفي HTML الخاص بك. عند titleاستخدامه ، سيقوم Popper باستبداله تلقائيًا data-bs-titleعندما يتم تقديم العنصر.

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

تمت الإضافة في الإصدار 5.2.0

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

.custom-tooltip {
  --bs-tooltip-bg: var(--bs-primary);
}

لغة البرمجة

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

<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

المتغيرات

تمت الإضافة في الإصدار 5.2.0

كجزء من نهج متغيرات CSS المتطور في Bootstrap ، تستخدم تلميحات الأدوات الآن متغيرات 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};

متغيرات ساس

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     $white;
$tooltip-bg:                        $black;
$tooltip-border-radius:             $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

إستعمال

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

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

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

تجاوز `auto`و`scroll`

يحاول موضع تلميح الأدوات أن يتغير تلقائيًا عندما يكون للحاوية الرئيسيةoverflow: auto أو overflow: scrollتشبهنا .table-responsive، لكنها تحافظ على موضع الموضع الأصلي. لحل هذه المشكلة ، اضبط boundaryالخيار (لمعدِّل الوجه باستخدام popperConfigالخيار) على أي HTMLElement لتجاوز القيمة الافتراضية 'clippingParents'، مثل document.body:

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

وضع علامة على

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

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

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

<!-- 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-top" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

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

العناصر التي تحتوي على disabledالسمة ليست تفاعلية ، مما يعني أنه لا يمكن للمستخدمين التركيز عليها أو التمرير فوقها أو النقر فوقها لتشغيل تلميح أداة (أو منبثق). كحل بديل ، سترغب في تشغيل تلميح الأداة من غلاف <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>

خيارات

نظرًا لأنه يمكن تمرير الخيارات عبر سمات البيانات أو 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"النهائية وستتجاوز سمات البيانات المنفصلة القيم المعطاة . بالإضافة إلى ذلك ، يمكن لسمات البيانات الحالية استيعاب قيم JSON مثل .title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

لاحظ أنه لأسباب تتعلق بالأمان sanitize، لا يمكن توفير الخيارات sanitizeFn، و ، باستخدام سمات البيانات.allowList

اسم	يكتب	تقصير	وصف
`allowList`	هدف	القيمة الافتراضية	الكائن الذي يحتوي على السمات والعلامات المسموح بها.
`animation`	قيمة منطقية	`true`	تطبيق انتقال الخبو في CSS إلى تلميح الأداة.
`boundary`	سلسلة ، عنصر	`'clippingParents'`	حدود قيد تجاوز السعة الخاصة بتلميح الأداة (تنطبق فقط على معدل منع تجاوز تدفق Popper). بشكل افتراضي ، يكون `'clippingParents'`ويمكن قبول مرجع HTMLElement (عبر JavaScript فقط). لمزيد من المعلومات ، راجع مستندات DiscoverOverflow الخاصة بـ Popper .
`container`	سلسلة ، عنصر ، خطأ	`false`	لإلحاق تلميح الأداة بعنصر معين. مثال `container: 'body'`:. هذا الخيار مفيد بشكل خاص لأنه يسمح لك بوضع تلميح الأداة في تدفق المستند بالقرب من عنصر التشغيل - والذي سيمنع تلميح الأداة من الابتعاد عن عنصر التشغيل أثناء تغيير حجم النافذة.
`customClass`	سلسلة ، وظيفة	`''`	أضف فئات إلى تلميح الأداة عندما يتم عرضها. لاحظ أنه ستتم إضافة هذه الفئات بالإضافة إلى أي فئات محددة في النموذج. لإضافة عدة فئات ، افصل بينها بمسافات `'class-1 class-2'`:. يمكنك أيضًا تمرير دالة يجب أن تُرجع سلسلة واحدة تحتوي على أسماء فئات إضافية.
`delay`	عدد وجوه	`0`	التأخير في إظهار تلميح الأداة وإخفائه (بالمللي ثانية) —لا ينطبق على نوع المشغل اليدوي. إذا تم توفير رقم ، فسيتم تطبيق التأخير على كل من الإخفاء / العرض. هيكل الكائن هو `delay: { "show": 500, "hide": 100 }`:.
`fallbackPlacements`	مجموعة مصفوفة	`['top', 'right', 'bottom', 'left']`	حدد المواضع الاحتياطية من خلال توفير قائمة بالمواضع في مصفوفة (بترتيب التفضيل). لمزيد من المعلومات ، راجع مستندات سلوك Popper .
`html`	قيمة منطقية	`false`	اسمح بتنسيق HTML في تلميح الأداة. `title`إذا كان هذا صحيحًا ، فسيتم تقديم علامات HTML في تلميح الأدوات في تلميح الأداة. إذا كان خطأ ، `innerText`فسيتم استخدام الخاصية لإدراج محتوى في DOM. استخدم النص إذا كنت قلقًا بشأن هجمات XSS.
`offset`	مجموعة ، سلسلة ، وظيفة	`[0, 0]`	إزاحة تلميح الأداة بالنسبة إلى هدفه. يمكنك تمرير سلسلة في سمات البيانات بقيم مفصولة بفواصل مثل `data-bs-offset="10,20"`:. عندما يتم استخدام دالة لتحديد الإزاحة ، يتم استدعاؤها بكائن يحتوي على موضع بوبر ، والمرجع ، ومستقيم بوبر كوسيطة أولى لها. يتم تمرير عقدة DOM المشغلة كوسيطة ثانية. يجب أن تُرجع الدالة مصفوفة برقمين : الانزلاق والمسافة . لمزيد من المعلومات راجع مستندات تعويض Popper .
`placement`	سلسلة ، وظيفة	`'top'`	كيفية وضع تلميح الأداة: تلقائي ، أعلى ، أسفل ، يسار ، يمين. عندما `auto`يتم تحديده ، فإنه سيعيد توجيه تلميح الأداة ديناميكيًا. عندما يتم استخدام دالة لتحديد الموضع ، يتم استدعاؤها باستخدام عقدة DOM تلميح كأول وسيط لها وعقدة DOM المشغلة كعقدة ثانية لها. يتم `this`تعيين السياق على مثيل تلميح الأدوات.
`popperConfig`	فارغة ، كائن ، وظيفة	`null`	لتغيير تكوين Popper الافتراضي الخاص بـ Bootstrap ، راجع تكوين Popper . عند استخدام وظيفة لإنشاء تكوين Popper ، يتم استدعاؤها بكائن يحتوي على تكوين Popper الافتراضي الخاص بـ Bootstrap. يساعدك على استخدام ودمج الافتراضي مع التكوين الخاص بك. يجب أن تقوم الوظيفة بإرجاع كائن تكوين لـ Popper.
`sanitize`	قيمة منطقية	`true`	تمكين أو تعطيل التطهير. في حالة التنشيط `'template'`، سيتم تعقيم الخيارات `'content'`.`'title'`
`sanitizeFn`	لاغية وظيفة	`null`	هنا يمكنك توفير وظيفة التعقيم الخاصة بك. يمكن أن يكون هذا مفيدًا إذا كنت تفضل استخدام مكتبة مخصصة لإجراء التعقيم.
`selector`	سلسلة ، خطأ	`false`	إذا تم توفير محدد ، فسيتم تفويض كائنات تلميح الأدوات إلى الأهداف المحددة. في الممارسة العملية ، يتم استخدام هذا أيضًا لتطبيق تلميحات الأدوات على عناصر DOM المضافة ديناميكيًا ( `jQuery.on`الدعم). انظر إلى هذه المشكلة ومثال إعلامي .
`template`	سلسلة	`'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'`	قاعدة HTML لاستخدامها عند إنشاء التلميح. `title`سيتم إدخال تلميح الأدوات في ملف `.tooltip-inner`. `.tooltip-arrow`سيصبح سهم تلميح الأداة. يجب أن يحتوي عنصر الغلاف الخارجي على `.tooltip`الفئة و `role="tooltip"`.
`title`	سلسلة ، عنصر ، وظيفة	`''`	قيمة العنوان الافتراضية إذا `title`لم تكن السمة موجودة. إذا تم توفير وظيفة ، فسيتم استدعاؤها مع `this`مجموعة مرجعية لها إلى العنصر الذي يتم إرفاق العنصر المنبثق به.
`trigger`	سلسلة	`'hover focus'`	كيف يتم تشغيل التلميح: النقر ، التمرير ، التركيز ، الدليل. يمكنك تمرير عدة مشغلات ؛ افصلهم بمسافة. `'manual'`يشير إلى أن تلميح الأداة سيتم تشغيله برمجيًا عبر `.tooltip('show')`، `.tooltip('hide')`و `.tooltip('toggle')`الطرق ؛ لا يمكن دمج هذه القيمة مع أي مشغل آخر. `'hover'`من تلقاء نفسه سينتج عن تلميحات أدوات لا يمكن تشغيلها عبر لوحة المفاتيح ، ويجب استخدامها فقط في حالة وجود طرق بديلة لنقل نفس المعلومات لمستخدمي لوحة المفاتيح.

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

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

استخدام وظيفة مع`popperConfig`

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

طُرق

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

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

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

طريقة	وصف
`disable`	يزيل إمكانية عرض تلميح أداة عنصر ما. لن يتم عرض التلميح إلا إذا تمت إعادة تمكينه.
`dispose`	يخفي ويدمر تلميح أداة عنصر (يزيل البيانات المخزنة على عنصر DOM). لا يمكن إتلاف تلميحات الأدوات التي تستخدم التفويض (والتي يتم إنشاؤها باستخدام الخيار ) بشكل فردي في عناصر المشغل التابعة.`selector`
`enable`	يمنح تلميح أداة عنصر القدرة على الظهور. يتم تمكين تلميحات الأدوات بشكل افتراضي.
`getInstance`	طريقة ثابتة تتيح لك ربط مثيل تلميح الأدوات بعنصر DOM ، أو إنشاء مثيل جديد في حالة عدم تهيئته.
`getOrCreateInstance`	طريقة ثابتة تتيح لك ربط مثيل تلميح الأدوات بعنصر DOM ، أو إنشاء مثيل جديد في حالة عدم تهيئته.
`hide`	يخفي تلميح أداة عنصر. يعود إلى المتصل قبل إخفاء التلميح (أي قبل `hidden.bs.tooltip`وقوع الحدث). يعتبر هذا بمثابة تشغيل "يدوي" للتلميح.
`setContent`	يوفر طريقة لتغيير محتوى التلميح بعد التهيئة.
`show`	يكشف عن تلميح أداة عنصر. يعود إلى المتصل قبل عرض التلميح بالفعل (أي قبل `shown.bs.tooltip`وقوع الحدث). يعتبر هذا بمثابة تشغيل "يدوي" للتلميح. لا يتم أبدًا عرض تلميحات الأدوات ذات العناوين ذات الطول الصفري.
`toggle`	يبدل تلميح أداة عنصر. يعود إلى المتصل قبل إظهار التلميح أو إخفاؤه بالفعل (أي قبل وقوع الحدث `shown.bs.tooltip`أو ). `hidden.bs.tooltip`يعتبر هذا بمثابة تشغيل "يدوي" للتلميح.
`toggleEnabled`	لتبديل إمكانية إظهار تلميح أداة عنصر ما أو إخفاؤه.
`update`	يحدّث موضع تلميح أداة العنصر.

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

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

setContentتقبل الطريقة وسيطة object، حيث يكون كل مفتاح خاصية stringمحددًا صالحًا داخل القالب المنبثق ، ويمكن أن تكون كل قيمة خاصية ذات صلة string| element| function| null

الأحداث

حدث	وصف
`hide.bs.tooltip`	يتم تشغيل هذا الحدث فورًا عند `hide`استدعاء أسلوب المثيل.
`hidden.bs.tooltip`	يتم تشغيل هذا الحدث عند انتهاء إخفاء العنصر المنبثق عن المستخدم (سينتظر حتى تكتمل انتقالات CSS).
`inserted.bs.tooltip`	يتم تشغيل هذا الحدث بعد `show.bs.tooltip`الحدث عند إضافة قالب تلميح الأدوات إلى DOM.
`show.bs.tooltip`	يتم تشغيل هذا الحدث فورًا عند `show`استدعاء أسلوب المثيل.
`shown.bs.tooltip`	يتم تشغيل هذا الحدث عندما يصبح العنصر المنبثق مرئيًا للمستخدم (سينتظر حتى تكتمل انتقالات CSS).

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

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

tooltip.hide()

تلميحات

ملخص

أمثلة

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

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

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

الاتجاهات

CSS

المتغيرات

متغيرات ساس

إستعمال

تجاوز autoوscroll

وضع علامة على

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

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

خيارات

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

استخدام وظيفة معpopperConfig

طُرق

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

الأحداث

تجاوز `auto`و`scroll`

استخدام وظيفة مع`popperConfig`