עצות כלים

תיעוד ודוגמאות להוספת טיפים מותאמים אישית של Bootstrap עם CSS ו-JavaScript באמצעות CSS3 עבור אנימציות ו-data-bs-attributes עבור אחסון כותרות מקומי.

בעמוד זה

סקירה כללית

דברים שכדאי לדעת בעת שימוש בתוסף טיפים:

עצות כלים מסתמכות על ספריית הצד השלישי Popper לצורך מיקום. עליך לכלול popper.min.js לפני bootstrap.js, או להשתמש באחד bootstrap.bundle.min.jsשמכיל Popper.
טיפים לכלים ניתנים להצטרפות מסיבות ביצועים, לכן עליך לאתחל אותם בעצמך .
עצות כלים עם כותרות באורך אפס לעולם אינן מוצגות.
ציין container: 'body'כדי להימנע מעיבוד בעיות ברכיבים מורכבים יותר (כמו קבוצות הקלט שלנו, קבוצות לחצנים וכו').
הפעלת עצות כלים על אלמנטים מוסתרים לא תעבוד.
יש להפעיל עצות כלים עבור רכיבים .disabledאו disabledאלמנטים על רכיב עטיפה.
כאשר מופעלים מהיפר-קישורים המשתרעים על פני שורות מרובות, עצות הכלים ירוכזו. השתמש white-space: nowrap;ב- <a>s שלך כדי להימנע מהתנהגות זו.
יש להסתיר עצות כלים לפני שהרכיבים התואמים שלהם יוסרו מה-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))

עצות כלים על קישורים

רחף מעל הקישורים למטה כדי לראות עצות כלים:

html

<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);
}

html

<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};

משתנים Sass

$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

נוֹהָג

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

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

html

<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", הערך הסופי titleיהיה 456ותכונות הנתונים הנפרדות יעקפו ערכים שניתנו ב- data-bs-config. בנוסף, תכונות נתונים קיימות מסוגלות להכיל ערכי JSON כמו data-bs-delay='{"show":0,"hide":150}'.

שים לב שמסיבות אבטחה לא ניתן לספק את האפשרויות sanitize, sanitizeFn, ו באמצעות תכונות נתונים.allowList

שֵׁם	סוּג	בְּרִירַת מֶחדָל	תיאור
`allowList`	לְהִתְנַגֵד	ערך ברירת מחדל	אובייקט המכיל תכונות ותגים מותרים.
`animation`	בוליאני	`true`	החל מעבר דהייה של CSS על הסבר הכלי.
`boundary`	מחרוזת, אלמנט	`'clippingParents'`	גבול אילוץ גלישה של הסבר הכלי (חל רק על השינוי של PreventOverflow של Popper). כברירת מחדל, זה `'clippingParents'`ויכול לקבל הפניה ל-HTMLElement (דרך JavaScript בלבד). למידע נוסף עיין במסמכי detectOverflow של Popper .
`container`	מחרוזת, אלמנט, false	`false`	מוסיף את הסבר הכלי לרכיב מסוים. דוגמה: `container: 'body'`. אפשרות זו שימושית במיוחד בכך שהיא מאפשרת למקם את תיאור הכלים בזרימת המסמך ליד האלמנט המפעיל - מה שימנע מקצה הכלים לצוף מהאלמנט המפעיל במהלך שינוי גודל החלון.
`customClass`	מחרוזת, פונקציה	`''`	הוסף כיתות להסבר הכלי כאשר הוא מוצג. שימו לב ששיעורים אלו יתווספו בנוסף לכל השיעורים המצוינים בתבנית. כדי להוסיף מחלקות מרובות, הפרד אותן באמצעות רווחים: `'class-1 class-2'`. אתה יכול גם להעביר פונקציה שאמורה להחזיר מחרוזת אחת המכילה שמות מחלקות נוספים.
`delay`	מספר, חפץ	`0`	עיכוב הצגה והסתרה של הסבר הכלים (ms) - אינו חל על סוג טריגר ידני. אם מסופק מספר, השהיה מוחל גם על הסתרה/הצגה. מבנה האובייקט הוא: `delay: { "show": 500, "hide": 100 }`.
`fallbackPlacements`	מַעֲרָך	`['top', 'right', 'bottom', 'left']`	הגדר מיקומי חילוף על ידי מתן רשימה של מיקומים במערך (לפי סדר העדפה). למידע נוסף עיין במסמכי ההתנהגות של פופר .
`html`	בוליאני	`false`	אפשר HTML בהסבר הכלי. אם זה נכון, תגי HTML בהסבר הכלי `title`יוצגו בהסבר. אם false, `innerText`המאפיין ישמש להוספת תוכן ל-DOM. השתמש בטקסט אם אתה מודאג מהתקפות XSS.
`offset`	מערך, מחרוזת, פונקציה	`[0, 0]`	קיזוז קצה הכלים ביחס למטרה שלו. אתה יכול להעביר מחרוזת בתכונות נתונים עם ערכים מופרדים בפסיקים כמו: `data-bs-offset="10,20"`. כאשר פונקציה משמשת לקביעת ההיסט, היא נקראת עם אובייקט המכיל את מיקום ה-popper, הפניה ו-popper rects כארגומנט הראשון שלה. הצומת DOM הגורם המפעיל מועבר כארגומנט השני. הפונקציה חייבת להחזיר מערך עם שני מספרים: החלקה , מרחק . למידע נוסף עיין במסמכי האופסט של פופר .
`placement`	מחרוזת, פונקציה	`'top'`	כיצד למקם את הסבר הכלי: אוטומטי, למעלה, למטה, שמאל, ימין. כאשר `auto`צוין, הוא יכוון מחדש את תיאור הכלים באופן דינמי. כאשר נעשה שימוש בפונקציה לקביעת המיקום, היא נקראת עם צומת DOM תיאור הכלי בתור הארגומנט הראשון שלה והצומת המפעיל DOM כצומת השני שלו. ההקשר `this`מוגדר למופע תיאור הכלים.
`popperConfig`	null, אובייקט, פונקציה	`null`	כדי לשנות את ברירת המחדל של תצורת Popper של Bootstrap, ראה את התצורה של Popper . כאשר משתמשים בפונקציה ליצירת תצורת Popper, היא נקראת עם אובייקט שמכיל את תצורת Popper המוגדרת כברירת מחדל של Bootstrap. זה עוזר לך להשתמש ולמזג את ברירת המחדל עם התצורה שלך. הפונקציה חייבת להחזיר אובייקט תצורה עבור Popper.
`sanitize`	בוליאני	`true`	הפעל או השבת את החיטוי. אם יופעל `'template'`, `'content'`והאפשרויות `'title'`יעברו חיטוי.
`sanitizeFn`	null, פונקציה	`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`	שיטה סטטית המאפשרת לך לקבל את מופע ה-Tooltip המשויך לרכיב DOM, או ליצור אחד חדש למקרה שהוא לא אותחל.
`getOrCreateInstance`	שיטה סטטית המאפשרת לך לקבל את מופע ה-Tooltip המשויך לרכיב 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מאפיין-key הוא בורר חוקי בתוך תבנית הפופ-אובר, וכל ערך מאפיין קשור יכול להיות 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

משתנים

משתנים Sass

נוֹהָג

הצפה autoוscroll

סימון

הפיכת עצות כלים לעבודה עבור משתמשי מקלדת וטכנולוגיה מסייעת

אלמנטים מושבתים

אפשרויות

תכונות נתונים עבור עצות כלים בודדות

שימוש בפונקציה עםpopperConfig

שיטות

שיטות ומעברים אסינכרוניים

אירועים

הצפה `auto`ו`scroll`

שימוש בפונקציה עם`popperConfig`