in English

JavaScript

Dê vida ao Bootstrap com nossos plugins JavaScript opcionais construídos em jQuery. Saiba mais sobre cada plug-in, nossos dados e opções de API programática e muito mais.

Individual ou compilado

Os plugins podem ser incluídos individualmente (usando o Bootstrap individual js/dist/*.js), ou todos de uma vez usando bootstrap.jsou minificado bootstrap.min.js(não inclua ambos).

Se você usa um bundler (Webpack, Rollup…), você pode usar /js/dist/*.jsarquivos prontos para UMD.

Dependências

Alguns plugins e componentes CSS dependem de outros plugins. Se você incluir plugins individualmente, certifique-se de verificar essas dependências nos documentos. Observe também que todos os plugins dependem do jQuery (isso significa que o jQuery deve ser incluído antes dos arquivos do plugin). Consulte nossopackage.json para ver quais versões do jQuery são suportadas.

Nossos menus suspensos, popovers e dicas de ferramentas também dependem do Popper.js .

Atributos de dados

Quase todos os plugins do Bootstrap podem ser habilitados e configurados apenas por meio de HTML com atributos de dados (nossa maneira preferida de usar a funcionalidade JavaScript). Certifique-se de usar apenas um conjunto de atributos de dados em um único elemento (por exemplo, você não pode acionar uma dica de ferramenta e modal a partir do mesmo botão).

No entanto, em algumas situações, pode ser desejável desabilitar essa funcionalidade. Para desabilitar a API de atributo de dados, desvincule todos os eventos no documento com namespace data-apiassim:

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

Como alternativa, para segmentar um plug-in específico, basta incluir o nome do plug-in como um namespace junto com o namespace data-api assim:

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

Seletores

Atualmente para consultar os elementos DOM usamos os métodos nativos querySelectore querySelectorAllpor questões de performance, então você tem que usar seletores válidos . Se você usar seletores especiais, por exemplo: collapse:Examplecertifique-se de escapar deles.

Eventos

O Bootstrap fornece eventos personalizados para ações exclusivas da maioria dos plugins. Geralmente, eles vêm na forma de infinitivo e particípio passado - onde o infinitivo (ex. show) é acionado no início de um evento e sua forma de particípio passado (ex. shown) é acionada na conclusão de uma ação.

Todos os eventos infinitivos fornecem preventDefault()funcionalidade. Isso fornece a capacidade de interromper a execução de uma ação antes que ela comece. Retornar false de um manipulador de eventos também chamará automaticamente preventDefault().

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

API programática

Também acreditamos que você deve ser capaz de usar todos os plugins Bootstrap puramente por meio da API JavaScript. Todas as APIs públicas são métodos únicos e encadeados e retornam a coleção em que atua.

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

Todos os métodos devem aceitar um objeto de opções opcional, uma string que tem como alvo um método específico ou nada (que inicia um plugin com comportamento padrão):

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

Cada plugin também expõe seu construtor bruto em uma Constructorpropriedade: $.fn.popover.Constructor. Se você quiser obter uma instância de plug-in específica, recupere-a diretamente de um elemento: $('[rel="popover"]').data('popover').

Funções e transições assíncronas

Todos os métodos de API programáticos são assíncronos e retornam ao chamador assim que a transição é iniciada, mas antes que ela termine .

Para executar uma ação quando a transição estiver concluída, você pode ouvir o evento correspondente.

$('#myCollapse').on('shown.bs.collapse', function (event) {
  // Action to execute once the collapsible area is expanded
})

Além disso, uma chamada de método em um componente de transição será ignorada .

$('#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 !!

Configurações padrão

Você pode alterar as configurações padrão de um plug-in modificando o Constructor.Defaultobjeto do plug-in:

// changes default for the modal plugin's `keyboard` option to false
$.fn.modal.Constructor.Default.keyboard = false

Sem conflito

Às vezes é necessário usar plugins do Bootstrap com outros frameworks de UI. Nessas circunstâncias, colisões de namespace podem ocorrer ocasionalmente. Se isso acontecer, você pode chamar .noConflicto plugin para o qual deseja 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 versão

A versão de cada um dos plugins jQuery do Bootstrap pode ser acessada através da VERSIONpropriedade do construtor do plugin. Por exemplo, para o plug-in de dica de ferramenta:

$.fn.tooltip.Constructor.VERSION // => "4.6.2"

Sem fallbacks especiais quando o JavaScript está desabilitado

Os plugins do Bootstrap não retornam de forma particularmente graciosa quando o JavaScript está desabilitado. Se você se preocupa com a experiência do usuário nesse caso, use <noscript>para explicar a situação (e como reativar o JavaScript) para seus usuários e/ou adicione seus próprios fallbacks personalizados.

Bibliotecas de terceiros

O Bootstrap não suporta oficialmente bibliotecas JavaScript de terceiros, como Prototype ou jQuery UI. Apesar .noConflictdos eventos com namespace, pode haver problemas de compatibilidade que você precisa corrigir por conta própria.

Util

Todos os arquivos JavaScript do Bootstrap dependem util.jse devem ser incluídos junto com os outros arquivos JavaScript. Se você estiver usando o compilado (ou minificado) bootstrap.js, não há necessidade de incluí-lo - ele já está lá.

util.jsinclui funções utilitárias e um auxiliar básico para transitionEndeventos, bem como um emulador de transição CSS. Ele é usado por outros plugins para verificar o suporte de transição CSS e capturar transições suspensas.

Desinfetante

As dicas de ferramentas e os popovers usam nosso desinfetante integrado para limpar as opções que aceitam HTML.

O whiteListvalor padrão é 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 você quiser adicionar novos valores a esse padrão whiteList, faça 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 você deseja ignorar nosso desinfetante porque prefere usar uma biblioteca dedicada, por exemplo DOMPurify , faça o seguinte:

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