פופ-אוברים

תיעוד ודוגמאות להוספת חלונות קופצים של Bootstrap, כמו אלה שנמצאים ב-iOS, לכל רכיב באתר שלך.

בעמוד זה

סקירה כללית

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

Popovers מסתמכים על ספריית הצד השלישי Popper לצורך מיקום. עליך לכלול popper.min.js לפני bootstrap.js או להשתמש ב bootstrap.bundle.min.js/ bootstrap.bundle.jsשמכיל Popper על מנת שפופ-אובר יעבוד!
חלונות קופצים דורשים את הפלאגין של תיאור כלי כתלות.
חלונות קופצים ניתנים להצטרפות מסיבות ביצועים, לכן עליך לאתחל אותם בעצמך .
אורך אפס titleוערכים contentלעולם לא יראו פופ-אובר.
ציין container: 'body'כדי להימנע מעיבוד בעיות ברכיבים מורכבים יותר (כמו קבוצות הקלט שלנו, קבוצות לחצנים וכו').
הפעלת popovers על אלמנטים מוסתרים לא תעבוד.
יש להפעיל פופ-אובר עבור אלמנטים .disabledאו disabledאלמנטים ברכיב עטיפה.
כאשר מופעלים מעוגנים העוטפים קווים מרובים, הפופ-אוברים יתרכזו בין הרוחב הכללי של העוגנים. השתמש .text-nowrapב- <a>s שלך כדי להימנע מהתנהגות זו.
יש להסתיר חלונות קופצים לפני שהרכיבים התואמים שלהם יוסרו מה-DOM.
ניתן להפעיל פופ-אובר הודות לאלמנט בתוך DOM בצל.

כברירת מחדל, רכיב זה משתמש בחיטוי התוכן המובנה, אשר מסיר את כל רכיבי ה-HTML שאינם מותרים במפורש. עיין בסעיף חומרי החיטוי בתיעוד ה-JavaScript שלנו לפרטים נוספים.

אפקט האנימציה של רכיב זה תלוי prefers-reduced-motionבשאילתת המדיה. עיין בסעיף תנועה מופחתת בתיעוד הנגישות שלנו .

המשך לקרוא כדי לראות כיצד פופ-אובר עובד עם כמה דוגמאות.

דוגמה: אפשר פופ-אובר בכל מקום

דרך אחת לאתחל את כל הפופ-אוברים בדף תהיה לבחור אותם לפי data-bs-toggleהתכונה שלהם:

var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
  return new bootstrap.Popover(popoverTriggerEl)
})

דוגמה: שימוש `container`באפשרות

כאשר יש לך כמה סגנונות ברכיב אב שמפריעים ל-popover, תרצה לציין התאמה אישית containerכך שה-HTML של ה-pover יופיע בתוך הרכיב הזה במקום זאת.

var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
  container: 'body'
})

דוגמא

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

ארבעה כיוונים

ארבע אפשרויות זמינות: מיושרות למעלה, ימינה, למטה ושמאלה. ההנחיות משתקפות בעת שימוש ב-Bootstrap ב-RTL.

<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
  Popover on top
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover">
  Popover on right
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover">
  Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover">
  Popover on left
</button>

סגור בלחיצה הבאה

השתמש focusבטריגר כדי לבטל פופ-אובר בלחיצה הבאה של המשתמש על רכיב אחר מאשר רכיב החלפת המצב.

נדרש סימון ספציפי לביטול בלחיצה הבאה

להתנהגות נכונה בין דפדפנים ופלטפורמות, עליך להשתמש <a>בתג, לא בתג<button> , וכן עליך לכלול tabindexתכונה.

פופ-אובר שניתן לדחות

<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>

var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
  trigger: 'focus'
})

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

אלמנטים עם disabledהתכונה אינם אינטראקטיביים, כלומר המשתמשים אינם יכולים לרחף או ללחוץ עליהם כדי להפעיל פופ-אובר (או טיפים). כפתרון לעקיפת הבעיה, תרצה להפעיל את הפופ-אובר מעטיפת <div>או <span>, העשויה באופן אידיאלי למיקוד מקלדת באמצעות tabindex="0".

עבור מפעילי פופ-אובר מושבתים, ייתכן שתעדיף גם data-bs-trigger="hover focus"כך שה-pover יופיע כמשוב ויזואלי מיידי למשתמשים שלך, מכיוון שהם עשויים שלא לצפות ללחוץ על אלמנט מושבת.

<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

סאס

משתנים

$popover-font-size:                 $font-size-sm;
$popover-bg:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              rgba($black, .2);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$popover-header-bg:                 shade-color($popover-bg, 6%);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                $body-color;
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

$popover-arrow-width:               1rem;
$popover-arrow-height:              .5rem;
$popover-arrow-color:               $popover-bg;

$popover-arrow-outer-color:         fade-in($popover-border-color, .05);

נוֹהָג

הפעל חלונות קופצים באמצעות JavaScript:

var exampleEl = document.getElementById('example')
var popover = new bootstrap.Popover(exampleEl, options)

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

כדי לאפשר למשתמשי מקלדת להפעיל את הפופ-אובר שלך, עליך להוסיף אותם רק לרכיבי HTML שבאופן מסורתי ניתנים למיקוד מקלדת ואינטראקטיביים (כגון קישורים או פקדי טופס). למרות שניתן להפוך רכיבי HTML שרירותיים (כגון <span>s) לניתנים למיקוד על ידי הוספת tabindex="0"התכונה, הדבר יוסיף עצירות טאב שעלולות להיות מעצבנות ומבלבלות ברכיבים לא אינטראקטיביים עבור משתמשי מקלדת, ורוב הטכנולוגיות המסייעות כרגע אינן מכריזות על תוכן הפופ-אובר במצב זה . בנוסף, אל תסתמך רק על hoverהטריגר עבור הפופ-אובר שלך, מכיוון שזה יהפוך אותם לבלתי אפשריים להפעלה עבור משתמשי מקלדת.

בעוד שאתה יכול להוסיף HTML עשיר ומובנה בחלונות קופצים עם htmlהאפשרות, אנו ממליצים בחום להימנע מהוספת כמות מוגזמת של תוכן. הדרך שבה פופ-אוברים פועלים כעת היא שברגע שהוצגו, התוכן שלהם קשור לרכיב הטריגר עם aria-describedbyהתכונה. כתוצאה מכך, כל התוכן של הפופ-אובר יוכרז למשתמשי טכנולוגיה מסייעת כזרם אחד ארוך ללא הפרעה.

בנוסף, למרות שניתן לכלול גם פקדים אינטראקטיביים (כגון רכיבי טופס או קישורים) ב-Popover שלך (על ידי הוספת אלמנטים אלה allowListלתכונות והתגים המותרים), שים לב שכרגע ה-Popover אינו מנהל את סדר המיקוד של המקלדת. כאשר משתמש מקלדת פותח פופ-אובר, הפוקוס נשאר באלמנט המפעיל, ומכיוון שה-popover בדרך כלל לא עוקב מיד אחרי הדק במבנה המסמך, אין ערובה לכך שמתקדם/לחיצהTABיעביר משתמש מקלדת לתוך הפופ-אובר עצמו. בקיצור, הוספת פקדים אינטראקטיביים לפופ-אובר עשויה להפוך את הפקדים הללו לבלתי ניתנים להשגה/לא שמישה עבור משתמשי מקלדת ומשתמשים בטכנולוגיות מסייעות, או לכל הפחות ליצור סדר מיקוד כולל לא הגיוני. במקרים אלה, שקול להשתמש בדיאלוג מודאלי במקום זאת.

אפשרויות

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

תכונות נתונים עבור פופ-אובר בודדים

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

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

var popover = new bootstrap.Popover(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

שיטות

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

כל שיטות ה-API הן אסינכרוניות ומתחילות מעבר . הם חוזרים למתקשר ברגע שהמעבר מתחיל אבל לפני שהוא מסתיים . בנוסף, תתעלם מקריאת שיטה על רכיב מעבר .

עיין בתיעוד JavaScript שלנו למידע נוסף .

הופעה

חושף פופ-אובר של אלמנט. חוזר אל המתקשר לפני שהפופ-אובר הוצג בפועל (כלומר לפני shown.bs.popoverהתרחשות האירוע). זה נחשב להפעלה "ידנית" של הפופ-אובר. חלונות קופצים שהכותרת והתוכן שלהם שניהם באורך אפס לעולם לא יוצגו.

myPopover.show()

להתחבא

מסתיר פופ-אובר של אלמנט. חוזר אל המתקשר לפני שהפופ-אובר הוסתר בפועל (כלומר לפני hidden.bs.popoverהתרחשות האירוע). זה נחשב להפעלה "ידנית" של הפופ-אובר.

myPopover.hide()

לְמַתֵג

מחליף את הפופ-אובר של רכיב. חוזר אל המתקשר לפני שהפופ-אובר הוצג או הוסתר בפועל (כלומר לפני שהאירוע shown.bs.popoverאו hidden.bs.popoverמתרחש). זה נחשב להפעלה "ידנית" של הפופ-אובר.

myPopover.toggle()

להיפטר

מסתיר והורס פופ-אובר של אלמנט (מסיר נתונים מאוחסנים באלמנט DOM). חלונות קופצים המשתמשים בהאצלה (שנוצרים באמצעות האפשרותselector ) אינם ניתנים להרס בנפרד על רכיבי טריגר צאצאים.

myPopover.dispose()

לְאַפשֵׁר

נותן לפופ-אובר של אלמנט את היכולת להיות מוצג. חלונות קופצים מופעלים כברירת מחדל.

myPopover.enable()

להשבית

מסיר את היכולת להציג פופ-אובר של רכיב. הפופ-אובר יוכל להיות מוצג רק אם הוא מופעל מחדש.

myPopover.disable()

ToggleEnabled

מחליף את היכולת להצגה או להסתרה של חלון קופץ של רכיב.

myPopover.toggleEnabled()

עדכון

מעדכן את המיקום של חלון קופץ של רכיב.

myPopover.update()

getInstance

שיטה סטטית המאפשרת לך לקבל את מופע הפופ-אובר המשויך לאלמנט DOM

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

getOrCreateInstance

שיטה סטטית המאפשרת לך לקבל את מופע הפופ-אובר המשויך לרכיב DOM, או ליצור אחד חדש למקרה שהוא לא אותחל

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

אירועים

סוג אירוע	תיאור
show.bs.popover	אירוע זה מופעל מיד כאשר `show`שיטת המופע נקראת.
מוצג.bs.popover	אירוע זה מופעל כאשר הפופ-אובר נעשה גלוי למשתמש (יחכה לסיום מעברי CSS).
hide.bs.popover	אירוע זה מופעל מיד כאשר `hide`שיטת המופע נקראה.
hidden.bs.popover	אירוע זה מופעל כאשר הפופ-אובר סיים להיות מוסתר מהמשתמש (יחכה לסיום מעברי CSS).
inserted.bs.popover	אירוע זה מופעל לאחר `show.bs.popover`האירוע כאשר תבנית הפופ-אובר נוספה ל-DOM.

var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
  // do something...
})