Suxestións sobre ferramentas
Documentación e exemplos para engadir consellos de ferramentas de Bootstrap personalizados con CSS e JavaScript usando CSS3 para animacións e atributos data-bs para o almacenamento local de títulos.
Visión xeral
Cousas que debes saber ao usar o complemento de información sobre ferramentas:
- As informacións sobre ferramentas dependen da biblioteca de terceiros Popper para o posicionamento. Debes incluír popper.min.js antes de bootstrap.js ou usar
bootstrap.bundle.min.js
/bootstrap.bundle.js
que contén Popper para que funcionen as informacións sobre ferramentas. - As informacións sobre ferramentas están activadas por motivos de rendemento, polo que debes inicialalas ti mesmo .
- Os consellos de ferramentas con títulos de lonxitude cero nunca se amosan.
- Especifique
container: 'body'
para evitar problemas de renderizado en compoñentes máis complexos (como os nosos grupos de entrada, grupos de botóns, etc.). - Non funcionará activar consellos sobre elementos ocultos.
- As informacións sobre ferramentas para
.disabled
oudisabled
elementos deben activarse nun elemento de envoltura. - Cando se activa desde hipervínculos que abranguen varias liñas, centraranse as suxestións sobre ferramentas. Use
white-space: nowrap;
no seu<a>
s para evitar este comportamento. - As informacións sobre ferramentas deben ocultarse antes de que se eliminen do DOM os seus elementos correspondentes.
- As informacións sobre ferramentas pódense activar grazas a un elemento dentro dun DOM en sombra.
prefers-reduced-motion
consulta multimedia. Consulta a
sección de movemento reducido da nosa documentación de accesibilidade .
Tes todo iso? Xenial, vexamos como funcionan con algúns exemplos.
Exemplo: activa as informacións sobre ferramentas en todas partes
Unha forma de inicializar todas as suxestións dunha páxina sería seleccionalas polo seu data-bs-toggle
atributo:
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
return new bootstrap.Tooltip(tooltipTriggerEl)
})
Exemplos
Pasa o cursor polas seguintes ligazóns para ver consellos:
Texto do marcador de posición para mostrar algunhas ligazóns en liña con información sobre ferramentas. Isto agora é só recheo, non asasino. Contido colocado aquí só para imitar a presenza de texto real . E todo iso só para darche unha idea de como se verían as informacións sobre ferramentas cando se usasen en situacións reais. Entón, esperamos que xa vira como estas suxestións sobre ligazóns poden funcionar na práctica, unha vez que as utilice no seu propio sitio ou proxecto.
Pasa o cursor sobre os botóns de abaixo para ver as catro indicacións das ferramentas: arriba, dereita, inferior e esquerda. As indicacións replícanse cando se usa Bootstrap en 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 con HTML personalizado engadido:
<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>
Cun SVG:
Sass
Variables
$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 complemento de información sobre ferramentas xera contido e marcas baixo demanda e, por defecto, coloca as informacións sobre ferramentas despois do seu elemento de activación.
Activa a información sobre ferramentas mediante JavaScript:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Desbordamento auto
escroll
A posición da información sobre ferramentas tenta cambiar automaticamente cando un contedor principal ten overflow: auto
ou overflow: scroll
gústalle o noso .table-responsive
, pero aínda así mantén a posición da ubicación orixinal. Para resolver isto, configure a boundary
opción (para o modificador de voltar usando a popperConfig
opción) en calquera elemento HTML para anular o valor predeterminado 'clippingParents'
, como document.body
:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
boundary: document.body // or document.querySelector('#boundary')
})
Marcado
O marcado necesario para unha información sobre ferramentas é só un data
atributo e title
no elemento HTML desexa ter unha información sobre ferramentas. O marcado xerado dunha información sobre ferramentas é bastante sinxelo, aínda que require unha posición (por defecto, definida top
polo complemento).
Facendo que as informacións sobre ferramentas funcionen para os usuarios de teclado e tecnoloxía de asistencia
Só deberías engadir información sobre ferramentas aos elementos HTML que tradicionalmente se centran no teclado e son interactivos (como ligazóns ou controis de formulario). Aínda que os elementos HTML arbitrarios (como <span>
s) pódense enfocar engadindo o tabindex="0"
atributo, isto engadirá tabulacións potencialmente molestas e confusas en elementos non interactivos para os usuarios de teclado, e a maioría das tecnoloxías de asistencia actualmente non anuncian a información sobre ferramentas nesta situación. Ademais, non te basees só hover
como activador da túa información sobre ferramentas, xa que isto fará que as túas informacións sobre ferramentas sexan imposibles de activar para os usuarios do teclado.
<!-- 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 desactivados
Os elementos co disabled
atributo non son interactivos, o que significa que os usuarios non poden enfocar, pasar o rato ou facer clic neles para activar unha información (ou popover). Como solución alternativa, quererá activar a información sobre ferramentas desde un envoltorio <div>
ou <span>
, idealmente enfocado ao 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>
Opcións
As opcións pódense pasar a través de atributos de datos ou JavaScript. Para os atributos de datos, engada o nome da opción a data-bs-
, como en data-bs-animation=""
. Asegúrate de cambiar o tipo de maiúsculas e minúsculas do nome da opción de camelCase a kebab-case ao pasar as opcións a través dos atributos de datos. Por exemplo, en lugar de usar data-bs-customClass="beautifier"
, use data-bs-custom-class="beautifier"
.
sanitize
,
sanitizeFn
, e
allowList
non se poden proporcionar mediante atributos de datos.
Nome | Tipo | Por defecto | Descrición |
---|---|---|---|
animation |
booleano | true |
Aplique unha transición de fundido CSS á información sobre ferramentas |
container |
cadea | elemento | falso | false |
Engade a información sobre ferramentas a un elemento específico. Exemplo: |
delay |
número | obxecto | 0 |
Atraso para mostrar e ocultar a información sobre ferramentas (ms): non se aplica ao tipo de activación manual Se se proporciona un número, aplícase un atraso tanto para ocultar como para mostrar A estrutura do obxecto é: |
html |
booleano | false |
Permitir HTML na información sobre ferramentas. Se é verdadeiro, as etiquetas HTML da información sobre ferramentas Usa texto se estás preocupado polos ataques XSS. |
placement |
cadea | función | 'top' |
Como colocar a información sobre ferramentas - auto | arriba | inferior | esquerda | certo. Cando se usa unha función para determinar a colocación, chámase co nodo DOM de información sobre ferramentas como primeiro argumento e o nodo DOM do elemento desencadeante como segundo. O |
selector |
cadea | falso | false |
Se se proporciona un selector, os obxectos de información sobre ferramentas delegaranse nos obxectivos especificados. Na práctica, utilízase tamén para aplicar información sobre ferramentas aos elementos DOM engadidos de forma dinámica ( jQuery.on soporte). Vexa isto e un exemplo informativo . |
template |
corda | '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' |
HTML base para usar ao crear a información sobre ferramentas. A información de ferramentas
O elemento de envoltura máis externo debe ter a |
title |
cadea | elemento | función | '' |
Valor predeterminado do título se Se se dá unha función, chamarase coa súa |
trigger |
corda | 'hover focus' |
Como se activa a información sobre ferramentas: fai clic en | pasar o rato | foco | manual. Podes pasar varios disparadores; separalos cun espazo.
|
fallbackPlacements |
matriz | ['top', 'right', 'bottom', 'left'] |
Defina colocacións alternativas proporcionando unha lista de colocacións na matriz (por orde de preferencia). Para obter máis información, consulte os documentos de comportamento de Popper |
boundary |
cadea | elemento | 'clippingParents' |
Límite de restricción de desbordamento da información sobre ferramentas (aplícase só ao modificador preventOverflow de Popper). Por defecto é 'clippingParents' e pode aceptar unha referencia HTMLElement (só a través de JavaScript). Para obter máis información, consulte os documentos detectOverflow de Popper . |
customClass |
cadea | función | '' |
Engade clases á información sobre ferramentas cando se mostra. Teña en conta que estas clases engadiranse ademais de todas as clases especificadas no modelo. Para engadir varias clases, sepáraas con espazos: Tamén pode pasar unha función que debería devolver unha única cadea que conteña nomes de clases adicionais. |
sanitize |
booleano | true |
Activa ou desactiva a desinfección. Se está activado 'template' e 'title' as opcións desinfectaranse. Consulte a sección de desinfectantes na nosa documentación de JavaScript . |
allowList |
obxecto | Valor predeterminado | Obxecto que contén atributos e etiquetas permitidos |
sanitizeFn |
nulo | función | null |
Aquí podes proporcionar a túa propia función de desinfección. Isto pode ser útil se prefires usar unha biblioteca dedicada para realizar a desinfección. |
offset |
matriz | cadea | función | [0, 0] |
Desfase da información sobre ferramentas en relación ao seu obxectivo. Podes pasar unha cadea en atributos de datos con valores separados por comas como: Cando se usa unha función para determinar a compensación, chámase cun obxecto que contén a posición do popper, a referencia e os rectos do popper como primeiro argumento. O nodo DOM do elemento desencadeante pásase como segundo argumento. A función debe devolver unha matriz con dous números: . Para obter máis información, consulte os documentos de offset de Popper . |
popperConfig |
nulo | obxecto | función | null |
Para cambiar a configuración de Popper predeterminada de Bootstrap, consulte Configuración de Popper . Cando se usa unha función para crear a configuración Popper, chámase cun obxecto que contén a configuración Popper predeterminada de Bootstrap. Axúdache a usar e combinar a configuración predeterminada coa túa propia configuración. A función debe devolver un obxecto de configuración para Popper. |
Atributos de datos para información sobre ferramentas individuais
Alternativamente, pódense especificar opcións para consellos individuais mediante o uso de atributos de datos, como se explicou anteriormente.
Usando a función conpopperConfig
var tooltip = new bootstrap.Tooltip(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
Métodos
Métodos asíncronos e transicións
Todos os métodos da API son asíncronos e inician unha transición . Volven ao interlocutor en canto se inicia a transición pero antes de que remate . Ademais, ignorarase unha chamada de método nun compoñente en transición .
Consulte a nosa documentación de JavaScript para obter máis información .
mostrar
Revela a información sobre ferramentas dun elemento. Volve ao interlocutor antes de que se amosase a información sobre ferramentas (é dicir, antes de shown.bs.tooltip
que se produza o evento). Isto considérase unha activación "manual" da información sobre ferramentas. Os consellos de ferramentas con títulos de lonxitude cero nunca se amosan.
tooltip.show()
ocultar
Oculta a información sobre ferramentas dun elemento. Volve ao interlocutor antes de que se ocultase a información sobre ferramentas (é dicir, antes de hidden.bs.tooltip
que se produza o evento). Isto considérase unha activación "manual" da información sobre ferramentas.
tooltip.hide()
alternar
Alterna a información sobre ferramentas dun elemento. Volve ao interlocutor antes de que se amosase ou ocultase a información sobre ferramentas (é dicir, antes de que se produza o evento shown.bs.tooltip
ou ). hidden.bs.tooltip
Isto considérase unha activación "manual" da información sobre ferramentas.
tooltip.toggle()
dispor
Oculta e destrúe a información sobre ferramentas dun elemento (Elimina os datos almacenados no elemento DOM). As informacións sobre ferramentas que usan a delegación (que se crean mediante a selector
opción ) non se poden destruír individualmente nos elementos desencadeantes descendentes.
tooltip.dispose()
habilitar
Dá a información sobre ferramentas dun elemento a posibilidade de mostrarse. As informacións sobre ferramentas están activadas por defecto.
tooltip.enable()
desactivar
Elimina a posibilidade de mostrar a información sobre ferramentas dun elemento. A información sobre ferramentas só se poderá mostrar se se volve activar.
tooltip.disable()
alternar Activado
Alterna a posibilidade de mostrar ou ocultar a información sobre ferramentas dun elemento.
tooltip.toggleEnabled()
actualizar
Actualiza a posición da información sobre ferramentas dun elemento.
tooltip.update()
getInstance
Método estático que lle permite obter a instancia de información sobre ferramentas asociada a un elemento DOM
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
getOrCreateInstance
Método estático que che permite obter a instancia de información sobre ferramentas asociada a un elemento DOM ou crear unha nova no caso de que non se inicializou
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
Eventos
Tipo de evento | Descrición |
---|---|
show.bs.tooltip |
Este evento desenvólvese inmediatamente cando show se chama ao método de instancia. |
shown.bs.tooltip |
Este evento desenvólvese cando a información sobre ferramentas se fixo visible para o usuario (esperará a que se completen as transicións CSS). |
hide.bs.tooltip |
Este evento desenvólvese inmediatamente cando hide se chamou ao método de instancia. |
hidden.bs.tooltip |
Este evento desenvólvese cando a información sobre ferramentas rematou de ocultarse ao usuario (esperará a que se completen as transicións CSS). |
inserted.bs.tooltip |
Este evento desenvólvese despois do show.bs.tooltip evento cando se engadiu o modelo de información sobre ferramentas ao DOM. |
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)
myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
// do something...
})
tooltip.hide()