JavaScript

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

בעמוד זה

בודדים או מורכבים

ניתן לכלול תוספים בנפרד (באמצעות ה-Individual של Bootstrap js/dist/*.js), או בבת אחת באמצעות bootstrap.jsה-Minified bootstrap.min.js(אל תכלול את שניהם).

אם אתה משתמש באנדלר (Webpack, Parcel, Vite...), אתה יכול להשתמש /js/dist/*.jsבקבצים שמוכנים ל-UMD.

שימוש עם מסגרות JavaScript

בעוד שניתן להשתמש ב-Bootstrap CSS עם כל מסגרת, ה-Bootstrap JavaScript אינו תואם באופן מלא למסגרות JavaScript כמו React, Vue ו-Angular אשר מניחות ידע מלא של ה-DOM. גם Bootstrap וגם ה-framework עשויים לנסות לשנות את אותו רכיב DOM, וכתוצאה מכך באגים כמו תפריטים נפתחים שנתקעו במצב "פתוח".

חלופה טובה יותר עבור אלה המשתמשים במסגרות מסוג זה היא להשתמש בחבילה ספציפית למסגרת במקום ב- Bootstrap JavaScript. להלן כמה מהאפשרויות הפופולריות ביותר:

תגובה: React Bootstrap
Vue: BootstrapVue (כרגע תומך רק ב-Vue 2 וב-Bootstrap 4)
זוויתי: ng-bootstrap

שימוש ב-Bootstrap כמודול

נסה זאת בעצמך! הורד את קוד המקור והדגמת עבודה לשימוש ב-Bootstrap כמודול ES ממאגר twbs/examples . אתה יכול גם לפתוח את הדוגמה ב-StackBlitz .

אנו מספקים גרסה של Bootstrap הבנויה כ- ESM( bootstrap.esm.jsו bootstrap.esm.min.js) המאפשרת לך להשתמש ב-Bootstrap כמודול בדפדפן, אם הדפדפנים הממוקדים שלך תומכים בכך .

<script type="module">
  import { Toast } from 'bootstrap.esm.min.js'

  Array.from(document.querySelectorAll('.toast'))
    .forEach(toastNode => new Toast(toastNode))
</script>

בהשוואה ל-JS bundlers, שימוש ב-ESM בדפדפן מחייב אותך להשתמש בנתיב ובשם הקובץ המלאים במקום בשם המודול. קרא עוד על מודולי JS בדפדפן. לכן אנחנו משתמשים 'bootstrap.esm.min.js'במקום 'bootstrap'למעלה. עם זאת, זה מסובך עוד יותר בגלל התלות שלנו ב-Popper, שמייבאת את פופר ל-JavaScript שלנו כך:

import * as Popper from "@popperjs/core"

אם תנסה את זה כפי שהוא, תראה שגיאה במסוף כמו הבאה:

Uncaught TypeError: Failed to resolve module specifier "@popperjs/core". Relative references must start with either "/", "./", or "../".

כדי לתקן זאת, אתה יכול להשתמש ב- importmapכדי לפתור את שמות המודולים השרירותיים להשלמת נתיבים. אם הדפדפנים הממוקדים שלך אינם תומכים ב- importmap, תצטרך להשתמש בפרויקט es-module-shims . כך זה עובד עבור Bootstrap ו-Popper:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-iYQeCzEYFbKjA/T2uDLTpkwGzCiq6soy8tYaI1GyVh/UjpbCx/TYkiZhlZB6+fzT" crossorigin="anonymous">
    <title>Hello, modularity!</title>
  </head>
  <body>
    <h1>Hello, modularity!</h1>
    <button id="popoverButton" type="button" class="btn btn-primary btn-lg" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="ESM in Browser" data-bs-content="Bang!">Custom popover</button>

    <script async src="https://cdn.jsdelivr.net/npm/es-module-shims@1/dist/es-module-shims.min.js" crossorigin="anonymous"></script>
    <script type="importmap">
    {
      "imports": {
        "@popperjs/core": "https://cdn.jsdelivr.net/npm/@popperjs/[email protected]/dist/umd/popper.min.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.esm.min.js"
      }
    }
    </script>
    <script type="module">
      import * as bootstrap from 'bootstrap'

      new bootstrap.Popover(document.getElementById('popoverButton'))
    </script>
  </body>
</html>

תלות

תוספים מסוימים ורכיבי CSS תלויים בתוספים אחרים. אם אתה כולל תוספים בנפרד, הקפד לבדוק את התלות הללו במסמכים.

התפריטים הנפתחים, הפופ-אוברים וטיפים שלנו תלויים גם ב- Popper .

תכונות נתונים

ניתן להפעיל ולהגדיר כמעט את כל התוספים של Bootstrap באמצעות HTML בלבד עם תכונות נתונים (הדרך המועדפת עלינו להשתמש בפונקציונליות JavaScript). הקפד להשתמש רק בקבוצה אחת של תכונות נתונים ברכיב בודד (לדוגמה, אינך יכול להפעיל תיאור כלים ומודאל מאותו כפתור).

מכיוון שניתן להעביר אפשרויות באמצעות תכונות נתונים או 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}'.

בוררים

אנו משתמשים ב-native querySelectorובשיטות querySelectorAllכדי לבצע שאילתות על רכיבי DOM מטעמי ביצועים, לכן עליך להשתמש בבוררים חוקיים . אם אתה משתמש בבוררים מיוחדים כמו collapse:Example, הקפד לברוח מהם.

אירועים

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

כל האירועים האינסופיים מספקים preventDefault()פונקציונליות. זה מספק את היכולת לעצור את ביצוע הפעולה לפני שהיא מתחילה. החזרת false ממטפל באירועים תקרא גם אוטומטית preventDefault().

const myModal = document.querySelector('#myModal')

myModal.addEventListener('show.bs.modal', event => {
  if (!data) {
    return event.preventDefault() // stops modal from being shown
  }
})

API פרוגרמטי

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

const myModalEl = document.querySelector('#myModal')

const modal = new bootstrap.Modal(myModalEl) // initialized with defaults

const configObject = { keyboard: false }
const modal1 = new bootstrap.Modal(myModalEl, configObject) // initialized with no keyboard

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

bootstrap.Popover.getInstance(myPopoverEl)

שיטה זו תחזור nullאם לא יופעל מופע על הרכיב המבוקש.

לחלופין, getOrCreateInstanceניתן להשתמש בו כדי לקבל את המופע המשויך לרכיב DOM, או ליצור מופע חדש למקרה שהוא לא אותחל.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

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

בוררי CSS בקונסטרוקטורים

בנוסף לשיטות getInstanceו getOrCreateInstance, כל בוני הפלאגין יכולים לקבל אלמנט DOM או בורר CSS חוקי כארגומנט הראשון. רכיבי פלאגין נמצאים עם querySelectorהשיטה שכן התוספים שלנו תומכים רק באלמנט בודד.

const modal = new bootstrap.Modal('#myModal')
const dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
const offcanvas = bootstrap.Offcanvas.getInstance('#myOffcanvas')
const alert = bootstrap.Alert.getOrCreateInstance('#myAlert')

פונקציות ומעברים אסינכרוניים

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

const myCollapseEl = document.querySelector('#myCollapse')

myCollapseEl.addEventListener('shown.bs.collapse', event => {
  // Action to execute once the collapsible area is expanded
})

בנוסף, תתעלם מקריאת שיטה על רכיב מעבר .

const myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance

myCarouselEl.addEventListener('slid.bs.carousel', event => {
  carousel.to('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
})

carousel.to('1') // Will start sliding to the slide 1 and returns to the caller
carousel.to('2') // !! Will be ignored, as the transition to the slide 1 is not finished !!

`dispose`שיטה

למרות שזה עשוי להיראות נכון להשתמש disposeבשיטה מיד לאחר hide(), זה יוביל לתוצאות שגויות. הנה דוגמה לשימוש בבעיה:

const myModal = document.querySelector('#myModal')
myModal.hide() // it is asynchronous

myModal.addEventListener('shown.bs.hidden', event => {
  myModal.dispose()
})

הגדרות ברירת מחדל

אתה יכול לשנות את הגדרות ברירת המחדל של תוסף על ידי שינוי Constructor.Defaultהאובייקט של הפלאגין:

// changes default for the modal plugin's `keyboard` option to false
bootstrap.Modal.Default.keyboard = false

שיטות ומאפיינים

כל תוסף Bootstrap חושף את השיטות והמאפיינים הסטטיים הבאים.

שיטה	תיאור
`dispose`	הורס את המודאל של אלמנט. (מסיר נתונים מאוחסנים ברכיב ה-DOM)
`getInstance`	שיטה סטטית המאפשרת לך לקבל את המופע המודאלי המשויך לאלמנט DOM.
`getOrCreateInstance`	שיטה סטטית המאפשרת לך לקבל את המופע המודאלי המשויך לרכיב DOM, או ליצור אחד חדש למקרה שהוא לא אותחל.

תכונה סטטית	תיאור
`NAME`	מחזיר את שם הפלאגין. (דוגמה: `bootstrap.Tooltip.NAME`)
`VERSION`	ניתן לגשת לגרסה של כל אחד מהפלאגינים של Bootstrap דרך `VERSION`המאפיין של בנאי הפלאגין (דוגמה: `bootstrap.Tooltip.VERSION`)

מחטא

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

ערך ברירת המחדל allowListהוא הבא:

const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
const DefaultAllowlist = {
  // Global attributes allowed on any supplied element below.
  '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  div: [],
  em: [],
  hr: [],
  h1: [],
  h2: [],
  h3: [],
  h4: [],
  h5: [],
  h6: [],
  i: [],
  img: ['src', 'srcset', 'alt', 'title', 'width', 'height'],
  li: [],
  ol: [],
  p: [],
  pre: [],
  s: [],
  small: [],
  span: [],
  sub: [],
  sup: [],
  strong: [],
  u: [],
  ul: []
}

אם ברצונך להוסיף ערכים חדשים לברירת המחדל הזו, allowListתוכל לבצע את הפעולות הבאות:

const myDefaultAllowList = bootstrap.Tooltip.Default.allowList

// To allow table elements
myDefaultAllowList.table = []

// To allow td elements and data-bs-option attributes on td elements
myDefaultAllowList.td = ['data-bs-option']

// You can push your custom regex to validate your attributes.
// Be careful about your regular expressions being too lax
const myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

אם אתה רוצה לעקוף את חומר החיטוי שלנו כי אתה מעדיף להשתמש בספרייה ייעודית, למשל DOMPurify , עליך לבצע את הפעולות הבאות:

const yourTooltipEl = document.querySelector('#yourTooltip')
const tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn(content) {
    return DOMPurify.sanitize(content)
  }
})

אופציונלי באמצעות jQuery

אתה לא צריך jQuery ב-Bootstrap 5 , אבל עדיין אפשר להשתמש ברכיבים שלנו עם jQuery. אם Bootstrap מזהה jQueryבאובייקט window, הוא יוסיף את כל הרכיבים שלנו במערכת הפלאגין של jQuery. זה מאפשר לך לבצע את הפעולות הבאות:

$('[data-bs-toggle="tooltip"]').tooltip() // to enable tooltips, with default configuration

$('[data-bs-toggle="tooltip"]').tooltip({ boundary: 'clippingParents', customClass: 'myClass' }) // to initialize tooltips with given configuration

$('#myTooltip').tooltip('show') // to trigger `show` method

אותו דבר לגבי הרכיבים האחרים שלנו.

אין סכסוך

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

const bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton // give $().bootstrapBtn the Bootstrap functionality

Bootstrap אינו תומך רשמית בספריות JavaScript של צד שלישי כמו אב טיפוס או ממשק משתמש jQuery. למרות .noConflictאירועים עם רווחי שמות, עשויות להיות בעיות תאימות שעליך לתקן בעצמך.

אירועי jQuery

Bootstrap יזהה את jQuery אם jQueryקיים windowבאובייקט ואין data-bs-no-jqueryתכונה מוגדרת על <body>. אם jQuery נמצא, Bootstrap יפלוט אירועים הודות למערכת האירועים של jQuery. אז אם אתה רוצה להאזין לאירועים של Bootstrap, תצטרך להשתמש בשיטות jQuery ( .on, .one) במקום addEventListener.

$('#myTab a').on('shown.bs.tab', () => {
  // do something...
})

JavaScript מושבת

לפלאגינים של Bootstrap אין נפילה מיוחדת כאשר JavaScript מושבת. אם אכפת לך מחוויית המשתמש במקרה זה, השתמש <noscript>כדי להסביר את המצב (וכיצד להפעיל מחדש את JavaScript) למשתמשים שלך, ו/או הוסף החזרות מותאמות אישית משלך.