in English

Consells d'eines

Documentació i exemples per afegir consells d'eines d'arrencada personalitzats amb CSS i JavaScript mitjançant CSS3 per a animacions i atributs de dades per a l'emmagatzematge de títols locals.

Visió general

Coses a saber quan s'utilitza el connector d'informació eines:

  • Els tooltips es basen en la biblioteca de tercers Popper per al posicionament. Heu d'incloure popper.min.js abans de bootstrap.js o utilitzar bootstrap.bundle.min.js/ bootstrap.bundle.jsque conté Popper per tal que els consells d'eines funcionin!
  • Si esteu creant el nostre JavaScript des de la font, requereixutil.js .
  • Els consells sobre eines estan activats per raons de rendiment, de manera que els heu d'inicialitzar vosaltres mateixos .
  • Els consells sobre eines amb títols de longitud zero no es mostren mai.
  • Especifiqueu container: 'body'per evitar problemes de renderització en components més complexos (com els nostres grups d'entrada, grups de botons, etc.).
  • No funcionarà l'activació de suggeriments sobre elements ocults.
  • Els consells sobre eines per a elements .disabledo disableds'han d'activar en un element d'embolcall.
  • Quan s'activa des d'hiperenllaços que abasten diverses línies, els consells sobre eines es centraran. Utilitzeu white-space: nowrap;-lo <a>per evitar aquest comportament.
  • Els consells sobre eines s'han d'amagar abans que els seus elements corresponents s'hagin eliminat del DOM.
  • Els tooltips es poden activar gràcies a un element dins d'un DOM ombra.
De manera predeterminada, aquest component utilitza el desinfectador de contingut integrat, que elimina tots els elements HTML que no estan permesos explícitament. Consulteu la secció desinfectant de la nostra documentació de JavaScript per obtenir més detalls.
L'efecte d'animació d'aquest component depèn de la prefers-reduced-motionconsulta de mitjans. Consulteu la secció de moviment reduït de la nostra documentació d'accessibilitat .

Tens tot això? Genial, anem a veure com funcionen amb alguns exemples.

Exemple: activeu els consells d'eines a tot arreu

Una manera d'iniciar tots els consells d'eines d'una pàgina seria seleccionar-los pel seu data-toggleatribut:

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

Exemples

Passeu el cursor per sobre dels enllaços següents per veure els consells sobre eines:

Text de marcador de posició per demostrar alguns enllaços en línia amb informació sobre eines. Això ara és només farciment, cap assassí. Contingut col·locat aquí només per imitar la presència de text real . I tot això només per donar-vos una idea de com es veurien els consells d'eines quan s'utilitzen en situacions del món real. Així que esperem que ara hàgiu vist com aquests consells sobre enllaços poden funcionar a la pràctica, un cop els feu servir al vostre lloc o projecte.

Passeu el cursor per sobre dels botons de sota per veure les quatre indicacions d'eines: superior, dreta, inferior i esquerra.

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

I amb HTML personalitzat afegit:

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

Ús

El connector d'informació sobre eines genera contingut i marques sota demanda i, per defecte, col·loca els consells sobre eines després del seu element activador.

Activa la informació sobre eines mitjançant JavaScript:

$('#example').tooltip(options)
Desbordament autoiscroll

La posició de la informació sobre eines intenta canviar automàticament quan un contenidor principal té overflow: autoo overflow: scrollagrada el nostre .table-responsive, però encara manté la posició de la ubicació original. Per resoldre'l, configureu l' boundaryopció amb qualsevol cosa que no sigui el valor predeterminat 'scrollParent', com ara 'window':

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

Marcatge

L'etiquetatge necessari per a una informació sobre eines és només un dataatribut i titlea l'element HTML voleu tenir una informació sobre eines. El marcatge generat d'una informació sobre eines és bastant senzill, tot i que requereix una posició (per defecte, establerta toppel connector).

Fer que els consells d'eines funcionin per als usuaris de teclat i tecnologia d'assistència

Només hauríeu d'afegir consells sobre eines als elements HTML que tradicionalment són interactius i enfocats al teclat (com ara enllaços o controls de formulari). Tot i que els elements HTML arbitraris (com ara <span>s) es poden enfocar afegint l' tabindex="0"atribut, això afegirà tabulacions potencialment molestes i confuses en elements no interactius per als usuaris del teclat, i la majoria de tecnologies d'assistència actualment no anuncien la informació sobre eines en aquesta situació. A més, no us confieu únicament hovercom a activador de la vostra informació sobre eines, ja que això farà que els vostres consells sobre eines siguin impossibles d'activar per als usuaris del teclat.

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

Elements inhabilitats

Els elements amb l' disabledatribut no són interactius, és a dir, els usuaris no poden centrar-hi, passar el cursor o fer-hi clic per activar una informació emergent (o una finestra emergent). Com a solució alternativa, voldreu activar la informació sobre eines des d'un embolcall <div>o <span>, idealment enfocat al teclat amb tabindex="0", i anul·lar l' pointer-eventselement desactivat.

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

Opcions

Les opcions es poden passar mitjançant atributs de dades o JavaScript. Per als atributs de dades, afegiu el nom de l'opció a data-, com a data-animation="".

Tingueu en compte que, per raons de seguretat, les opcions sanitize, sanitizeFni whiteListno es poden proporcionar mitjançant atributs de dades.
Nom Tipus Per defecte Descripció
animació booleà veritat Apliqueu una transició d'esvaïment CSS a la informació sobre eines
contenidor cadena | element | fals fals

Afegeix la informació sobre eines a un element específic. Exemple: container: 'body'. Aquesta opció és especialment útil perquè us permet situar la informació sobre eines en el flux del document a prop de l'element activador, cosa que evitarà que la informació sobre eines surti de l'element activador durant un canvi de mida de la finestra.

retard nombre | objecte 0

Retard per mostrar i amagar la informació sobre eines (ms): no s'aplica al tipus d'activador manual

Si es proporciona un número, s'aplica un retard tant per ocultar com per mostrar

L'estructura de l'objecte és:delay: { "show": 500, "hide": 100 }

html booleà fals

Permet HTML a la informació sobre eines.

Si és cert, les etiquetes HTML de la informació sobre eines es titlemostraran a la informació sobre eines. Si és fals, texts'utilitzarà el mètode de jQuery per inserir contingut al DOM.

Utilitzeu text si us preocupen els atacs XSS.

col·locació cadena | funció 'superior'

Com posicionar la informació sobre eines - automàtic | dalt | baix | esquerra | dret.
Quan autos'especifica, reorientarà dinàmicament la informació sobre eines.

Quan s'utilitza una funció per determinar la ubicació, es crida amb el node DOM d'informació eines com a primer argument i el node DOM de l'element activador com a segon. El thiscontext s'estableix a la instància d'informació eines.

selector cadena | fals fals Si es proporciona un selector, els objectes d'informació eines es delegaran als objectius especificats. A la pràctica, això també s'utilitza per aplicar informació sobre eines als elements DOM afegits dinàmicament ( jQuery.onsuport). Vegeu això i un exemple informatiu .
plantilla corda '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

HTML base que s'ha d'utilitzar en crear la informació sobre eines.

La informació sobre eines titles'injectarà al fitxer .tooltip-inner.

.arrowes convertirà en la fletxa de la informació sobre eines.

L'element d'embolcall més extern hauria de tenir la .tooltipclasse i role="tooltip".

títol cadena | element | funció ''

Valor del títol predeterminat si titlel'atribut no és present.

Si es dóna una funció, es cridarà amb la seva thisreferència establerta a l'element al qual s'adjunta la informació sobre eines.

disparador corda 'enfocament al ratolí'

Com s'activa la informació sobre eines - feu clic a | flotar | focus | manual. Podeu passar múltiples activadors; separeu-los amb un espai.

'manual'indica que la informació sobre eines s'activarà de manera programàtica mitjançant els mètodes i .tooltip('show'); aquest valor no es pot combinar amb cap altre activador..tooltip('hide').tooltip('toggle')

'hover'per si sol donarà lloc a consells sobre eines que no es poden activar mitjançant el teclat i només s'han d'utilitzar si hi ha mètodes alternatius per transmetre la mateixa informació als usuaris del teclat.

compensació nombre | cadena | funció 0

Desplaçament de la informació sobre eines respecte al seu objectiu.

Quan s'utilitza una funció per determinar el desplaçament, es crida amb un objecte que conté les dades del desplaçament com a primer argument. La funció ha de retornar un objecte amb la mateixa estructura. El node DOM de l'element desencadenant es passa com a segon argument.

Per obtenir més informació, consulteu els documents d'offset de Popper .

col·locació alternativa cadena | matriu 'flip' Permet especificar quina posició utilitzarà Popper a la alternativa. Per obtenir més informació, consulteu els documents de comportament de Popper
classe personalitzada cadena | funció ''

Afegiu classes a la informació sobre eines quan es mostri. Tingueu en compte que aquestes classes s'afegiran a més de les classes especificades a la plantilla. Per afegir diverses classes, separeu-les amb espais: 'a b'.

També podeu passar una funció que hauria de retornar una única cadena que contingui noms de classe addicionals.

límit cadena | element 'scrollParent' Límit de restricció de desbordament de la informació sobre eines. Accepta els valors de 'viewport', 'window', 'scrollParent', o una referència HTMLElement (només JavaScript). Per obtenir més informació, consulteu els documents preventOverflow de Popper .
desinfectar booleà veritat Activa o desactiva la desinfecció. Si està activat 'template'i 'title'les opcions es desinfectaran. Consulteu la secció desinfectant a la nostra documentació de JavaScript .
llista blanca objecte Valor per defecte Objecte que conté atributs i etiquetes permesos
desinfectarFn nul | funció nul Aquí podeu proporcionar la vostra pròpia funció de desinfecció. Això pot ser útil si preferiu utilitzar una biblioteca dedicada per realitzar la desinfecció.
popperConfig nul | objecte nul Per canviar la configuració de Popper per defecte de Bootstrap, consulteu la configuració de Popper

Atributs de dades per a informació sobre eines individuals

Les opcions per als consells d'eines individuals es poden especificar alternativament mitjançant l'ús d'atributs de dades, tal com s'ha explicat anteriorment.

Mètodes

Mètodes asíncrons i transicions

Tots els mètodes de l'API són asíncrons i comencen una transició . Tornen a la persona que truca tan bon punt s'inicia la transició però abans que acabi . A més, s'ignorarà una trucada de mètode en un component en transició .

Consulteu la nostra documentació de JavaScript per obtenir més informació .

$().tooltip(options)

Adjunta un controlador d'informació eines a una col·lecció d'elements.

.tooltip('show')

Revela la informació sobre eines d'un element. Torna a la persona que truca abans que s'hagi mostrat realment la informació sobre eines (és a dir, abans shown.bs.tooltipque es produeixi l'esdeveniment). Això es considera una activació "manual" de la informació sobre eines. Els consells sobre eines amb títols de longitud zero no es mostren mai.

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

.tooltip('hide')

Amaga la informació sobre eines d'un element. Torna a la persona que truca abans que la informació sobre eines s'hagi amagat (és a dir, abans hidden.bs.tooltipque es produeixi l'esdeveniment). Això es considera una activació "manual" de la informació sobre eines.

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

.tooltip('toggle')

Commuta la informació sobre eines d'un element. Torna a la persona que truca abans que s'hagi mostrat o amagat la informació sobre eines (és a dir, abans que es produeixi l'esdeveniment shown.bs.tooltipo ). hidden.bs.tooltipAixò es considera una activació "manual" de la informació sobre eines.

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

.tooltip('dispose')

Amaga i destrueix la informació sobre eines d'un element. Els consells sobre eines que utilitzen la delegació (que es creen amb l' selectoropció ) no es poden destruir individualment en elements activadors descendents.

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

.tooltip('enable')

Ofereix la possibilitat de mostrar la informació sobre eines d'un element. Els consells sobre eines estan activats de manera predeterminada.

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

.tooltip('disable')

Elimina la possibilitat que es mostri la informació sobre eines d'un element. La informació sobre eines només es podrà mostrar si es torna a activar.

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

.tooltip('toggleEnabled')

Activa o desactiva la possibilitat de mostrar o amagar la informació sobre eines d'un element.

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

.tooltip('update')

Actualitza la posició de la informació sobre eines d'un element.

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

Esdeveniments

Tipus d'esdeveniment Descripció
mostrar.bs.informació-eina Aquest esdeveniment s'activa immediatament quan showes crida al mètode d'instància.
indicació.bs.mostrada Aquest esdeveniment s'activa quan la informació sobre eines s'ha fet visible per a l'usuari (esperarà que finalitzin les transicions CSS).
ocultar.bs.tooltip Aquest esdeveniment s'activa immediatament quan hides'ha cridat el mètode d'instància.
hidden.bs.tooltip Aquest esdeveniment s'activa quan la informació sobre eines s'ha acabat d'ocultar per a l'usuari (esperarà que finalitzin les transicions CSS).
informació.bs.inserida Aquest esdeveniment s'activa després de l' show.bs.tooltipesdeveniment quan s'ha afegit la plantilla d'informació eines al DOM.
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})