in English

Dicas de ferramentas

Documentação e exemplos para adicionar dicas de ferramentas personalizadas do Bootstrap com CSS e JavaScript usando CSS3 para animações e atributos de dados para armazenamento local de títulos.

Visão geral

Coisas para saber ao usar o plug-in de dica de ferramenta:

  • As dicas de ferramentas 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 as dicas de ferramentas funcionem!
  • Se você estiver construindo nosso JavaScript a partir da fonte, ele requerutil.js .
  • As dicas de ferramentas são opcionais por motivos de desempenho, portanto, você deve inicializá-las .
  • Dicas de ferramentas com títulos de comprimento zero nunca são exibidas.
  • Especifique container: 'body'para evitar problemas de renderização em componentes mais complexos (como nossos grupos de entrada, grupos de botões etc.).
  • Acionar dicas de ferramentas em elementos ocultos não funcionará.
  • As dicas de ferramentas para .disabledou disabledelementos devem ser acionadas em um elemento wrapper.
  • Quando acionado a partir de hiperlinks que abrangem várias linhas, as dicas de ferramentas serão centralizadas. Use white-space: nowrap;em seus <a>s para evitar esse comportamento.
  • As dicas de ferramentas devem ser ocultadas antes que seus elementos correspondentes sejam removidos do DOM.
  • As dicas de ferramentas podem ser acionadas 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 .

Tem tudo isso? Ótimo, vamos ver como eles funcionam com alguns exemplos.

Exemplo: ativar dicas de ferramentas em todos os lugares

Uma maneira de inicializar todas as dicas de ferramentas em uma página seria selecioná-las por seu data-toggleatributo:

$(function () {
  $('[data-toggle="tooltip"]').tooltip()
})

Exemplos

Passe o mouse sobre os links abaixo para ver dicas de ferramentas:

Texto de espaço reservado para demonstrar alguns links embutidos com dicas de ferramentas. Isso agora é apenas enchimento, não assassino. Conteúdo colocado aqui apenas para imitar a presença de texto real . E tudo isso apenas para dar uma ideia de como as dicas de ferramentas ficariam quando usadas em situações do mundo real. Espero que você já tenha visto como essas dicas de ferramentas em links podem funcionar na prática, uma vez que você as use em seu próprio site ou projeto.

Passe o mouse sobre os botões abaixo para ver as quatro direções das dicas de ferramentas: superior, direita, inferior e esquerda.

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">
  Tooltip on left
</button>

E com HTML personalizado adicionado:

<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

Uso

O plug-in de dica de ferramenta gera conteúdo e marcação sob demanda e, por padrão, coloca dicas de ferramenta após o elemento de acionamento.

Acione a dica de ferramenta via JavaScript:

$('#example').tooltip(options)
Estouro autoescroll

A posição da dica de ferramenta tenta mudar automaticamente quando um contêiner pai tem overflow: autoou overflow: scrollgosta de nosso .table-responsive, mas ainda mantém o posicionamento do posicionamento original. Para resolver, defina a boundaryopção para algo diferente do valor padrão 'scrollParent', como 'window':

$('#example').tooltip({ boundary: 'window' })

Marcação

A marcação necessária para uma dica de ferramenta é apenas um dataatributo e titleno elemento HTML você deseja ter uma dica de ferramenta. A marcação gerada de uma dica de ferramenta é bastante simples, embora exija uma posição (por padrão, definida toppelo plug-in).

Como fazer com que as dicas de ferramentas funcionem para usuários de teclado e tecnologia assistiva

Você só deve adicionar dicas de ferramentas 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 a dica de ferramenta nessa situação. Além disso, não confie apenas no hovergatilho para sua dica de ferramenta, pois isso tornará suas dicas de ferramenta impossíveis de serem acionadas para usuários de teclado.

<!-- HTML to write -->
<a href="#" data-toggle="tooltip" title="Some tooltip text!">Hover over me</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-top" role="tooltip">
  <div class="arrow"></div>
  <div class="tooltip-inner">
    Some tooltip text!
  </div>
</div>

Elementos desativados

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

<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="Disabled tooltip">
  <button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>

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-, como em data-animation="".

Observe que, por motivos de segurança, as sanitizeopções sanitizeFne whiteListnão podem ser fornecidas usando atributos de dados.
Nome Modelo Predefinição Descrição
animação boleano verdadeiro Aplicar uma transição de fade CSS à dica de ferramenta
recipiente seqüência | elemento | falso falso

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

Atraso na exibição e ocultação da dica de ferramenta (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 falso

Permitir HTML na dica de ferramenta.

Se true, as tags HTML na dica de ferramenta titleserão renderizadas na dica de ferramenta. Se false, o textmétodo do jQuery será usado para inserir conteúdo no DOM.

Use texto se estiver preocupado com ataques XSS.
colocação seqüência | função 'topo'

Como posicionar a dica de ferramenta - auto | topo | inferior | esquerda | certo.
Quando autofor especificado, ele reorientará dinamicamente a dica de ferramenta.

Quando uma função é usada para determinar o posicionamento, ela é chamada com o nó DOM da dica de ferramenta como seu primeiro argumento e o nó DOM do elemento acionador como seu segundo. O thiscontexto é definido para a instância da dica de ferramenta.
seletor seqüência | falso falso Se um seletor for fornecido, os objetos de dica de ferramenta serão delegados aos destinos especificados. Na prática, isso também é usado para aplicar dicas de ferramentas a elementos DOM adicionados dinamicamente ( jQuery.onsuporte). Veja este e um exemplo informativo .
modelo corda '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

HTML base a ser usado ao criar a dica de ferramenta.

As dicas de ferramentas titleserão injetadas no arquivo .tooltip-inner.

.arrowse tornará a seta da dica de ferramenta.

O elemento wrapper mais externo deve ter a .tooltipclasse e role="tooltip".
título 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 a dica de ferramenta está anexada.
acionar corda 'foco flutuante'

Como a dica de ferramenta é acionada - clique | pairar | foco | manual. Você pode passar vários gatilhos; separe-os com um espaço.

'manual'indica que a dica de ferramenta será acionada programaticamente por meio dos métodos .tooltip('show'), .tooltip('hide')e ; .tooltip('toggle')este valor não pode ser combinado com nenhum outro acionador.

'hover'por si só resultará em dicas de ferramentas que não podem ser acionadas pelo teclado e só devem ser usadas se houver métodos alternativos para transmitir as mesmas informações para usuários de teclado.
Deslocamento número | seqüência | função 0

Deslocamento da dica de ferramenta em relação ao seu destino.

Quando uma função é usada para determinar o deslocamento, ela é chamada com um objeto contendo os dados do deslocamento como seu primeiro argumento. A função deve retornar um objeto com a mesma estrutura. O nó DOM do elemento acionador é passado como o segundo argumento.

Para obter mais informações, consulte os documentos de deslocamento de Popper .
fallbackPlace seqüência | variedade 'virar' Permite especificar qual posição o Popper usará no fallback. Para obter mais informações, consulte os documentos de comportamento de Popper
customClass seqüência | função ''

Adicione classes à dica de ferramenta quando ela for exibida. 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: 'a b'.

Você também pode passar uma função que deve retornar uma única string contendo nomes de classes adicionais.
fronteira seqüência | elemento 'scrollParent' Limite de restrição de estouro da dica de ferramenta. Aceita os valores de 'viewport', 'window', 'scrollParent'ou uma referência HTMLElement (somente JavaScript). Para obter mais informações, consulte os documentos preventOverflow do Popper .
higienizar boleano verdadeiro Habilite ou desabilite a higienização. Se ativado 'template'e 'title'as opções serão higienizadas. Consulte a seção de limpeza em nossa documentação JavaScript .
lista branca objeto Valor padrão Objeto que contém atributos e tags permitidos
higienizarFn nulo | função nulo 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.
popperConfig nulo | objeto nulo Para alterar a configuração padrão do Popper do Bootstrap, consulte a configuração do Popper

Atributos de dados para dicas de ferramentas individuais

Opções para dicas de ferramentas individuais podem ser especificadas alternativamente por meio do uso de atributos de dados, conforme explicado acima.

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 .

$().tooltip(options)

Anexa um manipulador de dica de ferramenta a uma coleção de elementos.

.tooltip('show')

Revela a dica de ferramenta de um elemento. Retorna ao chamador antes que a dica de ferramenta tenha sido mostrada (ou seja, antes que o shown.bs.tooltipevento ocorra). Isso é considerado um acionamento “manual” da dica de ferramenta. Dicas de ferramentas com títulos de comprimento zero nunca são exibidas.

$('#element').tooltip('show')

.tooltip('hide')

Oculta a dica de ferramenta de um elemento. Retorna ao chamador antes que a dica de ferramenta tenha sido ocultada (ou seja, antes que o hidden.bs.tooltipevento ocorra). Isso é considerado um acionamento “manual” da dica de ferramenta.

$('#element').tooltip('hide')

.tooltip('toggle')

Alterna a dica de ferramenta de um elemento. Retorna ao chamador antes que a dica de ferramenta tenha sido mostrada ou ocultada (ou seja, antes que o evento shown.bs.tooltipou hidden.bs.tooltipocorra). Isso é considerado um acionamento “manual” da dica de ferramenta.

$('#element').tooltip('toggle')

.tooltip('dispose')

Oculta e destrói a dica de ferramenta de um elemento. As dicas de ferramentas que usam delegação (que são criadas usando a selectoropção ) não podem ser destruídas individualmente em elementos acionadores descendentes.

$('#element').tooltip('dispose')

.tooltip('enable')

Dá à dica de ferramenta de um elemento a capacidade de ser mostrada. As dicas de ferramentas são habilitadas por padrão.

$('#element').tooltip('enable')

.tooltip('disable')

Remove a capacidade de mostrar a dica de ferramenta de um elemento. A dica de ferramenta só poderá ser exibida se for reativada.

$('#element').tooltip('disable')

.tooltip('toggleEnabled')

Alterna a capacidade de mostrar ou ocultar a dica de ferramenta de um elemento.

$('#element').tooltip('toggleEnabled')

.tooltip('update')

Atualiza a posição da dica de ferramenta de um elemento.

$('#element').tooltip('update')

Eventos

Tipo de evento Descrição
show.bs.dica Este evento é acionado imediatamente quando o showmétodo de instância é chamado.
mostrado.bs.dica Este evento é acionado quando a dica de ferramenta se torna visível para o usuário (aguardará a conclusão das transições CSS).
hide.bs.dica Este evento é acionado imediatamente quando o hidemétodo de instância é chamado.
hidden.bs.dica de ferramenta Este evento é acionado quando a dica de ferramenta termina de ser ocultada do usuário (aguardará a conclusão das transições CSS).
insert.bs.dica de ferramenta Este evento é acionado após o show.bs.tooltipevento quando o modelo de dica de ferramenta foi adicionado ao DOM. 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})