Tooltips
Documentación y ejemplos para agregar tooltips de Bootstrap personalizados con CSS y JavaScript usando CSS3 para animaciones y data-bs-attributes para el almacenamiento local de títulos.
😎 Esta traducción es parte del proyecto esdocu.com.
Descripción general
Cosas que debes saber al usar el complemento de tooltip:
- Los tooltips se basan en la biblioteca de terceros Popper para el
posicionamiento. Debes incluir popper.min.js antes
de bootstrap.js o usar
bootstrap.bundle.min.js
/bootstrap.bundle.js
que contiene Popper para que los tooltips funcionen! - Los tooltips no están habilitados por motivos de rendimiento, por lo que debes inicializarlos tú mismo.
- Los tooltips con títulos de longitud cero nunca se muestran.
- Especifica
container: 'body'
para evitar problemas de representación en componentes más complejos (como nuestros input groups, button groups, etc.). - La activación de tooltips en elementos ocultos no funcionará.
- Los tooltips para los elementos
.disabled
odisabled
deben activarse en un elemento contenedor. - Cuando se activa desde hipervínculos que abarcan varias líneas, el tooltip se centrará. Usa
white-space: nowrap;
en tus<a>
s para evitar este comportamiento. - Los tooltips deben ocultarse antes de que sus elementos correspondientes se eliminen del DOM.
- Los tooltips se puede activar gracias a un elemento dentro del shadow DOM.
prefers-reduced-motion
.
Consulta la sección de movimiento reducido
de nuestra documentación de accesibilidad.
¿Lo tienes? Genial, veamos cómo funcionan con algunos ejemplos.
Ejemplo: habilita los tooltips en todas partes
Una forma de inicializar todos los tooltips en una página sería seleccionarlos por su atributo
data-bs-toggle
:
var tooltipTriggerList = Array.prototype.slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
return new bootstrap.Tooltip(tooltipTriggerEl)
})
Ejemplos
Pasa el cursor sobre los enlaces a continuación para ver sus tooltips:
Texto placeholder para demostrar algunos enlaces en línea con tooltips. Esto ahora es solo un relleno. Contenido colocado aquí solo para imitar la presencia de texto real. Y todo eso solo para darte una idea de cómo se vería el tooltip cuando se usa en situaciones del mundo real. Espero que ahora hayas visto cómo este tooltip en los enlaces puede funcionar en la práctica, una vez que los uses en tu propio sitio web o proyecto.
Pasa el cursor sobre los botones a continuación para ver las cuatro direcciones de tooltips: top, right, bottom, y left. Las direcciones se reflejan cuando se usa Bootstrap en RTL.
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip superior">
Tooltip superior
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Tooltip derecho">
Tooltip derecho
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Tooltip inferior">
Tooltip inferior
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="Tooltip izquierdo">
Tooltip izquierdo
</button>
Y con HTML personalizado:
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<em>Tooltip</em> <u>con</u> <b>HTML</b>">
Tooltip con HTML
</button>
Con un 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
El complemento de tooltip genera contenido y marcado a pedido y, de forma predeterminada, coloca tooltips después de tu elemento desencadenante.
Activa el tooltip a través de JavaScript:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Desbordamiento auto
y scroll
La posición del tooltip intenta cambiar automáticamente cuando un contenedor padre tiene
overflow: auto
o overflow: scroll
como nuestro .table-responsive
,
pero aún mantiene el posicionamiento de la ubicación original. Para resolver esto, establece la opción boundary
(para el
modificador flip usando la opción popperConfig
) a cualquier HTMLElement para sobrescribir el
valor predeterminado, 'clippingParents'
, como document.body
:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
boundary: document.body // o document.querySelector('#boundary')
})
Marcado
El marcado requerido para un tooltip es solo un atributo data
y un title
en el
elemento HTML que deseas tener un tooltip. El marcado generado de un tooltip es bastante simple, aunque
requiere una posición (de forma predeterminada, establecida en top
por el complemento).
Hacer que el tooltip funcione para los usuarios de teclados y tecnología de asistencia
Solo debes agregar el tooltip a los elementos HTML que tradicionalmente se pueden enfocar con el teclado y
son interactivos (como enlaces o controles de formulario). Aunque los elementos HTML arbitrarios (como
<span>
s) se pueden enfocar agregando el atributo tabindex="0"
, esto agregará
tabulaciones potencialmente molestas y confusas en elementos no interactivos para usuarios de teclado, y
actualmente la mayoría de las tecnologías de asistencia no anuncian el tooltip en esta situación. Además, no
confíes únicamente en hover
como el disparador de tu tooltip, ya que esto hará que tu tooltip
sea imposible de activar para los usuarios del teclado.
<!-- HTML a escribir -->
<a href="#" data-bs-toggle="tooltip" title="Algo de texto tooltip!">Pasa el puntero de mouse aquí</a>
<!-- Marcado generado por el complemento -->
<div class="tooltip bs-tooltip-top" role="tooltip">
<div class="tooltip-arrow"></div>
<div class="tooltip-inner">
Algo de texto tooltip!
</div>
</div>
Elementos deshabilitados
Los elementos con el atributo disabled
no son interactivos, lo que significa que los usuarios no
pueden enfocarlos, desplazarlos o hacer clic en ellos para activar un tooltip (o un popover). Como solución
alternativa, querrás activar el tooltip desde un contenedor <div>
o
<span>
, idealmente enfocable desde el teclado usando tabindex="0"
.
<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="Tooltip deshabilitado">
<button class="btn btn-primary" type="button" disabled>Botón deshabilitado</button>
</span>
Opciones
Las opciones se pueden pasar a través de atributos de datos o JavaScript. Para los atributos de datos, agrega
el
nombre de la opción a data-bs-
, como en data-bs-animation=""
. Asegúrate de cambiar
el tipo de caso del nombre de la opción de camelCase a kebab-case al pasar las opciones a través de
atributos
de datos. Por ejemplo, en lugar de usar data-bs-customClass="beautifier"
, usa
data-bs-custom-class="beautifier"
.
sanitize
, sanitizeFn
y
allowList
no se pueden proporcionar mediante atributos de datos.
Nombre | Tipo | Por defecto | Descripción |
---|---|---|---|
animation |
boolean | true |
Aplicar una transición de fundido CSS al tooltip |
container |
string | element | false | false |
Agrega el tooltip a un elemento específico. Ejemplo: |
delay |
number | object | 0 |
Retraso en mostrar y ocultar el tooltip (ms): no se aplica al tipo de activación manual Si se proporciona un número, se aplica un retraso tanto para ocultar como para mostrar La estructura del objeto es: |
html |
boolean | false |
Permitir HTML en el tooltip. Si es true, las etiquetas HTML en el Usa texto si te preocupan los ataques XSS. |
placement |
string | function | 'top' |
Cómo colocar el tooltip - auto | top | bottom | left | right. Cuando se usa una función para determinar la ubicación, se llama con el nodo DOM del tooltip como
primer argumento y el nodo DOM del elemento desencadenante como segundo. El contexto |
selector |
string | false | false |
Si se proporciona un selector, los objetos de tooltips se delegarán a los objetivos especificados. En
la práctica, esto también se usa para aplicar tooltips a elementos DOM agregados dinámicamente
(compatible con jQuery.on ). Consulta this y un ejemplo informativo. |
template |
string |
'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'
|
HTML base para usar al crear el tooltip. El
El elemento envolvente más externo debe tener la clase |
title |
string | element | function | '' |
Valor de título predeterminado si el atributo Si se proporciona una función, se llamará con su referencia |
trigger |
string | 'hover focus' |
Cómo se activa el tooltip: click | hover | focus | manual. Puedes pasar varios disparadores; sepáralas con un espacio.
|
fallbackPlacements |
array | ['top', 'right', 'bottom', 'left'] |
Define las ubicaciones de respaldo proporcionando una lista de ubicaciones en un array (en orden de preferencia). Para obtener más información, consulta documentos de comportamiento de Popper |
boundary |
string | element | 'clippingParents' |
Límite de restricción de desbordamiento del tooltip (se aplica solo al modificador preventOverflow de
Popper). De forma predeterminada, es 'clippingParents' y puede aceptar una referencia
HTMLElement (solo a través de JavaScript). Para
obtener más información,
consulta los detectOverflow
docs de Popper. |
customClass |
string | function | '' |
Agrega clases al tooltip cuando se muestre. Ten en cuenta que estas clases se agregarán además de las
clases especificadas en el template. Para agregar varias clases, sepáralas con espacios:
También puedes pasar una función que debería devolver una sola cadena que contenga nombres de clases adicionales. |
sanitize |
boolean | true |
Habilita o deshabilita la desinfección. Si está activado, las opciones 'template' y
'title' se desinfectarán. Consulta la sección de desinfección en nuestra
documentación de JavaScript.
|
allowList |
object | Default value | Objeto que contiene atributos y etiquetas permitidas |
sanitizeFn |
null | function | null |
Aquí puedes proporcionar tu propia función de desinfección. Esto puede ser útil si prefieres usar una biblioteca dedicada para realizar la desinfección. |
offset |
array | string | function | [0, 0] |
Desplazamiento del tooltip en relación con su destino. Puedes pasar una cadena en atributos de datos
con valores separados por comas como: Cuando se usa una función para determinar el desplazamiento, se llama con un objeto que contiene la
ubicación del popper, la referencia y los rects del popper como su primer argumento. El nodo DOM del
elemento desencadenante se pasa como segundo argumento. La función debe devolver un array con dos
números:
Para obtener más información, consulta los documentos de compensación de Popper. |
popperConfig |
null | object | function | null |
Para cambiar la configuración predeterminada de Popper de Bootstrap, consulta Configuración de Popper. Cuando se usa una función para crear la configuración Popper, se llama con un objeto que contiene la configuración Popper predeterminada de Bootstrap. Te ayuda a usar y fusionar el valor predeterminado con tu propia configuración. La función debe devolver un objeto de configuración para Popper. |
Atributos de datos para tooltips individuales
Las opciones para tooltips individuales se pueden especificar alternativamente mediante el uso de atributos de datos, como se explicó anteriormente.
Uso de la función con popperConfig
var tooltip = new bootstrap.Tooltip(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// usa defaultBsPopperConfig si es necesario...
// return newPopperConfig
}
})
Métodos
Transiciones y métodos asíncronos
Todos los métodos de la API son asincrónicos e inician una transition. Regresan al lugar donde se realizó la llamada tan pronto como se inicia la transición, pero antes de que finalice. Además, se ignorará una llamada de método en un componente en medio de una transición.
Consulte nuestra documentación de JavaScript para obtener más información.
show
Revela el tooltip de un elemento. Regresa al punto de la llamada antes de que se haya mostrado
realmente la tooltip (es decir, antes de que ocurra el evento shown.bs.tooltip
). Esto
se considera una activación “manual” del tooltip. El tooltip con títulos de longitud cero nunca se muestra.
tooltip.show()
hide
Oculta el tooltip de un elemento. Regresa al punto de la llamada antes de que la tooltip se haya
ocultado (es decir, antes de que ocurra el evento hidden.bs.tooltip
). Esto se
considera una activación “manual” del tooltip.
tooltip.hide()
toggle
Alterna el tooltip de un elemento. Regresa al punto de la llamada antes de que la tooltip se haya
mostrado u ocultado (es decir, antes de que ocurra el evento shown.bs.tooltip
o
hidden.bs.tooltip
). Esto se considera una activación “manual” del tooltip.
tooltip.toggle()
dispose
Oculta y destruye el tooltip de un elemento (elimina los datos almacenados en el elemento DOM). El tooltip
que utiliza la delegación (que se crea mediante la opción selector
) no se
puede destruir individualmente en los elementos desencadenantes descendientes.
tooltip.dispose()
enable
Le da al tooltip de un elemento la capacidad de mostrarse. El tooltip está habilitada de forma predeterminada.
tooltip.enable()
disable
Elimina la capacidad de mostrar el tooltip de un elemento. El tooltip solo se podrá mostrar si se vuelve a habilitar.
tooltip.disable()
setContent
Brinda una forma de cambiar el contenido del tooltip después de su inicialización.
tooltip.setContent({ '.tooltip-inner': 'another title' })
setContent
acepta un argumento object
, donde cada clave de propiedad es un
selector de string
válido dentro de la plantilla emergente, y cada valor de propiedad relacionado
puede ser string
| element
| function
| null
toggleEnabled
Alterna la capacidad de mostrar u ocultar el tooltip de un elemento.
tooltip.toggleEnabled()
update
Actualiza la posición del tooltip de un elemento.
tooltip.update()
getInstance
Método estático que te permite obtener la instancia del tooltip asociado con un elemento DOM
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Devuelve una instancia del tooltip de Bootstrap
getOrCreateInstance
Método estático que te permite obtener la instancia de tooltip asociado con un elemento DOM, o crear uno nuevo en caso de que no se haya inicializado
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Devuelve una instancia del tooltip de Bootstrap
Eventos
Tipo de evento | Descripción |
---|---|
show.bs.tooltip |
Este evento se activa inmediatamente cuando se llama al método de instancia show . |
shown.bs.tooltip |
Este evento se activa cuando el tooltip se hace visible para el usuario (esperará a que se completen las transiciones CSS). |
hide.bs.tooltip |
Este evento se activa inmediatamente cuando se llama al método de instancia hide . |
hidden.bs.tooltip |
Este evento se activa cuando el tooltip ha terminado de ocultarse para el usuario (esperará a que se completen las transiciones CSS). |
inserted.bs.tooltip |
Este evento se activa después del evento show.bs.tooltip cuando el template de tooltip se
ha agregado al DOM. |
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)
myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
// hacer algo...
})
tooltip.hide()
😎 Esta traducción es parte del proyecto esdocu.com.