Clique em botões para ver um lista de links e outras coisas, usando o plugin Bootstrap dropdown.
Visão Geral
Dropdowns são botões com alternância de visibilidade de listas de links e outras coisas. Conseguem ser interativos graças a sua construção que foi feita com o plugin JavaScript dropdown. A visibilidade do conteúdo é alternada com cliques e nunca só ao passar o mouse em cima do botão (uma decisão de design intencional).
Dropdowns são feitos em cima de uma biblioteca de terceiros, Popper.js, a qual permite posicionamento dinâmico e detecção de viewport. Se assegure de invocar popper.min.js, antes do JavaScript Bootstrap ou use bootstrap.bundle.min.js / bootstrap.bundle.js, os quais já possuem o Popper.js. No entanto, Popper.js não é usada para posicionar dropdowns em navbars, já que posicionamento dinâmico não é necessário.
Se você está construindo nosso JavaScript a partir da fonte, vai precisar do util.js.
Acessibilidade
O padrões WAI ARIA pedem o uso do atributo role="menu", mas ele é específico para menus de aplicações que ativam ações ou funções. Menus ARIA só podem conter itens de menu, checkbox, grupos e botões radio, além de sub-menus.
Os dropdowns Bootstrap, por outro lado, são desenhados para serem genéricos e aplicáveis em várias situações e estruturas de marcação. Por exemplo, é possível criar dropdowns que possuem inputs e form controls adicionais, como campos de pesquisa ou formulários de login. Por essa razão, Bootstrap não espera (nem adiciona automaticamente) a presença dos atributos role e aria, exigidos nos reais menus ARIA. Os autores terão que incluí-los, por si só.
No entanto, Bootstrap tem suporte para a maioria das interações padrões de teclado, como a habilidade de mover-se através de elementos individuais dropdown-item (usando o as setinhas do teclado) ou fechar o menu com a tecla ESC.
Exemplos
Envolte os itens ou menu dropdown dentro da classe .dropdown ou qualquer outro elemento que tenha position: relative; declarado. Dropdowns podem ser acionados de um elemento <a> ou <button>, te dando mais flexibilidade.
Único botão
Qualquer .btn pode se transformar em um dropdown, com algumas adições na marcação HTML.
Aqui está como você pode fazê-los funcionar, usando <button>:
Similarmente, crie botões divididos com a mesma marcação HTML de botões dropdowns, mas com a adição da classe .dropdown-toggle-split para espaçamento apropriado, ao redor da setinha.
Nós usamos esta classe extra para reduzir o padding horizontal, em 25% dos lados da setinha e remover a margin-left que é adicionada em botões dropdowns comuns. Estas mudanças extras mantém a setinha centralizada e dá uma área de clique maior, no botão principal.
Historicamente, o conteúdo dos dropdowns tinham que ser links, mas isso não é mais o caso, na v4. Agora, você pode usar elementos <button> em seus dropdowns, invés de <a>.
Você também pode criar dropdowns com itens não interativos, usando .dropdown-item-text. Sinta-se livre para fazer mais estilizações com CSS ou utilitários de texto.
Por padrão, o menu dropdown é, automaticamente, posicionado 100% a partir do topo e esquerda do elemento pai. Use .dropdown-menu-right em um .dropdown-menu para alinhar o menu dropdown a direita.
Atenção! Dropdowns são posicionados com ajuda do Popper.js (exceto quando estão dentro de uma navbar).
Conteúdo do menu
Cabeçalho
Coloque um cabeçalho para rotular seções, no menu dropdown.
Coloque qualquer texto dentro do menu dropdown e use utilitários de espaçamentos. Perceba que você pode precisar estilizar o tamanho da fonte para se adequar a largura do menu.
Algum exemplo de texto, aqui dentro do menu.
Mais um exemplo de texto.
Formulários
Coloque um formulário dentro do menu dropdown ou transforme-o em um menu dropdown. Use utilitários de margem ou padding para conseguir o espaço negativo necessário.
Usando JavaScript ou atributos data, o plugin dropdown alterna a visibilidade de conteúdo invisível (menus dropdown) trocando a classe .show, no elemento pai da lista. O atributo data-toggle="dropdown" é acreditado para fechar os menus dropdown em level de aplicação, então, é uma boa ideia sempre usá-lo.
Em dispositivos touch, abrir um menu adiciona manipuladores ($.noop) mouseover vazios em filhos imediatos do elemento <body>. Essa gambiarra feia é necessária para contornar um problema na delegação de eventos do iOS, o qual poderia evitar que toques fora do dropdown acionassem o código que fecha o próprio dropdown. Uma vez que o dropdown é fechado, esses manipuladores mouseover adicionais vazios são removidos.
Via atributos data
Use data-toggle="dropdown" em um link ou botão para alternar a visibilidade do menu dropdown.
Via JavaScript
Invoque os dropdowns, usando JavaScript:
data-toggle="dropdown" é obrigatório
Independente se você invoca seu dropdown com JavaScript ou com a data-api, o uso de data-toggle="dropdown" sempre é obrigatório no gatilho dropdown.
Parâmetros
Parâmetros sempre podem ser passados usando atributos ou JavaScript. Para atributos, anexe o parâmetro no prefixo data-, como em data-offset="".
Nome
Tipo
Padrão
Descrição
offset
number | string | função
0
Deslocamento do dropdown, em relação ao seu alvo. Para mais informações, veja a documentação do offset Popper.js.
flip
boolean
true
Permite o dropdown virar, em caso de sobreposição no elemento de referência. Para mais informações, veja a documentação do flip Popper.js.
boundary
string | elemento
'scrollParent'
Limite de transbordamento do menu dropdown. Aceita os valores 'viewport', 'window', 'scrollParent' ou uma referência HTMLElement (JavaScript, apenas). Para mias informações, veja a documentação preventOverflow Popper.js.
reference
string | elemento
'toggle'
Elemento de referência do menu dropdown. Aceita os valores 'toggle', 'parent' ou uma referência HTMLElement. Para mais informações, veja a documentação referenceObject Popper.js.
display
string
'dynamic'
Por padrão, nós usamos o posicionamento dinâmico do Popper.js. Desative isso, usando o valor static.
Nota: quando boundary tem como valor definido qualquer coisa, que não 'scrollParent', o estilo position: static é aplicado no container .dropdown.
Métodos
Método
Descrição
$().dropdown('toggle')
Alterna a visibilidade do menu dropdown em uma dada navbar ou navegação por abas.
$().dropdown('update')
Atualiza a posição do dropdown de um elemento.
$().dropdown('dispose')
Destroi o dropdown de um elemento.
Eventos
Todos eventos dropdown são acionados no elemento pai do .dropdown-menu e possuem uma propriedade relatedTarget, a qual tem o valor referente ao elemento âncora de alternância.
Os eventos hide.bs.dropdown e hidden.bs.dropdown possuem uma propriedade clickEvent (só quando o tipo do evento original é click), a qual contém um objeto de evento (Event Object) para o evento do clique.
Evento
Descrição
show.bs.dropdown
Este evento é acionado, imediatamente, quando o método show é invocado.
shown.bs.dropdown
Este evento é acionado quando o dropdown se torna visível ao usuário (espera as transições CSS finalizarem).
hide.bs.dropdown
Este evento é acionado, imediatamente, quando o método hide foi invocado.
hidden.bs.dropdown
Este evento é acionado quando o dropdown acaba de se esconder do usuário (espera as transições CSS finalizarem).