Preskoči na glavno vsebino Preskoči na navigacijo po dokumentih
Check
in English

JavaScript

Oživite Bootstrap z našimi izbirnimi vtičniki JavaScript. Izvedite več o vsakem vtičniku, naših podatkovnih in programskih možnostih API-ja in več.

Na tej strani

Posamezno ali sestavljeno

Vtičnike je mogoče vključiti posamično (z uporabo individualnega Bootstrapa js/dist/*.js) ali vse naenkrat z uporabo bootstrap.jsali pomanjšanim bootstrap.min.js(ne vključujte obojega).

Če uporabljate povezovalnik (Webpack, Parcel, Vite ...), lahko uporabite /js/dist/*.jsdatoteke, ki so pripravljene za UMD.

Uporaba z okviri JavaScript

Čeprav je Bootstrap CSS mogoče uporabiti s katerim koli ogrodjem, Bootstrap JavaScript ni popolnoma združljiv z ogrodji JavaScript, kot so React, Vue in Angular, ki predvidevajo popolno poznavanje DOM. Tako Bootstrap kot ogrodje lahko poskušata mutirati isti element DOM, kar povzroči hrošče, kot so spustni meniji, ki ostanejo v položaju »odprto«.

Boljša alternativa za tiste, ki uporabljajo to vrsto okvirov, je uporaba paketa, specifičnega za okvir, namesto Bootstrap JavaScript. Tukaj je nekaj najbolj priljubljenih možnosti:

Uporaba Bootstrapa kot modula

Poskusite sami! Prenesite izvorno kodo in delujočo predstavitev za uporabo Bootstrapa kot modula ES iz repozitorija twbs/examples . Primer lahko odprete tudi v StackBlitzu .

Ponujamo različico Bootstrapa, zgrajeno kot ESM( bootstrap.esm.jsin bootstrap.esm.min.js), ki vam omogoča uporabo Bootstrapa kot modula v brskalniku, če to podpirajo vaši ciljni brskalniki .

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

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

V primerjavi s povezovalniki JS uporaba ESM v brskalniku zahteva uporabo celotne poti in imena datoteke namesto imena modula. Preberite več o modulih JS v brskalniku. Zato uporabljamo 'bootstrap.esm.min.js'namesto 'bootstrap'zgoraj. Vendar pa je to še dodatno zapleteno zaradi naše odvisnosti od Popperja, ki uvozi Popper v naš JavaScript takole:

import * as Popper from "@popperjs/core"

Če poskusite tako, kot je, boste v konzoli videli napako, kot je ta:

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

Če želite to popraviti, lahko uporabite importmapza razrešitev poljubnih imen modulov za dokončanje poti. Če vaši ciljni brskalniki ne podpirajo importmap, boste morali uporabiti projekt es-module-shims . Takole deluje za Bootstrap in 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>

Odvisnosti

Nekateri vtičniki in komponente CSS so odvisni od drugih vtičnikov. Če dodate vtičnike posamezno, preverite te odvisnosti v dokumentih.

Naši spustni meniji, pojavna okna in opisi orodij so prav tako odvisni od Popperja .

Atributi podatkov

Skoraj vse vtičnike Bootstrap je mogoče omogočiti in konfigurirati samo prek HTML s podatkovnimi atributi (naš najprimernejši način uporabe funkcije JavaScript). Prepričajte se, da uporabljate samo en nabor podatkovnih atributov na posameznem elementu (npr. ne morete sprožiti namiga orodja in modala z istega gumba.)

Ker je možnosti mogoče posredovati prek podatkovnih atributov ali JavaScripta, lahko dodate ime možnosti v data-bs-, kot v data-bs-animation="{value}". Prepričajte se, da ste spremenili vrsto malega črke imena možnosti iz " camelCase " v " kebab-case ", ko posredujete možnosti prek podatkovnih atributov. Na primer, uporabite data-bs-custom-class="beautifier"namesto data-bs-customClass="beautifier".

Od Bootstrap 5.2.0 naprej vse komponente podpirajo poskusni atribut rezerviranih podatkov, data-bs-configki lahko hrani preprosto konfiguracijo komponente kot niz JSON. Ko ima element atribute data-bs-config='{"delay":0, "title":123}'in data-bs-title="456", bo končna titlevrednost 456in ločeni atributi podatkov bodo preglasili vrednosti, podane na data-bs-config. Poleg tega lahko obstoječi atributi podatkov hranijo vrednosti JSON, kot je data-bs-delay='{"show":0,"hide":150}'.

Selektorji

Za poizvedovanje po elementih DOM zaradi učinkovitosti uporabljamo izvorne metode querySelectorin querySelectorAllmetode, zato morate uporabiti veljavne izbirnike . Če uporabljate posebne izbirnike, kot collapse:Exampleje , jim ne pozabite ubežati.

Dogodki

Bootstrap ponuja dogodke po meri za večino edinstvenih dejanj vtičnikov. Na splošno so ti v obliki nedoločnika in deležnika preteklosti – kjer se nedoločnik (npr. show) sproži na začetku dogodka, njegova oblika deležnika preteklosti (npr. shown) pa se sproži ob zaključku dejanja.

Vsi nedoločni dogodki zagotavljajo preventDefault()funkcionalnost. To omogoča, da ustavite izvajanje dejanja, preden se začne. Če obravnavalec dogodkov vrne false, bo tudi samodejno poklical preventDefault().

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

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

Programski API

Vsi konstruktorji sprejmejo izbirni objekt možnosti ali nič (kar sproži vtičnik s privzetim vedenjem):

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

Če želite dobiti določen primerek vtičnika, vsak vtičnik izpostavi getInstancemetodo. Na primer, če želite pridobiti primerek neposredno iz elementa:

bootstrap.Popover.getInstance(myPopoverEl)

Ta metoda se bo vrnila, nullče primerek ni zagnan nad zahtevanim elementom.

Lahko getOrCreateInstancepa se uporabi tudi za pridobivanje primerka, povezanega z elementom DOM, ali ustvarjanje novega, če ni bil inicializiran.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

V primeru, da primerek ni bil inicializiran, lahko sprejme in uporabi izbirni konfiguracijski objekt kot drugi argument.

Selektorji CSS v konstruktorjih

Poleg metod getInstancein lahko vsi konstruktorji vtičnikov kot prvi argument getOrCreateInstancesprejmejo element DOM ali veljaven izbirnik CSS . Elemente vtičnikov najdemo z querySelectormetodo, saj naši vtičniki podpirajo samo en element.

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

Asinhrone funkcije in prehodi

Vse programske metode API-ja so asinhrone in se vrnejo klicatelju, ko se prehod začne, vendar preden se konča . Če želite izvesti dejanje, ko je prehod končan, lahko poslušate ustrezen dogodek.

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

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

Poleg tega bo prezrt klic metode prehodne komponente .

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

disposemetoda

Čeprav se morda zdi pravilna uporaba disposemetode takoj po hide(), bo to povzročilo napačne rezultate. Tukaj je primer uporabe težave:

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

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

Privzete nastavitve

Privzete nastavitve za vtičnik lahko spremenite tako, da spremenite predmet vtičnika Constructor.Default:

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

Metode in lastnosti

Vsak vtičnik Bootstrap izpostavlja naslednje metode in statične lastnosti.

Metoda Opis
dispose Uniči modalnost elementa. (Odstrani shranjene podatke v elementu DOM)
getInstance Statična metoda, ki vam omogoča pridobitev modalne instance, povezane z elementom DOM.
getOrCreateInstance Statična metoda, ki vam omogoča, da pridobite modalni primerek, povezan z elementom DOM, ali ustvarite novega, če ni bil inicializiran.
Statična lastnost Opis
NAME Vrne ime vtičnika. (Primer: bootstrap.Tooltip.NAME)
VERSION Do različice vsakega vtičnika Bootstrap je mogoče dostopati prek VERSIONlastnosti konstruktorja vtičnika (Primer: bootstrap.Tooltip.VERSION)

Razkužilo

Namigi orodij in pojavni elementi uporabljajo naš vgrajeni čistilec za čiščenje možnosti, ki sprejemajo HTML.

Privzeta allowListvrednost je naslednja:

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

Če želite tej privzeti vrednosti dodati nove vrednosti allowList, lahko storite naslednje:

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)

Če želite zaobiti naš sanitizer, ker raje uporabljate namensko knjižnico, na primer DOMPurify , storite naslednje:

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

Po želji z uporabo jQuery

V Bootstrap 5 ne potrebujete jQuery , vendar je še vedno mogoče uporabljati naše komponente z jQuery. Če Bootstrap zazna jQueryv windowobjektu, bo dodal vse naše komponente v sistem vtičnikov jQuery. To vam omogoča naslednje:

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

Enako velja za naše druge komponente.

Brez konflikta

Včasih je treba uporabiti vtičnike Bootstrap z drugimi okviri uporabniškega vmesnika. V teh okoliščinah lahko občasno pride do kolizij imenskega prostora. Če se to zgodi, lahko pokličete .noConflictvtičnik, katerega vrednost želite razveljaviti.

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

Bootstrap uradno ne podpira knjižnic JavaScript tretjih oseb, kot sta Prototype ali jQuery UI. Kljub .noConflictdogodkom in imenskim prostorom lahko pride do težav z združljivostjo, ki jih morate odpraviti sami.

dogodki jQuery

Bootstrap bo zaznal jQuery, če jQueryje prisoten v windowobjektu in ni nastavljen noben data-bs-no-jqueryatribut <body>. Če najde jQuery, bo Bootstrap oddal dogodke zahvaljujoč sistemu dogodkov jQuery. Torej, če želite poslušati dogodke Bootstrapa, boste morali uporabiti metode jQuery ( .on, .one) namesto addEventListener.

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

Onemogočen JavaScript

Bootstrapovi vtičniki nimajo posebne nadomestne možnosti, ko je JavaScript onemogočen. Če vam je mar za uporabniško izkušnjo v tem primeru, uporabite, <noscript>da svojim uporabnikom pojasnite situacijo (in kako znova omogočiti JavaScript) in/ali dodajte lastne nadomestne možnosti po meri.