in English

Suxestións sobre ferramentas

Documentación e exemplos para engadir ferramentas de Bootstrap personalizadas con CSS e JavaScript mediante CSS3 para animacións e atributos de datos 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.jsque contén Popper para que funcionen as informacións sobre ferramentas.
  • Se estás construíndo o noso JavaScript desde a orixe, requireutil.js .
  • 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 .disabledou disabledelementos 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.
De forma predeterminada, este compoñente usa o desinfectante de contido integrado, que elimina todos os elementos HTML que non están permitidos de forma explícita. Consulta a sección de desinfectantes na nosa documentación de JavaScript para obter máis detalles.
O efecto de animación deste compoñente depende da prefers-reduced-motionconsulta 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-toggleatributo:

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

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.

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

E con HTML personalizado engadido:

<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

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:

$('#example').tooltip(options)
Desbordamento autoescroll

A posición da información sobre ferramentas tenta cambiar automaticamente cando un contedor principal ten overflow: autoou overflow: scrollgústalle o noso .table-responsive, pero aínda así mantén a posición da ubicación orixinal. Para resolver, configure a boundaryopción en calquera cousa que non sexa o valor predeterminado 'scrollParent', como 'window':

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

Marcado

O marcado necesario para unha información sobre ferramentas é só un dataatributo e titleno 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 toppolo 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ó hovercomo 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-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 desactivados

Os elementos co disabledatributo 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", e anular o pointer-eventselemento desactivado.

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

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-, como en data-animation="".

Teña en conta que, por razóns de seguridade, as opcións sanitize, sanitizeFne whiteListnon se poden proporcionar mediante atributos de datos.
Nome Tipo Por defecto Descrición
animación booleano verdade Aplique unha transición de fundido CSS á información sobre ferramentas
envase cadea | elemento | falso falso

Engade a información sobre ferramentas a un elemento específico. Exemplo: container: 'body'. Esta opción é particularmente útil xa que lle permite situar a información sobre ferramentas no fluxo do documento preto do elemento desencadeador, o que evitará que a información sobre ferramentas se afasta do elemento desencadeador durante un cambio de tamaño da xanela.
atraso 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 é:delay: { "show": 500, "hide": 100 }
html booleano falso

Permitir HTML na información sobre ferramentas.

Se é verdadeiro, as etiquetas HTML da información sobre ferramentas titlemostraranse na información sobre ferramentas. textSe é falso, empregarase o método de jQuery para inserir contido no DOM.

Usa texto se estás preocupado polos ataques XSS.
colocación cadea | función 'arriba'

Como colocar a información sobre ferramentas - auto | arriba | inferior | esquerda | certo.
Cando autose especifica, reorientará dinámicamente a información sobre ferramentas.

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 thiscontexto establécese na instancia da información sobre ferramentas.
selector cadea | falso falso 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.onsoporte). Vexa isto e un exemplo informativo .
modelo corda '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

HTML base para usar ao crear a información sobre ferramentas.

A información de ferramentas titleinxectarase no .tooltip-inner.

.arrowconverterase na frecha da información sobre ferramentas.

O elemento de envoltura máis externo debe ter a .tooltipclase e role="tooltip".
título cadea | elemento | función ''

Valor predeterminado do título se titleo atributo non está presente.

Se se dá unha función, chamarase coa súa thisreferencia definida ao elemento ao que está anexa a información sobre ferramentas.
disparador corda 'foco do rato'

Como se activa a información sobre ferramentas: fai clic en | pasar o rato | foco | manual. Podes pasar varios disparadores; separalos cun espazo.

'manual'indica que a información sobre ferramentas se activará mediante programación mediante os métodos .tooltip('show'), .tooltip('hide')e ; .tooltip('toggle')este valor non se pode combinar con ningún outro disparador.

'hover'por si só dará lugar a información sobre ferramentas que non se poden activar a través do teclado e só se deberían utilizar se existen métodos alternativos para transmitir a mesma información aos usuarios do teclado.
compensar número | cadea | función 0

Desfase da información sobre ferramentas en relación ao seu obxectivo.

Cando se usa unha función para determinar a compensación, chámase cun obxecto que contén os datos de compensación como primeiro argumento. A función debe devolver un obxecto coa mesma estrutura. O nodo DOM do elemento desencadeante pásase como segundo argumento.

Para obter máis información, consulte os documentos de offset de Popper .
colocación de reserva cadea | matriz 'flip' Permitir especificar a posición que utilizará Popper no respaldo. Para obter máis información, consulte os documentos de comportamento de Popper
clase personalizada 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: 'a b'.

Tamén pode pasar unha función que debería devolver unha única cadea que conteña nomes de clases adicionais.
límite cadea | elemento 'scrollParent' Límite de restricción de desbordamento da información sobre ferramentas. Acepta os valores de 'viewport', 'window', 'scrollParent', ou unha referencia HTMLElement (só JavaScript). Para obter máis información, consulte os documentos preventOverflow de Popper .
desinfectar booleano verdade 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 .
lista branca obxecto Valor predeterminado Obxecto que contén atributos e etiquetas permitidos
desinfectarFn nulo | función nulo 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.
popperConfig nulo | obxecto nulo Para cambiar a configuración de Popper predeterminada de Bootstrap, consulte a configuración de 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.

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 .

$().tooltip(options)

Anexa un controlador de información sobre ferramentas a unha colección de elementos.

.tooltip('show')

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

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

.tooltip('hide')

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.tooltipque se produza o evento). Isto considérase unha activación "manual" da información sobre ferramentas.

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

.tooltip('toggle')

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.tooltipou ). hidden.bs.tooltipIsto considérase unha activación "manual" da información sobre ferramentas.

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

.tooltip('dispose')

Oculta e destrúe a información sobre ferramentas dun elemento. As informacións sobre ferramentas que usan a delegación (que se crean mediante a selectoropción ) non se poden destruír individualmente nos elementos desencadeantes descendentes.

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

.tooltip('enable')

Dá a información sobre ferramentas dun elemento a posibilidade de mostrarse. As informacións sobre ferramentas están activadas por defecto.

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

.tooltip('disable')

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.

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

.tooltip('toggleEnabled')

Alterna a posibilidade de mostrar ou ocultar a información sobre ferramentas dun elemento.

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

.tooltip('update')

Actualiza a posición da información sobre ferramentas dun elemento.

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

Eventos

Tipo de evento Descrición
mostrar.bs.información Este evento desenvólvese inmediatamente cando showse chama ao método de instancia.
mostrado.bs.información 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).
ocultar.bs.informativa Este evento desenvólvese inmediatamente cando hidese 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).
inserido.bs.información Este evento desenvólvese despois do show.bs.tooltipevento cando se engadiu o modelo de información sobre ferramentas ao DOM. 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})