עצות כלים
תיעוד ודוגמאות להוספת טיפים מותאמים אישית של Bootstrap עם CSS ו-JavaScript באמצעות CSS3 עבור אנימציות ו-data-bs-attributes עבור אחסון כותרות מקומי.
סקירה כללית
דברים שכדאי לדעת בעת שימוש בתוסף טיפים:
- עצות כלים מסתמכות על ספריית הצד השלישי Popper לצורך מיקום. עליך לכלול popper.min.js לפני bootstrap.js או להשתמש ב
bootstrap.bundle.min.js
/bootstrap.bundle.js
המכיל Popper כדי שטיפים לכלים יפעלו! - טיפים לכלים ניתנים להצטרפות מסיבות ביצועים, לכן עליך לאתחל אותם בעצמך .
- עצות כלים עם כותרות באורך אפס לעולם אינן מוצגות.
- ציין
container: 'body'
כדי להימנע מעיבוד בעיות ברכיבים מורכבים יותר (כמו קבוצות הקלט שלנו, קבוצות לחצנים וכו'). - הפעלת עצות כלים על אלמנטים מוסתרים לא תעבוד.
- יש להפעיל עצות כלים עבור רכיבים
.disabled
אוdisabled
אלמנטים על רכיב עטיפה. - כאשר מופעלים מהיפר-קישורים המשתרעים על פני שורות מרובות, עצות הכלים ירוכזו. השתמש
white-space: nowrap;
ב-<a>
s שלך כדי להימנע מהתנהגות זו. - יש להסתיר עצות כלים לפני שהרכיבים התואמים שלהם יוסרו מה-DOM.
- ניתן להפעיל עצות כלים הודות לאלמנט בתוך DOM צל.
prefers-reduced-motion
בשאילתת המדיה. עיין
בסעיף תנועה מופחתת בתיעוד הנגישות שלנו .
יש לך את כל זה? נהדר, בוא נראה איך הם עובדים עם כמה דוגמאות.
דוגמה: אפשר עצות כלים בכל מקום
דרך אחת לאתחל את כל טיפים הכלים בדף תהיה לבחור אותם לפי data-bs-toggle
התכונה שלהם:
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
return new bootstrap.Tooltip(tooltipTriggerEl)
})
דוגמ��ות
רחף מעל הקישורים למטה כדי לראות עצות כלים:
טקסט מציין מיקום כדי להדגים כמה קישורים מוטבעים עם עצות כלים. עכשיו זה רק מילוי, לא רוצח. תוכן שהוצב כאן רק כדי לחקות את נוכחותו של טקסט אמיתי . וכל זה רק כדי לתת לך מושג כיצד ייראו עצות כלים בשימוש במצבים בעולם האמיתי. אז אני מקווה שעכשיו ראית איך עצות הכלים האלה על קישורים יכולים לעבוד בפועל, ברגע שאתה משתמש בהם באתר או בפרויקט שלך .
רחף מעל הלחצנים למטה כדי לראות את ארבעת הכיוונים של טיפים: למעלה, ימינה, למטה ושמאלה. ההנחיות משתקפות בעת שימוש ב-Bootstrap ב-RTL.
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip on top">
Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Tooltip on right">
Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Tooltip on bottom">
Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="Tooltip on left">
Tooltip on left
</button>
ועם HTML מותאם אישית נוסף:
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
Tooltip with HTML
</button>
עם SVG:
סאס
משתנים
$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: 0;
$tooltip-arrow-width: .8rem;
$tooltip-arrow-height: .4rem;
$tooltip-arrow-color: $tooltip-bg;
נוֹהָג
תוסף Tooltip מייצר תוכן וסימון לפי דרישה, וכברירת מחדל מציב עצות כלים אחרי אלמנט הטריגר שלהם.
הפעל את הסבר הכלי באמצעות JavaScript:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
הצפה auto
וscroll
מיקום תיאור הכלים מנסה להשתנות אוטומטית כאשר מכיל אב יש overflow: auto
או overflow: scroll
אוהב את .table-responsive
, אך עדיין שומר על המיקום המקורי של המיקום. כדי לפתור זאת, הגדר את boundary
האפשרות (עבור שינוי היפוך המשתמש popperConfig
באפשרות) לכל HTMLElement כדי לעקוף את ערך ברירת המחדל, 'clippingParents'
, כגון document.body
:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
boundary: document.body // or document.querySelector('#boundary')
})
סימון
הסימון הנדרש עבור תיאור כלים הוא רק data
תכונה title
וברכיב ה-HTML ברצונך לקבל תיאור כלי. הסימון שנוצר של הסבר כלים הוא די פשוט, אם כי הוא דורש מיקום (כברירת מחדל, מוגדר על top
ידי הפלאגין).
הפיכת עצות כלים לעבודה עבור משתמשי מקלדת וטכנולוגיה מסייעת
עליך להוסיף רק עצות כלים לרכיבי HTML שבאופן מסורתי ניתנים למיקוד מקלדת ואינטראקטיביים (כגון קישורים או פקדי טופס). למרות שניתן להפוך רכיבי HTML שרירותיים (כגון <span>
s) לניתנים למיקוד על ידי הוספת tabindex="0"
התכונה, הדבר יוסיף עצירות טאב שעלולות להיות מעצבנות ומבלבלות ברכיבים לא אינטראקטיביים עבור משתמשי מקלדת, ורוב הטכנולוגיות המסייעות כרגע אינן מכריזות על הסבר הכלי במצב זה. בנוסף, אל תסתמך רק עליו hover
בתור הטריגר עבור הסבר הכלים שלך, מכיוון שזה יהפוך את טיפים הכלים שלך לבלתי אפשריים להפעלה עבור משתמשי מקלדת.
<!-- HTML to write -->
<a href="#" data-bs-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="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" title="Disabled tooltip">
<button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>
אפשרויות
ניתן להעביר אפשרויות באמצעות תכונות נתונים או JavaScript. עבור תכונות נתונים, הוסף את שם האפשרות ל- data-bs-
, כמו ב- data-bs-animation=""
. הקפד לשנות את סוג המארז של שם האופציה מ-camelCase ל-kebab-case בעת העברת האפשרויות באמצעות תכונות נתונים. לדוגמה, במקום להשתמש data-bs-customClass="beautifier"
, השתמש ב- data-bs-custom-class="beautifier"
.
sanitize
,
sanitizeFn
, ו
באמצעות תכונות נתונים.allowList
שֵׁם | סוּג | בְּרִירַת מֶחדָל | תיאור |
---|---|---|---|
animation |
בוליאני | true |
החל מעבר דהייה של CSS על הסבר הכלי |
container |
מחרוזת | אלמנט | שֶׁקֶר | false |
מוסיף את הסבר הכלי לרכיב מסוים. דוגמה: |
delay |
מספר | לְהִתְנַגֵד | 0 |
עיכוב הצגת והסתרה של הסבר הכלי (ms) - אינו חל על סוג טריגר ידני אם מסופק מספר, השהיה מוחל גם על הסתרה/הצגה מבנה האובייקט הוא: |
html |
בוליאני | false |
אפשר HTML בהסבר הכלי. אם זה נכון, תגי HTML בהסבר הכלי השתמש בטקסט אם אתה מודאג מהתקפות XSS. |
placement |
מחרוזת | פוּנקצִיָה | 'top' |
כיצד למקם את הסבר הכלי - אוטומטי | למעלה | תחתון | שמאל | ימין. כאשר נעשה שימוש בפונקציה לקביעת המיקום, היא נקראת עם צומת DOM תיאור הכלי בתור הארגומנט הראשון שלה והצומת המפעיל DOM כצומת השני שלו. ההקשר |
selector |
מחרוזת | שֶׁקֶר | false |
אם מסופק בורר, אובייקטי תיאור כלים יואצלו ליעדים שצוינו. בפועל, זה משמש גם ליישום עצות כלים על רכיבי DOM שנוספו באופן דינמי ( jQuery.on תמיכה). ראה זאת ודוגמה אינפורמטיבית . |
template |
חוּט | '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' |
בסיס HTML לשימוש בעת יצירת הסבר הכלי. הסבר הכלי
רכיב העטיפה החיצוני ביותר צריך לכלול את |
title |
מחרוזת | אלמנט | פוּנקצִיָה | '' |
ערך כותרת ברירת מחדל אם אם ניתנת פונקציה, היא תיקרא כשההתייחסות שלה |
trigger |
חוּט | 'hover focus' |
כיצד מופעלת הסבר כלים - לחץ על | לרחף | מיקוד | מדריך ל. אתה יכול לעבור טריגרים מרובים; להפריד ביניהם עם רווח.
|
fallbackPlacements |
מַעֲרָך | ['top', 'right', 'bottom', 'left'] |
הגדר מיקומי חילוף על ידי מתן רשימה של מיקומים במערך (לפי סדר העדפה). למידע נוסף עיין במסמכי ההתנהגות של פופר |
boundary |
מחרוזת | אֵלֵמֶנט | 'clippingParents' |
גבול אילוץ גלישה של הסבר הכלי (חל רק על השינוי של PreventOverflow של Popper). כברירת מחדל זה 'clippingParents' ויכול לקבל הפניה של HTMLElement (דרך JavaScript בלבד). למידע נוסף עיין במסמכי detectOverflow של Popper . |
customClass |
מחרוזת | פוּנקצִיָה | '' |
הוסף כיתות להסבר הכלי כאשר הוא מוצג. שימו לב ששיעורים אלו יתווספו בנוסף לכל השיעורים המצוינים בתבנית. כדי להוסיף מחלקות מרובות, הפרד אותן באמצעות רווחים: אתה יכול גם להעביר פונקציה שאמורה להחזיר מחרוזת אחת המכילה שמות מחלקות נוספים. |
sanitize |
בוליאני | true |
הפעל או השבת את החיטוי. אם יופעל 'template' והאפשרויות 'title' יעברו חיטוי. עיין בסעיף חיטוי בתיעוד ה-JavaScript שלנו . |
allowList |
לְהִתְנַגֵד | ערך ברירת מחדל | אובייקט המכיל תכונות ותגים מותרים |
sanitizeFn |
null | פוּנקצִיָה | null |
כאן אתה יכול לספק פונקציית חיטוי משלך. זה יכול להיות שימושי אם אתה מעדיף להשתמש בספרייה ייעודית לביצוע חיטוי. |
offset |
מערך | מחרוזת | פוּנקצִיָה | [0, 0] |
קיזוז קצה הכלים ביחס למטרה שלו. אתה יכול להעביר מחרוזת בתכונות נתונים עם ערכים מופרדים בפסיקים כמו: כאשר נעשה שימוש בפונקציה לקביעת ההיסט, היא נקראת עם אובייקט המכיל את מיקום ה-popper, הפניות ו-popper rects כארגומנט הראשון שלה. הצומת DOM הגורם המפעיל מועבר כארגומנט השני. הפונקציה חייבת להחזיר מערך עם שני מספרים: . למידע נוסף עיין במסמכי האופסט של פופר . |
popperConfig |
null | חפץ | פוּנקצִיָה | null |
כדי לשנות את ברירת המחדל של תצורת Popper של Bootstrap, ראה את התצורה של Popper . כאשר משתמשים בפונקציה ליצירת תצורת Popper, היא נקראת עם אובייקט שמכיל את תצורת Popper המוגדרת כברירת מחדל של Bootstrap. זה עוזר לך להשתמש ולמזג את ברירת המחדל עם התצורה שלך. הפונקציה חייבת להחזיר אובייקט תצורה עבור Popper. |
תכונות נתונים עבור עצות כלים בודדות
לחילופין ניתן לציין אפשרויות עבור עצות כלים בודדות באמצעות שימוש בתכונות נתונים, כפי שהוסבר לעיל.
שימוש בפונקציה עםpopperConfig
var tooltip = new bootstrap.Tooltip(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
שיטות
שיטות ומעברים אסינכרוניים
כל שיטות ה-API הן אסינכרוניות ומתחילות מעבר . הם חוזרים למתקשר ברגע שהמעבר מתחיל אבל לפני שהוא מסתיים . בנוסף, תתעלם מקריאת שיטה על רכיב מעבר .
הופעה
חושף תיאור כלי של אלמנט. חוזר אל המתקשר לפני שהסבר הכלי הוצג בפועל (כלומר לפני shown.bs.tooltip
התרחשות האירוע). זה נחשב להפעלה "ידנית" של הסבר הכלי. עצות כלים עם כותרות באורך אפס לעולם אינן מוצגות.
tooltip.show()
להתחבא
מסתיר תיאור כלי של רכיב. חוזר אל המתקשר לפני שהסבר הכלי הוסתר בפועל (כלומר לפני hidden.bs.tooltip
שהאירוע מתרחש). זה נחשב להפעלה "ידנית" של הסבר הכלי.
tooltip.hide()
לְמַתֵג
מחליף תיאור כלי של רכיב. חוזר אל המתקשר לפני שהסבר הכלי הוצג או הוסתר בפועל (כלומר לפני שהאירוע shown.bs.tooltip
או מתרחש). hidden.bs.tooltip
זה נחשב להפעלה "ידנית" של הסבר הכלי.
tooltip.toggle()
להיפטר
מסתיר ומשמיד הסבר כלים של אלמנט (מסיר נתונים מאוחסנים באלמנט DOM). לא ניתן להשמיד עצות כלים המשתמשות בהאצלה (שנוצרות באמצעות האפשרות ) בנפרד על רכיבי טריגר צאצאים.selector
tooltip.dispose()
לְאַפשֵׁר
נותן לתיאור כלי של אלמנט את היכולת להיות מוצג. טיפים לכלים מופעלים כברירת מחדל.
tooltip.enable()
להשבית
מסיר את היכולת להציג תיאור כלים של רכיב. הסבר הכלי יוכל להיות מוצג רק אם הוא מופעל מחדש.
tooltip.disable()
ToggleEnabled
מחליף את היכולת להציג או להסתיר תיאור כלי של אלמנט.
tooltip.toggleEnabled()
עדכון
מעדכן את המיקום של תיאור כלי של רכיב.
tooltip.update()
getInstance
שיטה סטטית המאפשרת לך לקבל את מופע הכלים המשויך לאלמנט DOM
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
getOrCreateInstance
שיטה סטטית המאפשרת לך לקבל את מופע ה-Tooltip המשויך לרכיב DOM, או ליצור אחד חדש למקרה שהוא לא אותחל
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
אירועים
סוג אירוע | תיאור |
---|---|
show.bs.tooltip |
אירוע זה מופעל מיד כאשר show שיטת המופע נקראת. |
shown.bs.tooltip |
אירוע זה מופעל כאשר הסבר הכלי נעשה גלוי למשתמש (יחכה לסיום מעברי CSS). |
hide.bs.tooltip |
אירוע זה מופעל מיד כאשר hide שיטת המופע נקראה. |
hidden.bs.tooltip |
אירוע זה מופעל כאשר הסבר הכלים סיים להסתיר מהמשתמש (יחכה לסיום מעברי CSS). |
inserted.bs.tooltip |
אירוע זה מופעל לאחר show.bs.tooltip האירוע כאשר תבנית הסבר הכלי נוספה ל-DOM. |
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)
myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
// do something...
})
tooltip.hide()