Source

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.js para posicionamento. Você deve incluir popper.min.js antes de bootstrap.js ou usar bootstrap.bundle.min.js/ bootstrap.bundle.jsque contém Popper.js 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.

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:

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 `auto`e`scroll`

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 `title`serão renderizadas na dica de ferramenta. Se false, o `text`mé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 `auto`for 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 `this`contexto é 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.on`suporte). 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 `title`serão injetadas no arquivo `.tooltip-inner`. `.arrow`se tornará a seta da dica de ferramenta. O elemento wrapper mais externo deve ter a `.tooltip`classe e `role="tooltip"`.
título	seqüência \| elemento \| função	''	Valor de título padrão se o `title`atributo não estiver presente. Se uma função for fornecida, ela será chamada com sua `this`referê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 do Popper.js .
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 do Popper.js
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.js .
higienizar	boleano	verdadeiro	Habilite ou desabilite a higienização. Se ativado `'template'`e `'title'`as opções serão higienizadas.
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.js do Bootstrap, consulte a configuração do Popper.js

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 `show`mé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 `hide`mé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.tooltip`evento quando o modelo de dica de ferramenta foi adicionado ao DOM.

$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})

Dicas de ferramentas

Visão geral

Exemplo: ativar dicas de ferramentas em todos os lugares

Exemplos

Uso

Estouro autoescroll

Marcação

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

Elementos desativados

Opções

Atributos de dados para dicas de ferramentas individuais

Métodos

Métodos e transições assíncronas

$().tooltip(options)

.tooltip('show')

.tooltip('hide')

.tooltip('toggle')

.tooltip('dispose')

.tooltip('enable')

.tooltip('disable')

.tooltip('toggleEnabled')

.tooltip('update')