in English

JavaScript

Doneu vida a Bootstrap amb els nostres connectors opcionals de JavaScript. Obteniu informació sobre cada connector, les nostres opcions de dades i API programàtiques i molt més.

En aquesta pàgina

Individual o compilat

Els connectors es poden incloure individualment (utilitzant l'individu de Bootstrap js/dist/*.js), o tots alhora utilitzant bootstrap.jso minificats bootstrap.min.js(no incloure tots dos).

Si utilitzeu un bundler (Webpack, Parcel, Vite...), podeu utilitzar /js/dist/*.jsfitxers que estiguin preparats per UMD.

Ús amb marcs JavaScript

Tot i que el CSS Bootstrap es pot utilitzar amb qualsevol marc, el JavaScript Bootstrap no és totalment compatible amb marcs JavaScript com React, Vue i Angular, que assumeixen un coneixement total del DOM. Tant Bootstrap com el marc poden intentar mutar el mateix element DOM, donant lloc a errors com ara menús desplegables que queden enganxats a la posició "oberta".

Una millor alternativa per a aquells que utilitzen aquest tipus de marcs és utilitzar un paquet específic del marc en lloc del JavaScript Bootstrap. Aquestes són algunes de les opcions més populars:

Reaccionar: reaccionar Bootstrap
Vue: BootstrapVue (actualment només admet Vue 2 i Bootstrap 4)
Angular: ng-bootstrap

Utilitzant Bootstrap com a mòdul

Prova-ho tu mateix! Baixeu el codi font i la demostració de treball per utilitzar Bootstrap com a mòdul ES des del repositori twbs/examples . També podeu obrir l'exemple a StackBlitz .

Oferim una versió de Bootstrap creada com ESM( bootstrap.esm.jsi bootstrap.esm.min.js) que us permet utilitzar Bootstrap com a mòdul al navegador, si els vostres navegadors de destinació ho admeten .

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

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

En comparació amb els paquets JS, utilitzar ESM al navegador requereix que utilitzeu el camí complet i el nom del fitxer en lloc del nom del mòdul. Llegiu més sobre els mòduls JS al navegador. Per això fem servir 'bootstrap.esm.min.js'en comptes de l' 'bootstrap'anterior. Tanmateix, això es complica encara més per la nostra dependència de Popper, que importa Popper al nostre JavaScript així:

import * as Popper from "@popperjs/core"

Si proveu això tal com és, veureu un error a la consola com el següent:

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

Per solucionar-ho, podeu utilitzar un importmapper resoldre els noms de mòduls arbitraris per completar els camins. Si els vostres navegadors de destinació no admeten importmap, haureu d'utilitzar el projecte es-module-shims . A continuació es mostra com funciona amb 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>

Dependències

Alguns connectors i components CSS depenen d'altres connectors. Si incloeu connectors individualment, assegureu-vos de comprovar aquestes dependències als documents.

Els nostres menús desplegables, finestres emergents i informació sobre eines també depenen de Popper .

Atributs de dades

Gairebé tots els connectors Bootstrap es poden habilitar i configurar només mitjançant HTML amb atributs de dades (la nostra manera preferida d'utilitzar la funcionalitat de JavaScript). Assegureu-vos d' utilitzar només un conjunt d'atributs de dades en un sol element (p. ex., no podeu activar una informació sobre eines i un modal des del mateix botó).

Com que les opcions es poden passar mitjançant atributs de dades o JavaScript, podeu afegir un nom d'opció a data-bs-, com a data-bs-animation="{value}". Assegureu-vos de canviar el tipus de cas del nom de l'opció de " camelCase " a " kebab-case " quan passeu les opcions mitjançant atributs de dades. Per exemple, utilitzeu data-bs-custom-class="beautifier"en comptes de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, tots els components admeten un atribut de dades reservades experimentalsdata-bs-config que pot albergar una configuració senzilla de components com a cadena JSON. Quan un element té data-bs-config='{"delay":0, "title":123}'i data-bs-title="456"atributs, el titlevalor final serà 456i els atributs de dades independents substituiran els valors donats a data-bs-config. A més, els atributs de dades existents poden albergar valors JSON com data-bs-delay='{"show":0,"hide":150}'.

Selectors

Utilitzem els mètodes natius querySelectori querySelectorAllper consultar elements DOM per motius de rendiment, de manera que heu d'utilitzar selectors vàlids . Si feu servir selectors especials com ara collapse:Example, assegureu-vos d'escapar-los.

Esdeveniments

Bootstrap ofereix esdeveniments personalitzats per a les accions úniques de la majoria dels connectors. Generalment, aquests es presenten en una forma d'infinitiu i de participi passat, on l'infinitiu (p. ex. show) s'activa a l'inici d'un esdeveniment i la seva forma de participi passat (p. ex. shown) s'activa en finalitzar una acció.

Tots els esdeveniments infinitius proporcionen preventDefault()funcionalitat. Això proporciona la possibilitat d'aturar l'execució d'una acció abans que comenci. Si retorneu false des d'un controlador d'esdeveniments, també es trucarà automàticament preventDefault().

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

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

API programàtica

Tots els constructors accepten un objecte d'opcions opcionals o res (que inicia un connector amb el seu comportament per defecte):

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

Si voleu obtenir una instància de connector concreta, cada connector exposa un getInstancemètode. Per exemple, per recuperar una instància directament d'un element:

bootstrap.Popover.getInstance(myPopoverEl)

Aquest mètode tornarà nullsi no s'inicia una instància sobre l'element sol·licitat.

Alternativament, getOrCreateInstancees pot utilitzar per obtenir la instància associada a un element DOM o crear-ne una de nova en cas que no s'hagi inicialitzat.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

En cas que una instància no s'hagi inicialitzat, pot acceptar i utilitzar un objecte de configuració opcional com a segon argument.

Selectors CSS en constructors

A més dels mètodes getInstancei getOrCreateInstance, tots els constructors de connectors poden acceptar un element DOM o un selector CSS vàlid com a primer argument. Els elements del connector es troben amb el querySelectormètode, ja que els nostres connectors només admeten un sol 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')

Funcions asíncrones i transicions

Tots els mètodes de l'API programàtica són asíncrons i tornen a la persona que truca un cop s'inicia la transició, però abans que acabi . Per executar una acció un cop finalitzada la transició, podeu escoltar l'esdeveniment corresponent.

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

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

A més, s'ignorarà una trucada de mètode en un component en transició .

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`mètode

Tot i que pot semblar correcte utilitzar el disposemètode immediatament després hide()de , donarà resultats incorrectes. Aquí teniu un exemple de l'ús del problema:

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

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

Configuració per defecte

Podeu canviar la configuració predeterminada d'un connector modificant l' Constructor.Defaultobjecte del connector:

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

Mètodes i propietats

Cada connector Bootstrap exposa els següents mètodes i propietats estàtiques.

Mètode	Descripció
`dispose`	Destrueix el modal d'un element. (Elimina les dades emmagatzemades a l'element DOM)
`getInstance`	Mètode estàtic que permet obtenir la instància modal associada a un element DOM.
`getOrCreateInstance`	Mètode estàtic que us permet obtenir la instància modal associada a un element DOM o crear-ne una de nova en cas que no s'hagi inicialitzat.

Propietat estàtica	Descripció
`NAME`	Retorna el nom del connector. (Exemple: `bootstrap.Tooltip.NAME`)
`VERSION`	Es pot accedir a la versió de cadascun dels connectors de Bootstrap mitjançant la `VERSION`propietat del constructor del connector (Exemple: `bootstrap.Tooltip.VERSION`)

Desinfectant

Els consells sobre eines i les finestres emergents utilitzen el nostre desinfectador integrat per desinfectar les opcions que accepten HTML.

El valor per defecte allowListés el següent:

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

Si voleu afegir nous valors a aquest valor predeterminat allowList, podeu fer el següent:

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)

Si voleu evitar el nostre desinfectant perquè preferiu utilitzar una biblioteca dedicada, per exemple DOMPurify , hauríeu de fer el següent:

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

Opcionalment utilitzant jQuery

No necessiteu jQuery a Bootstrap 5 , però encara és possible utilitzar els nostres components amb jQuery. Si Bootstrap detecta jQueryl' windowobjecte, afegirà tots els nostres components al sistema de connectors de jQuery. Això us permet fer el següent:

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

El mateix passa amb els nostres altres components.

Cap conflicte

De vegades és necessari utilitzar connectors Bootstrap amb altres marcs d'interfície d'usuari. En aquestes circumstàncies, ocasionalment es poden produir col·lisions d'espais de noms. Si això passa, podeu trucar .noConflictal connector del qual voleu revertir el valor.

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

Bootstrap no admet oficialment biblioteques JavaScript de tercers com Prototype o jQuery UI. Malgrat .noConflictels esdeveniments amb espai de noms, és possible que hi hagi problemes de compatibilitat que hàgiu de solucionar pel vostre compte.

Esdeveniments jQuery

Bootstrap detectarà jQuery si jQueryestà present a l' windowobjecte i no hi ha cap data-bs-no-jqueryatribut establert a <body>. Si es troba jQuery, Bootstrap emetrà esdeveniments gràcies al sistema d'esdeveniments de jQuery. Per tant, si voleu escoltar els esdeveniments de Bootstrap, haureu d'utilitzar els mètodes jQuery ( .on, .one) en comptes de addEventListener.

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

JavaScript desactivat

Els connectors de Bootstrap no tenen una alternativa especial quan JavaScript està desactivat. Si t'importa l'experiència de l'usuari en aquest cas, fes servir <noscript>per explicar la situació (i com tornar a activar JavaScript) als teus usuaris i/o afegir les teves pròpies alternatives personalitzades.