in English

JavaScript

Dale vida a Bootstrap con nuestros complementos de JavaScript opcionales. Obtenga información sobre cada complemento, nuestras opciones de API programáticas y de datos, y más.

En esta página

Individual o compilado

Los complementos se pueden incluir individualmente (usando el individual de Bootstrap js/dist/*.js), o todos a la vez usando bootstrap.jso minified bootstrap.min.js(no incluya ambos).

Si usa un paquete (Webpack, Parcel, Vite...), puede usar /js/dist/*.jsarchivos que estén preparados para UMD.

Uso con marcos de JavaScript

Si bien Bootstrap CSS se puede usar con cualquier marco, Bootstrap JavaScript no es totalmente compatible con marcos de JavaScript como React, Vue y Angular, que asumen un conocimiento completo del DOM. Tanto Bootstrap como el marco pueden intentar mutar el mismo elemento DOM, lo que genera errores como menús desplegables que se atascan en la posición "abierta".

Una mejor alternativa para aquellos que usan este tipo de marcos es usar un paquete específico del marco en lugar de Bootstrap JavaScript. Estas son algunas de las opciones más populares:

Reaccionar: Reaccionar Bootstrap
Vue: BootstrapVue (actualmente solo es compatible con Vue 2 y Bootstrap 4)
Angular: ng-bootstrap

Usando Bootstrap como un módulo

¡Inténtalo tú mismo! Descargue el código fuente y la demostración de trabajo para usar Bootstrap como un módulo ES del repositorio twbs/examples . También puede abrir el ejemplo en StackBlitz .

Proporcionamos una versión de Bootstrap creada como ESM( bootstrap.esm.jsy bootstrap.esm.min.js) que le permite usar Bootstrap como un módulo en el navegador, si sus navegadores específicos lo 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 con los paquetes de JS, el uso de ESM en el navegador requiere que use la ruta completa y el nombre de archivo en lugar del nombre del módulo. Lea más sobre los módulos JS en el navegador. Es por eso que usamos 'bootstrap.esm.min.js'en lugar de 'bootstrap'arriba. Sin embargo, esto se complica aún más por nuestra dependencia de Popper, que importa Popper a nuestro JavaScript de la siguiente manera:

import * as Popper from "@popperjs/core"

Si intenta esto tal como está, verá un error en la consola como el siguiente:

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

Para solucionar esto, puede usar an importmappara resolver los nombres de módulos arbitrarios para completar las rutas. Si sus navegadores objetivo no son compatibles importmap, deberá usar el proyecto es-module-shims . Así es como funciona para Bootstrap y 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

Algunos complementos y componentes CSS dependen de otros complementos. Si incluye plugins individualmente, asegúrese de comprobar si existen estas dependencias en los documentos.

Nuestros menús desplegables, popovers e información sobre herramientas también dependen de Popper .

Atributos de datos

Casi todos los complementos de Bootstrap se pueden habilitar y configurar solo a través de HTML con atributos de datos (nuestra forma preferida de usar la funcionalidad de JavaScript). Asegúrese de usar solo un conjunto de atributos de datos en un solo elemento (por ejemplo, no puede activar una información sobre herramientas y un modal desde el mismo botón).

Como las opciones se pueden pasar a través de atributos de datos o JavaScript, puede agregar un nombre de opción a data-bs-, como en data-bs-animation="{value}". Asegúrese de cambiar el tipo de caso del nombre de la opción de " camelCase " a " kebab-case " al pasar las opciones a través de atributos de datos. Por ejemplo, use data-bs-custom-class="beautifier"en lugar de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos los componentes admiten un atributo de datos reservados experimentaldata-bs-config que puede albergar una configuración de componente simple como una cadena JSON. Cuando un elemento tiene atributos data-bs-config='{"delay":0, "title":123}'y , el valor final será y los atributos de datos separados anularán los valores dados en . Además, los atributos de datos existentes pueden albergar valores JSON como .data-bs-title="456"title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

Selectores

Usamos los métodos nativos querySelectory querySelectorAllpara consultar elementos DOM por razones de rendimiento, por lo que debe usar selectores válidos . Si usa selectores especiales como collapse:Example, asegúrese de escaparlos.

Eventos

Bootstrap proporciona eventos personalizados para la mayoría de las acciones únicas de los complementos. Por lo general, estos vienen en forma de infinitivo y participio pasado, donde el infinitivo (p. ej. show) se activa al comienzo de un evento y su forma de participio pasado (p. ej. shown) se activa al completar una acción.

Todos los eventos de infinitivo proporcionan preventDefault()funcionalidad. Esto proporciona la capacidad de detener la ejecución de una acción antes de que comience. Devolver falso desde un controlador de eventos también llamará automáticamente 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 los constructores aceptan un objeto de opciones opcionales o nada (que inicia un complemento con su comportamiento 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

Si desea obtener una instancia de complemento en particular, cada complemento expone un getInstancemétodo. Por ejemplo, para recuperar una instancia directamente de un elemento:

bootstrap.Popover.getInstance(myPopoverEl)

Este método regresará nullsi no se inicia una instancia sobre el elemento solicitado.

Alternativamente, getOrCreateInstancese puede usar para asociar la instancia con un elemento DOM, o crear uno nuevo en caso de que no se haya inicializado.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

En caso de que una instancia no se haya inicializado, puede aceptar y usar un objeto de configuración opcional como segundo argumento.

Selectores CSS en constructores

Además de los métodos getInstancey getOrCreateInstance, todos los constructores de complementos pueden aceptar un elemento DOM o un selector CSS válido como primer argumento. Los elementos del complemento se encuentran con el querySelectormétodo, ya que nuestros complementos solo admiten un único 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')

Funciones asíncronas y transiciones

Todos los métodos programáticos de la API son asincrónicos y regresan a la persona que llama una vez que se inicia la transición, pero antes de que finalice . Para ejecutar una acción una vez completada la transición, puede escuchar el evento correspondiente.

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

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

Además, se ignorará una llamada de método en un componente 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

Si bien puede parecer correcto usar el disposemétodo inmediatamente después hide()de , dará lugar a resultados incorrectos. He aquí un ejemplo del problema de uso:

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

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

Configuración por defecto

Puede cambiar la configuración predeterminada de un complemento modificando el Constructor.Defaultobjeto del complemento:

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

Métodos y propiedades

Cada complemento de Bootstrap expone los siguientes métodos y propiedades estáticas.

Método	Descripción
`dispose`	Destruye el modal de un elemento. (Elimina los datos almacenados en el elemento DOM)
`getInstance`	Método estático que le permite obtener la instancia modal asociada con un elemento DOM.
`getOrCreateInstance`	Método estático que le permite obtener la instancia modal asociada con un elemento DOM, o crear una nueva en caso de que no se haya inicializado.

propiedad estática	Descripción
`NAME`	Devuelve el nombre del complemento. (Ejemplo: `bootstrap.Tooltip.NAME`)
`VERSION`	Se puede acceder a la versión de cada uno de los complementos de Bootstrap a través de la `VERSION`propiedad del constructor del complemento (Ejemplo `bootstrap.Tooltip.VERSION`:)

Desinfectante

La información sobre herramientas y las ventanas emergentes utilizan nuestro desinfectante incorporado para desinfectar las opciones que aceptan HTML.

El valor predeterminado allowListes el siguiente:

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 desea agregar nuevos valores a este valor predeterminado allowList, puede hacer lo siguiente:

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 desea omitir nuestro desinfectante porque prefiere usar una biblioteca dedicada, por ejemplo , DOMPurify , debe hacer lo siguiente:

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

Opcionalmente usando jQuery

No necesita jQuery en Bootstrap 5 , pero aún es posible usar nuestros componentes con jQuery. Si Bootstrap detecta jQueryen el windowobjeto, agregará todos nuestros componentes en el sistema de complementos de jQuery. Esto le permite hacer lo siguiente:

$('[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 mismo ocurre con nuestros otros componentes.

No conflicto

A veces es necesario usar complementos de Bootstrap con otros marcos de interfaz de usuario. En estas circunstancias, ocasionalmente pueden ocurrir colisiones de espacios de nombres. Si esto sucede, puede llamar .noConflictal complemento cuyo valor desea revertir.

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

Bootstrap no admite oficialmente bibliotecas de JavaScript de terceros como Prototype o jQuery UI. A pesar .noConflictde los eventos con espacio de nombres, puede haber problemas de compatibilidad que deba solucionar por su cuenta.

eventos de jQuery

Bootstrap detectará jQuery si jQueryestá presente en el windowobjeto y no hay ningún data-bs-no-jqueryatributo establecido en <body>. Si se encuentra jQuery, Bootstrap emitirá eventos gracias al sistema de eventos de jQuery. Entonces, si desea escuchar los eventos de Bootstrap, deberá usar los métodos jQuery ( .on, .one) en lugar de addEventListener.

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

JavaScript deshabilitado

Los complementos de Bootstrap no tienen un respaldo especial cuando JavaScript está deshabilitado. Si le preocupa la experiencia del usuario en este caso, utilice <noscript>para explicar la situación (y cómo volver a habilitar JavaScript) a sus usuarios y/o agregue sus propios recursos alternativos personalizados.