الفرق بين المراجعتين لصفحة: «Bootstrap/tooltips»
لا ملخص تعديل |
لا ملخص تعديل |
||
| (مراجعتان متوسطتان بواسطة مستخدم واحد آخر غير معروضتين) | |||
| سطر 1: | سطر 1: | ||
<noinclude>{{DISPLAYTITLE:التلميحات Tooltips في إطار العمل Bootstrap}}</noinclude> | <noinclude>{{DISPLAYTITLE:التلميحات Tooltips في إطار العمل Bootstrap}}</noinclude> | ||
[[تصنيف:Bootstrap]] | [[تصنيف:Bootstrap|{{SUBPAGENAME}}]] | ||
[[تصنيف:Bootstrap components]] | [[تصنيف:Bootstrap components|{{SUBPAGENAME}}]] | ||
أضف تلميحات Bootstrap المُخصَّصة إلى صفحات الويب باستخدام التأثيرات في انتقالات | أضف تلميحات Bootstrap المُخصَّصة إلى صفحات الويب باستخدام التأثيرات في انتقالات CSS وخاصيّات البيانات لتخزين العناوين محليًّا. | ||
== نظرة عامة == | == نظرة عامة == | ||
| سطر 13: | سطر 13: | ||
* لن تعمل التلميحات على العناصر المخفيّة. | * لن تعمل التلميحات على العناصر المخفيّة. | ||
* يجب تحفيز التلميحات من العنصُر المُغلِّف عند استهداف عناصر تطبِّق الخاصيّة <code>disabled</code> أو الصنف <code>.disabled</code>. | * يجب تحفيز التلميحات من العنصُر المُغلِّف عند استهداف عناصر تطبِّق الخاصيّة <code>disabled</code> أو الصنف <code>.disabled</code>. | ||
* تتوسّط التلميحات عند تحفيزها من روابط تلتفّ على أسطر متعدّدة، تتوسّط العرض الكامل للرابط. استخدم الخاصيّة <code>[[CSS/white-space|white-space]]: nowrap;</code> على الرابط <code> | * تتوسّط التلميحات عند تحفيزها من روابط تلتفّ على أسطر متعدّدة، تتوسّط العرض الكامل للرابط. استخدم الخاصيّة <code>[[CSS/white-space|white-space]]: nowrap;</code> على الرابط <code></code> لتفادي هذا الأمر. | ||
* يجب إخفاء التلميحات حتى يتسنّى حذفُ العناصر المتعلّقة بها من كائن المستند DOM. | * يجب إخفاء التلميحات حتى يتسنّى حذفُ العناصر المتعلّقة بها من كائن المستند DOM. | ||
* يمكن ابتداء التلميحات عبر عنصر داخل شجرة DOM. | |||
'''ملحوظة''': تأثير الحركة الخاص بهذه المكونة يعتمد على استعلام الوسائط <code>prefers-reduced-motion</code>. راجع [[Bootstrap/accessibility|صفحة سهولة الوصول]] لمزيد من المعلومات. | |||
واصل القراءة لأمثلة عن كيفيّة عمل التلميحات. | واصل القراءة لأمثلة عن كيفيّة عمل التلميحات. | ||
| سطر 49: | سطر 52: | ||
في ما يلي كيفيّة إظهار تلميحة بشفرة JavaScript:<syntaxhighlight lang="javascript"> | في ما يلي كيفيّة إظهار تلميحة بشفرة JavaScript:<syntaxhighlight lang="javascript"> | ||
$('#example').tooltip(options) | $('#example').tooltip(options) | ||
</syntaxhighlight>'''ملحوظة''': يحاول bootstrap تغيير موضع التلميحات تلقائيا إن كان للحاوية الخاصيتان <code>overflow: auto</code> و <code>overflow: scroll</code>، كما في الصنف <code>.table-responsive</code>. مع الحفاظ على التموضع الأصلي. لحل هذه المشكلة، عين قيمة الخيار <code>boundary</code> إلى أي قيمة خلا القيمة الافتراضية 'scrollParent'، مثل '<code>window</code>'.<syntaxhighlight lang="javascript"> | |||
$('#example').tooltip({ boundary: 'window' }) | |||
</syntaxhighlight> | </syntaxhighlight> | ||
| سطر 73: | سطر 79: | ||
العناصر التي تُطبَّق عليها الخاصيّة <code>disabled</code> ليست تفاعليّة؛ ممّا يعني أنّه لا يمكن للمستخدمين تركيز المؤشّر عليها، أو الحومان فوقها أو النقر عليها لإظهار تلميحة (أو عنصُر منبثق). توجد حيلة لتخطّي هذا العائق تتمثّل في إظهار التلميحة من عنصُر مغلِّف (<code>[[HTML/div|<nowiki><div></nowiki>]]</code> أو <code>[[HTML/span|<nowiki><span></nowiki>]]</code>)، وجعله قابلًا لاستقبال المؤشّر من لوحة المفاتيح باستخدام <code>tabindex="0"</code> وإبطال مفعول الخاصيّة <code>pointer-events</code> على العناصر المُعطَّلة.<syntaxhighlight lang="html"> | العناصر التي تُطبَّق عليها الخاصيّة <code>disabled</code> ليست تفاعليّة؛ ممّا يعني أنّه لا يمكن للمستخدمين تركيز المؤشّر عليها، أو الحومان فوقها أو النقر عليها لإظهار تلميحة (أو عنصُر منبثق). توجد حيلة لتخطّي هذا العائق تتمثّل في إظهار التلميحة من عنصُر مغلِّف (<code>[[HTML/div|<nowiki><div></nowiki>]]</code> أو <code>[[HTML/span|<nowiki><span></nowiki>]]</code>)، وجعله قابلًا لاستقبال المؤشّر من لوحة المفاتيح باستخدام <code>tabindex="0"</code> وإبطال مفعول الخاصيّة <code>pointer-events</code> على العناصر المُعطَّلة.<syntaxhighlight lang="html"> | ||
<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="تلمحية على زرّ معطّل"> | <span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="تلمحية على زرّ معطّل"> | ||
<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled> | <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button> | ||
</span> | </span> | ||
</syntaxhighlight> | </syntaxhighlight> | ||
| سطر 79: | سطر 85: | ||
=== الخيّارات === | === الخيّارات === | ||
يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق JavaScript. ألحق اسم الخيّار بالكلمة <code>data-</code> (مثلًا <code>data-animation=""</code> للخيّار <code>animation</code>) عند التمرير عبر خاصيّات البيانات. | يمكن تمرير الخيّارات عبر خاصيّات البيانات أو عن طريق JavaScript. ألحق اسم الخيّار بالكلمة <code>data-</code> (مثلًا <code>data-animation=""</code> للخيّار <code>animation</code>) عند التمرير عبر خاصيّات البيانات. | ||
'''ملحوظة''': لأسباب أمنية، لا يمكن تمرير الخيارات <code>sanitize</code> و <code>sanitizeFn</code> و <code>whiteList</code> في خاصيات البيانات. | |||
{| class="wikitable" | {| class="wikitable" | ||
!الاسم | !الاسم | ||
| سطر 93: | سطر 100: | ||
| سلسلة محارف |<nowiki> عنصُر | </nowiki><code>false</code> | | سلسلة محارف |<nowiki> عنصُر | </nowiki><code>false</code> | ||
|<code>false</code> | |<code>false</code> | ||
| | |<p>إلحاق التلميحة بالعنصُر المخصوص. مثال: <code>container: 'body'</code>. هذا الخيّار مفيد جدًّا، إذ يمكّنك من وضع التلميحة قرب العنصُر الذي تشير إليه، ممّا يمنع التلميحة من الابتعاد أثناء تغيير قياس النافذة.</p> | ||
|- | |- | ||
|<code>delay</code> (تأخير) | |<code>delay</code> (تأخير) | ||
| | | سلسلة محارف |كائن | ||
|<code>0</code> | |<code>0</code> | ||
| | |<p>تأخير إظهار أو إخفاء االتلميحة (بالميلّي ثانيّة). لا ينطبق على التلميحات المُظهرة يدويّا.</p> | ||
<p>عند تمرير عدد فإنّ التأخير يُطبَّق على الإظهار (<code>show</code>) والإخفاء (<code>hide</code>) كليهما.</p> | <p>عند تمرير عدد فإنّ التأخير يُطبَّق على الإظهار (<code>show</code>) والإخفاء (<code>hide</code>) كليهما.</p> | ||
<p>بنية الكائن هي كالتالي</p><p><code>delay: { "show": 500, "hide": 100 }</code></p> | <p>بنية الكائن هي كالتالي</p><p><code>delay: { "show": 500, "hide": 100 }</code></p> | ||
|- | |- | ||
|<code>html</code> | |<code>html</code> | ||
|قيمة منطقيّة | | عدد |قيمة منطقيّة | ||
|<code>false</code> | |<code>false</code> | ||
| | |<p>يسمح بكتابة شفرات HTML داخل نصّ التلميحة.</p> | ||
<p>إنْ كانت قيمة الخيار <code>true</code> فستُعرَض وسوم HTML داخل عنوان التلميحة (الخاصيّة <code>title</code>)؛ وإلّا فإنّ التابع <code>text</code> في jQuery سيُستخدَم لإدراج المحتوى في كائن المستند DOM. | <p>إنْ كانت قيمة الخيار <code>true</code> فستُعرَض وسوم HTML داخل عنوان التلميحة (الخاصيّة <code>title</code>)؛ وإلّا فإنّ التابع <code>text</code> في jQuery سيُستخدَم لإدراج المحتوى في كائن المستند DOM. | ||
</p>استخدم نصًّا بسيطًا إنْ كنت تخشى من هجمات XSS.</p> | </p>استخدم نصًّا بسيطًا إنْ كنت تخشى من هجمات XSS.</p> | ||
|- | |- | ||
|<code>placement</code> (التموضع) | |<code>placement</code> (التموضع) | ||
|دالّة | |||
|<code>'top'</code> | |<code>'top'</code> | ||
| | |<p>تموضع التلميحة: <code>auto</code><nowiki> (تلقائي) | </nowiki><code>top</code><nowiki> (أعلى) | </nowiki><code>bottom</code><nowiki> (أسفل) | </nowiki><code>left</code><nowiki> (يسار) | </nowiki><code>right</code> (يمين).<br>يُعاد توجيه التلميحة تلقائيَّا عند اختيّار التموضع التلقائي (<code>auto</code>). | ||
</p> | </p> | ||
<p>عند استخدام دالّة لتحديد التموضع فإنّ المُعطَى الأوّل الذي يُمرّر لها أثناء استدعائها هو موقع التلميحة في كائن المستنَد والمُعطَى الثاني هو مكان العنصُر الذي تتبع له التلميحة. يُعيَّن سياق المتغيّر <code>[[JavaScript/this|this]]</code> إلى التلميحة.</p> | <p>عند استخدام دالّة لتحديد التموضع فإنّ المُعطَى الأوّل الذي يُمرّر لها أثناء استدعائها هو موقع التلميحة في كائن المستنَد والمُعطَى الثاني هو مكان العنصُر الذي تتبع له التلميحة. يُعيَّن سياق المتغيّر <code>[[JavaScript/this|this]]</code> إلى التلميحة.</p> | ||
|- | |- | ||
|<code>selector</code> (المُحدِّد) | |<code>selector</code> (المُحدِّد) | ||
| | | سلسة محارف |false | ||
|<code>false</code> | |<code>false</code> | ||
|تُفوّض كائنات العناصر المنبثقة إلى الأهداف المُحدّدة إذا كان هناك مُحدِد مُمرّر. يُستخدَم هذا الخيّار عمليًّا لتفعيل محتوى HTML ديناميكيّ لإضافة عناصر منبثقة. انظر [https://github.com/twbs/bootstrap/issues/4215 هنا] و[https://jsbin.com/zopod/1/edit هذا المثال المفيد] | |تُفوّض كائنات العناصر المنبثقة إلى الأهداف المُحدّدة إذا كان هناك مُحدِد مُمرّر. يُستخدَم هذا الخيّار عمليًّا لتفعيل محتوى HTML ديناميكيّ لإضافة عناصر منبثقة. انظر [https://github.com/twbs/bootstrap/issues/4215 هنا] و[https://jsbin.com/zopod/1/edit هذا المثال المفيد] | ||
|- | |- | ||
|<code>template</code> (قالب) | |<code>template</code> (قالب) | ||
|سلسلة محارف | | سلسلة محارف |سلسلة محارف | ||
|<code>'<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'</code> | |<code>'<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'</code> | ||
| | |<p>شفرة HTML قاعديّة للاستخدام أثناء إنشاء التلميحة.</p> | ||
<p>يُحقَن عنوان التلميحة (<code>title</code>) في الصنف (<code>.tooltip-inner</code>). | <p>يُحقَن عنوان التلميحة (<code>title</code>) في الصنف (<code>.tooltip-inner</code>). | ||
</p> | </p> | ||
| سطر 140: | سطر 138: | ||
<p>يجب أن يحوي العنصُر المغلِّف الأعلى الصنف <code>.tooltip</code> والخاصيّة <code>role="tooltip"</code>. | <p>يجب أن يحوي العنصُر المغلِّف الأعلى الصنف <code>.tooltip</code> والخاصيّة <code>role="tooltip"</code>. | ||
</p> | </p> | ||
|- | |- | ||
|<code>title</code> (العنوان) | |<code>title</code> (العنوان) | ||
|<nowiki> عنصُر | دالّة</nowiki> | |||
|سلسلة محارف فارغة | |سلسلة محارف فارغة | ||
| | |<p>قيمة العنوان المبدئيّة إنْ لم تكن الخاصيّة <code>title</code> موجودة في التلميحة.</p> | ||
<p>عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي تحيل إليه التلميحة إلى المتغيّر <code>this</code>.</p> | <p>عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي تحيل إليه التلميحة إلى المتغيّر <code>this</code>.</p> | ||
|- | |- | ||
|<code>trigger</code> (التفعيل) | |<code>trigger</code> (التفعيل) | ||
|سلسلة محارف | | سلسلة محارف |سلسلة محارف | ||
|<code>'hover focus'</code> | |<code>'hover focus'</code> | ||
| | |<p>كيفيّة إظهار التلميحة: <code>click</code><nowiki> (النقر) | </nowiki><code>hover</code><nowiki> (الحومان)| </nowiki><code>focus</code><nowiki> (تركيز المؤشّر)| </nowiki><code>manual</code> (يدوي). يمكن تمرير طرق عدّة، افصل بينها بمسافة. | ||
</p> | </p> | ||
<p>تشير القيمة <code>'manual'</code> إلى أنّ التلميحة ستُفعَّل برمجيّا بالتوابع <code>.tooltip('show')</code>، و <code>.tooltip('hide')</code> و <code>.tooltip('toggle')</code>. لا يمكن استعمال أيّ قيمة أخرى إلى جانب هذه القيمة. </p> | <p>تشير القيمة <code>'manual'</code> إلى أنّ التلميحة ستُفعَّل برمجيّا بالتوابع <code>.tooltip('show')</code>، و <code>.tooltip('hide')</code> و <code>.tooltip('toggle')</code>. لا يمكن استعمال أيّ قيمة أخرى إلى جانب هذه القيمة. </p> | ||
| سطر 160: | سطر 155: | ||
|- | |- | ||
|<code>offset</code> (الانزياح) | |<code>offset</code> (الانزياح) | ||
|سلسلة محارف | |||
|0 | |0 | ||
|انزيّاح التلميحة عن العنصُر المستهدَف. راجع [https://popper.js.org/popper-documentation.html#modifiers..offset.offset توثيق Offset في Popper.js] للمزيد من المعلومات. | | كيفيّة تفعيل العنصُر المنبثق: click (النقر) |انزيّاح التلميحة عن العنصُر المستهدَف. راجع [https://popper.js.org/popper-documentation.html#modifiers..offset.offset توثيق Offset في Popper.js] للمزيد من المعلومات. | ||
|- | |- | ||
|<code>fallbackPlacement</code> (موضع التراجع) | |<code>fallbackPlacement</code> (موضع التراجع) | ||
| | | عدد |مصفوفة | ||
|<code>'flip'</code> | |<code>'flip'</code> | ||
|يسمح بتحديد الموضع الذي سيختاره Popper.js عند التراجع Fallback. راجع [https://popper.js.org/popper-documentation.html#modifiers..flip.behavior توثيق Popper.js] للمزيد من المعلومات. | |يسمح بتحديد الموضع الذي سيختاره Popper.js عند التراجع Fallback. راجع [https://popper.js.org/popper-documentation.html#modifiers..flip.behavior توثيق Popper.js] للمزيد من المعلومات. | ||
|- | |- | ||
|<code>boundary</code> (حدود) | |<code>boundary</code> (حدود) | ||
| سلسلة محارف | عنصُر | | سلسلة محارف |عنصُر | ||
|<code>'scrollParent'</code> | |<code>'scrollParent'</code> | ||
|حدود قيد طفح Overflow التلميحة. يقبل القيم <code>'viewport'</code> (إطار العرض)، أو<code>'window'</code> (نافذة)، أو <code>'scrollParent'</code> (عنصُر أب يقبل التمرير) أو عنصُر HTML (فقط عند استخدام JavaScript). راجع [https://popper.js.org/popper-documentation.html#modifiers..preventOverflow.boundariesElement توثيق Popper.js] للمزيد من المعلومات. | |حدود قيد طفح Overflow التلميحة. يقبل القيم <code>'viewport'</code> (إطار العرض)، أو<code>'window'</code> (نافذة)، أو <code>'scrollParent'</code> (عنصُر أب يقبل التمرير) أو عنصُر HTML (فقط عند استخدام JavaScript). راجع [https://popper.js.org/popper-documentation.html#modifiers..preventOverflow.boundariesElement توثيق Popper.js] للمزيد من المعلومات. | ||
|- | |- | ||
|<code>sanitize</code> | |||
|قيمة منطقية | |||
|<code>true</code> | |||
|يتيح أو يعطل التصحيح. في حال تفعيلها، ستُصحّح كلّ من <code>'template'</code>و <code>'content'</code> و <code>'title'</code> | |||
|- | |||
|<code>whiteList</code> | |||
|كائن | |||
|[[Bootstrap/javascript#.D8.A7.D9.84.D9.85.D8.B5.D8.AD.D8.AD.D8.A7.D8.AA Sanitizers|القيمة الافتراضية]] | |||
|كائن يحتوي السمات والوسوم المسموح بها | |||
|- | |||
|<code>sanitizeFn</code> | |||
|قيمة معدومة أو دالة | |||
|قيمة معدومة | |||
|يمكنك هنا تخصيص دالة التصحيح. هذا مفيد في حال كنت تفضل استخدام مكتبة خاصة لإجراء التصحيح | |||
|- | |||
|<code>popperConfig</code> | |||
|قيمة معدومة أو كائن | |||
|قيمة معدومة | |||
|لتغيير إعدادات Popper.js الافتراضية. راجع [https://popper.js.org/docs/v1/#Popper.Defaults هذه الصفحة] لمزيد من التفاصيل | |||
|} | |} | ||
=== خاصيّات البيانات لتلميحات منفردة === | === خاصيّات البيانات لتلميحات منفردة === | ||
يمكن تعيين خيّارات بديلة لتلميحات منفردة باستخدام خاصيّات البيانات كما هو محدَّد أعلاه. | يمكن تعيين خيّارات بديلة لتلميحات منفردة باستخدام خاصيّات البيانات كما هو محدَّد أعلاه. | ||
| سطر 205: | سطر 218: | ||
يخفي ويحذف تلميحة من عنصُر. لا يمكن حذف التلميحات التي تستخدم التفويض (أي التي أُنشِئت باستخدام المُحدِّد <code>selector</code>) فرديًّا من العناصر الأبناء.<syntaxhighlight lang="javascript"> | يخفي ويحذف تلميحة من عنصُر. لا يمكن حذف التلميحات التي تستخدم التفويض (أي التي أُنشِئت باستخدام المُحدِّد <code>selector</code>) فرديًّا من العناصر الأبناء.<syntaxhighlight lang="javascript"> | ||
$('#element').tooltip('dispose') | $('#element').tooltip('dispose') | ||
</syntaxhighlight> | |||
==== <code>.tooltip('enable')</code> ==== | |||
يمنح عنصر تلميحة قابليّة العرض. وهو الخيار الافتراضي.<syntaxhighlight lang="javascript"> | |||
$('#element').tooltip('enable') | |||
</syntaxhighlight> | </syntaxhighlight> | ||
| سطر 248: | سطر 267: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
== مصادر == | == مصادر == | ||
* [https://getbootstrap.com/docs/4. | * [https://getbootstrap.com/docs/4.5/components/tooltips/ صفحة Tooltips في توثيق Bootstrap]. | ||
المراجعة الحالية بتاريخ 11:40، 13 يوليو 2020
أضف تلميحات 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
|
إلحاق التلميحة بالعنصُر المخصوص. مثال: |
delay (تأخير)
|
كائن | 0
|
تأخير إظهار أو إخفاء االتلميحة (بالميلّي ثانيّة). لا ينطبق على التلميحات المُظهرة يدويّا. عند تمرير عدد فإنّ التأخير يُطبَّق على الإظهار ( بنية الكائن هي كالتالي
|
html
|
قيمة منطقيّة | false
|
يسمح بكتابة شفرات HTML داخل نصّ التلميحة. إنْ كانت قيمة الخيار |
placement (التموضع)
|
دالّة | 'top'
|
تموضع التلميحة: عند استخدام دالّة لتحديد التموضع فإنّ المُعطَى الأوّل الذي يُمرّر لها أثناء استدعائها هو موقع التلميحة في كائن المستنَد والمُعطَى الثاني هو مكان العنصُر الذي تتبع له التلميحة. يُعيَّن سياق المتغيّر |
selector (المُحدِّد)
|
false | false
|
تُفوّض كائنات العناصر المنبثقة إلى الأهداف المُحدّدة إذا كان هناك مُحدِد مُمرّر. يُستخدَم هذا الخيّار عمليًّا لتفعيل محتوى HTML ديناميكيّ لإضافة عناصر منبثقة. انظر هنا وهذا المثال المفيد |
template (قالب)
|
سلسلة محارف | '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'
|
شفرة HTML قاعديّة للاستخدام أثناء إنشاء التلميحة. يُحقَن عنوان التلميحة ( تصبح قيمة يجب أن يحوي العنصُر المغلِّف الأعلى الصنف |
title (العنوان)
|
عنصُر | دالّة | سلسلة محارف فارغة | قيمة العنوان المبدئيّة إنْ لم تكن الخاصيّة عند تمرير دالّة فإنّها تُستدعَى مع إسناد العنصُر الذي تحيل إليه التلميحة إلى المتغيّر |
trigger (التفعيل)
|
سلسلة محارف | 'hover focus'
|
كيفيّة إظهار التلميحة: تشير القيمة ينتُج عن استخدام القيمة |
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 () {
// افعل شيئا هنا …
})