JavaScript

Da vida a Bootstrap cos nosos complementos de JavaScript opcionais. Obtén información sobre cada complemento, as nosas opcións de datos e API programáticas e moito máis.

Nesta páxina

Individual ou compilado

Os complementos poden incluírse individualmente (usando o individual de Bootstrap js/dist/*.js), ou todos á vez usando bootstrap.jsou minificados bootstrap.min.js(non inclúa ambos).

Se usa un paquete de paquetes (Webpack, Parcel, Vite...), pode usar /js/dist/*.jsficheiros que estean preparados para UMD.

Uso con frameworks JavaScript

Aínda que o Bootstrap CSS pódese usar con calquera marco, o Bootstrap JavaScript non é totalmente compatible con marcos JavaScript como React, Vue e Angular, que asumen un coñecemento total do DOM. Tanto Bootstrap como o framework poden tentar mutar o mesmo elemento DOM, o que provoca erros como menús despregables que quedan atrapados na posición "aberto".

Unha alternativa mellor para aqueles que usan este tipo de cadros é usar un paquete específico do cadro en lugar do JavaScript de Bootstrap. Aquí tes algunhas das opcións máis populares:

Reaccionar: Reaccionar Bootstrap
Vue: BootstrapVue (actualmente só admite Vue 2 e Bootstrap 4)
Angular: ng-bootstrap

Usando Bootstrap como módulo

Probao vostede mesmo! Descarga o código fonte e a demostración de traballo para usar Bootstrap como módulo ES desde o repositorio twbs/examples . Tamén pode abrir o exemplo en StackBlitz .

Proporcionamos unha versión de Bootstrap creada como ESM( bootstrap.esm.jse bootstrap.esm.min.js) que che permite usar Bootstrap como módulo no navegador, se os teus navegadores de destino o admiten .

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

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

En comparación cos paquetes JS, o uso de ESM no navegador require que use a ruta e o nome do ficheiro completos en lugar do nome do módulo. Lea máis sobre os módulos JS no navegador. É por iso que usamos 'bootstrap.esm.min.js'en lugar do 'bootstrap'anterior. Non obstante, isto complícase aínda máis pola nosa dependencia de Popper, que importa Popper ao noso JavaScript do seguinte xeito:

import * as Popper from "@popperjs/core"

Se probas isto tal e como está, verás un erro na consola como o seguinte:

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

Para solucionar isto, pode usar un importmappara resolver os nomes de módulos arbitrarios para completar camiños. Se os teus navegadores de destino non admiten importmap, terás que utilizar o proxecto es-module-shims . Así é como funciona para 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>

Dependencias

Algúns complementos e compoñentes CSS dependen doutros complementos. Se inclúes complementos individualmente, asegúrate de comprobar estas dependencias nos documentos.

Os nosos menús despregable, popovers e informacións sobre ferramentas tamén dependen de Popper .

Atributos de datos

Case todos os complementos de Bootstrap pódense activar e configurar só mediante HTML con atributos de datos (a nosa forma preferida de usar a funcionalidade de JavaScript). Asegúrate de usar só un conxunto de atributos de datos nun único elemento (por exemplo, non podes activar unha información sobre ferramentas e un modal desde o mesmo botón).

Como as opcións se poden pasar a través de atributos de datos ou JavaScript, pode engadir un nome de opción a data-bs-, como en data-bs-animation="{value}". Asegúrate de cambiar o tipo de maiúsculas e minúsculas do nome da opción de " camelCase " a " kebab-case " ao pasar as opcións a través dos atributos de datos. Por exemplo, use data-bs-custom-class="beautifier"no canto de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos os compoñentes admiten un atributo de datos reservados experimentaisdata-bs-config que pode albergar unha configuración sinxela de compoñentes como cadea JSON. Cando un elemento ten data-bs-config='{"delay":0, "title":123}'e data-bs-title="456"atributos, o titlevalor final será 456e os atributos de datos separados anularán os valores indicados en data-bs-config. Ademais, os atributos de datos existentes poden albergar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

Selectores

Usamos os métodos nativos querySelectore querySelectorAllpara consultar elementos DOM por motivos de rendemento, polo que debes usar selectores válidos . Se usas selectores especiais como collapse:Example, asegúrate de escapar deles.

Eventos

Bootstrap ofrece eventos personalizados para as accións únicas da maioría dos complementos. Xeralmente, estes veñen nunha forma de infinitivo e de participio pasado, onde o infinitivo (ex. show) se activa ao comezo dun evento, e a súa forma de participio pasado (ex. shown) desenvólvese ao completar unha acción.

Todos os eventos de infinitivo proporcionan preventDefault()funcionalidade. Isto proporciona a capacidade de deter a execución dunha acción antes de que comece. Devolver false desde un controlador de eventos tamén chamará automaticamente a 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

Todos os construtores aceptan un obxecto de opcións opcionais ou nada (que inicia un complemento co seu comportamento predeterminado):

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 desexa obter unha instancia de complemento en particular, cada complemento expón un getInstancemétodo. Por exemplo, para recuperar unha instancia directamente dun elemento:

bootstrap.Popover.getInstance(myPopoverEl)

Este método volverá nullse non se inicia unha instancia sobre o elemento solicitado.

Alternativamente, getOrCreateInstancepódese usar para asociar a instancia cun elemento DOM ou crear un novo no caso de que non se inicializou.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

No caso de que unha instancia non fose inicializada, pode aceptar e utilizar un obxecto de configuración opcional como segundo argumento.

Selectores CSS en construtores

Ademais dos métodos getInstancee , todos os construtores de complementos poden aceptar un elemento DOM ou un selector CSS válido como primeiro argumento. Os elementos do complemento atópanse co método xa que os nosos complementos só admiten un só elemento.getOrCreateInstancequerySelector

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

Funcións asíncronas e transicións

Todos os métodos de API programáticas son asíncronos e volven ao interlocutor unha vez iniciada a transición, pero antes de que remate . Para executar unha acción unha vez completada a transición, podes escoitar o evento correspondente.

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

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

Ademais, ignorarase unha chamada de método nun compoñente en transición .

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étodo

Aínda que poida parecer correcto usar o disposemétodo inmediatamente despois hide()de , dará lugar a resultados incorrectos. Aquí tes un exemplo do uso do problema:

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

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

Configuración predeterminada

Podes cambiar a configuración predeterminada dun complemento modificando o Constructor.Defaultobxecto do complemento:

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

Métodos e propiedades

Cada complemento de Bootstrap expón os seguintes métodos e propiedades estáticas.

Método	Descrición
`dispose`	Destrúe o modal dun elemento. (Elimina os datos almacenados no elemento DOM)
`getInstance`	Método estático que permite obter a instancia modal asociada a un elemento DOM.
`getOrCreateInstance`	Método estático que permite obter a instancia modal asociada a un elemento DOM ou crear unha nova no caso de que non se inicializou.

Propiedade estática	Descrición
`NAME`	Devolve o nome do complemento. (Exemplo: `bootstrap.Tooltip.NAME`)
`VERSION`	Pódese acceder á versión de cada un dos complementos de Bootstrap a través da `VERSION`propiedade do construtor do complemento (Exemplo: `bootstrap.Tooltip.VERSION`)

Sanitizante

As informacións sobre ferramentas e popovers usan o noso desinfectante integrado para desinfectar as opcións que aceptan HTML.

O valor predeterminado allowListé o seguinte:

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 queres engadir novos valores a este valor predeterminado allowList, podes facer o seguinte:

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 queres evitar o noso desinfectante porque prefires usar unha biblioteca dedicada, por exemplo DOMPurify , debes facer o seguinte:

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

Opcionalmente usando jQuery

Non necesitas jQuery en Bootstrap 5 , pero aínda é posible usar os nosos compoñentes con jQuery. Se Bootstrap detecta jQueryo windowobxecto, engadirá todos os nosos compoñentes no sistema de complementos de jQuery. Isto permítelle facer o seguinte:

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

O mesmo ocorre cos nosos outros compoñentes.

Sen conflito

Ás veces é necesario usar complementos de Bootstrap con outros marcos de IU. Nestas circunstancias, ocasionalmente poden ocorrer colisións de espazos de nomes. Se isto ocorre, podes chamar .noConflictao complemento do que desexas reverter o valor.

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

Bootstrap non admite oficialmente bibliotecas JavaScript de terceiros como Prototype ou jQuery UI. A pesar .noConflictdos eventos separados dos nomes, pode haber problemas de compatibilidade que teñas que solucionar por ti mesmo.

eventos jQuery

Bootstrap detectará jQuery se jQueryestá presente no windowobxecto e non hai ningún data-bs-no-jqueryatributo definido en <body>. Se se atopa jQuery, Bootstrap emitirá eventos grazas ao sistema de eventos de jQuery. Polo tanto, se queres escoitar os eventos de Bootstrap, terás que usar os métodos jQuery ( .on, .one) en lugar de addEventListener.

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

JavaScript desactivado

Os complementos de Bootstrap non teñen unha alternativa especial cando JavaScript está desactivado. Se che importa a experiencia do usuario neste caso, úsao <noscript>para explicar a situación (e como volver activar JavaScript) aos teus usuarios e/ou engade as túas propias opcións de reserva personalizadas.