JavaScript

Vivu Bootstrap per niaj laŭvolaj JavaScript-kromaĵoj. Lernu pri ĉiu kromaĵo, niaj datumoj kaj programaj API-opcioj, kaj pli.

Sur ĉi tiu paĝo

Individuaj aŭ kompilitaj

Kromaĵoj povas esti inkluzivitaj individue (uzante la individuan de Bootstrap js/dist/*.js), aŭ ĉiuj samtempe uzante bootstrap.jsaŭ la minigitajn bootstrap.min.js(ne inkluzivas ambaŭ).

Se vi uzas bundler (Webpack, Parcel, Vite...), vi povas uzi /js/dist/*.jsdosierojn kiuj estas UMD pretaj.

Uzado kun JavaScript kadroj

Dum la Bootstrap CSS povas esti uzata kun iu ajn kadro, la Bootstrap JavaScript ne estas plene kongrua kun JavaScript-kadroj kiel React, Vue kaj Angular, kiuj supozas plenan scion pri la DOM. Kaj Bootstrap kaj la kadro povas provi mutacii la saman DOM-elementon, rezultigante cimojn kiel falmenuoj, kiuj estas blokitaj en la "malferma" pozicio.

Pli bona alternativo por tiuj uzantaj ĉi tiun tipon de kadroj estas uzi kadro-specifan pakaĵon anstataŭ la Bootstrap JavaScript. Jen kelkaj el la plej popularaj elektoj:

Reagi: Reagi Bootstrap
Vue: BootstrapVue (nuntempe nur subtenas Vue 2 kaj Bootstrap 4)
Angula: ng-bootstrap

Uzante Bootstrap kiel modulon

Provu ĝin mem! Elŝutu la fontkodon kaj labordemonstraĵon por uzi Bootstrap kiel ES-modulon el la twbs/examples-deponejo . Vi ankaŭ povas malfermi la ekzemplon en StackBlitz .

Ni provizas version de Bootstrap konstruita kiel ESM( bootstrap.esm.jskaj bootstrap.esm.min.js) kiu permesas vin uzi Bootstrap kiel modulon en la retumilo, se viaj celitaj retumiloj subtenas ĝin .

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

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

Kompare kun JS-pakistoj, uzi ESM en la retumilo postulas, ke vi uzu la plenan vojon kaj dosiernomon anstataŭ la modulnomo. Legu pli pri JS-moduloj en la retumilo. Tial ni uzas 'bootstrap.esm.min.js'anstataŭ 'bootstrap'supre. Tamen, ĉi tio estas pli komplika pro nia Popper-dependeco, kiu importas Popper en nian JavaScript tiel:

import * as Popper from "@popperjs/core"

Se vi provas ĉi tion tia, vi vidos eraron en la konzolo kiel la jena:

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

Por ripari ĉi tion, vi povas uzi importmappor solvi la arbitrajn modulnomojn por kompletigi vojojn. Se viaj celitaj retumiloj ne subtenas importmap, vi devos uzi la projekton es-module-shims . Jen kiel ĝi funkcias por Bootstrap kaj 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>

Dependecoj

Iuj aldonaĵoj kaj CSS-komponentoj dependas de aliaj aldonaĵoj. Se vi inkluzivas kromaĵojn individue, nepre kontroli ĉi tiujn dependecojn en la dokumentoj.

Niaj falmenuoj, popovers kaj konsiletoj ankaŭ dependas de Popper .

Datumaj atributoj

Preskaŭ ĉiuj Bootstrap-kromaĵoj povas esti ebligitaj kaj agorditaj per HTML sole kun datumaj atributoj (nia preferata maniero uzi JavaScript-funkciecon). Nepre uzu nur unu aron da datumaj atributoj sur ununura elemento (ekz., vi ne povas ekigi konsileton kaj modalon de la sama butono.)

Ĉar opcioj povas esti pasigitaj per datumaj atributoj aŭ JavaScript, vi povas almeti opcionomon al data-bs-, kiel en data-bs-animation="{value}". Nepre ŝanĝu la kazon de la opcionomo de " camelCase " al " kebab-case " kiam vi pasas la opciojn per datumaj atributoj. Ekzemple, uzu data-bs-custom-class="beautifier"anstataŭ data-bs-customClass="beautifier".

Ekde Bootstrap 5.2.0, ĉiuj komponantoj subtenas eksperimentan rezervitan datuman atributon data-bs-config, kiu povas enhavi simplan komponan agordon kiel JSON-ĉeno. Kiam elemento havas data-bs-config='{"delay":0, "title":123}'kaj data-bs-title="456"atributojn, la fina titlevaloro estos 456kaj la apartaj datumaj atributoj anstataŭigos valorojn donitajn sur data-bs-config. Krome, ekzistantaj datumaj atributoj povas enhavi JSON-valorojn kiel data-bs-delay='{"show":0,"hide":150}'.

Elektiloj

Ni uzas la indiĝenajn querySelectorkaj querySelectorAllmetodojn por pridemandi DOM-elementojn pro agado-kialoj, do vi devas uzi validajn elektilojn . Se vi uzas specialajn elektilojn kiel collapse:Example, nepre evitu ilin.

Eventoj

Bootstrap provizas kutimajn eventojn por la unikaj agoj de la plej multaj kromprogramoj. Ĝenerale, tiuj venas en infinitiva kaj preterito participo - kie la infinitivo (ekz. show) estas ekigita ĉe la komenco de okazaĵo, kaj ĝia preterito participformo (ekz. shown) estas ekigita sur la kompletigo de ago.

Ĉiuj infinitivaj eventoj disponigas preventDefault()funkciecon. Ĉi tio disponigas la kapablon ĉesigi la ekzekuton de ago antaŭ ol ĝi komenciĝas. Reveno de malvera de evento-traktilo ankaŭ aŭtomate vokos preventDefault().

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

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

Programa API

Ĉiuj konstrukciistoj akceptas laŭvolan opcian objekton aŭ nenion (kiu iniciatas kromprogramon kun sia defaŭlta konduto):

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

Se vi ŝatus akiri apartan kromprogramon, ĉiu kromaĵo elmontras getInstancemetodon. Ekzemple, por preni ekzemplon rekte de elemento:

bootstrap.Popover.getInstance(myPopoverEl)

Ĉi tiu metodo revenos nullse okazo ne estas komencita super la petita elemento.

Alternative, getOrCreateInstancepovas esti uzata por ricevi la petskribon asociita kun DOM-elemento, aŭ krei novan se ĝi ne estis pravigita.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Se iu kazo ne estis pravigita, ĝi povas akcepti kaj uzi laŭvolan agordan objekton kiel duan argumenton.

CSS-elektiloj en konstrukciistoj

Krom la metodoj getInstancekaj getOrCreateInstance, ĉiuj kromkonstruistoj povas akcepti DOM-elementon aŭ validan CSS-elektilon kiel la unuan argumenton. Kromaĵoj estas trovitaj kun la querySelectormetodo ĉar niaj kromprogramoj nur subtenas ununuran elementon.

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

Nesinkronaj funkcioj kaj transiroj

Ĉiuj programaj API-metodoj estas nesinkronaj kaj revenas al la alvokanto post kiam la transiro estas komencita, sed antaŭ ol ĝi finiĝas . Por efektivigi agon post kiam la transiro estas finita, vi povas aŭskulti la respondan eventon.

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

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

Krome, metodovoko sur transira komponento estos ignorita .

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`metodo

Kvankam eble ŝajnas ĝusta uzi la disposemetodon tuj post hide(), ĝi kondukos al malĝustaj rezultoj. Jen ekzemplo de la problemo-uzo:

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

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

Defaŭltaj agordoj

Vi povas ŝanĝi la defaŭltajn agordojn por kromaĵo modifante la Constructor.Defaultobjekton de la kromaĵo:

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

Metodoj kaj propraĵoj

Ĉiu Bootstrap kromaĵo elmontras la sekvajn metodojn kaj senmovajn ecojn.

Metodo	Priskribo
`dispose`	Detruas la modalon de elemento. (Forigas konservitajn datumojn sur la DOM-elemento)
`getInstance`	Senmova metodo, kiu ebligas al vi akiri la modalan petskribon asociitan kun DOM-elemento.
`getOrCreateInstance`	Statika metodo, kiu ebligas al vi akiri la modalan petskribon asociitan kun DOM-elemento, aŭ krei novan se ĝi ne estis pravigita.

Statika propraĵo	Priskribo
`NAME`	Redonas la kromnomon. (Ekzemplo: `bootstrap.Tooltip.NAME`)
`VERSION`	La versio de ĉiu el la kromprogramoj de Bootstrap estas alirebla per la `VERSION`posedaĵo de la konstrukciisto de la kromaĵo (Ekzemplo: `bootstrap.Tooltip.VERSION`)

Sanitizer

Konsiletoj kaj Popovers uzas nian enkonstruitan sanigilon por malpurigi opciojn kiuj akceptas HTML.

La defaŭlta allowListvaloro estas la sekva:

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

Se vi volas aldoni novajn valorojn al ĉi tiu defaŭlto allowList, vi povas fari la jenon:

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)

Se vi volas preteriri nian sanigilon ĉar vi preferas uzi dediĉitan bibliotekon, ekzemple DOMPurify , vi devus fari la jenon:

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

Laŭvole uzante jQuery

Vi ne bezonas jQuery en Bootstrap 5 , sed ankoraŭ eblas uzi niajn komponantojn kun jQuery. Se Bootstrap detektas jQueryen la windowobjekto, ĝi aldonos ĉiujn niajn komponantojn en la kromprogramon de jQuery. Ĉi tio permesas al vi fari la sekvajn:

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

La sama validas por niaj aliaj komponantoj.

Neniu konflikto

Kelkfoje necesas uzi Bootstrap-kromaĵojn kun aliaj UI-kadroj. En tiuj cirkonstancoj, nomspackolizioj povas foje okazi. Se tio okazas, vi povas alvoki .noConflictla kromprogramon, pri kiu vi volas reverti la valoron.

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

Bootstrap ne oficiale subtenas triajn JavaScript-bibliotekojn kiel Prototype aŭ jQuery UI. Malgraŭ .noConflictkaj nomspacitaj eventoj, povas esti kongruaj problemoj, kiujn vi devas ripari memstare.

jQuery eventoj

Bootstrap detektos jQuery se jQueryĉeestas en la windowobjekto kaj ne estas data-bs-no-jqueryatributo agordita sur <body>. Se jQuery estas trovita, Bootstrap elsendos eventojn danke al la eventa sistemo de jQuery. Do se vi volas aŭskulti la eventojn de Bootstrap, vi devos uzi la jQuery-metodojn ( .on, .one) anstataŭ addEventListener.

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

Malŝaltita JavaScript

La kromprogramoj de Bootstrap havas neniun specialan reziston kiam JavaScript estas malŝaltita. Se vi zorgas pri la uzantsperto en ĉi tiu kazo, uzu <noscript>por klarigi la situacion (kaj kiel reebligi JavaScript) al viaj uzantoj, kaj/aŭ aldoni viajn proprajn laŭmendajn kompensojn.