JavaScript

Da vida a Bootstrap cos nosos complementos de JavaScript opcionais construídos en jQuery. 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.

Dependencias

Algúns complementos e compoñentes CSS dependen doutros complementos. Se inclúes complementos individualmente, asegúrate de comprobar estas dependencias nos documentos. Teña en conta tamén que todos os complementos dependen de jQuery (isto significa que jQuery debe incluírse antes dos ficheiros de complementos). Consulte o nosopackage.json para ver que versións de jQuery son compatibles.

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

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

Non obstante, nalgunhas situacións pode ser desexable desactivar esta función. Para desactivar a API do atributo de datos, desvincule todos os eventos do documento espaciados de nomes deste data-apixeito:

$(document).off('.data-api')

Alternativamente, para apuntar a un complemento específico, simplemente inclúa o nome do complemento como espazo de nomes xunto co espazo de nomes da API de datos como este:

$(document).off('.alert.data-api')

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

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

API programática

Tamén cremos que deberías poder usar todos os complementos de Bootstrap só a través da API de JavaScript. Todas as API públicas son métodos únicos que se poden encadear e devolven a colección sobre a que se actuou.

$('.btn.danger').button('toggle').addClass('fat')

Todos os métodos deben aceptar un obxecto de opcións opcionais, unha cadea que se dirixe a un método en particular ou nada (que inicia un complemento co comportamento predeterminado):

$('#myModal').modal() // initialized with defaults
$('#myModal').modal({ keyboard: false }) // initialized with no keyboard
$('#myModal').modal('show') // initializes and invokes show immediately

Cada complemento tamén expón o seu construtor bruto nunha Constructorpropiedade: $.fn.popover.Constructor. Se queres obter unha instancia de complemento en particular, obtén directamente desde un elemento: $('[rel="popover"]').data('popover').

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.

$('#myCollapse').on('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 .

$('#myCarousel').on('slid.bs.carousel', function (event) {
  $('#myCarousel').carousel('2') // Will slide to the slide 2 as soon as the transition to slide 1 is finished
})

$('#myCarousel').carousel('1') // Will start sliding to the slide 1 and returns to the caller
$('#myCarousel').carousel('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
$.fn.modal.Constructor.Default.keyboard = false

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.

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 jQuery de Bootstrap a través da VERSIONpropiedade do construtor do complemento. Por exemplo, para o complemento de información sobre ferramentas:

$.fn.tooltip.Constructor.VERSION // => "4.6.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.

Util

Todos os ficheiros JavaScript de Bootstrap dependen util.jse deben incluírse xunto cos outros ficheiros JavaScript. Se estás a usar o compilado (ou minificado) bootstrap.js, non hai que incluír isto, xa está aí.

util.jsinclúe funcións de utilidade e un axudante básico para transitionEndeventos, así como un emulador de transición CSS. Úsano os outros complementos para comprobar a compatibilidade de transición CSS e capturar as transicións pendentes.

Sanitizante

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

O valor predeterminado whiteListé o seguinte:

var ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
var DefaultWhitelist = {
  // 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 whiteList, podes facer o seguinte:

var myDefaultWhiteList = $.fn.tooltip.Constructor.Default.whiteList

// To allow table elements
myDefaultWhiteList.table = []

// To allow td elements and data-option attributes on td elements
myDefaultWhiteList.td = ['data-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-]+/
myDefaultWhiteList['*'].push(myCustomRegex)

Se queres evitar o noso desinfectante porque prefires usar unha biblioteca dedicada, por exemplo DOMPurify , debes facer o seguinte:

$('#yourTooltip').tooltip({
  sanitizeFn: function (content) {
    return DOMPurify.sanitize(content)
  }
})