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.js
ou minificados bootstrap.min.js
(non inclúa ambos).
Se usas un paquete de paquetes (Webpack, Rollup...), podes usar /js/dist/*.js
ficheiros que estean preparados para UMD.
Usando Bootstrap como módulo
Ofrecemos unha versión de Bootstrap creada como ESM
( bootstrap.esm.js
e 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 module
tipo 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 jQuery
o window
obxecto , 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 querySelector
e querySelectorAll
por razóns de rendemento, polo que tes que usar selectores válidos . Se usas selectores especiais, por exemplo: 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()
.
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 jQuery
está presente no window
obxecto e non hai ningún data-bs-no-jquery
atributo 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 getInstance
mé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 querySelector
mé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.Default
obxecto 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 .noConflict
ao 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 VERSION
propiedade do construtor do complemento. Por exemplo, para o complemento de información sobre ferramentas:
bootstrap.Tooltip.VERSION // => "5.0.2"
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 .noConflict
dos eventos separados dos nomes, pode haber problemas de compatibilidade que teñas que solucionar por ti mesmo.
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:
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)
}
})