Ir ao contido principal Ir á navegación de documentos
in English

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.

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 usas un paquete de paquetes (Webpack, Rollup...), podes usar /js/dist/*.jsficheiros que estean preparados para UMD.

Usando Bootstrap como módulo

Ofrecemos unha versión de Bootstrap creada como ESM( bootstrap.esm.jse bootstrap.esm.min.js) que che permite usar Bootstrap como módulo no teu 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>

Complementos incompatibles

Debido ás limitacións do navegador, algúns dos nosos complementos, como os complementos Dropdown, Tooltip e Popover, non se poden usar nunha <script>etiqueta con moduletipo porque dependen de Popper. Para obter máis información sobre o problema, consulte aquí .

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 despregables, popovers e informacións sobre ferramentas tamén dependen de Popper .

Aínda queres usar jQuery? É posible!

Bootstrap 5 está deseñado para ser usado sen jQuery, 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 significa que poderás $('[data-bs-toggle="tooltip"]').tooltip()activar as informacións sobre ferramentas. O mesmo ocorre cos nosos outros compoñentes.

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

Selectores

Actualmente para consultar elementos DOM usamos os métodos nativos querySelectore querySelectorAllpor razóns de rendemento, polo que tes que usar selectores válidos . Se usas selectores especiais, por exemplo: collapse:Exampleasegú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().

var myModal = document.getElementById('myModal')

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

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', function () {
  // do something...
})

API programática

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

var myModalEl = document.getElementById('myModal')

var modal = new bootstrap.Modal(myModalEl) // initialized with defaults
var modal = new bootstrap.Modal(myModalEl, { keyboard: false }) // initialized with no keyboard

Se desexa obter unha instancia de complemento en particular, cada complemento expón un getInstancemétodo. Para recuperalo directamente dun elemento, fai isto: bootstrap.Popover.getInstance(myPopoverEl).

Selectores CSS en construtores

Tamén podes usar un selector CSS como primeiro argumento en lugar dun elemento DOM para inicializar o complemento. Actualmente o elemento para o complemento atópase polo querySelectormétodo xa que os nosos complementos só admiten un só elemento.

var modal = new bootstrap.Modal('#myModal')
var dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')

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.

var myCollapseEl = document.getElementById('myCollapse')

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

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

var myCarouselEl = document.getElementById('myCarousel')
var carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance

myCarouselEl.addEventListener('slid.bs.carousel', function (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 !!

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

Sen conflito (só se usa jQuery)

Á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.

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

Números de versión

Pódese acceder á versión de cada un dos complementos de Bootstrap a través da VERSIONpropiedade do construtor do complemento. Por exemplo, para o complemento de información sobre ferramentas:

bootstrap.Tooltip.VERSION // => "5.1.3"

Non hai opcións especiais cando JavaScript está desactivado

Os complementos de Bootstrap non caen con especial gracia 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.

Bibliotecas de terceiros

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.

Desinfectante

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:

var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var 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:

var 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
var 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:

var yourTooltipEl = document.getElementById('yourTooltip')
var tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn: function (content) {
    return DOMPurify.sanitize(content)
  }
})