in English

JavaScript

Keltse életre a Bootstrapet opcionális JavaScript-bővítményeinkkel. Tudjon meg többet az egyes beépülő modulokról, adat- és programozási API-lehetőségeinkről és még sok másról.

Ezen az oldalon

Egyéni vagy összeállított

A beépülő modulok beépíthetők külön-külön (a Bootstrap egyéni használatával js/dist/*.js), vagy egyszerre, bootstrap.jsvagy a kicsinyített változat használatával bootstrap.min.js(ne tartalmazza mindkettőt).

Ha kötegelőt (Webpack, Parcel, Vite…) használ, akkor /js/dist/*.jsUMD-kompatibilis fájlokat is használhat.

Használat JavaScript keretrendszerekkel

Míg a Bootstrap CSS bármilyen keretrendszerrel használható, a Bootstrap JavaScript nem teljesen kompatibilis az olyan JavaScript-keretrendszerekkel, mint a React, Vue és Angular, amelyek feltételezik a DOM teljes ismeretét. A Bootstrap és a keretrendszer is megkísérelheti ugyanazt a DOM-elemet mutálni, ami olyan hibákat eredményezhet, mint például a legördülő listák, amelyek a „nyitott” pozícióban ragadnak.

Az ilyen típusú keretrendszereket használók számára jobb alternatíva egy keretspecifikus csomag használata a Bootstrap JavaScript helyett . Íme néhány a legnépszerűbb lehetőségek közül:

React: React Bootstrap
Vue: BootstrapVue (jelenleg csak a Vue 2-t és a Bootstrap 4-et támogatja)
Szögletes: ng-bootstrap

A Bootstrap használata modulként

Próbáld ki magad! Töltse le a forráskódot és a működő bemutatót a Bootstrap ES-modulként való használatához a twbs/examples tárolóból . A példát a StackBlitzben is megnyithatja .

ESMA Bootstrap ( bootstrap.esm.jsés ) néven készült verzióját biztosítjuk, bootstrap.esm.min.jsamely lehetővé teszi a Bootstrap modulként való használatát a böngészőben, ha a megcélzott böngészők támogatják .

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

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

A JS kötegelőkkel összehasonlítva az ESM böngészőben való használatához a modulnév helyett a teljes elérési utat és fájlnevet kell használni. További információ a JS modulokról a böngészőben. Ezért használjuk a fenti 'bootstrap.esm.min.js'helyett . 'bootstrap'Ezt azonban tovább bonyolítja Popper-függőségünk, amely így importálja a Poppert a JavaScriptünkbe:

import * as Popper from "@popperjs/core"

Ha ezt úgy próbálja meg, ahogy van, a következőhöz hasonló hibaüzenetet fog látni a konzolon:

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

Ennek kijavításához használhatja importmapa tetszőleges modulnevek feloldásához a teljes elérési utat. Ha a megcélzott böngészők nem támogatják importmapa , akkor az es-module-shims projektet kell használnia. Így működik a Bootstrap és a Popper esetében:

<!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>

Függőségek

Egyes bővítmények és CSS-összetevők más beépülő moduloktól függenek. Ha a beépülő modulokat külön-külön is felveszi, feltétlenül ellenőrizze ezeket a függőségeket a dokumentumokban.

Legördülő menüink, előugró ablakaink és elemleírásaink a Poppertől is függenek .

Adatattribútumok

Szinte minden Bootstrap beépülő modul engedélyezhető és konfigurálható kizárólag HTML-en keresztül adatattribútumokkal (a JavaScript funkció használatának előnyben részesített módja). Ügyeljen arra, hogy egyetlen elemnél csak egy adatattribútum-készletet használjon (pl. nem indíthat el eszközleírást és módozatot ugyanarról a gombról).

Mivel az opciók átadhatók adatattribútumokon vagy JavaScript-en keresztül, hozzáfűzhet egy beállításnevet a -hoz data-bs-, mint például a data-bs-animation="{value}". Ügyeljen arra, hogy az opció nevének esettípusát „ camelCase ”-ról „ kebab-case ”-re változtassa, amikor a beállításokat adatattribútumokon keresztül adja át. Például használja data-bs-custom-class="beautifier"a helyett data-bs-customClass="beautifier".

A Bootstrap 5.2.0-tól kezdve minden összetevő támogatja a kísérleti fenntartott adatattribútumot, data-bs-configamely JSON-karakterláncként tartalmazhat egyszerű összetevőkonfigurációt. Ha egy elemnek data-bs-config='{"delay":0, "title":123}'és data-bs-title="456"attribútumai vannak, a végső titleérték a következő lesz, 456és a különálló adatattribútumok felülírják a megadott értékeket data-bs-config. Ezenkívül a meglévő adatattribútumok JSON-értékeket, például data-bs-delay='{"show":0,"hide":150}'.

Kiválasztók

A natív querySelectorés querySelectorAllmetódusokat használjuk a DOM-elemek lekérdezésére teljesítmény okokból, ezért érvényes kiválasztókat kell használnia . Ha speciális választókat használ, mint például collapse:Example, ne felejtse el elkerülni őket.

Események

A Bootstrap egyéni eseményeket biztosít a legtöbb plugin egyedi műveletéhez. Általában ezek főnévi igenév és múlttag alakban fordulnak elő – ahol az infinitivus (pl. show) egy esemény elején, múltbeli igenév alakja (pl. shown) pedig egy cselekvés befejezésekor aktiválódik.

Minden infinitiv esemény preventDefault()funkcionalitást biztosít. Ez lehetővé teszi egy művelet végrehajtásának leállítását, mielőtt az elindulna. Ha az eseménykezelő false értéket ad vissza, az automatikusan meghívja a preventDefault().

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

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

Programozott API

Minden konstruktor elfogad egy opcionális opciós objektumot vagy semmit (ami elindít egy beépülő modult az alapértelmezett viselkedésével):

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

Ha egy adott bővítménypéldányt szeretne beszerezni, minden beépülő modul felfed egy getInstancemetódust. Például egy példány lekéréséhez közvetlenül egy elemből:

bootstrap.Popover.getInstance(myPopoverEl)

Ez a metódus akkor tér vissza null, ha egy példányt nem indítanak el a kért elem felett.

Alternatív megoldásként getOrCreateInstancehasználható a példány DOM-elemhez társítására, vagy új létrehozására, ha nem lett inicializálva.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Ha egy példányt nem inicializáltak, akkor elfogadhat és második argumentumként használhat egy opcionális konfigurációs objektumot.

CSS-szelektorok a konstruktorokban

A getInstanceés getOrCreateInstancemetódusokon kívül minden beépülő modul-konstruktor elfogadhat egy DOM-elemet vagy egy érvényes CSS-választót első argumentumként. A metódussal beépülő elemeket találunk, querySelectormivel a beépülő moduljaink csak egyetlen elemet támogatnak.

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')

Aszinkron funkciók és átmenetek

Minden programozott API-metódus aszinkron , és az átmenet megkezdése után, de még azelőtt visszatér a hívóhoz . Egy művelet végrehajtásához, miután az átmenet befejeződött, meghallgathatja a megfelelő eseményt.

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

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

Ezenkívül a rendszer figyelmen kívül hagyja az átmeneti komponens metódushívásait .

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`módszer

Bár helyesnek tűnhet, ha a disposemódszert közvetlenül utána használja hide(), ez helytelen eredményekhez vezet. Íme egy példa a probléma használatára:

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

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

Alapbeállítások

A beépülő modul alapértelmezett beállításait módosíthatja a bővítmény Constructor.Defaultobjektumának módosításával:

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

Módszerek és tulajdonságok

Minden Bootstrap beépülő modul a következő módszereket és statikus tulajdonságokat teszi közzé.

Módszer	Leírás
`dispose`	Elpusztítja egy elem modálisát. (Eltávolítja a DOM elemen tárolt adatokat)
`getInstance`	Statikus módszer, amely lehetővé teszi a DOM-elemhez társított modális példány beszerzését.
`getOrCreateInstance`	Statikus módszer, amely lehetővé teszi a DOM-elemhez társított modális példány lekérését, vagy új létrehozását, ha nem inicializálták.

Statikus tulajdonság	Leírás
`NAME`	A beépülő modul nevét adja vissza. (Példa `bootstrap.Tooltip.NAME`:)
`VERSION`	`VERSION`A Bootstrap egyes bővítményeinek verziója a beépülő modul konstruktorának tulajdonságán keresztül érhető el (Példa: `bootstrap.Tooltip.VERSION`)

Fertőtlenítő

Az eszköztippek és az előugró ablakok a beépített fertőtlenítőnket használják a HTML-t elfogadó opciók tisztítására.

Az alapértelmezett allowListérték a következő:

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: []
}

Ha új értékeket szeretne hozzáadni ehhez az alapértelmezett értékhez, allowListtegye a következőket:

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)

Ha szeretné megkerülni a fertőtlenítőnket, mert inkább egy dedikált könyvtárat szeretne használni, például a DOMPurify , akkor tegye a következőket:

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

Opcionálisan jQuery használatával

A Bootstrap 5-ben nincs szükség jQuery- re, de továbbra is használható összetevőink a jQuery-vel. Ha a Bootstrap észleli jQueryaz windowobjektumban, akkor az összes komponensünket hozzáadja a jQuery bővítményrendszeréhez. Ezzel a következőket teheti:

$('[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

Ugyanez vonatkozik a többi alkatrészünkre is.

Nincs konfliktus

Néha szükséges a Bootstrap beépülő modulok használata más UI keretrendszerekkel. Ilyen körülmények között időnként előfordulhatnak névtér-ütközések. Ha ez megtörténik, hívhatja azt .noConflicta beépülő modult, amelynek az értékét vissza szeretné állítani.

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

A Bootstrap hivatalosan nem támogatja a harmadik fél JavaScript-könyvtárait, mint például a Prototype vagy a jQuery UI. A .noConflictnévteres események ellenére előfordulhatnak kompatibilitási problémák, amelyeket egyedül kell megoldania.

jQuery események

A Bootstrap észleli a jQuery-t, ha jQueryjelen van az windowobjektumban, és nincs data-bs-no-jquerybeállítva attribútum a <body>. Ha a rendszer megtalálja a jQuery-t, a Bootstrap eseményeket bocsát ki a jQuery eseményrendszerének köszönhetően. Tehát ha meg akarja hallgatni a Bootstrap eseményeit, akkor a jQuery metódusokat ( .on, .one) kell használnia a helyett addEventListener.

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

Letiltott JavaScript

A Bootstrap beépülő moduljainak nincs speciális tartaléka, ha a JavaScript le van tiltva. Ha ebben az esetben érdekli a felhasználói élmény, használja <noscript>a helyzet elmagyarázásához (és a JavaScript újraengedélyezéséhez) a felhasználóknak, és/vagy adja hozzá saját egyéni tartalékait.