in English

JavaScript

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

Nesta página

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, Parcel, Vite…), você pode usar /js/dist/*.jsarquivos prontos para UMD.

Uso com estruturas JavaScript

Embora o CSS do Bootstrap possa ser usado com qualquer estrutura, o JavaScript do Bootstrap não é totalmente compatível com estruturas JavaScript como React, Vue e Angular, que pressupõem total conhecimento do DOM. Tanto o Bootstrap quanto o framework podem tentar alterar o mesmo elemento DOM, resultando em bugs como dropdowns que ficam presos na posição “open”.

Uma alternativa melhor para quem usa esse tipo de framework é usar um pacote específico de framework em vez do JavaScript Bootstrap. Aqui estão algumas das opções mais populares:

Reagir: Reagir Bootstrap
Vue: BootstrapVue (atualmente suporta apenas Vue 2 e Bootstrap 4)
Angular: ng-bootstrap

Usando o Bootstrap como um módulo

Tente você mesmo! Baixe o código-fonte e a demonstração de trabalho para usar o Bootstrap como um módulo ES do repositório twbs/examples . Você também pode abrir o exemplo no StackBlitz .

Fornecemos uma versão do Bootstrap construída como ESM( bootstrap.esm.jse bootstrap.esm.min.js) que permite que você use o Bootstrap como um módulo no navegador, se os navegadores de destino o suportarem .

<script type="module">
  import { Toast } from 'bootstrap.esm.min.js'

  Array.from(document.querySelectorAll('.toast'))
    .forEach(toastNode => new Toast(toastNode))
</script>

Comparado aos empacotadores JS, o uso do ESM no navegador exige que você use o caminho completo e o nome do arquivo em vez do nome do módulo. Leia mais sobre módulos JS no navegador. É por isso que usamos 'bootstrap.esm.min.js'em vez de 'bootstrap'acima. No entanto, isso é ainda mais complicado pela nossa dependência do Popper, que importa o Popper para o nosso JavaScript da seguinte forma:

import * as Popper from "@popperjs/core"

Se você tentar como está, verá um erro no console como o seguinte:

Uncaught TypeError: Failed to resolve module specifier "@popperjs/core". Relative references must start with either "/", "./", or "../".

Para corrigir isso, você pode usar um importmappara resolver os nomes de módulos arbitrários para concluir os caminhos. Se seus navegadores de destino não suportarem importmap, você precisará usar o projeto es-module-shims . Veja como funciona para Bootstrap e Popper:

<!doctype html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link href="https://cdn.jsdelivr.net/npm/[email protected]/dist/css/bootstrap.min.css" rel="stylesheet" integrity="sha384-iYQeCzEYFbKjA/T2uDLTpkwGzCiq6soy8tYaI1GyVh/UjpbCx/TYkiZhlZB6+fzT" crossorigin="anonymous">
    <title>Hello, modularity!</title>
  </head>
  <body>
    <h1>Hello, modularity!</h1>
    <button id="popoverButton" type="button" class="btn btn-primary btn-lg" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="ESM in Browser" data-bs-content="Bang!">Custom popover</button>

    <script async src="https://cdn.jsdelivr.net/npm/es-module-shims@1/dist/es-module-shims.min.js" crossorigin="anonymous"></script>
    <script type="importmap">
    {
      "imports": {
        "@popperjs/core": "https://cdn.jsdelivr.net/npm/@popperjs/[email protected]/dist/umd/popper.min.js",
        "bootstrap": "https://cdn.jsdelivr.net/npm/[email protected]/dist/js/bootstrap.esm.min.js"
      }
    }
    </script>
    <script type="module">
      import * as bootstrap from 'bootstrap'

      new bootstrap.Popover(document.getElementById('popoverButton'))
    </script>
  </body>
</html>

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.

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

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

Como as opções podem ser passadas por meio de atributos de dados ou JavaScript, você pode anexar um nome de opção a data-bs-, como em data-bs-animation="{value}". Certifique-se de alterar o tipo de caso do nome da opção de “ camelCase ” para “ kebab-case ” ao passar as opções por meio de atributos de dados. Por exemplo, use data-bs-custom-class="beautifier"em vez de data-bs-customClass="beautifier".

A partir do Bootstrap 5.2.0, todos os componentes oferecem suporte a um atributo experimental de dados reservados data-bs-configque pode abrigar a configuração simples do componente como uma string JSON. Quando um elemento tem atributos data-bs-config='{"delay":0, "title":123}'e data-bs-title="456", o valor final titleserá 456e os atributos de dados separados substituirão os valores fornecidos em data-bs-config. Além disso, os atributos de dados existentes podem hospedar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

Seletores

Usamos os métodos nativos querySelectore querySelectorAllpara consultar elementos DOM por motivos de desempenho, portanto, você deve usar seletores válidos . Se você usar seletores especiais como 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().

const myModal = document.querySelector('#myModal')

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

API programática

Todos os construtores aceitam um objeto de opções opcional ou nada (que inicia um plugin com seu comportamento padrão):

const myModalEl = document.querySelector('#myModal')

const modal = new bootstrap.Modal(myModalEl) // initialized with defaults

const configObject = { keyboard: false }
const modal1 = new bootstrap.Modal(myModalEl, configObject) // initialized with no keyboard

Se você deseja obter uma instância de plug-in específica, cada plug-in expõe um getInstancemétodo. Por exemplo, para recuperar uma instância diretamente de um elemento:

bootstrap.Popover.getInstance(myPopoverEl)

Este método retornará nullse uma instância não for iniciada sobre o elemento solicitado.

Alternativamente, getOrCreateInstancepode ser usado para obter a instância associada a um elemento DOM ou criar uma nova caso não tenha sido inicializada.

bootstrap.Popover.getOrCreateInstance(myPopoverEl, configObject)

Caso uma instância não tenha sido inicializada, ela pode aceitar e usar um objeto de configuração opcional como segundo argumento.

Seletores CSS em construtores

Além dos métodos getInstancee , todos os construtores de plugins podem aceitar um elemento DOM ou um seletor CSS válido como o primeiro argumento. Os elementos de plug-in são encontrados com o método, pois nossos plug-ins suportam apenas um único elemento.getOrCreateInstancequerySelector

const modal = new bootstrap.Modal('#myModal')
const dropdown = new bootstrap.Dropdown('[data-bs-toggle="dropdown"]')
const offcanvas = bootstrap.Offcanvas.getInstance('#myOffcanvas')
const alert = bootstrap.Alert.getOrCreateInstance('#myAlert')

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.

const myCollapseEl = document.querySelector('#myCollapse')

myCollapseEl.addEventListener('shown.bs.collapse', 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 .

const myCarouselEl = document.querySelector('#myCarousel')
const carousel = bootstrap.Carousel.getInstance(myCarouselEl) // Retrieve a Carousel instance

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

`dispose`método

Embora possa parecer correto usar o disposemétodo imediatamente após hide(), isso levará a resultados incorretos. Aqui está um exemplo do uso do problema:

const myModal = document.querySelector('#myModal')
myModal.hide() // it is asynchronous

myModal.addEventListener('shown.bs.hidden', event => {
  myModal.dispose()
})

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
bootstrap.Modal.Default.keyboard = false

Métodos e propriedades

Cada plugin Bootstrap expõe os seguintes métodos e propriedades estáticas.

Método	Descrição
`dispose`	Destrói o modal de um elemento. (Remove os dados armazenados no elemento DOM)
`getInstance`	Método estático que permite obter a instância modal associada a um elemento DOM.
`getOrCreateInstance`	Método estático que permite obter a instância modal associada a um elemento DOM ou criar uma nova caso não tenha sido inicializada.

Propriedade estática	Descrição
`NAME`	Retorna o nome do plug-in. (Exemplo: `bootstrap.Tooltip.NAME`)
`VERSION`	A versão de cada um dos plugins do Bootstrap pode ser acessada através da `VERSION`propriedade do construtor do plugin (Exemplo: `bootstrap.Tooltip.VERSION`)

Desinfetante

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

O allowListvalor padrão é o seguinte:

const ARIA_ATTRIBUTE_PATTERN = /^aria-[\w-]*$/i
const 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 você quiser adicionar novos valores a esse padrão allowList, faça o seguinte:

const 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
const myCustomRegex = /^data-my-app-[\w-]+/
myDefaultAllowList['*'].push(myCustomRegex)

Se você deseja ignorar nosso desinfetante porque prefere usar uma biblioteca dedicada, por exemplo DOMPurify , faça o seguinte:

const yourTooltipEl = document.querySelector('#yourTooltip')
const tooltip = new bootstrap.Tooltip(yourTooltipEl, {
  sanitizeFn(content) {
    return DOMPurify.sanitize(content)
  }
})

Opcionalmente usando jQuery

Você não precisa de jQuery no Bootstrap 5 , mas ainda é possível usar nossos componentes com jQuery. Se o Bootstrap detectar jQueryno windowobjeto, ele adicionará todos os nossos componentes no sistema de plugins do jQuery. Isso permite que você faça o seguinte:

$('[data-bs-toggle="tooltip"]').tooltip() // to enable tooltips, with default configuration

$('[data-bs-toggle="tooltip"]').tooltip({ boundary: 'clippingParents', customClass: 'myClass' }) // to initialize tooltips with given configuration

$('#myTooltip').tooltip('show') // to trigger `show` method

O mesmo vale para nossos outros componentes.

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.

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

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.

eventos jQuery

O Bootstrap detectará o jQuery se jQueryestiver presente no windowobjeto e não houver nenhum data-bs-no-jqueryatributo definido em <body>. Se o jQuery for encontrado, o Bootstrap emitirá eventos graças ao sistema de eventos do jQuery. Portanto, se você quiser ouvir os eventos do Bootstrap, terá que usar os métodos jQuery ( .on, .one) em vez de addEventListener.

$('#myTab a').on('shown.bs.tab', () => {
  // do something...
})

JavaScript desabilitado

Os plugins do Bootstrap não têm fallback especial 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.