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 bootstrap.jsde , ou usar um bootstrap.bundle.min.jsque contenha Popper.
• 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.

Exemplos

Ativar dicas de ferramentas

Conforme mencionado acima, você deve inicializar as dicas de ferramentas antes que elas possam ser usadas. Uma maneira de inicializar todas as dicas de ferramentas em uma página seria selecioná-las por seu data-bs-toggleatributo, assim:

const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))

Dicas de ferramentas sobre links

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

<p class="muted">Placeholder text to demonstrate some <a href="#" data-bs-toggle="tooltip" data-bs-title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-bs-toggle="tooltip" data-bs-title="Another tooltip">real text</a>. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you've now seen how <a href="#" data-bs-toggle="tooltip" data-bs-title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-bs-toggle="tooltip" data-bs-title="The last tip!">your own</a> site or project.
</p>

Dicas de ferramentas personalizadas

Você pode personalizar a aparência das dicas de ferramentas usando variáveis ​​CSS . Definimos uma classe personalizada com data-bs-custom-class="custom-tooltip"o escopo de nossa aparência personalizada e a usamos para substituir uma variável CSS local.

.custom-tooltip {
  --bs-tooltip-bg: var(--bs-primary);
}

<button type="button" class="btn btn-secondary"
        data-bs-toggle="tooltip" data-bs-placement="top"
        data-bs-custom-class="custom-tooltip"
        data-bs-title="This top tooltip is themed via CSS variables.">
  Custom tooltip
</button>

instruções

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" data-bs-title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" data-bs-title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" data-bs-title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" data-bs-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" data-bs-title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

Com um SVG:

CSS

Variáveis

Como parte da abordagem de variáveis ​​CSS em evolução do Bootstrap, as dicas de ferramentas agora usam variáveis ​​CSS locais .tooltippara personalização aprimorada em tempo real. Os valores das variáveis ​​CSS são definidos por meio do Sass, portanto, a personalização do Sass também é suportada.

  --#{$prefix}tooltip-zindex: #{$zindex-tooltip};
  --#{$prefix}tooltip-max-width: #{$tooltip-max-width};
  --#{$prefix}tooltip-padding-x: #{$tooltip-padding-x};
  --#{$prefix}tooltip-padding-y: #{$tooltip-padding-y};
  --#{$prefix}tooltip-margin: #{$tooltip-margin};
  @include rfs($tooltip-font-size, --#{$prefix}tooltip-font-size);
  --#{$prefix}tooltip-color: #{$tooltip-color};
  --#{$prefix}tooltip-bg: #{$tooltip-bg};
  --#{$prefix}tooltip-border-radius: #{$tooltip-border-radius};
  --#{$prefix}tooltip-opacity: #{$tooltip-opacity};
  --#{$prefix}tooltip-arrow-width: #{$tooltip-arrow-width};
  --#{$prefix}tooltip-arrow-height: #{$tooltip-arrow-height};
  

Variáveis ​​atrevidas

$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:                    null; // TODO: remove this in v6

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
// fusv-disable
$tooltip-arrow-color:               null; // Deprecated in Bootstrap 5.2.0 for CSS variables
// fusv-enable

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:

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

const tooltip = new bootstrap.Tooltip('#example', {
  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" data-bs-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" data-bs-title="Disabled tooltip">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

Opções

Como as opções podem ser passadas por meio de atributos de dados ou JavaScript, você pode anexar um nome de opção a data-bs-, como em data-bs-animation="{value}". 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, use data-bs-custom-class="beautifier"em vez de data-bs-customClass="beautifier".

A partir do Bootstrap 5.2.0, todos os componentes oferecem suporte a um atributo experimental de dados reservados data-bs-configque pode abrigar a configuração simples do componente como uma string JSON. Quando um elemento tem atributos data-bs-config='{"delay":0, "title":123}'e data-bs-title="456", o valor final titleserá 456e os atributos de dados separados substituirão os valores fornecidos em data-bs-config. Além disso, os atributos de dados existentes podem hospedar valores JSON como data-bs-delay='{"show":0,"hide":150}'.

Usando a função compopperConfig

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

Métodos

const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })

Eventos

const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

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

tooltip.hide()