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.js
ou minificado bootstrap.min.js
(não inclua ambos).
Se você usa um bundler (Webpack, Rollup…), você pode usar /js/dist/*.js
arquivos 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-api
assim:
$(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 querySelector
e querySelectorAll
por questões de performance, então você tem que usar seletores válidos . Se você usar seletores especiais, por exemplo: collapse:Example
certifique-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 Constructor
propriedade: $.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.Default
objeto 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 .noConflict
o 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 VERSION
propriedade 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 .noConflict
dos 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.js
e 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.js
inclui funções utilitárias e um auxiliar básico para transitionEnd
eventos, 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 whiteList
valor 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)
}
})