Bootstrap 5.3: Plugins de Javascript, APIs y más

por

Da vida a Bootstrap con nuestros plugins de JavaScript opcionales. Aprende sobre cada plugin, nuestras opciones de API de datos y programática, y más.

Individual o compilado

Los plugins pueden incluirse individualmente (usando los archivos individuales js/dist/*.js de Bootstrap) o todos a la vez usando bootstrap.js o la versión minificada bootstrap.min.js (no incluyas ambos).

Si usas un empaquetador (Webpack, Parcel, Vite) puedes usar los archivos /JS/DIST/*.JS que están listos para UMD.

Uso con frameworks de JavaScript

Aunque el CSS de Bootstrap puede usarse con cualquier framework, el JavaScript de Bootstrap no es completamente compatible con frameworks de JavaScript como React, Vue y Angular que asumen conocimiento completo del DOM.

Tanto Bootstrap como el framework pueden intentar mutar el mismo elemento del DOM, resultando en errores como dropdowns que se quedan atascados en la posición «abierto».

Una mejor alternativa para aquellos que usan este tipo de frameworks es usar un paquete específico del framework en lugar de el JavaScript de Bootstrap.

Aquí están algunas de las opciones más populares:

Usando Bootstrap como módulo

¡Pruébalo tú mismo! Descarga el código fuente y la demostración funcional para usar Bootstrap como un módulo ES desde el repositorio twbs/examples.

También puedes abrir el ejemplo en StackBlitz.

Proporcionamos una versión de Bootstrap construida como ESM (bootstrap.esm.js y bootstrap.esm.min.js) que te permite usar Bootstrap como un módulo en el navegador, si tus navegadores objetivo lo soportan.

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

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

Comparado con los empaquetadores JS, usar ESM en el navegador requiere que uses la ruta completa y el nombre del archivo en lugar del nombre del módulo. Lee más sobre módulos JS en el navegador..

Por eso usamos 'bootstrap.esm.min.js' en lugar de 'bootstrap' arriba. Aunque esto se complica más por nuestra dependencia de Popper, que importa Popper en nuestro JavaScript así:

import * as Popper from "@popperjs/core"

Si intentas esto tal como está, verás 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 arreglar esto, puedes usar un importmap para resolver los nombres de módulos arbitrarios a rutas completas.

Si tus navegadores objetivo no soportan importmap, necesitarás 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/bootstrap@5.3.6/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-4Q6Gf2aSP4eDXB8Miphtr37CMZZQ5oXLH2yaXMJ2w8e2ZtHTl7GptT4jmndRuHDT" crossorigin="anonymous">
    <title>Hello, modularity!</title>
  </head>
  <body>
    <h1>Hello, modularity!</h1>
    <button id="popoverButton" type="button" class="btn btn-primary btn-lg" 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/core@2.11.8/dist/esm/popper.min.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/bootstrap@5.3.6/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 plugins y componentes CSS dependen de otros plugins. Si incluyes plugins individualmente, asegúrate de verificar estas dependencias en la documentación.

Nuestros dropdowns, popovers y tooltips también dependen de Popper.

Atributos de datos

Casi todos los plugins de Bootstrap pueden habilitarse y configurarse solo a través de HTML con atributos de datos (nuestra forma preferida de usar la funcionalidad JavaScript).

Asegúrate de usar solo un conjunto de atributos de datos en un solo elemento (por ejemplo, no puedes activar un tooltip y un modal desde el mismo botón.)

Como las opciones pueden pasarse a través de atributos de datos o JavaScript, puedes agregar un nombre de opción a data-bs-, como en data-bs-animation="{value}".

Asegúrate de cambiar el tipo de caso del nombre de la opción de «camelCase» a «kebab-case» cuando pases las opciones a través de atributos de datos.

Por ejemplo, usa data-bs-custom-class="beautifier" en lugar de data-bs-customClass="beautifier".

A partir de Bootstrap 5.2.0, todos los componentes soportan un atributo de datos reservado experimental data-bs-config que puede albergar configuración simple de componentes como una cadena JSON.

Cuando un elemento tiene atributos data-bs-config='{"delay":0, "title":123}' y data-bs-title="456", el valor final de title será 456 y los atributos de datos separados anularán los valores dados en data-bs-config.

Además, los atributos de datos existentes pueden albergar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

El objeto de configuración final es el resultado fusionado de data-bs-config, data-bs- y js object donde el último par clave-valor dado anula a los otros.

Selectores

Usamos los métodos nativos querySelector y querySelectorAll para consultar elementos del DOM por razones de rendimiento, así que debes usar selectores válidos.

Si usas selectores especiales como collapse:Example, asegúrate de escaparlos.

Eventos

Bootstrap proporciona eventos personalizados para las acciones únicas de la mayoría de los plugins.

Generalmente, estos vienen en forma infinitiva y participio pasado – donde el infinitivo (ej. show) se activa al inicio de un evento, y su forma de participio pasado (ej. shown) se activa al completarse una acción.

Todos los eventos infinitivos proporcionan funcionalidad preventDefault(). Esto proporciona la capacidad de detener la ejecución de una acción antes de que comience.

Devolver false desde un manejador de eventos también llamará automáticamente a preventDefault().

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

myModal.addEventListener('show.bs.modal', event => {
  return event.preventDefault() // evita que se muestre el modal
})

API Programática

Todos los constructores aceptan un objeto de opciones opcional o nada (lo que inicia un plugin con su comportamiento predeterminado):

const myModalEl = document.querySelector('#myModal')
const modal = new bootstrap.Modal(myModalEl) // inicializado con valores predeterminados

const configObject = { keyboard: false }
const modal1 = new bootstrap.Modal(myModalEl, configObject) // inicializado sin teclado

Si quisieras obtener una instancia particular de plugin, cada plugin expone un método getInstance. Por ejemplo, para recuperar una instancia directamente desde un elemento:

bootstrap.Popover.getInstance(myPopoverEl)

Este método devolverá null si no se inicia una instancia sobre el elemento solicitado.

Alternativamente, getOrCreateInstance puede usarse para obtener la instancia asociada con un elemento DOM, o crear una nueva en caso de que no haya sido inicializada.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

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

Selectores CSS en constructores

Además de los métodos getInstance y getOrCreateInstance, todos los constructores de plugins pueden aceptar un elemento DOM o un selector CSS válido como primer argumento.

Los elementos de plugin se encuentran con el método querySelector ya que nuestros plugins solo soportan un solo 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 de API programática son asíncronos y regresan al llamador una vez que la transición ha comenzado, pero antes de que termine. Para ejecutar una acción una vez que la transición esté completa, puedes escuchar el evento correspondiente.

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

myCollapseEl.addEventListener('shown.bs.collapse', event => {
  // Acción a ejecutar una vez que el área colapsable esté expandida
})

Además, una llamada de método en un componente en transición será ignorada.

const myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Recuperar una instancia de Carousel

myCarouselEl.addEventListener('slid.bs.carousel', event => {
  carousel.to('2') // Se deslizará a la diapositiva 2 tan pronto como termine la transición a la diapositiva 1
})

carousel.to('1') // Comenzará a deslizarse a la diapositiva 1 y regresará al llamador
carousel.to('2') // !! Será ignorado, ya que la transición a la diapositiva 1 no ha terminado !!

Método DISPOSE

Aunque puede parecer correcto usar el método dispose inmediatamente después de hide() llevará a resultados incorrectos. Aquí hay un ejemplo del uso problemático:

const myModal = document.querySelector('#myModal')
myModal.hide() // es asíncrono

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

Configuraciones predeterminadas

Puedes cambiar las configuraciones predeterminadas para un plugin modificando el objeto Constructor.Default del plugin:

// cambia el valor predeterminado para la opción `keyboard` del plugin modal a false
bootstrap.Modal.Default.keyboard = false

Métodos y propiedades

Cada plugin 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 te permite obtener la instancia modal asociada con un elemento DOM.
getOrCreateInstance Método estático que te permite obtener la instancia modal asociada con un elemento DOM, o crear una nueva en caso de que no haya sido inicializada.
Propiedad estática Descripción
NAME Devuelve el nombre del plugin. (Ejemplo: bootstrap.Tooltip.NAME)
VERSION Se puede acceder a la versión de cada uno de los plugins de Bootstrap a través de la propiedad VERSION del constructor del plugin (Ejemplo: bootstrap.Tooltip.VERSION)

Sanitizador

Los Tooltips y Popovers usan nuestro sanitizador incorporado para sanitizar opciones que aceptan HTML.

El valor predeterminado de allowList es el siguiente:

const ARIA_ATTRIBUTE_PATTERN = /^aria-[w-]*$/i

export const DefaultAllowlist = {
  // Atributos globales permitidos en cualquier elemento suministrado abajo.
  '*': ['class', 'dir', 'id', 'lang', 'role', ARIA_ATTRIBUTE_PATTERN],
  a: ['target', 'href', 'title', 'rel'],
  area: [],
  b: [],
  br: [],
  col: [],
  code: [],
  dd: [],
  div: [],
  dl: [],
  dt: [],
  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 quieres agregar nuevos valores a esta allowList predeterminada puedes hacer lo siguiente:

const myDefaultAllowList = bootstrap.Tooltip.Default.allowList

// Para permitir elementos table
myDefaultAllowList.table = []

// Para permitir elementos td y atributos data-bs-option en elementos td
myDefaultAllowList.td = ['data-bs-option']

// Puedes agregar tu regex personalizada para validar tus atributos.
// Ten cuidado de que tus expresiones regulares no sean demasiado laxas
const myCustomRegex = /^data-my-app-[w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

Si quieres omitir nuestro sanitizador porque prefieres usar una librería dedicada, por ejemplo DOMPurify, deberías hacer lo siguiente:

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

Usando jQuery opcionalmente

No necesitas jQuery en Bootstrap 5, pero aún es posible usar nuestros componentes con jQuery.

Si Bootstrap detecta jQuery en el objeto window, agregará todos nuestros componentes en el sistema de plugins de jQuery.

Esto te permite hacer lo siguiente:

// para habilitar tooltips con la configuración predeterminada
$('[data-bs-toggle="tooltip"]').tooltip()

// para inicializar tooltips con configuración dada
$('[data-bs-toggle="tooltip"]').tooltip({
  boundary: 'clippingParents',
  customClass: 'myClass'
})

// para activar el método `show`
$('#myTooltip').tooltip('show')

Lo mismo aplica para nuestros otros componentes.

Sin conflicto

A veces es necesario usar plugins de Bootstrap con otros frameworks de UI. En estas circunstancias, ocasionalmente pueden ocurrir colisiones de namespace.

Si esto sucede, puedes llamar a .noConflict en el plugin al que deseas revertir el valor.

const bootstrapButton = $.fn.button.noConflict() // devuelve $.fn.button al valor previamente asignado
$.fn.bootstrapBtn = bootstrapButton // da a $().bootstrapBtn la funcionalidad de Bootstrap

Bootstrap no soporta oficialmente librerías de JavaScript de terceros como Prototype o jQuery UI.

A pesar de .noConflict y eventos con namespace, puede haber problemas de compatibilidad que necesites arreglar por tu cuenta.

Eventos de jQuery

Bootstrap detectará jQuery si jQuery está presente en el objeto window y no hay un atributo data-bs-no-jquery establecido en «.

Si se encuentra jQuery, Bootstrap emitirá eventos gracias al sistema de eventos de jQuery.

Así que si quieres escuchar los eventos de Bootstrap, tendrás que usar los métodos de jQuery (.on, .one) en lugar de addEventListener.

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

JavaScript deshabilitado

Los plugins de Bootstrap no tienen un respaldo especial cuando JavaScript está deshabilitado.

Si te importa la experiencia del usuario en este caso, usa « para explicar la situación (y cómo volver a habilitar JavaScript) a tus usuarios, y/o agrega tus propios respaldos personalizados.

Preguntas Frecuentes de JavaScript en Bootstrap

¿Cuáles son las formas de incluir Bootstrap JavaScript?

Tienes tres opciones: incluir plugins individuales con js/dist/*.js, todos juntos con bootstrap.js, o la versión minificada bootstrap.min.js. Nunca incluyas ambos archivos completos simultáneamente.

¿Por qué Bootstrap JS no funciona con React, Vue o Angular?

Porque estos frameworks controlan completamente el DOM y pueden conflictuar con Bootstrap, causando errores como dropdowns atascados. Usa alternativas específicas: React Bootstrap, BootstrapVue, BootstrapVueNext, ng-bootstrap o ngx-bootstrap.

¿Cómo implementar Bootstrap como módulo ES?

Usa bootstrap.esm.js o bootstrap.esm.min.js con la ruta completa. Necesitas un importmap para resolver dependencias de Popper o el proyecto es-module-shims para navegadores sin soporte.

¿Qué son los atributos de datos y cómo usarlos?

Son la forma preferida de configurar plugins solo con HTML. Usa data-bs- seguido del nombre en kebab-case (no camelCase). Solo un conjunto de atributos por elemento.

¿Cómo funciona el sistema de eventos?

Los eventos vienen en dos formas: infinitiva (show) al inicio y participio pasado (shown) al completarse. Los infinitivos proporcionan preventDefault() para detener la acción.

¿Qué métodos ofrece la API programática?

Los principales son: constructores que aceptan opciones opcionales, getInstance para obtener instancias existentes (devuelve null si no existe), y getOrCreateInstance para obtener o crear instancias.

¿Cómo manejar dependencias entre plugins?

Verifica dependencias en la documentación al incluir plugins individualmente. Dropdowns, popovers y tooltips requieren Popper.js.

¿Qué es el sanitizador de Bootstrap?

Tooltips y Popovers usan un sanitizador incorporado para limpiar HTML. Tiene una allowList predeterminada de elementos y atributos permitidos que puedes extender o reemplazar con librerías como DOMPurify.

¿Cómo usar Bootstrap con jQuery?

jQuery no es necesario, pero si está presente, Bootstrap agregará automáticamente todos los componentes al sistema de plugins de jQuery, permitiendo sintaxis como $('[data-bs-toggle="tooltip"]').tooltip().

¿Qué hacer cuando JavaScript está deshabilitado?

Bootstrap no proporciona respaldos automáticos. Usa mensajes en HTML para explicar cómo habilitar JavaScript o implementa respaldos personalizados.

¿Cómo resolver conflictos de namespace?

Usa el método .noConflict() en el plugin específico para revertir su valor y asignarlo a un nuevo nombre, como $.fn.bootstrapBtn = $.fn.button.noConflict().

¿Cuáles son los métodos y propiedades estáticas?

Todos los plugins exponen: dispose (destruye instancia), getInstance (obtiene instancia), getOrCreateInstance (obtiene o crea), (nombre del plugin) y VERSION (versión del plugin).

¿Cómo funcionan las transiciones asíncronas?

Todos los métodos API son asíncronos y regresan cuando la transición comienza, no cuando termina. Escucha eventos correspondientes para ejecutar acciones al completarse. Las llamadas durante transiciones son ignoradas.

¿Cómo cambiar configuraciones predeterminadas?

Modifica el objeto Constructor.Default del plugin. Por ejemplo: bootstrap.Modal.Default.keyboard = false cambia el valor predeterminado de la opción keyboard.

¿Qué selectores se pueden usar?

Bootstrap usa querySelector y querySelectorAll nativos, así que debes usar selectores CSS válidos. Los constructores aceptan elementos DOM o selectores CSS válidos.

Artículos Relacionados

Descubre más desde CIBERED

Suscríbete y recibe las últimas entradas en tu correo electrónico.

Deja un comentario