in English

JavaScript

Atdzīviniet Bootstrap, izmantojot mūsu izvēles JavaScript spraudņus. Uzziniet par katru spraudni, mūsu datu un programmatiskās API opcijām un daudz ko citu.

Šajā lapā

Individuāli vai apkopoti

Spraudņus var iekļaut atsevišķi (izmantojot Bootstrap individuālo js/dist/*.js), vai visus uzreiz, izmantojot bootstrap.jsvai samazinātu bootstrap.min.js(neietveriet abus).

Ja izmantojat komplektētāju (Webpack, Parcel, Vite…), varat izmantot /js/dist/*.jsfailus, kas ir gatavi UMD.

Lietošana ar JavaScript ietvariem

Lai gan Bootstrap CSS var izmantot ar jebkuru sistēmu, Bootstrap JavaScript nav pilnībā saderīgs ar JavaScript ietvariem, piemēram, React, Vue un Angular, kas uzņemas visas zināšanas par DOM. Gan Bootstrap, gan ietvars var mēģināt mutēt vienu un to pašu DOM elementu, radot kļūdas, piemēram, nolaižamās izvēlnes, kas ir iestrēgušas “atvērtā” pozīcijā.

Labāka alternatīva tiem, kas izmanto šāda veida ietvarus, ir izmantot ietvaram specifisku pakotni Bootstrap JavaScript vietā . Šeit ir dažas no populārākajām iespējām:

Reaģēt: reaģēt Bootstrap
Vue: BootstrapVue (šobrīd atbalsta tikai Vue 2 un Bootstrap 4)
Leņķiskais: ng-bootstrap

Bootstrap izmantošana kā modulis

Izmēģiniet to pats! Lejupielādējiet avota kodu un darba demonstrāciju, lai izmantotu Bootstrap kā ES moduli no twbs/examples krātuves . Varat arī atvērt piemēru programmā StackBlitz .

Mēs piedāvājam Bootstrap versiju, kas izveidota kā ESM( bootstrap.esm.jsun bootstrap.esm.min.js), kas ļauj izmantot Bootstrap kā moduli pārlūkprogrammā, ja jūsu atlasītās pārlūkprogrammas to atbalsta .

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

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

Salīdzinājumā ar JS komplektētājiem, izmantojot ESM pārlūkprogrammā, ir jāizmanto pilns ceļš un faila nosaukums, nevis moduļa nosaukums. Lasiet vairāk par JS moduļiem pārlūkprogrammā. Tāpēc mēs izmantojam 'bootstrap.esm.min.js', nevis 'bootstrap'iepriekš minēto. Tomēr to vēl vairāk sarežģī mūsu Popper atkarība, kas importē Popper mūsu JavaScript, piemēram:

import * as Popper from "@popperjs/core"

Ja izmēģināsit šo darbību tādu, kāds tas ir, konsolē tiks parādīta šāda kļūda:

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

Lai to labotu, varat izmantot , importmaplai atrisinātu patvaļīgos moduļu nosaukumus, lai pabeigtu ceļus. Ja jūsu atlasītās pārlūkprogrammas neatbalsta importmap, jums būs jāizmanto projekts es-module-shims . Lūk, kā tas darbojas Bootstrap un 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>

Atkarības

Daži spraudņi un CSS komponenti ir atkarīgi no citiem spraudņiem. Ja spraudņus iekļaujat atsevišķi, noteikti pārbaudiet, vai dokumentos nav šīs atkarības.

Mūsu nolaižamās izvēlnes, uznirstošie elementi un rīka padomi ir atkarīgi arī no Popper .

Datu atribūti

Gandrīz visus Bootstrap spraudņus var iespējot un konfigurēt, izmantojot tikai HTML ar datu atribūtiem (mūsu vēlamais JavaScript funkcionalitātes izmantošanas veids). Noteikti izmantojiet tikai vienu datu atribūtu kopu vienam elementam (piemēram, jūs nevarat aktivizēt rīka padomu un modālu no vienas pogas).

Tā kā opcijas var nodot, izmantojot datu atribūtus vai JavaScript, varat pievienot opcijas nosaukumu data-bs-, piemēram, data-bs-animation="{value}". Nododot opcijas, izmantojot datu atribūtus , noteikti nomainiet opcijas nosaukuma reģistra veidu no “ camelCase ” uz “ kebab-case ”. Piemēram, data-bs-custom-class="beautifier"izmantojiet data-bs-customClass="beautifier".

Sākot ar versiju Bootstrap 5.2.0, visi komponenti atbalsta eksperimentālu rezervēto datu atribūtu data-bs-config, kurā var ievietot vienkāršu komponentu konfigurāciju kā JSON virkni. Ja elementam ir atribūti data-bs-config='{"delay":0, "title":123}'un data-bs-title="456", galīgā titlevērtība būs 456un atsevišķie datu atribūti ignorēs vērtības, kas norādītas data-bs-config. Turklāt esošie datu atribūti var ietvert JSON vērtības, piemēram, data-bs-delay='{"show":0,"hide":150}'.

Atlasītāji

DOM elementu vaicāšanai veiktspējas nolūkos mēs izmantojam vietējo querySelectorun metodes, tāpēc jums ir jāizmanto derīgi atlasītāji . Ja izmantojat īpašus atlasītājus, piemēram , , noteikti izvairieties no tiem.querySelectorAllcollapse:Example

Pasākumi

Bootstrap nodrošina pielāgotus notikumus lielākajai daļai spraudņu unikālo darbību. Parasti tie ir infinitīva un pagātnes divdabja formā — kur infinitīvs (piem. show) tiek aktivizēts notikuma sākumā, bet tā pagātnes divdabja forma (piem. shown) tiek aktivizēta pēc darbības pabeigšanas.

Visi infinitīvie notikumi nodrošina preventDefault()funkcionalitāti. Tas nodrošina iespēju apturēt darbības izpildi pirms tās sākšanas. Atgriežot false no notikumu apstrādātāja, automātiski tiks izsaukts arī preventDefault().

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

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

Programmatiskā API

Visi konstruktori pieņem izvēles opciju objektu vai neko (kas iniciē spraudni ar tā noklusējuma darbību):

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

Ja vēlaties iegūt konkrētu spraudņa gadījumu, katrs spraudnis atklāj getInstancemetodi. Piemēram, lai izgūtu gadījumu tieši no elementa:

bootstrap.Popover.getInstance(myPopoverEl)

Šī metode tiks atgriezta, nullja instance netiks uzsākta, izmantojot pieprasīto elementu.

Alternatīvi getOrCreateInstancevar izmantot, lai saistītu gadījumu ar DOM elementu vai izveidotu jaunu, ja tas nav inicializēts.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Ja gadījums nav inicializēts, tas var pieņemt un izmantot neobligātu konfigurācijas objektu kā otro argumentu.

CSS atlasītāji konstruktoros

Papildus getInstanceun metodēm visi spraudņu konstruktori kā pirmo argumentu getOrCreateInstancevar pieņemt DOM elementu vai derīgu CSS atlasītāju . Spraudņu elementi tiek atrasti ar šo querySelectormetodi, jo mūsu spraudņi atbalsta tikai vienu elementu.

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

Asinhronās funkcijas un pārejas

Visas programmatiskās API metodes ir asinhronas un atgriežas pie zvanītāja, kad pāreja ir sākta, bet pirms tās beigām . Lai veiktu darbību, kad pāreja ir pabeigta, varat noklausīties atbilstošo notikumu.

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

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

Turklāt pārejas komponenta metodes izsaukums tiks ignorēts .

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

Lai gan var šķist pareizi izmantot disposemetodi tūlīt pēc hide(), tas radīs nepareizus rezultātus. Šeit ir problēmas izmantošanas piemērs:

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

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

Noklusējuma iestatījumi

Varat mainīt spraudņa noklusējuma iestatījumus, modificējot spraudņa Constructor.Defaultobjektu:

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

Metodes un īpašības

Katrs Bootstrap spraudnis atklāj šādas metodes un statiskās īpašības.

Metode	Apraksts
`dispose`	Iznīcina elementa modālu. (Noņem DOM elementā saglabātos datus)
`getInstance`	Statiskā metode, kas ļauj iegūt modālo instanci, kas saistīta ar DOM elementu.
`getOrCreateInstance`	Statiskā metode, kas ļauj iegūt modālo instanci, kas saistīta ar DOM elementu, vai izveidot jaunu, ja tas nav inicializēts.

Statisks īpašums	Apraksts
`NAME`	Atgriež spraudņa nosaukumu. (Piemērs `bootstrap.Tooltip.NAME`:)
`VERSION`	Katra Bootstrap spraudņa versijai var piekļūt, izmantojot `VERSION`spraudņa konstruktora rekvizītu (piemērs: `bootstrap.Tooltip.VERSION`)

Dezinficētājs

Rīka padomi un uznirstošie elementi izmanto mūsu iebūvēto dezinfekcijas līdzekli, lai dezinficētu opcijas, kas pieņem HTML.

Noklusējuma allowListvērtība ir šāda:

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

Ja šim noklusējumam vēlaties pievienot jaunas vērtības, allowListvarat rīkoties šādi:

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)

Ja vēlaties apiet mūsu dezinfekcijas līdzekli, jo vēlaties izmantot īpašu bibliotēku, piemēram , DOMpurify , rīkojieties šādi:

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

Pēc izvēles izmantojot jQuery

Jums nav nepieciešams jQuery operētājsistēmā Bootstrap 5 , taču joprojām ir iespējams izmantot mūsu komponentus ar jQuery. Ja Bootstrap objektā konstatē jQuery, windowtas pievienos visus mūsu komponentus jQuery spraudņu sistēmā. Tas ļauj veikt tālāk norādītās darbības.

$('[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 attiecas uz citām mūsu sastāvdaļām.

Nav konflikta

Dažreiz ir nepieciešams izmantot Bootstrap spraudņus ar citiem lietotāja interfeisa ietvariem. Šādos apstākļos dažkārt var rasties nosaukumtelpas sadursmes. Ja tā notiek, varat izsaukt .noConflictspraudni, kura vērtību vēlaties atjaunot.

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

Bootstrap does not officially support third-party JavaScript libraries like Prototype or jQuery UI. Despite .noConflict and namespaced events, there may be compatibility problems that you need to fix on your own.

jQuery events

Bootstrap will detect jQuery if jQuery is present in the window object and there is no data-bs-no-jquery attribute set on <body>. If jQuery is found, Bootstrap will emit events thanks to jQuery’s event system. So if you want to listen to Bootstrap’s events, you’ll have to use the jQuery methods (.on, .one) instead of addEventListener.

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

Disabled JavaScript

Bootstrap spraudņiem nav īpašu atkāpšanās iespēju, ja JavaScript ir atspējots. Ja jums rūp lietotāja pieredze šajā gadījumā, izmantojiet <noscript>, lai izskaidrotu situāciju (un kā atkārtoti iespējot JavaScript) saviem lietotājiem un/vai pievienojiet savus pielāgotos atkāpšanās variantus.