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>s שלך כדי להימנע מהתנהגות זו.
  • יש להסתיר עצות כלים לפני שהרכיבים התואמים שלהם יוסרו מה-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>

נוֹהָג

תוסף Tooltip מייצר תוכן וסימון לפי דרישה, וכברירת מחדל מציב עצות כלים אחרי אלמנט הטריגר שלהם.

הפעל את הסבר הכלי באמצעות 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>s) לניתנים למיקוד על ידי הוספת 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

עיכוב הצגת והסתרה של הסבר הכלי (ms) - אינו חל על סוג טריגר ידני

אם מסופק מספר, השהיה מוחל גם על הסתרה/הצגה

מבנה האובייקט הוא:delay: { "show": 500, "hide": 100 }
html בוליאני שֶׁקֶר

אפשר HTML בהסבר הכלי.

אם זה נכון, תגי HTML בהסבר הכלי titleיוצגו בהסבר. אם False, textהשיטה של ​​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 הגורם המפעיל מועבר כארגומנט השני.

למידע נוסף עיין במסמכי האופסט של פופר .
מיקום fallback מחרוזת | מַעֲרָך 'לְהַעִיף' אפשר לציין באיזו עמדה פופר ישתמש ב-fallback. למידע נוסף עיין במסמכי ההתנהגות של פופר
customClass מחרוזת | פוּנקצִיָה ''

הוסף כיתות להסבר הכלי כאשר הוא מוצג. שימו לב ששיעורים אלו יתווספו בנוסף לכל השיעורים המצוינים בתבנית. כדי להוסיף מחלקות מרובות, הפרד אותן באמצעות רווחים: 'a b'.

אתה יכול גם להעביר פונקציה שאמורה להחזיר מחרוזת אחת המכילה שמות מחלקות נוספים.
גְבוּל מחרוזת | אֵלֵמֶנט 'סcrollPrent' גבול אילוץ הצפת של הסבר הכלי. מקבל את הערכים של 'viewport', 'window', 'scrollParent'או הפניה ל-HTMLElement (JavaScript בלבד). למידע נוסף עיין במסמכי preventOverflow של Popper .
לחטא בוליאני נָכוֹן הפעל או השבת את החיטוי. אם יופעל 'template'והאפשרויות 'title'יעברו חיטוי. עיין בסעיף חיטוי בתיעוד ה-JavaScript שלנו .
רשימה לבנה לְהִתְנַגֵד ערך ברירת מחדל אובייקט המכיל תכונות ותגים מותרים
sanitizeFn null | פוּנקצִיָה ריק כאן אתה יכול לספק פונקציית חיטוי משלך. זה יכול להיות שימושי אם אתה מעדיף להשתמש בספרייה ייעודית לביצוע חיטוי.
popperConfig null | לְהִתְנַגֵד ריק כדי לשנות את ברירת המחדל של תצורת 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.tooltool אירוע זה מופעל כאשר הסבר הכלי נעשה גלוי למשתמש (יחכה לסיום מעברי CSS).
hide.bs.tooltip אירוע זה מופעל מיד כאשר hideשיטת המופע נקראה.
hidden.bs.tooltool אירוע זה מופעל כאשר הסבר הכלים סיים להסתיר מהמשתמש (יחכה לסיום מעברי CSS).
inserted.bs.tooltip אירוע זה מופעל לאחר show.bs.tooltipהאירוע כאשר תבנית הסבר הכלי נוספה ל-DOM. 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})