in English

JavaScript

Dați viață Bootstrap-ului cu pluginurile noastre opționale JavaScript. Aflați despre fiecare plugin, despre opțiunile noastre de date și API programatice și multe altele.

Pe aceasta pagina

Individual sau compilat

Pluginurile pot fi incluse individual (folosind individualul Bootstrap js/dist/*.js) sau toate odată folosind bootstrap.jssau diminuate bootstrap.min.js(nu le includeți pe ambele).

Dacă utilizați un bundler (Webpack, Parcel, Vite...), puteți utiliza /js/dist/*.jsfișiere care sunt gata UMD.

Utilizare cu cadre JavaScript

În timp ce Bootstrap CSS poate fi folosit cu orice cadru, Bootstrap JavaScript nu este pe deplin compatibil cu framework-urile JavaScript precum React, Vue și Angular, care presupun cunoștințe complete despre DOM. Atât Bootstrap, cât și cadrul pot încerca să modifice același element DOM, rezultând erori precum meniurile derulante care sunt blocate în poziția „deschisă”.

O alternativă mai bună pentru cei care folosesc acest tip de cadre este să folosească un pachet specific cadrului în loc de JavaScript Bootstrap. Iată câteva dintre cele mai populare opțiuni:

Reacționează: Reacționează Bootstrap
Vue: BootstrapVue (în prezent acceptă doar Vue 2 și Bootstrap 4)
Angular: ng-bootstrap

Folosind Bootstrap ca modul

Incearca-l tu insuti! Descărcați codul sursă și demonstrația de lucru pentru utilizarea Bootstrap ca modul ES din depozitul twbs/examples . De asemenea, puteți deschide exemplul în StackBlitz .

Oferim o versiune de Bootstrap construită ca ESM( bootstrap.esm.jsși bootstrap.esm.min.js) care vă permite să utilizați Bootstrap ca modul în browser, dacă browserele vizate îl acceptă .

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

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

În comparație cu pachetele JS, utilizarea ESM în browser necesită să utilizați calea completă și numele fișierului în loc de numele modulului. Citiți mai multe despre modulele JS în browser. De aceea folosim 'bootstrap.esm.min.js'în loc de 'bootstrap'mai sus. Cu toate acestea, acest lucru este complicat și mai mult de dependența noastră Popper, care importă Popper în JavaScript astfel:

import * as Popper from "@popperjs/core"

Dacă încercați acest lucru așa cum este, veți vedea o eroare în consolă precum următoarea:

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

Pentru a remedia acest lucru, puteți utiliza un importmappentru a rezolva numele de module arbitrare pentru a finaliza căile. Dacă browserele vizate nu acceptă importmap, va trebui să utilizați proiectul es-module-shims . Iată cum funcționează pentru Bootstrap și 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>

Dependente

Unele plugin-uri și componente CSS depind de alte plugin-uri. Dacă includeți pluginuri individual, asigurați-vă că verificați aceste dependențe în documente.

Mențiunile derulante, popover-urile și sfaturile noastre de instrumente depind și de Popper .

Atributele datelor

Aproape toate pluginurile Bootstrap pot fi activate și configurate numai prin HTML cu atribute de date (modul nostru preferat de a folosi funcționalitatea JavaScript). Asigurați-vă că utilizați un singur set de atribute de date pe un singur element (de exemplu, nu puteți declanșa un balon explicativ și un modal de pe același buton.)

Deoarece opțiunile pot fi transmise prin atribute de date sau JavaScript, puteți adăuga un nume de opțiune la data-bs-, ca în data-bs-animation="{value}". Asigurați-vă că schimbați tipul de caz al numelui opțiunii din „ camelCase ” în „ kebab-case ” atunci când treceți opțiunile prin atributele de date. De exemplu, utilizați data-bs-custom-class="beautifier"în loc de data-bs-customClass="beautifier".

Începând cu Bootstrap 5.2.0, toate componentele acceptă un atribut de date rezervat experimentaldata-bs-config care poate găzdui configurarea simplă a componentelor ca șir JSON. Când un element are data-bs-config='{"delay":0, "title":123}'și data-bs-title="456"atribute, valoarea finală titleva fi 456și atributele de date separate vor înlocui valorile date pe data-bs-config. În plus, atributele de date existente pot găzdui valori JSON precum data-bs-delay='{"show":0,"hide":150}'.

Selectoare

Folosim metodele native querySelectorși querySelectorAllpentru a interoga elementele DOM din motive de performanță, așa că trebuie să utilizați selectoare valide . Dacă utilizați selectoare speciale precum collapse:Example, asigurați-vă că le scăpați.

Evenimente

Bootstrap oferă evenimente personalizate pentru acțiunile unice ale majorității pluginurilor. În general, acestea vin într-o formă de infinitiv și participiu trecut - unde infinitivul (ex. show) este declanșat la începutul unui eveniment, iar forma sa de participiu trecut (ex. shown) este declanșat la finalizarea unei acțiuni.

Toate evenimentele infinitive oferă preventDefault()funcționalitate. Aceasta oferă posibilitatea de a opri execuția unei acțiuni înainte de a începe. Întoarcerea false de la un handler de evenimente va apela automat și preventDefault().

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

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

API-ul programatic

Toți constructorii acceptă un obiect opțional opțional sau nimic (care inițiază un plugin cu comportamentul său implicit):

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

Dacă doriți să obțineți o anumită instanță de plugin, fiecare plugin expune o getInstancemetodă. De exemplu, pentru a prelua o instanță direct dintr-un element:

bootstrap.Popover.getInstance(myPopoverEl)

Această metodă va reveni nulldacă o instanță nu este inițiată peste elementul solicitat.

Alternativ, getOrCreateInstancepoate fi folosit pentru a obține instanța asociată cu un element DOM sau pentru a crea unul nou în cazul în care nu a fost inițializat.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

În cazul în care o instanță nu a fost inițializată, aceasta poate accepta și utiliza un obiect de configurare opțional ca al doilea argument.

Selectori CSS în constructori

În plus față de metodele getInstanceși getOrCreateInstance, toți constructorii de pluginuri pot accepta un element DOM sau un selector CSS valid ca prim argument. Elementele de plugin sunt găsite cu querySelectormetoda, deoarece pluginurile noastre acceptă doar un singur 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')

Funcții și tranziții asincrone

Toate metodele API programatice sunt asincrone și revin la apelant odată ce tranziția este începută, dar înainte ca aceasta să se încheie . Pentru a executa o acțiune odată ce tranziția este finalizată, puteți asculta evenimentul corespunzător.

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

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

În plus, un apel de metodă pentru o componentă de tranziție va fi ignorat .

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`metodă

Deși poate părea corect să utilizați disposemetoda imediat după hide(), aceasta va duce la rezultate incorecte. Iată un exemplu de utilizare a problemei:

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

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

Setări implicite

Puteți modifica setările implicite pentru un plugin modificând obiectul pluginului Constructor.Default:

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

Metode și proprietăți

Fiecare plugin Bootstrap expune următoarele metode și proprietăți statice.

Metodă	Descriere
`dispose`	Distruge modalul unui element. (Elimină datele stocate pe elementul DOM)
`getInstance`	Metodă statică care vă permite să obțineți instanța modală asociată cu un element DOM.
`getOrCreateInstance`	Metodă statică care vă permite să obțineți instanța modală asociată cu un element DOM sau să creați una nouă în cazul în care nu a fost inițializată.

Proprietate statică	Descriere
`NAME`	Returnează numele pluginului. (Exemplu: `bootstrap.Tooltip.NAME`)
`VERSION`	Versiunea fiecărui plugin Bootstrap poate fi accesată prin `VERSION`proprietatea constructorului pluginului (Exemplu: `bootstrap.Tooltip.VERSION`)

Dezinfectant

Sfaturile cu instrumente și popoverele folosesc dezinfectantul nostru încorporat pentru a dezinfecta opțiunile care acceptă HTML.

Valoarea implicită allowListeste următoarea:

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

Dacă doriți să adăugați noi valori la această valoare implicită allowList, puteți face următoarele:

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)

Dacă doriți să ocoliți dezinfectantul nostru deoarece preferați să utilizați o bibliotecă dedicată, de exemplu DOMPurify , ar trebui să faceți următoarele:

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

Opțional folosind jQuery

Nu aveți nevoie de jQuery în Bootstrap 5 , dar este totuși posibil să folosiți componentele noastre cu jQuery. Dacă Bootstrap detectează jQueryobiectul window, va adăuga toate componentele noastre în sistemul de pluginuri jQuery. Acest lucru vă permite să faceți următoarele:

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

Același lucru este valabil și pentru celelalte componente ale noastre.

Fără conflict

Uneori este necesar să utilizați pluginuri Bootstrap cu alte cadre UI. În aceste circumstanțe, pot apărea ocazional coliziuni ale spațiului de nume. Dacă se întâmplă acest lucru, puteți apela .noConflictla pluginul căruia doriți să reveniți la valoarea.

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

Bootstrap nu acceptă oficial biblioteci JavaScript terță parte, cum ar fi Prototype sau jQuery UI. În ciuda .noConflictevenimentelor cu spații de nume, pot exista probleme de compatibilitate pe care trebuie să le rezolvați singur.

evenimente jQuery

Bootstrap va detecta jQuery dacă jQueryeste prezent în windowobiect și nu există niciun data-bs-no-jqueryatribut setat pe <body>. Dacă se găsește jQuery, Bootstrap va emite evenimente datorită sistemului de evenimente jQuery. Deci, dacă doriți să ascultați evenimentele Bootstrap, va trebui să utilizați metodele jQuery ( .on, .one) în loc de addEventListener.

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

JavaScript a fost dezactivat

Pluginurile Bootstrap nu au o rezervă specială atunci când JavaScript este dezactivat. Dacă vă pasă de experiența utilizatorului în acest caz, folosiți <noscript>pentru a explica situația (și cum să reactivați JavaScript) utilizatorilor dvs. și/sau adăugați propriile alternative personalizate.