in English

Información sobre herramientas

Documentación y ejemplos para agregar información sobre herramientas de Bootstrap personalizada con CSS y JavaScript usando CSS3 para animaciones y atributos de datos para el almacenamiento local de títulos.

Visión general

Cosas que debe saber al usar el complemento de información sobre herramientas:

  • La información sobre herramientas se basa en la biblioteca Popper de terceros para el posicionamiento. Debe incluir popper.min.js antes de bootstrap.js o usar bootstrap.bundle.min.js/ bootstrap.bundle.jsque contiene Popper para que funcione la información sobre herramientas.
  • Si está compilando nuestro JavaScript desde la fuente, requiereutil.js .
  • La información sobre herramientas está habilitada por motivos de rendimiento, por lo que debe inicializarla usted mismo .
  • La información sobre herramientas con títulos de longitud cero nunca se muestra.
  • Especifique container: 'body'para evitar problemas de representación en componentes más complejos (como nuestros grupos de entrada, grupos de botones, etc.).
  • La activación de información sobre herramientas en elementos ocultos no funcionará.
  • La información sobre herramientas para los elementos .disabledo disableddebe activarse en un elemento contenedor.
  • Cuando se activa desde hipervínculos que abarcan varias líneas, la información sobre herramientas se centrará. Úselo white-space: nowrap;en su <a>s para evitar este comportamiento.
  • La información sobre herramientas debe ocultarse antes de que sus elementos correspondientes se eliminen del DOM.
  • La información sobre herramientas se puede activar gracias a un elemento dentro de un DOM de sombra.
De forma predeterminada, este componente utiliza el desinfectante de contenido incorporado, que elimina los elementos HTML que no están permitidos explícitamente. Consulte la sección de desinfectantes en nuestra documentación de JavaScript para obtener más detalles.
El efecto de animación de este componente depende de la prefers-reduced-motionconsulta de medios. Consulte la sección de movimiento reducido de nuestra documentación de accesibilidad .

¿Tienes todo eso? Genial, veamos cómo funcionan con algunos ejemplos.

Ejemplo: habilite la información sobre herramientas en todas partes

Una forma de inicializar toda la información sobre herramientas en una página sería seleccionarla por su data-toggleatributo:

$(function () {
  $('[data-toggle="tooltip"]').tooltip()
})

Ejemplos

Pase el cursor sobre los enlaces a continuación para ver información sobre herramientas:

Texto de marcador de posición para demostrar algunos enlaces en línea con información sobre herramientas. Esto ahora es solo un relleno, no un asesino. Contenido colocado aquí solo para imitar la presencia de texto real . Y todo eso solo para darle una idea de cómo se vería la información sobre herramientas cuando se usa en situaciones del mundo real. Espero que ahora haya visto cómo estos consejos sobre herramientas en los enlaces pueden funcionar en la práctica, una vez que los use en su propio sitio o proyecto.

Pase el cursor sobre los botones a continuación para ver las cuatro direcciones de información sobre herramientas: arriba, derecha, abajo e izquierda.

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

Y con HTML personalizado agregado:

<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

El complemento de información sobre herramientas genera contenido y marcado a pedido y, de forma predeterminada, coloca información sobre herramientas después de su elemento desencadenante.

Active la información sobre herramientas a través de JavaScript:

$('#example').tooltip(options)
desbordamiento autoyscroll

La posición de la información sobre herramientas intenta cambiar automáticamente cuando un contenedor principal tiene overflow: autoo le overflow: scrollgusta nuestro .table-responsive, pero aún mantiene el posicionamiento de la ubicación original. Para resolver, establezca la boundaryopción en cualquier valor que no sea el valor predeterminado 'scrollParent', como 'window':

$('#example').tooltip({ boundary: 'window' })

Margen

El marcado requerido para una información sobre herramientas es solo un dataatributo y titleen el elemento HTML que desea tener una información sobre herramientas. El marcado generado de una información sobre herramientas es bastante simple, aunque requiere una posición (de forma predeterminada, establecida toppor el complemento).

Hacer que la información sobre herramientas funcione para los usuarios de teclados y tecnología de asistencia

Solo debe agregar información sobre herramientas 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 tabindex="0"atributo, esto agregará tabulaciones potencialmente molestas y confusas en elementos no interactivos para usuarios de teclado, y la mayoría de las tecnologías de asistencia actualmente no anuncian la información sobre herramientas en esta situación. Además, no confíe únicamente en hoverel activador de la información sobre herramientas, ya que esto hará que la información sobre herramientas sea imposible de activar para los usuarios del 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 deshabilitados

Los elementos con el disabledatributo no son interactivos, lo que significa que los usuarios no pueden enfocarlos, desplazarlos o hacer clic en ellos para activar una información sobre herramientas (o una ventana emergente). Como solución alternativa, deseará activar la información sobre herramientas desde un contenedor <div>o <span>, idealmente enfocable desde el teclado usando tabindex="0", y anular el pointer-eventselemento deshabilitado.

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

Opciones

Las opciones se pueden pasar a través de atributos de datos o JavaScript. Para los atributos de datos, agregue el nombre de la opción a data-, como en data-animation="".

Tenga en cuenta que, por motivos de seguridad sanitize, las opciones sanitizeFny whiteListno se pueden proporcionar mediante atributos de datos.
Nombre Escribe Defecto Descripción
animación booleano verdadero Aplicar una transición de fundido CSS a la información sobre herramientas
envase cadena | elemento | falso falso

Agrega la información sobre herramientas a un elemento específico. Ejemplo: container: 'body'. Esta opción es particularmente útil porque le permite colocar la información sobre herramientas en el flujo del documento cerca del elemento de activación, lo que evitará que la información sobre herramientas se separe del elemento de activación durante el cambio de tamaño de la ventana.
demora número | objeto 0

Retraso en mostrar y ocultar la información sobre herramientas (ms): no se aplica al tipo de disparo manual

Si se proporciona un número, la demora se aplica tanto para ocultar/mostrar

La estructura del objeto es:delay: { "show": 500, "hide": 100 }
html booleano falso

Permitir HTML en la información sobre herramientas.

Si es verdadero, las etiquetas HTML en la información sobre herramientas titlese representarán en la información sobre herramientas. Si es falso, se textusará el método de jQuery para insertar contenido en el DOM.

Use texto si le preocupan los ataques XSS.
colocación cadena | función 'parte superior'

Cómo colocar la información sobre herramientas - automático | parte superior | fondo | izquierda | Correcto.
Cuando autose especifica, reorientará dinámicamente la información sobre herramientas.

Cuando se usa una función para determinar la ubicación, se llama con el nodo DOM de información sobre herramientas como primer argumento y el nodo DOM del elemento desencadenante como segundo. El thiscontexto se establece en la instancia de información sobre herramientas.
selector cadena | falso falso Si se proporciona un selector, los objetos de información sobre herramientas se delegarán a los destinos especificados. En la práctica, esto también se usa para aplicar información sobre herramientas a elementos DOM agregados dinámicamente ( jQuery.onsoporte). Vea esto y un ejemplo informativo .
modelo cuerda '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

HTML base para usar al crear la información sobre herramientas.

La información sobre herramientas titlese inyectará en el archivo .tooltip-inner.

.arrowse convertirá en la flecha de la información sobre herramientas.

El elemento contenedor más externo debe tener la .tooltipclase y role="tooltip".
título cadena | elemento | función ''

Valor de título predeterminado si titleel atributo no está presente.

Si se proporciona una función, se llamará con su thisconjunto de referencia al elemento al que se adjunta la información sobre herramientas.
generar cuerda 'enfoque flotante'

Cómo se activa la información sobre herramientas: haga clic en | flotar | enfoque | manual. Puede pasar varios disparadores; sepáralos con un espacio.

'manual'indica que la información sobre herramientas se activará mediante programación mediante los métodos .tooltip('show'), .tooltip('hide')y ; .tooltip('toggle')este valor no se puede combinar con ningún otro disparador.

'hover'por sí solo dará como resultado información sobre herramientas que no se puede activar a través del teclado, y solo debe usarse si existen métodos alternativos para transmitir la misma información a los usuarios del teclado.
compensar número | cadena | función 0

Desplazamiento de la información sobre herramientas en relación con su objetivo.

Cuando se utiliza una función para determinar el desplazamiento, se llama con un objeto que contiene los datos de desplazamiento como primer argumento. La función debe devolver un objeto con la misma estructura. El nodo DOM del elemento desencadenante se pasa como segundo argumento.

Para obtener más información, consulte los documentos de compensación de Popper .
ubicación alternativa cadena | formación 'dar la vuelta' Permita especificar qué posición usará Popper en la reserva. Para obtener más información, consulte los documentos de comportamiento de Popper.
clase personalizada cadena | función ''

Agregue clases a la información sobre herramientas cuando se muestre. Tenga en cuenta que estas clases se agregarán además de las clases especificadas en la plantilla. Para agregar varias clases, sepárelas con espacios: 'a b'.

También puede pasar una función que debería devolver una sola cadena que contenga nombres de clases adicionales.
Perímetro cadena | elemento 'padre de desplazamiento' Límite de restricción de desbordamiento de la información sobre herramientas. Acepta los valores de 'viewport', 'window', 'scrollParent'o una referencia HTMLElement (solo JavaScript). Para obtener más información, consulte los documentos de preventOverflow de Popper .
desinfectar booleano verdadero Activa o desactiva la desinfección. Si está activado 'template', las 'title'opciones se desinfectarán. Consulte la sección de desinfectantes en nuestra documentación de JavaScript .
lista blanca objeto Valor por defecto Objeto que contiene atributos y etiquetas permitidos
desinfectarFn nulo | función nulo Aquí puede proporcionar su propia función de desinfección. Esto puede ser útil si prefiere usar una biblioteca dedicada para realizar la desinfección.
popperConfig nulo | objeto nulo Para cambiar la configuración predeterminada de Popper de Bootstrap, consulte la configuración de Popper

Atributos de datos para información sobre herramientas individuales

Las opciones para información sobre herramientas individuales se pueden especificar alternativamente mediante el uso de atributos de datos, como se explicó anteriormente.

Métodos

Transiciones y métodos asíncronos

Todos los métodos de API son asíncronos e inician una transición . Vuelven a la persona que llama 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 transición .

Consulte nuestra documentación de JavaScript para obtener más información .

$().tooltip(options)

Adjunta un controlador de información sobre herramientas a una colección de elementos.

.tooltip('show')

Revela la información sobre herramientas de un elemento. Vuelve a la persona que llama antes de que se muestre la información sobre herramientas (es decir, antes de shown.bs.tooltipque ocurra el evento). Esto se considera una activación "manual" de la información sobre herramientas. La información sobre herramientas con títulos de longitud cero nunca se muestra.

$('#element').tooltip('show')

.tooltip('hide')

Oculta la información sobre herramientas de un elemento. Vuelve a la persona que llama antes de que la información sobre herramientas se haya ocultado (es decir, antes de hidden.bs.tooltipque ocurra el evento). Esto se considera una activación "manual" de la información sobre herramientas.

$('#element').tooltip('hide')

.tooltip('toggle')

Alterna la información sobre herramientas de un elemento. Vuelve a la persona que llama antes de que se muestre u oculte la información sobre herramientas (es decir, antes de que ocurra el evento shown.bs.tooltipo ). hidden.bs.tooltipEsto se considera una activación "manual" de la información sobre herramientas.

$('#element').tooltip('toggle')

.tooltip('dispose')

Oculta y destruye la información sobre herramientas de un elemento. La información sobre herramientas que utiliza la delegación (que se crea con la selectoropción ) no se puede destruir individualmente en los elementos desencadenantes descendientes.

$('#element').tooltip('dispose')

.tooltip('enable')

Le da a la información sobre herramientas de un elemento la capacidad de mostrarse. La información sobre herramientas está habilitada de forma predeterminada.

$('#element').tooltip('enable')

.tooltip('disable')

Elimina la capacidad de mostrar la información sobre herramientas de un elemento. La información sobre herramientas solo se podrá mostrar si se vuelve a habilitar.

$('#element').tooltip('disable')

.tooltip('toggleEnabled')

Alterna la capacidad de mostrar u ocultar la información sobre herramientas de un elemento.

$('#element').tooltip('toggleEnabled')

.tooltip('update')

Actualiza la posición de la información sobre herramientas de un elemento.

$('#element').tooltip('update')

Eventos

Tipo de evento Descripción
mostrar.bs.información sobre herramientas Este evento se activa inmediatamente cuando showse llama al método de instancia.
se muestra.bs.tooltip Este evento se activa cuando la información sobre herramientas se hace visible para el usuario (esperará a que se completen las transiciones de CSS).
ocultar.bs.información sobre herramientas Este evento se activa inmediatamente cuando hidese llama al método de instancia.
oculto.bs.tooltip Este evento se activa cuando la información sobre herramientas ha terminado de ocultarse para el usuario (esperará a que se completen las transiciones de CSS).
insertado.bs.tooltip Este evento se activa después del show.bs.tooltipevento cuando la plantilla de información sobre herramientas se ha agregado al DOM. 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})