JavaScript

Dai vita a Bootstrap con i nostri plugin JavaScript opzionali. Scopri ogni plug-in, i nostri dati e le opzioni dell'API programmatica e altro ancora.

Su questa pagina

Individuale o compilato

I plugin possono essere inclusi individualmente (usando l'individuale di Bootstrap js/dist/*.js) o tutti in una volta usando bootstrap.jso minimizzati bootstrap.min.js(non includerli entrambi).

Se utilizzi un bundler (Webpack, Parcel, Vite...), puoi utilizzare /js/dist/*.jsfile che sono pronti per UMD.

Utilizzo con framework JavaScript

Sebbene Bootstrap CSS possa essere utilizzato con qualsiasi framework, Bootstrap JavaScript non è completamente compatibile con framework JavaScript come React, Vue e Angular che presuppongono la piena conoscenza del DOM. Sia Bootstrap che il framework possono tentare di mutare lo stesso elemento DOM, causando bug come i menu a discesa che sono bloccati nella posizione "aperta".

Un'alternativa migliore per coloro che utilizzano questo tipo di framework consiste nell'utilizzare un pacchetto specifico del framework invece del JavaScript Bootstrap. Ecco alcune delle opzioni più popolari:

Reagire: Reagire Bootstrap
Vue: BootstrapVue (attualmente supporta solo Vue 2 e Bootstrap 4)
Angolare: ng-bootstrap

Utilizzo di Bootstrap come modulo

Provate voi stessi! Scarica il codice sorgente e la demo funzionante per l'utilizzo di Bootstrap come modulo ES dal repository twbs/examples . Puoi anche aprire l'esempio in StackBlitz .

Forniamo una versione di Bootstrap costruita come ESM( bootstrap.esm.jse bootstrap.esm.min.js) che ti consente di utilizzare Bootstrap come modulo nel browser, se i browser di destinazione lo supportano .

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

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

Rispetto ai bundler JS, l'utilizzo di ESM nel browser richiede l'utilizzo del percorso completo e del nome file invece del nome del modulo. Maggiori informazioni sui moduli JS nel browser. Ecco perché usiamo 'bootstrap.esm.min.js'invece di 'bootstrap'sopra. Tuttavia, questo è ulteriormente complicato dalla nostra dipendenza Popper, che importa Popper nel nostro JavaScript in questo modo:

import * as Popper from "@popperjs/core"

Se provi così com'è, vedrai un errore nella console come il seguente:

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

Per risolvere questo problema, puoi utilizzare an importmapper risolvere i nomi dei moduli arbitrari per completare i percorsi. Se i tuoi browser di destinazione non supportano importmap, dovrai utilizzare il progetto es-module-shims . Ecco come funziona per Bootstrap e 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

Alcuni plugin e componenti CSS dipendono da altri plugin. Se includi i plug-in singolarmente, assicurati di controllare queste dipendenze nei documenti.

Anche i nostri menu a discesa, popover e suggerimenti dipendono da Popper .

Attributi dei dati

Quasi tutti i plug-in Bootstrap possono essere abilitati e configurati tramite HTML solo con attributi di dati (il nostro modo preferito di utilizzare la funzionalità JavaScript). Assicurati di utilizzare solo un set di attributi di dati su un singolo elemento (ad esempio, non puoi attivare una descrizione comando e modale dallo stesso pulsante).

Poiché le opzioni possono essere passate tramite attributi di dati o JavaScript, puoi aggiungere un nome di opzione a data-bs-, come in data-bs-animation="{value}". Assicurati di cambiare il tipo di caso del nome dell'opzione da " camelCase " a " kebab-case " quando passi le opzioni tramite attributi di dati. Ad esempio, utilizzare data-bs-custom-class="beautifier"invece di data-bs-customClass="beautifier".

A partire da Bootstrap 5.2.0, tutti i componenti supportano un attributo di dati riservato sperimentaledata-bs-config che può ospitare una semplice configurazione del componente come una stringa JSON. Quando un elemento ha data-bs-config='{"delay":0, "title":123}'e data-bs-title="456"attributi, il titlevalore finale sarà 456e gli attributi di dati separati sovrascriveranno i valori forniti su data-bs-config. Inoltre, gli attributi di dati esistenti sono in grado di ospitare valori JSON come data-bs-delay='{"show":0,"hide":150}'.

Selettori

Utilizziamo i metodi nativi querySelectore querySelectorAllper interrogare gli elementi DOM per motivi di prestazioni, quindi è necessario utilizzare selettori validi . Se usi selettori speciali come collapse:Example, assicurati di sfuggire ad essi.

Eventi

Bootstrap fornisce eventi personalizzati per le azioni uniche della maggior parte dei plugin. Generalmente, questi si presentano in una forma di participio passato e infinito, in cui l'infinito (es. show) viene attivato all'inizio di un evento e la sua forma participio passato (es. shown) viene attivata al completamento di un'azione.

Tutti gli eventi infiniti forniscono preventDefault()funzionalità. Ciò fornisce la possibilità di interrompere l'esecuzione di un'azione prima che inizi. Anche la restituzione di false da un gestore di eventi chiamerà automaticamente preventDefault().

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

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

API programmatica

Tutti i costruttori accettano un oggetto opzioni opzionale o niente (che avvia un plug-in con il suo comportamento predefinito):

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 desideri ottenere una particolare istanza di plug-in, ogni plug-in espone un getInstancemetodo. Ad esempio, per recuperare un'istanza direttamente da un elemento:

bootstrap.Popover.getInstance(myPopoverEl)

Questo metodo verrà restituito nullse un'istanza non viene avviata sull'elemento richiesto.

In alternativa, getOrCreateInstancepuò essere utilizzato per ottenere l'istanza associata a un elemento DOM o crearne uno nuovo nel caso non sia stato inizializzato.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Nel caso in cui un'istanza non sia stata inizializzata, può accettare e utilizzare un oggetto di configurazione opzionale come secondo argomento.

Selettori CSS nei costruttori

Oltre ai metodi getInstancee getOrCreateInstance, tutti i costruttori di plugin possono accettare un elemento DOM o un selettore CSS valido come primo argomento. Gli elementi del plug-in si trovano con il querySelectormetodo poiché i nostri plug-in supportano solo un singolo elemento.

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 e transizioni asincrone

Tutti i metodi dell'API programmatica sono asincroni e ritornano al chiamante una volta avviata la transizione, ma prima che termini . Per eseguire un'azione una volta completata la transizione, è possibile ascoltare l'evento corrispondente.

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

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

Inoltre, una chiamata al metodo su un componente in transizione verrà ignorata .

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

Sebbene possa sembrare corretto utilizzare il disposemetodo subito dopo hide(), porterà a risultati errati. Ecco un esempio dell'utilizzo problematico:

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

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

Impostazioni predefinite

È possibile modificare le impostazioni predefinite per un plug-in modificando l' Constructor.Defaultoggetto del plug-in:

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

Metodi e proprietà

Ogni plugin Bootstrap espone i seguenti metodi e proprietà statiche.

Metodo	Descrizione
`dispose`	Distrugge il modale di un elemento. (Rimuove i dati memorizzati sull'elemento DOM)
`getInstance`	Metodo statico che consente di ottenere l'istanza modale associata a un elemento DOM.
`getOrCreateInstance`	Metodo statico che consente di ottenere l'istanza modale associata a un elemento DOM o di crearne una nuova nel caso non sia stata inizializzata.

Proprietà statica	Descrizione
`NAME`	Restituisce il nome del plugin. (Esempio: `bootstrap.Tooltip.NAME`)
`VERSION`	È possibile accedere alla versione di ciascuno dei plug-in di Bootstrap tramite la `VERSION`proprietà del costruttore del plug-in (Esempio: `bootstrap.Tooltip.VERSION`)

Disinfettante

Tooltip e Popover utilizzano il nostro disinfettante integrato per disinfettare le opzioni che accettano HTML.

Il allowListvalore predefinito è il 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 vuoi aggiungere nuovi valori a questo valore predefinito allowListpuoi fare quanto segue:

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 vuoi bypassare il nostro igienizzante perché preferisci utilizzare una libreria dedicata, ad esempio DOMPurify , dovresti fare quanto segue:

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

Facoltativamente usando jQuery

Non è necessario jQuery in Bootstrap 5 , ma è comunque possibile utilizzare i nostri componenti con jQuery. Se Bootstrap rileva jQuerynell'oggetto window, aggiungerà tutti i nostri componenti nel sistema di plugin di jQuery. Questo ti permette di fare quanto segue:

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

Lo stesso vale per gli altri nostri componenti.

Nessun conflitto

A volte è necessario utilizzare i plug-in Bootstrap con altri framework dell'interfaccia utente. In queste circostanze, possono verificarsi occasionalmente collisioni nello spazio dei nomi. Se ciò accade, puoi richiamare .noConflictil plugin di cui desideri ripristinare il valore.

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

Bootstrap non supporta ufficialmente librerie JavaScript di terze parti come Prototype o jQuery UI. Nonostante .noConflictgli eventi con spazio dei nomi, potrebbero esserci problemi di compatibilità che è necessario risolvere da soli.

eventi jQuery

Bootstrap rileverà jQuery se jQueryè presente windownell'oggetto e non è data-bs-no-jqueryimpostato alcun attributo su <body>. Se viene trovato jQuery, Bootstrap emetterà eventi grazie al sistema di eventi di jQuery. Quindi, se vuoi ascoltare gli eventi di Bootstrap, dovrai usare i metodi jQuery ( .on, .one) invece di addEventListener.

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

JavaScript disabilitato

I plugin di Bootstrap non hanno un fallback speciale quando JavaScript è disabilitato. Se ti interessa l'esperienza dell'utente in questo caso, usa <noscript>per spiegare la situazione (e come riattivare JavaScript) ai tuoi utenti e/o aggiungi i tuoi fallback personalizzati.