Tooltips

Documentación y ejemplos para agregar información sobre herramientas 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 de terceros Popper.js para el posicionamiento. Debe incluir popper.min.js antes de bootstrap.js o usar bootstrap.bundle.min.js / bootstrap.bundle.js que contiene Popper.js para que la información sobre herramientas funcione.
  • Si está construyendo nuestro JavaScript desde la fuente, requiere util.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 muestran.
  • 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 elementos .disabled o disabled debe 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 sus <a> s para evitar este comportamiento.
  • La información sobre herramientas debe estar oculta antes de que sus elementos correspondientes se hayan eliminado del DOM.
  • La información sobre herramientas se puede activar gracias a un elemento dentro de un DOM de sombra.

El efecto de animación de este componente depende de la prefers-reduced-motion consulta 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: habilitar la información sobre herramientas en todas partes

Una forma de inicializar todas las descripciones emergentes de una página sería seleccionarlas por su data-toggle atributo: 


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

Ejemplos

Desplácese sobre los enlaces a continuación para ver información sobre herramientas:

Pantalones ajustados keffiyeh del siguiente nivel , probablemente no hayas oído hablar de ellos. Photo booth beard raw denim tipografía vegana bandolera stumptown. Seitán de la granja a la mesa, la ropa americana fixie de quinua sostenible de 8 bits de mcsweeney tiene un chambray de vinilo de terry richardson. Beard stumptown, cardigans banh mi lomo thundercats. Tofu biodiesel williamsburg marfa, cuatro cambray vegano de limpieza de loko mcsweeney. Un artesano realmente irónico, sea ​​cual sea el keytar , escenas de la granja a la mesa banksy Austin twitter maneja freegan cred raw denim de origen único café viral.

Desplácese sobre los botones de abajo 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 la información sobre herramientas después de su elemento de activación.

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


  $('#example').tooltip(options)
Desbordamiento auto y scroll

La posición de la información sobre herramientas intenta cambiar automáticamente cuando un contenedor principal tiene overflow: auto o me overflow: scroll gusta nuestro .table-responsive , pero mantiene la posición de la ubicación original. Para resolverlo, establezca la boundary opción en cualquier otro valor que no sea el predeterminado 'scrollParent' , como 'window': 


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

Margen

El marcado requerido para una información sobre herramientas es solo un data atributo y title en el elemento HTML 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, configurada top por el complemento).

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

Solo debe agregar información sobre herramientas a los elementos HTML que tradicionalmente se pueden enfocar con el teclado e 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 los usuarios del 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 hover como disparador 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 disabled atributo no son interactivos, lo que significa que los usuarios no pueden enfocar, desplazarse o hacer clic en ellos para activar una información sobre herramientas (o popover). Como solución alternativa, querrá activar la información sobre herramientas desde un contenedor <div> o <span> , idealmente, hacer que se pueda enfocar con el teclado tabindex="0" y anular el pointer-events elemento 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 razones de seguridad sanitize , las opciones, sanitizeFn y whiteList no se pueden proporcionar utilizando atributos de datos.

Nombre Tipo Defecto Descripción
animación booleano cierto Aplicar una transición de desvanecimiento 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 disparador, lo que evitará que la información sobre herramientas flote lejos del elemento disparador durante el cambio de tamaño de una ventana.

retrasar numero | objeto 0

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

Si se proporciona un número, se aplica un retraso 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 de la información sobre herramientas se title mostrarán en la información sobre herramientas. Si es falso, se text usará el método de jQuery para insertar contenido en el DOM.

Utilice texto si le preocupan los ataques XSS.

colocación cadena | función 'parte superior'

Cómo colocar la información sobre herramientas - automático | arriba | abajo | izquierda | derecho.
Cuando auto se 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 this contexto 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.on soporte). 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 title se inyectará en el archivo .tooltip-inner.

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

El elemento contenedor más externo debe tener la .tooltip clase y role="tooltip".

título cadena | elemento | función ''

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

Si se proporciona una función, se llamará con su this conjunto de referencias al elemento al que se adjunta la información sobre herramientas.

desencadenar cuerda 'enfoque de desplazamiento'

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

'manual' indica que la información de herramientas se activará mediante programación a través de los .tooltip('show'), .tooltip('hide')y .tooltip('toggle') métodos; 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 para los usuarios del teclado.

compensar numero | 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 del 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.js .

fallbackPlacement cadena | formación 'dar la vuelta' Permitir especificar qué posición utilizará Popper en la reserva. Para obtener más información, consulte los documentos de comportamiento de Popper.js
Perímetro cadena | elemento 'scrollParent' Límite de restricción de desbordamiento de la información sobre herramientas. Acepta los valores de 'viewport', 'window', 'scrollParent' , o una referencia de HTMLElement (JavaScript solamente). Para obtener más información, consulte los documentos de preventOverflow de Popper.js .
desinfectar booleano cierto Habilite o deshabilite la desinfección. Si se activa 'template'y 'title'se desinfectan opciones.
whiteList objeto Valor por defecto Objeto que contiene atributos y etiquetas permitidos
sanitizeFn nulo | función nulo Aquí puede proporcionar su propia función de desinfección. Esto puede resultar útil si prefiere utilizar una biblioteca dedicada para realizar la desinfección.
popperConfig nulo | objeto nulo Para cambiar la configuración predeterminada de Popper.js de Bootstrap, consulte la configuración de Popper.js

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 asincrónicos

Todos los métodos API son asincrónicos 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 a un 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 realmente la información sobre herramientas (es decir, antes de shown.bs.tooltip que 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 muestran. 


  $('#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.tooltip que 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 la información sobre herramientas se haya mostrado u ocultada (es decir, antes de que ocurra el evento shown.bs.tooltip o hidden.bs.tooltip ). Esto 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. Las descripciones emergentes que utilizan la delegación (que se crean mediante la selector opción ) no se pueden destruir individualmente en elementos desencadenantes descendientes. 


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

.tooltip('enable')

Da a la descripción emergente 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
show.bs.tooltip Este evento se activa inmediatamente cuando show se llama al método de instancia.
muestra.bs.tooltip Este evento se activa cuando la información sobre herramientas se ha hecho visible para el usuario (esperará a que se completen las transiciones CSS).
hide.bs.tooltip Este evento se activa inmediatamente cuando hide se llama al método de instancia.
hidden.bs.tooltip Este evento se activa cuando la información sobre herramientas ha terminado de ocultarse al usuario (esperará a que se completen las transiciones CSS).
insert.bs.tooltip Este evento se activa después del show.bs.tooltip evento cuando la plantilla de información sobre herramientas se ha agregado al DOM. 

  $('#myTooltip').on('hidden.bs.tooltip', function () {
    // do something...
  })