Pereiti prie pagrindinio turinio Pereiti prie dokumentų naršymo
Check
in English

JavaScript

Atgaivinkite „Bootstrap“ naudodami pasirenkamus „JavaScript“ papildinius. Sužinokite apie kiekvieną papildinį, mūsų duomenų ir programinės API parinktis ir dar daugiau.

Šiame puslapyje

Individualus arba sudarytas

Papildiniai gali būti įtraukti atskirai (naudojant Bootstrap individualų js/dist/*.js), arba visus iš karto, naudojant bootstrap.jsarba sumažintą bootstrap.min.js(neįtraukti abiejų).

Jei naudojate rinktuvą (Webpack, Parcel, Vite…), galite naudoti /js/dist/*.jsUMD paruoštus failus.

Naudojimas su JavaScript sistemomis

Nors „Bootstrap CSS“ galima naudoti su bet kokia sistema, „Bootstrap JavaScript“ nėra visiškai suderinama su „JavaScript“ sistemomis, tokiomis kaip „React“, „Vue“ ir „Angular“ , kurios prisiima visas DOM žinias. Tiek „Bootstrap“, tiek sistema gali bandyti pakeisti tą patį DOM elementą, todėl gali atsirasti klaidų, pvz., išskleidžiamųjų sąrašų, kurie įstrigo „atviroje“ padėtyje.

Geresnė alternatyva tiems, kurie naudoja tokio tipo sistemas, yra naudoti konkrečiam rėmui skirtą paketą , o ne „Bootstrap JavaScript“. Štai keletas populiariausių variantų:

Bootstrap naudojimas kaip modulis

Išbandykite patys! Atsisiųskite šaltinio kodą ir demonstracinę versiją, skirtą Bootstrap naudoti kaip ES modulį iš twbs/examples saugyklos . Taip pat galite atidaryti pavyzdį „StackBlitz“ .

Pateikiame „Bootstrap“ versiją, sukurtą kaip ESM( bootstrap.esm.jsir bootstrap.esm.min.js), kuri leidžia naudoti „Bootstrap“ kaip naršyklės modulį, jei jūsų tikslinės naršyklės ją palaiko .

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

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

Palyginti su JS rinktuvais, naudojant ESM naršyklėje reikia naudoti visą kelią ir failo pavadinimą, o ne modulio pavadinimą. Skaitykite daugiau apie JS modulius naršyklėje. Štai kodėl mes naudojame 'bootstrap.esm.min.js'vietoj 'bootstrap'aukščiau. Tačiau tai dar labiau apsunkina mūsų Popper priklausomybė, kuri importuoja Popper į mūsų JavaScript taip:

import * as Popper from "@popperjs/core"

Jei bandysite tai padaryti taip, kaip yra, konsolėje pamatysite tokią klaidą:

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

Norėdami tai išspręsti, galite naudoti , importmapkad išspręstumėte savavališkus modulių pavadinimus, kad užbaigtumėte kelius. Jei jūsų tikslinės naršyklės nepalaiko importmap, turėsite naudoti projektą es-module-shims . Štai kaip tai veikia „Bootstrap“ ir „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>

Priklausomybės

Kai kurie papildiniai ir CSS komponentai priklauso nuo kitų papildinių. Jei įskiepius įtraukiate atskirai, būtinai patikrinkite, ar dokumentuose nėra šių priklausomybių.

Mūsų išskleidžiamieji meniu, iššokantys langai ir patarimai taip pat priklauso nuo Popper .

Duomenų atributai

Beveik visus „Bootstrap“ papildinius galima įjungti ir konfigūruoti naudojant tik HTML su duomenų atributais (mūsų pageidaujamas „JavaScript“ funkcijos naudojimo būdas). Įsitikinkite, kad viename elemente naudojate tik vieną duomenų atributų rinkinį (pvz., negalite suaktyvinti patarimo ir modalo iš to paties mygtuko).

Kadangi parinktis galima perduoti naudojant duomenų atributus arba „JavaScript“, galite pridėti parinkties pavadinimą prie data-bs-, kaip ir data-bs-animation="{value}". Perduodant parinktis per duomenų atributus , būtinai pakeiskite parinkties pavadinimo didžiosios raidės tipą iš „ camelCase “ į „ kebab-case “. Pavyzdžiui, naudokite data-bs-custom-class="beautifier"vietoj data-bs-customClass="beautifier".

Nuo 5.2.0 versijos „Bootstrap“ visi komponentai palaiko eksperimentinį rezervuotų duomenų atributą data-bs-config, kuriame galima laikyti paprastą komponento konfigūraciją kaip JSON eilutę. Kai elementas turi data-bs-config='{"delay":0, "title":123}'ir data-bs-title="456"atributus, galutinė titlereikšmė bus 456ir atskiri duomenų atributai nepaisys reikšmių, pateiktų data-bs-config. Be to, esamuose duomenų atributuose gali būti JSON reikšmės, pvz ., data-bs-delay='{"show":0,"hide":150}'.

Selektoriai

DOM elementų užklausai dėl našumo naudojame savąjį querySelectorir metodus, todėl turite naudoti galiojančius parinkiklius . Jei naudojate specialius parinkiklius, tokius kaip , būtinai jų atsisakykite.querySelectorAllcollapse:Example

Renginiai

„Bootstrap“ teikia tinkintus įvykius daugumos unikalių papildinių veiksmams. Paprastai jie būna įnagininko ir būtojo laiko formos – kai įnagininkas (pvz. show, ) suaktyvinamas įvykio pradžioje, o jo būtojo laiko forma (pvz. shown, ) – baigus veiksmą.

Visi begaliniai įvykiai suteikia preventDefault()funkcionalumo. Tai suteikia galimybę sustabdyti veiksmo vykdymą prieš jam pradedant. Grąžinus false iš įvykių tvarkyklės taip pat bus automatiškai iškviesta preventDefault().

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

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

Programinė API

Visi konstruktoriai priima pasirenkamų parinkčių objektą arba nieko (kuris inicijuoja papildinį pagal numatytąją elgseną):

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

Jei norite gauti konkretų papildinio egzempliorių, kiekvienas papildinys atskleidžia getInstancemetodą. Pavyzdžiui, norėdami gauti egzempliorių tiesiai iš elemento:

bootstrap.Popover.getInstance(myPopoverEl)

Šis metodas grįš null, jei egzempliorius nebus inicijuotas per prašomą elementą.

Arba getOrCreateInstancegali būti naudojamas egzemplioriui susieti su DOM elementu arba sukurti naują, jei jis nebuvo inicijuotas.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Jei egzempliorius nebuvo inicijuotas, jis gali priimti ir naudoti pasirenkamą konfigūracijos objektą kaip antrąjį argumentą.

CSS selektoriai konstruktoriuose

Be getInstanceir getOrCreateInstancemetodų, visi papildinių konstruktoriai gali priimti DOM elementą arba galiojantį CSS parinkiklį kaip pirmąjį argumentą. Papildinių elementai randami naudojant šį querySelectormetodą, nes mūsų papildiniai palaiko tik vieną 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')

Asinchroninės funkcijos ir perėjimai

Visi programiniai API metodai yra asinchroniniai ir grįžta į skambinantįjį, kai tik pradedamas perėjimas, bet jam nepasibaigus . Norėdami atlikti veiksmą, kai perėjimas bus baigtas, galite klausytis atitinkamo įvykio.

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

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

Be to, pereinamojo komponento metodo iškvietimas bus ignoruojamas .

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

disposemetodas

Nors gali atrodyti teisinga naudoti disposemetodą iš karto po hide(), tai sukels neteisingus rezultatus. Štai problemos naudojimo pavyzdys:

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

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

Numatytieji nustatymai

Galite pakeisti numatytuosius papildinio nustatymus pakeisdami papildinio Constructor.Defaultobjektą:

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

Metodai ir savybės

Kiekvienas „Bootstrap“ papildinys atskleidžia šiuos metodus ir statines savybes.

Metodas apibūdinimas
dispose Sunaikina elemento modalą. (Pašalina saugomus duomenis DOM elemente)
getInstance Statinis metodas, leidžiantis gauti modalinį egzempliorių, susietą su DOM elementu.
getOrCreateInstance Statinis metodas, leidžiantis gauti modalinį egzempliorių, susietą su DOM elementu, arba sukurti naują, jei jis nebuvo inicijuotas.
Statinė savybė apibūdinimas
NAME Grąžina papildinio pavadinimą. (Pavyzdys bootstrap.Tooltip.NAME:)
VERSION Kiekvieno „Bootstrap“ įskiepio versiją galima pasiekti naudojant VERSIONpapildinio konstruktoriaus ypatybę (pavyzdys: bootstrap.Tooltip.VERSION)

Dezinfekavimo priemonė

Patarimai ir popovers naudoja mūsų integruotą dezinfekavimo priemonę, kad išvalytų parinktis, kurios priima HTML.

Numatytoji allowListreikšmė yra tokia:

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

Jei prie šios numatytosios vertės norite pridėti naujų reikšmių, allowListgalite atlikti šiuos veiksmus:

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)

Jei norite apeiti mūsų dezinfekavimo priemonę, nes norite naudoti tam skirtą biblioteką, pvz. , DOMpurify , turėtumėte atlikti šiuos veiksmus:

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

Pasirinktinai naudojant jQuery

„Bootstrap 5“ jums nereikia „jQuery“ , bet vis tiek galima naudoti mūsų komponentus su „jQuery“. jQueryJei „Bootstrap “ aptiks windowobjekte, jis pridės visus mūsų komponentus į „jQuery“ papildinių sistemą. Tai leidžia atlikti šiuos veiksmus:

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

Tas pats pasakytina ir apie kitus mūsų komponentus.

Jokio konflikto

Kartais reikia naudoti Bootstrap papildinius su kitomis vartotojo sąsajos sistemomis. Tokiomis aplinkybėmis kartais gali įvykti vardų erdvės susidūrimai. Jei taip atsitiks, galite iškviesti .noConflictpapildinį, kurio vertę norite grąžinti.

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

„Bootstrap“ oficialiai nepalaiko trečiųjų šalių „JavaScript“ bibliotekų, tokių kaip „Prototype“ arba „jQuery“ vartotojo sąsaja. Nepaisant .noConflictįvykių su pavadinimais, gali kilti suderinamumo problemų, kurias turėsite išspręsti patys.

jQuery įvykiai

„Bootstrap“ aptiks „jQuery“, jei jQueryjis yra windowobjekte ir nėra data-bs-no-jquerynustatytas joks atributas <body>. Jei „jQuery“ randama, „Bootstrap“ išduos įvykius „jQuery“ įvykių sistemos dėka. Taigi, jei norite klausytis Bootstrap įvykių, turėsite naudoti jQuery metodus ( .on, .one), o ne addEventListener.

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

Išjungtas JavaScript

Kai „JavaScript“ išjungta, „Bootstrap“ papildiniai neturi specialių atsarginių dalių. Jei šiuo atveju jums rūpi naudotojo patirtis, naudokite <noscript>norėdami paaiškinti situaciją (ir kaip iš naujo įgalinti „JavaScript“) savo naudotojams ir (arba) pridėti savo pasirinktinių atsarginių variantų.