Dicas de ferramentas

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!
• 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.

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-bs-toggleatributo:

var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl)
})

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. As direções são espelhadas ao usar o Bootstrap em RTL.

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

E com HTML personalizado adicionado:

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

Com um SVG:

Sass

Variáveis

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     $white;
$tooltip-bg:                        $black;
$tooltip-border-radius:             $border-radius;
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    0;

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
$tooltip-arrow-color:               $tooltip-bg;

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:

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
  boundary: document.body // or document.querySelector('#boundary')
})

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

<!-- HTML to write -->
<a href="#" data-bs-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="tooltip-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".

<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="Disabled tooltip">
  <button class="btn btn-primary" 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-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".

Usando a função compopperConfig

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

Métodos

mostrar

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.

tooltip.show()

ocultar

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.

tooltip.hide()

alternar

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.

tooltip.toggle()

dispor

Oculta e destrói a dica de ferramenta de um elemento (remove os dados armazenados no elemento DOM). 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.

tooltip.dispose()

permitir

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

tooltip.enable()

desativar

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

tooltip.disable()

alternarAtivado

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

tooltip.toggleEnabled()

atualizar

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

tooltip.update()

getInstance

Método estático que permite obter a instância da dica de ferramenta associada a um elemento DOM

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

getOrCreateInstance

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

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

Eventos

var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
  // do something...
})

tooltip.hide()