JavaScript

Herätä Bootstrap henkiin valinnaisilla JavaScript-laajennuksillamme. Lisätietoja kustakin laajennuksesta, data- ja ohjelmallisista sovellusliittymävaihtoehdoistamme ja paljon muuta.

Tällä sivulla

Yksittäinen tai koottu

Laajennukset voidaan sisällyttää yksitellen (käyttäen Bootstrapin yksittäistä js/dist/*.js) tai kaikki kerralla käyttämällä bootstrap.jstai pienennettyä bootstrap.min.js(älä sisällytä molempia).

Jos käytät niputtajaa (Webpack, Parcel, Vite…), voit käyttää /js/dist/*.jsUMD-valmiita tiedostoja.

Käyttö JavaScript-kehysten kanssa

Vaikka Bootstrap CSS:ää voidaan käyttää minkä tahansa kehyksen kanssa, Bootstrap JavaScript ei ole täysin yhteensopiva JavaScript-kehysten, kuten React, Vue ja Angular, kanssa, jotka olettavat täyden tuntemuksen DOM:sta. Sekä Bootstrap että kehys voivat yrittää mutatoida samaa DOM-elementtiä, mikä johtaa bugeihin, kuten pudotusvalikkoihin, jotka ovat juuttuneet "avoin"-asentoon.

Parempi vaihtoehto tämän tyyppisiä kehyksiä käyttäville on käyttää kehyskohtaista pakettia Bootstrap JavaScriptin sijaan . Tässä on joitain suosituimmista vaihtoehdoista:

React: React Bootstrap
Vue: BootstrapVue (tukee tällä hetkellä vain Vue 2:ta ja Bootstrap 4:ää)
Kulma: ng-bootstrap

Bootstrapin käyttö moduulina

Kokeile itse! Lataa lähdekoodi ja toimiva demo Bootstrapin käyttämiseksi ES-moduulina twbs/examples-arkistosta . Voit myös avata esimerkin StackBlitzissä .

Tarjoamme Bootstrap-version, joka on rakennettu muodossa ESM( bootstrap.esm.jsja bootstrap.esm.min.js), jonka avulla voit käyttää Bootstrapia selaimen moduulina, jos kohdeselaimesi tukevat sitä .

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

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

JS-niputtajiin verrattuna ESM:n käyttäminen selaimessa edellyttää, että käytät koko polkua ja tiedostonimeä moduulin nimen sijaan. Lue lisää JS-moduuleista selaimessa. Siksi käytämme yllä 'bootstrap.esm.min.js'olevan sijasta 'bootstrap'. Tätä monimutkaistaa kuitenkin Popper-riippuvuus, joka tuo Popperin JavaScriptiin seuraavasti:

import * as Popper from "@popperjs/core"

Jos yrität tätä sellaisenaan, näet konsolissa seuraavanlaisen virheilmoituksen:

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

Voit korjata tämän importmapratkaisemalla mielivaltaiset moduulien nimet täydentävien polkujen avulla. Jos kohdistetut selaimesi eivät tue importmap, sinun on käytettävä es-module-shims -projektia. Näin se toimii Bootstrapissa ja Popperissa:

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

Riippuvuudet

Jotkut laajennukset ja CSS-komponentit ovat riippuvaisia muista laajennuksista. Jos lisäät laajennuksia yksitellen, varmista, että tarkistat nämä riippuvuudet asiakirjoista.

Pudotusvalikot, ponnahdusikkunat ja työkaluvinkkimme riippuvat myös Popperista .

Tietojen attribuutit

Lähes kaikki Bootstrap-laajennukset voidaan ottaa käyttöön ja määrittää pelkän HTML:n kautta dataattribuuttien kanssa (suosittu tapamme käyttää JavaScript-toimintoa). Varmista, että käytät vain yhtä tietomääritejoukkoa yhdessä elementissä (esim. et voi käynnistää työkaluvihjettä ja modaalia samasta painikkeesta).

Koska valinnat voidaan välittää tietomääritteiden tai JavaScriptin kautta, voit liittää vaihtoehdon nimen kohtaan data-bs-, kuten data-bs-animation="{value}". Varmista, että vaihdat vaihtoehdon nimen tapaustyypin " camelCase " arvoksi " kebab-case ", kun välität valinnat tietomääritteiden kautta. Käytä data-bs-custom-class="beautifier"esimerkiksi data-bs-customClass="beautifier".

Bootstrap 5.2.0:sta lähtien kaikki komponentit tukevat kokeellista varattua dataattribuuttia, data-bs-configjoka voi sisältää yksinkertaisen komponenttimäärityksen JSON-merkkijonona. Kun elementillä on attribuutit data-bs-config='{"delay":0, "title":123}'ja data-bs-title="456", lopullinen titlearvo on 456ja erilliset tietoattribuutit ohittavat annetut arvot data-bs-config. Lisäksi olemassa olevat dataattribuutit voivat sisältää JSON-arvoja, kuten data-bs-delay='{"show":0,"hide":150}'.

Valitsijat

Käytämme natiivia querySelectorja querySelectorAllmenetelmiä DOM-elementtien kyselyyn suorituskykysyistä, joten sinun on käytettävä kelvollisia valitsimia . Jos käytät erityisiä valitsimia, kuten collapse:Example, muista välttää niitä.

Tapahtumat

Bootstrap tarjoaa mukautettuja tapahtumia useimpien laajennusten ainutlaatuisia toimintoja varten. Yleensä nämä tulevat infinitiivi- ja menneisyyden partisiipin muodossa - missä infinitiivi (esim. show) laukeaa tapahtuman alussa ja sen mennyt partisiippimuoto (esim. shown) käynnistetään toiminnon päätyttyä.

Kaikki infinitiiviset tapahtumat tarjoavat preventDefault()toimivuutta. Tämä tarjoaa mahdollisuuden pysäyttää toiminnon suorittaminen ennen sen alkamista. Tapahtumien käsittelijän palauttaminen false kutsuu myös automaattisesti preventDefault().

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

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

Ohjelmallinen sovellusliittymä

Kaikki rakentajat hyväksyvät valinnaisen optioobjektin tai ei mitään (joka käynnistää laajennuksen oletuskäyttäytymisellään):

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

Jos haluat saada tietyn laajennuksen esiintymän, jokainen laajennus paljastaa getInstancemenetelmän. Esimerkiksi, jos haluat hakea ilmentymän suoraan elementistä:

bootstrap.Popover.getInstance(myPopoverEl)

Tämä menetelmä palauttaa, nulljos esiintymää ei aloiteta pyydetyn elementin yli.

Vaihtoehtoisesti getOrCreateInstancevoidaan käyttää DOM-elementtiin liittyvän ilmentymän saamiseen tai uuden luomiseen, jos sitä ei ole alustettu.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Jos ilmentymää ei alustettu, se voi hyväksyä valinnaisen määritysobjektin ja käyttää sitä toisena argumenttina.

CSS-valitsimet konstruktoreissa

getInstanceMenetelmien ja lisäksi getOrCreateInstancekaikki liitännäisrakentajat voivat hyväksyä DOM-elementin tai kelvollisen CSS-valitsimen ensimmäisenä argumenttina. Plugin-elementit löytyvät querySelectormenetelmällä, koska laajennukset tukevat vain yhtä elementtiä.

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

Asynkroniset toiminnot ja siirtymät

Kaikki ohjelmoidut API-menetelmät ovat asynkronisia ja palaavat soittajalle siirron alkaessa, mutta ennen sen päättymistä . Jos haluat suorittaa toiminnon siirron jälkeen, voit kuunnella vastaavaa tapahtumaa.

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

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

Lisäksi siirtyvän komponentin menetelmäkutsu jätetään huomioimatta .

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`menetelmä

Vaikka disposemenetelmän käyttäminen heti -kohdan jälkeen saattaa tuntua oikealta hide(), se johtaa vääriin tuloksiin. Tässä esimerkki ongelman käytöstä:

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

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

Oletusasetukset

Voit muuttaa laajennuksen oletusasetuksia muokkaamalla laajennuksen Constructor.Defaultobjektia:

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

Menetelmät ja ominaisuudet

Jokainen Bootstrap-laajennus paljastaa seuraavat menetelmät ja staattiset ominaisuudet.

Menetelmä	Kuvaus
`dispose`	Tuhoaa elementin modaalin. (Poistaa DOM-elementtiin tallennetut tiedot)
`getInstance`	Staattinen menetelmä, jonka avulla voit saada DOM-elementtiin liittyvän modaalin esiintymän.
`getOrCreateInstance`	Staattinen menetelmä, jonka avulla voit saada DOM-elementtiin liittyvän modaalin esiintymän tai luoda uuden, jos sitä ei alustettu.

Staattinen ominaisuus	Kuvaus
`NAME`	Palauttaa laajennuksen nimen. (Esimerkki `bootstrap.Tooltip.NAME`:)
`VERSION`	Jokaisen Bootstrapin lisäosan versiota voi käyttää `VERSION`laajennuksen rakentajan ominaisuuden kautta (esimerkki: `bootstrap.Tooltip.VERSION`)

Desinfiointiaine

Työkaluvihjeet ja ponnahdusikkunat käyttävät sisäänrakennettua desinfiointiohjelmaamme HTML:n hyväksyvien vaihtoehtojen puhdistamiseen.

Oletusarvo allowListon seuraava:

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

Jos haluat lisätä uusia arvoja tähän oletusarvoon allowList, voit tehdä seuraavasti:

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)

Jos haluat ohittaa desinfiointituotteemme, koska käytät mieluummin erityistä kirjastoa, esimerkiksi DOMPurify , sinun tulee toimia seuraavasti:

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

Vaihtoehtoisesti jQueryllä

Et tarvitse jQueryä Bootstrap 5 :ssä , mutta komponenttejamme voi silti käyttää jQueryn kanssa. Jos Bootstrap havaitsee jQueryobjektissa window, se lisää kaikki osamme jQueryn laajennusjärjestelmään. Tämän avulla voit tehdä seuraavat:

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

Sama koskee muitakin komponenttejamme.

Ei konfliktia

Joskus on tarpeen käyttää Bootstrap-laajennuksia muiden käyttöliittymäkehysten kanssa. Näissä olosuhteissa nimiavaruuden törmäyksiä voi toisinaan tapahtua. Jos näin tapahtuu, voit kutsua .noConflictlaajennusta, jonka arvon haluat palauttaa.

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

Bootstrap ei tue virallisesti kolmannen osapuolen JavaScript-kirjastoja, kuten Prototype- tai jQuery-käyttöliittymää. Nimivälillisistä .noConflicttapahtumista huolimatta saattaa esiintyä yhteensopivuusongelmia, jotka sinun on korjattava itse.

jQuery-tapahtumat

Bootstrap havaitsee jQueryn, jos jQueryse on windowobjektissa eikä sille ole data-bs-no-jqueryasetettu attribuuttia <body>. Jos jQuery löytyy, Bootstrap lähettää tapahtumia jQueryn tapahtumajärjestelmän ansiosta. Joten jos haluat kuunnella Bootstrapin tapahtumia, sinun on käytettävä jQuery-menetelmiä ( .on, .one) addEventListener.

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

JavaScript poistettu käytöstä

Bootstrapin liitännäisillä ei ole erityistä varavaihtoehtoa, kun JavaScript on poistettu käytöstä. Jos välität käyttökokemuksesta tässä tapauksessa, käytä <noscript>selittääksesi tilanteen (ja kuinka JavaScript otetaan uudelleen käyttöön) käyttäjillesi ja/tai lisää omia mukautettuja varavaihtoehtoja.