Passà à u cuntenutu principale Salta à a navigazione di documenti
Check
in English

JavaScript

Portate Bootstrap in vita cù i nostri plugins JavaScript opzionali. Amparate nantu à ogni plugin, i nostri dati è opzioni di API di prugrammazione, è più.

In sta pagina

Individuali o cumpilati

I plugins ponu esse inclusi individualmente (aduprendu l'individuu di Bootstrap js/dist/*.js), o tutti in una volta usendu bootstrap.jso minificati bootstrap.min.js(ùn include micca i dui).

Sè aduprate un bundler (Webpack, Parcel, Vite...), pudete aduprà /js/dist/*.jsschedari chì sò pronti per UMD.

Utilizà cù frameworks JavaScript

Mentre chì u Bootstrap CSS pò esse usatu cù qualsiasi framework, u Bootstrap JavaScript ùn hè micca cumplettamente cumpatibile cù frameworks JavaScript cum'è React, Vue è Angular chì assumenu a cunniscenza completa di u DOM. Tramindui Bootstrap è u quadru pò pruvà à mutà u listessu elementu DOM, risultatu in bugs cum'è dropdowns chì sò chjappi in a pusizione "aperta".

Una alternativa megliu per quelli chì utilizanu stu tipu di frameworks hè di utilizà un pacchettu specificu di framework invece di Bootstrap JavaScript. Eccu alcuni di l'opzioni più populari:

Utilizà Bootstrap cum'è modulu

Pruvate voi stessu! Scaricate u codice fonte è a demo di travagliu per aduprà Bootstrap cum'è modulu ES da u repository twbs/examples . Pudete ancu apre l'esempiu in StackBlitz .

Furnemu una versione di Bootstrap custruita cum'è ESM( bootstrap.esm.jsè bootstrap.esm.min.js) chì vi permette di utilizà Bootstrap cum'è modulu in u navigatore, se i vostri navigatori destinati u supportanu .

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

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

Comparatu à i bundlers JS, l'usu di ESM in u navigatore richiede di utilizà a strada completa è u nome di u schedariu invece di u nome di u modulu. Leghjite più nantu à i moduli JS in u navigatore. Hè per quessa chì avemu usatu 'bootstrap.esm.min.js'invece di 'bootstrap'sopra. Tuttavia, questu hè più complicatu da a nostra dipendenza Popper, chì importa Popper in u nostru JavaScript cusì:

import * as Popper from "@popperjs/core"

Se pruvate questu cum'è, vi vede un errore in a cunsola cum'è u seguente:

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

Per riparà questu, pudete aduprà un importmapper risolve i nomi di moduli arbitrarii per cumplettà i percorsi. Se i vostri navigatori destinati ùn supportanu micca importmap, avete bisognu di utilizà u prughjettu es-module-shims . Eccu cumu funziona per Bootstrap è 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>

Dipendenze

Certi plugins è cumpunenti CSS dipendenu da altri plugins. Se include plugins individualmente, assicuratevi di verificà queste dipendenze in i documenti.

I nostri dropdowns, popovers è tooltips dipendenu ancu da Popper .

Attributi di dati

Quasi tutti i plugins Bootstrap ponu esse attivati ​​​​è cunfigurati cù HTML solu cù attributi di dati (u nostru modu preferitu di utilizà a funziunalità JavaScript). Assicuratevi di utilizà solu un set di attributi di dati nantu à un elementu unicu (per esempiu, ùn pudete micca attivà un tooltip è modale da u stessu buttone).

Siccomu l'opzioni ponu esse passati via attributi di dati o JavaScript, pudete appiccicà un nome d'opzione à data-bs-, cum'è in data-bs-animation="{value}". Assicuratevi di cambià u tipu di casu di u nome di l'opzione da " camelCase " à " kebab-case " quandu passanu l'opzioni via attributi di dati. Per esempiu, aduprà data-bs-custom-class="beautifier"invece di data-bs-customClass="beautifier".

A partire da Bootstrap 5.2.0, tutti i cumpunenti supportanu un attributu di dati riservatu sperimentaledata-bs-config chì pò accoglie una cunfigurazione di cumpunenti simplice cum'è una stringa JSON. Quandu un elementu hà data-bs-config='{"delay":0, "title":123}'è data-bs-title="456"attributi, u valore finali titleserà 456è l'attributi di dati separati anu da annullà i valori dati nantu à data-bs-config. Inoltre, l'attributi di dati esistenti sò capaci di allughjà valori JSON cum'è data-bs-delay='{"show":0,"hide":150}'.

Selettori

Utilizemu u nativu querySelectorè querySelectorAlli metudi per interrogà l'elementi DOM per ragioni di rendiment, cusì duvete aduprà selettori validi . Se utilizate selettori speciali cum'è collapse:Example, assicuratevi di scappà.

Avvenimenti

Bootstrap furnisce avvenimenti persunalizati per a maiò parte di l'azzioni uniche di i plugins. In generale, questi venenu in una forma di participiu infinitu è ​​passatu - induve l'infinitivu (es. show) hè attivatu à l'iniziu di un avvenimentu, è a so forma di participiu passatu (es. shown) hè attivatu à a fine di una azione.

Tutti l'avvenimenti infiniti furnisce preventDefault()funziunalità. Questu furnisce a capacità di piantà l'esekzione di un'azzione prima di principià. Riturnà falsi da un gestore di l'eventi chjamarà ancu automaticamente preventDefault().

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

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

API di prugrammazione

Tutti i custruttori accettanu un ogettu d'opzioni opzionali o nunda (chì inizia un plugin cù u so cumpurtamentu predeterminatu):

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 vulete ottene una istanza di plugin particulari, ogni plugin espone un getInstancemetudu. Per esempiu, per ricuperà una istanza direttamente da un elementu:

bootstrap.Popover.getInstance(myPopoverEl)

Stu metudu tornerà nullse una istanza ùn hè micca iniziata annantu à l'elementu dumandatu.

In alternativa, getOrCreateInstancepò esse usatu per uttene l'istanza assuciata à un elementu DOM, o creanu un novu in casu ùn hè micca inizializatu.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

In casu chì una istanza ùn hè micca inizializzata, pò accettà è aduprà un oggettu di cunfigurazione opzionale cum'è secondu argumentu.

I selettori CSS in i custruttori

In più di i metudi getInstanceè getOrCreateInstance, tutti i custruttori di plugin ponu accettà un elementu DOM o un selettore CSS validu cum'è u primu argumentu. Elementi di Plugin si trovanu cù u querySelectormetudu postu chì i nostri plugins supportanu solu un elementu unicu.

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

Funzioni asincrone è transizioni

Tutti i metudi API di prugrammazione sò asincroni è tornanu à u chjamante una volta chì a transizione hè iniziata, ma prima di finisce . Per eseguisce una azzione una volta chì a transizione hè cumpleta, pudete sente l'avvenimentu currispundente.

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

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

Inoltre, un metudu chjamatu nantu à un cumpunente di transizione serà ignoratu .

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

disposemetudu

Ancu s'ellu pò parè currettu à aduprà u disposemetudu subitu dopu hide(), purterà à risultati incorrecte. Eccu un esempiu di u prublema di usu:

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

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

Paràmetri predeterminati

Pudete cambià i paràmetri predeterminati per un plugin mudificà l' Constructor.Defaultughjettu di u plugin:

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

I metudi è proprietà

Ogni plugin Bootstrap espone i seguenti metudi è proprietà statiche.

Metudu Descrizzione
dispose Distrughje u modale di un elementu. (Elimina i dati almacenati nantu à l'elementu DOM)
getInstance Metudu staticu chì permette di ottene l'istanza modale assuciata à un elementu DOM.
getOrCreateInstance Metudu staticu chì permette di ottene l'istanza modale assuciata à un elementu DOM, o creanu un novu in casu ùn hè micca inizializatu.
Pruprietà statica Descrizzione
NAME Ritorna u nome di u plugin. (Esempiu: bootstrap.Tooltip.NAME)
VERSION A versione di ognuna di i plugins di Bootstrap pò esse accessu via a VERSIONpruprietà di u custruttore di u plugin (Esempiu: bootstrap.Tooltip.VERSION)

Sanitizer

Tooltips è Popovers utilizanu u nostru sanitizer integratu per sanitizà l'opzioni chì accettanu HTML.

allowListU valore predeterminatu hè u seguente:

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 vulete aghjunghje novi valori à questu predefinitu allowList, pudete fà e seguenti:

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 vulete sguassate u nostru disinfettante perchè preferite aduprà una biblioteca dedicata, per esempiu DOMPurify , duvete fà ciò chì segue:

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

Opcionalmente utilizendu jQuery

Ùn avete bisognu di jQuery in Bootstrap 5 , ma hè sempre pussibule di utilizà i nostri cumpunenti cù jQuery. Se Bootstrap detecta jQueryin l' windowughjettu, aghjunghje tutti i nostri cumpunenti in u sistema di plugin di jQuery. Questu permette di fà i seguenti:

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

U stessu passa per i nostri altri cumpunenti.

Nisun cunflittu

A volte hè necessariu di utilizà plugins Bootstrap cù altri frameworks UI. In queste circustanze, i collisioni di u spaziu di nomi ponu accade in ocasioni. Se questu succede, pudete chjamà .noConflictu plugin chì vulete rinvià u valore.

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

Bootstrap ùn sustene micca ufficialmente biblioteche JavaScript di terze parti cum'è Prototype o jQuery UI. Malgradu .noConflictl'avvenimenti cù spazii di nome, pò esse prublemi di cumpatibilità chì avete bisognu di riparà nantu à u vostru propiu.

Eventi jQuery

Bootstrap detecterà jQuery s'ellu jQueryhè presente in l' windowughjettu è ùn ci hè micca un data-bs-no-jqueryattributu stabilitu nantu à <body>. Se si trova jQuery, Bootstrap emetterà avvenimenti grazia à u sistema di eventi di jQuery. Allora se vulete sente l'avvenimenti di Bootstrap, avete da aduprà i metudi jQuery ( .on, .one) invece di addEventListener.

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

JavaScript disabilitatu

I plugins di Bootstrap ùn anu micca un fallback speciale quandu JavaScript hè disattivatu. Se ti interessa l'esperienza di l'utilizatori in questu casu, aduprate <noscript>per spiegà a situazione (è cumu riattivate JavaScript) à i vostri utilizatori, è / o aghjunghje i vostri propri fallbacks persunalizati.