Ir para o conteúdo principal Pular para a navegação de documentos
in English

Popovers

Documentação e exemplos para adicionar popovers do Bootstrap, como os encontrados no iOS, a qualquer elemento do seu site.

Visão geral

Coisas para saber ao usar o plugin popover:

  • Popovers contam com a biblioteca de terceiros Popper para posicionamento. Você deve incluir popper.min.js antes de bootstrap.js ou usar bootstrap.bundle.min.js/ bootstrap.bundle.jsque contém Popper para que os popovers funcionem!
  • Os popovers exigem o plug -in de dica de ferramenta como uma dependência.
  • Os popovers são opcionais por motivos de desempenho, portanto, você mesmo deve inicializá-los .
  • O comprimento zero titlee contentos valores nunca mostrarão um popover.
  • Especifique container: 'body'para evitar problemas de renderização em componentes mais complexos (como nossos grupos de entrada, grupos de botões etc.).
  • Acionar popovers em elementos ocultos não funcionará.
  • Popovers para .disabledou disabledelementos devem ser acionados em um elemento wrapper.
  • Quando acionados a partir de âncoras que envolvem várias linhas, os popovers serão centralizados entre a largura total das âncoras. Use .text-nowrapem seus <a>s para evitar esse comportamento.
  • Os popovers devem ser ocultados antes que seus elementos correspondentes sejam removidos do DOM.
  • Popovers podem ser acionados graças a um elemento dentro de um shadow DOM.
Por padrão, esse componente usa o desinfetante de conteúdo integrado, que remove todos os elementos HTML que não são explicitamente permitidos. Consulte a seção de desinfetante em nossa documentação JavaScript para obter mais detalhes.
O efeito de animação deste componente depende da prefers-reduced-motionconsulta de mídia. Consulte a seção de movimento reduzido de nossa documentação de acessibilidade .

Continue lendo para ver como os popovers funcionam com alguns exemplos.

Exemplo: ativar popovers em todos os lugares

Uma maneira de inicializar todos os popovers em uma página seria selecioná-los por seu data-bs-toggleatributo:

var popoverTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="popover"]'))
var popoverList = popoverTriggerList.map(function (popoverTriggerEl) {
  return new bootstrap.Popover(popoverTriggerEl)
})

Exemplo: Usando a containeropção

Quando você tiver alguns estilos em um elemento pai que interferem com um popover, você desejará especificar um personalizado containerpara que o HTML do popover apareça dentro desse elemento.

var popover = new bootstrap.Popover(document.querySelector('.example-popover'), {
  container: 'body'
})

Exemplo

<button type="button" class="btn btn-lg btn-danger" data-bs-toggle="popover" title="Popover title" data-bs-content="And here's some amazing content. It's very engaging. Right?">Click to toggle popover</button>

Quatro direções

Quatro opções estão disponíveis: alinhamento superior, direito, inferior e alinhamento à esquerda. As direções são espelhadas ao usar o Bootstrap em RTL.

<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="top" data-bs-content="Top popover">
  Popover on top
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="right" data-bs-content="Right popover">
  Popover on right
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="bottom" data-bs-content="Bottom popover">
  Popover on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-container="body" data-bs-toggle="popover" data-bs-placement="left" data-bs-content="Left popover">
  Popover on left
</button>

Dispensar no próximo clique

Use o focusgatilho para dispensar popovers no próximo clique do usuário em um elemento diferente do elemento de alternância.

Marcação específica necessária para dispensar no próximo clique

Para um comportamento adequado entre navegadores e plataformas, você deve usar a <a>tag, não a <button>tag, e também deve incluir um tabindexatributo.

<a tabindex="0" class="btn btn-lg btn-danger" role="button" data-bs-toggle="popover" data-bs-trigger="focus" title="Dismissible popover" data-bs-content="And here's some amazing content. It's very engaging. Right?">Dismissible popover</a>
var popover = new bootstrap.Popover(document.querySelector('.popover-dismiss'), {
  trigger: 'focus'
})

Elementos desativados

Elementos com o disabledatributo não são interativos, o que significa que os usuários não podem passar o mouse ou clicar neles para acionar um popover (ou dica de ferramenta). Como solução alternativa, você desejará acionar o popover de um wrapper <div>ou <span>, idealmente focado no teclado usando tabindex="0".

Para gatilhos de popover desativados, você também pode preferir data-bs-trigger="hover focus"que o popover apareça como feedback visual imediato para seus usuários, pois eles podem não esperar clicar em um elemento desativado.

<span class="d-inline-block" tabindex="0" data-bs-toggle="popover" data-bs-trigger="hover focus" data-bs-content="Disabled popover">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

Sass

Variáveis

$popover-font-size:                 $font-size-sm;
$popover-bg:                        $white;
$popover-max-width:                 276px;
$popover-border-width:              $border-width;
$popover-border-color:              rgba($black, .2);
$popover-border-radius:             $border-radius-lg;
$popover-inner-border-radius:       subtract($popover-border-radius, $popover-border-width);
$popover-box-shadow:                $box-shadow;

$popover-header-bg:                 shade-color($popover-bg, 6%);
$popover-header-color:              $headings-color;
$popover-header-padding-y:          .5rem;
$popover-header-padding-x:          $spacer;

$popover-body-color:                $body-color;
$popover-body-padding-y:            $spacer;
$popover-body-padding-x:            $spacer;

$popover-arrow-width:               1rem;
$popover-arrow-height:              .5rem;
$popover-arrow-color:               $popover-bg;

$popover-arrow-outer-color:         fade-in($popover-border-color, .05);

Uso

Habilite popovers via JavaScript:

var exampleEl = document.getElementById('example')
var popover = new bootstrap.Popover(exampleEl, options)

Fazendo popovers funcionarem para usuários de teclado e tecnologia assistiva

Para permitir que usuários de teclado ativem seus popovers, você deve adicioná-los apenas a elementos HTML que são tradicionalmente focados no teclado e interativos (como links ou controles de formulário). Embora elementos HTML arbitrários (como <span>s) possam ser focalizados adicionando o tabindex="0"atributo, isso adicionará paradas de tabulação potencialmente irritantes e confusas em elementos não interativos para usuários de teclado, e a maioria das tecnologias assistivas atualmente não anuncia o conteúdo do popover nessa situação . Além disso, não confie apenas no hovergatilho para seus popovers, pois isso os tornará impossíveis de acionar para usuários de teclado.

Embora você possa inserir HTML rico e estruturado em popovers com a htmlopção, recomendamos que você evite adicionar uma quantidade excessiva de conteúdo. A maneira como os popovers funcionam atualmente é que, uma vez exibidos, seu conteúdo é vinculado ao elemento de gatilho com o aria-describedbyatributo. Como resultado, todo o conteúdo do popover será anunciado aos usuários de tecnologia assistiva como um fluxo longo e ininterrupto.

Além disso, embora seja possível incluir também controles interativos (como elementos de formulário ou links) em seu popover (adicionando esses elementos aos allowListatributos e tags permitidos), esteja ciente de que atualmente o popover não gerencia a ordem de foco do teclado. Quando um usuário de teclado abre um popover, o foco permanece no elemento acionador e, como o popover geralmente não segue imediatamente o acionador na estrutura do documento, não há garantia de que avançar/pressionarTABmoverá um usuário de teclado para o próprio popover. Em suma, simplesmente adicionar controles interativos a um popover provavelmente tornará esses controles inacessíveis/inutilizáveis ​​para usuários de teclado e usuários de tecnologias assistivas, ou pelo menos criar uma ordem de foco geral ilógica. Nesses casos, considere usar uma caixa de diálogo modal.

Opções

As opções podem ser passadas por meio de atributos de dados ou JavaScript. Para atributos de dados, anexe o nome da opção a data-bs-, como em data-bs-animation="". 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, em vez de usar data-bs-customClass="beautifier", use data-bs-custom-class="beautifier".

Observe que, por motivos de segurança, as sanitizeopções sanitizeFn, e allowListnão podem ser fornecidas usando atributos de dados.
Nome Modelo Predefinição Descrição
animation boleano true Aplicar uma transição de fade CSS ao popover
container seqüência | elemento | falso false

Acrescenta o popover a um elemento específico. Exemplo: container: 'body'. Esta opção é particularmente útil porque permite que você posicione o popover no fluxo do documento próximo ao elemento acionador - o que impedirá que o popover flutue para longe do elemento acionador durante o redimensionamento da janela.

content seqüência | elemento | função ''

Valor de conteúdo padrão se data-bs-contento atributo não estiver presente.

Se uma função for fornecida, ela será chamada com sua thisreferência definida para o elemento ao qual o popover está anexado.

delay número | objeto 0

Atraso na exibição e ocultação do popover (ms) - não se aplica ao tipo de gatilho manual

Se um número for fornecido, o atraso será aplicado tanto para ocultar/exibir

A estrutura do objeto é:delay: { "show": 500, "hide": 100 }

html boleano false Insira o HTML no popover. Se false, innerTexta propriedade será usada para inserir conteúdo no DOM. Use texto se estiver preocupado com ataques XSS.
placement seqüência | função 'right'

Como posicionar o popover - auto | topo | inferior | esquerda | certo.
Quando autofor especificado, ele reorientará dinamicamente o popover.

Quando uma função é usada para determinar o posicionamento, ela é chamada com o nó DOM popover como seu primeiro argumento e o nó DOM do elemento acionador como seu segundo. O thiscontexto é definido para a instância popover.

selector seqüência | falso false Se um seletor for fornecido, os objetos popover serão delegados aos destinos especificados. Na prática, isso é usado para permitir que o conteúdo HTML dinâmico tenha popovers adicionados. Veja este e um exemplo informativo .
template corda '<div class="popover" role="tooltip"><div class="popover-arrow"></div><h3 class="popover-header"></h3><div class="popover-body"></div></div>'

HTML base para usar ao criar o popover.

Os popovers titleserão injetados no arquivo .popover-header.

Os popovers contentserão injetados no arquivo .popover-body.

.popover-arrowse tornará a seta do popover.

O elemento wrapper mais externo deve ter a .popoverclasse.

title seqüência | elemento | função ''

Valor de título padrão se o titleatributo não estiver presente.

Se uma função for fornecida, ela será chamada com sua thisreferência definida para o elemento ao qual o popover está anexado.

trigger corda 'click' Como o popover é acionado - clique | pairar | foco | manual. Você pode passar vários gatilhos; separe-os com um espaço. manualnão pode ser combinado com nenhum outro gatilho.
fallbackPlacements variedade ['top', 'right', 'bottom', 'left'] Defina as veiculações de fallback fornecendo uma lista de veiculações na matriz (em ordem de preferência). Para obter mais informações, consulte os documentos de comportamento de Popper
boundary seqüência | elemento 'clippingParents' Limite de restrição de estouro do popover (aplica-se apenas ao modificador preventOverflow do Popper). Por padrão, é 'clippingParents'e pode aceitar uma referência HTMLElement (somente via JavaScript). Para obter mais informações, consulte os documentos detectOverflow do Popper .
customClass seqüência | função ''

Adicione classes ao popover quando ele for exibido. Observe que essas classes serão adicionadas além de quaisquer classes especificadas no modelo. Para adicionar várias classes, separe-as com espaços: 'class-1 class-2'.

Você também pode passar uma função que deve retornar uma única string contendo nomes de classes adicionais.

sanitize boleano true Habilite ou desabilite a higienização. Se ativado 'template', 'content'as 'title'opções serão higienizadas. Consulte a seção de limpeza em nossa documentação JavaScript .
allowList objeto Valor padrão Objeto que contém atributos e tags permitidos
sanitizeFn nulo | função null Aqui você pode fornecer sua própria função de higienização. Isso pode ser útil se você preferir usar uma biblioteca dedicada para realizar a higienização.
offset matriz | seqüência | função [0, 8]

Deslocamento do popover em relação ao seu destino. Você pode passar uma string em atributos de dados com valores separados por vírgulas como:data-bs-offset="10,20"

Quando uma função é usada para determinar o deslocamento, ela é chamada com um objeto contendo o posicionamento do popper, a referência e os retos do popper como seu primeiro argumento. O nó DOM do elemento acionador é passado como o segundo argumento. A função deve retornar um array com dois números: .[skidding, distance]

Para obter mais informações, consulte os documentos de deslocamento de Popper .

popperConfig nulo | objeto | função null

Para alterar a configuração padrão do Popper do Bootstrap, consulte a configuração do Popper .

Quando uma função é usada para criar a configuração do Popper, ela é chamada com um objeto que contém a configuração padrão do Popper do Bootstrap. Ele ajuda você a usar e mesclar o padrão com sua própria configuração. A função deve retornar um objeto de configuração para Popper.

Atributos de dados para popovers individuais

Opções para popovers individuais podem ser especificadas alternativamente através do uso de atributos de dados, conforme explicado acima.

Usando a função compopperConfig

var popover = new bootstrap.Popover(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

Métodos

Métodos e transições assíncronas

Todos os métodos de API são assíncronos e iniciam uma transição . Eles retornam ao chamador assim que a transição é iniciada, mas antes que ela termine . Além disso, uma chamada de método em um componente de transição será ignorada .

Consulte nossa documentação JavaScript para obter mais informações .

mostrar

Revela o popover de um elemento. Retorna ao chamador antes que o popover tenha sido realmente mostrado (ou seja, antes que o shown.bs.popoverevento ocorra). Isso é considerado um acionamento “manual” do popover. Os popovers cujo título e conteúdo são ambos de comprimento zero nunca são exibidos.

myPopover.show()

ocultar

Oculta o popover de um elemento. Retorna ao chamador antes que o popover tenha sido ocultado (ou seja, antes que o hidden.bs.popoverevento ocorra). Isso é considerado um acionamento “manual” do popover.

myPopover.hide()

alternar

Alterna o popover de um elemento. Retorna ao chamador antes que o popover tenha sido exibido ou ocultado (ou seja, antes que o evento shown.bs.popoverou hidden.bs.popoverocorra). Isso é considerado um acionamento “manual” do popover.

myPopover.toggle()

dispor

Oculta e destrói o popover de um elemento (remove os dados armazenados no elemento DOM). Popovers que usam delegação (que são criados usando a selectoropção ) não podem ser destruídos individualmente em elementos de disparo descendentes.

myPopover.dispose()

permitir

Dá ao popover de um elemento a capacidade de ser mostrado. Os popovers são ativados por padrão.

myPopover.enable()

desativar

Remove a capacidade de mostrar o popover de um elemento. O popover só poderá ser exibido se for reativado.

myPopover.disable()

alternarAtivado

Alterna a capacidade de mostrar ou ocultar o popover de um elemento.

myPopover.toggleEnabled()

atualizar

Atualiza a posição do popover de um elemento.

myPopover.update()

getInstance

Método estático que permite obter a instância popover associada a um elemento DOM

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

getOrCreateInstance

Método estático que permite obter a instância popover associada a um elemento DOM ou criar uma nova caso não tenha sido inicializada

var exampleTriggerEl = document.getElementById('example')
var popover = bootstrap.Popover.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap popover instance

Eventos

Tipo de evento Descrição
show.bs.popover Este evento é acionado imediatamente quando o showmétodo de instância é chamado.
mostrado.bs.popover Este evento é acionado quando o popover se torna visível para o usuário (aguardará a conclusão das transições CSS).
hide.bs.popover Este evento é acionado imediatamente quando o hidemétodo de instância é chamado.
oculto.bs.popover Este evento é acionado quando o popover termina de ser ocultado do usuário (aguardará a conclusão das transições CSS).
inserido.bs.popover Este evento é acionado após o show.bs.popoverevento quando o modelo popover foi adicionado ao DOM.
var myPopoverTrigger = document.getElementById('myPopover')
myPopoverTrigger.addEventListener('hidden.bs.popover', function () {
  // do something...
})