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-bs 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.js
que conté Popper per tal que els consells d'eines funcionin! - 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
.disabled
odisabled
s'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 tooltips 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.
prefers-reduced-motion
consulta 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-bs-toggle
atribut:
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
return new bootstrap.Tooltip(tooltipTriggerEl)
})
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. Les indicacions es reflecteixen quan s'utilitza Bootstrap a RTL.
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" title="Tooltip on top">
Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" title="Tooltip on right">
Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Tooltip on bottom">
Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" title="Tooltip on left">
Tooltip on left
</button>
I amb HTML personalitzat afegit:
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
Tooltip with HTML
</button>
Amb un SVG:
Sass
Les 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;
Ú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:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Desbordament auto
iscroll
La posició de la informació sobre eines intenta canviar automàticament quan un contenidor principal té overflow: auto
o overflow: scroll
agrada el nostre .table-responsive
, però encara manté la posició de la ubicació original. Per resoldre-ho, establiu l' boundary
opció (per al modificador de volteig que utilitza l' popperConfig
opció) a qualsevol HTMLElement per substituir el valor predeterminat 'clippingParents'
, com ara document.body
:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
boundary: document.body // or document.querySelector('#boundary')
})
Marcatge
L'etiquetatge necessari per a una informació sobre eines és només un data
atribut i title
a 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 top
pel 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 hover
com 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-bs-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="tooltip-arrow"></div>
<div class="tooltip-inner">
Some tooltip text!
</div>
</div>
Elements inhabilitats
Els elements amb l' disabled
atribut 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"
.
<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" title="Disabled tooltip">
<button class="btn btn-primary" 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-bs-
, com a data-bs-animation=""
. Assegureu-vos de canviar el tipus de cas del nom de l'opció de camelCase a kebab-case quan passeu les opcions mitjançant atributs de dades. Per exemple, en comptes d'utilitzar data-bs-customClass="beautifier"
, utilitzeu data-bs-custom-class="beautifier"
.
sanitize
,
sanitizeFn
, i
allowList
no es poden proporcionar amb atributs de dades.
Nom | Tipus | Per defecte | Descripció |
---|---|---|---|
animation |
booleà | true |
Apliqueu una transició d'esvaïment CSS a la informació sobre eines |
container |
cadena | element | fals | false |
Afegeix la informació sobre eines a un element específic. Exemple: |
delay |
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: |
html |
booleà | false |
Permet HTML a la informació sobre eines. Si és cert, les etiquetes HTML de la informació sobre eines es Utilitzeu text si us preocupen els atacs XSS. |
placement |
cadena | funció | 'top' |
Com posicionar la informació sobre eines - automàtic | dalt | baix | esquerra | dret. 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 |
selector |
cadena | fals | false |
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.on suport). Vegeu això i un exemple informatiu . |
template |
corda | '<div class="tooltip" role="tooltip"><div class="tooltip-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
L'element d'embolcall més extern hauria de tenir la |
title |
cadena | element | funció | '' |
Valor del títol predeterminat si Si es dóna una funció, es cridarà amb la seva |
trigger |
corda | 'hover focus' |
Com s'activa la informació sobre eines - feu clic a | flotar | focus | manual. Podeu passar múltiples activadors; separeu-los amb un espai.
|
fallbackPlacements |
matriu | ['top', 'right', 'bottom', 'left'] |
Definiu ubicacions alternatives proporcionant una llista d'ubicacions en matriu (per ordre de preferència). Per obtenir més informació, consulteu els documents de comportament de Popper |
boundary |
cadena | element | 'clippingParents' |
Límit de restricció de desbordament de la informació sobre eines (només s'aplica al modificador preventOverflow de Popper). Per defecte és 'clippingParents' i pot acceptar una referència HTMLElement (només mitjançant JavaScript). Per obtenir més informació, consulteu els documents detectOverflow de Popper . |
customClass |
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: També podeu passar una funció que hauria de retornar una única cadena que contingui noms de classe addicionals. |
sanitize |
booleà | true |
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 . |
allowList |
objecte | Valor per defecte | Objecte que conté atributs i etiquetes permesos |
sanitizeFn |
nul | funció | null |
Aquí podeu proporcionar la vostra pròpia funció de desinfecció. Això pot ser útil si preferiu utilitzar una biblioteca dedicada per realitzar la desinfecció. |
offset |
matriu | cadena | funció | [0, 0] |
Desplaçament de la informació sobre eines respecte al seu objectiu. Podeu passar una cadena en atributs de dades amb valors separats per comes com: Quan s'utilitza una funció per determinar el desplaçament, s'anomena amb un objecte que conté la ubicació del popper, la referència i rectes del popper com a primer argument. El node DOM de l'element desencadenant es passa com a segon argument. La funció ha de retornar una matriu amb dos números: . Per obtenir més informació, consulteu els documents d'offset de Popper . |
popperConfig |
nul | objecte | funció | null |
Per canviar la configuració de Popper per defecte de Bootstrap, vegeu la configuració de Popper . Quan s'utilitza una funció per crear la configuració de Popper, s'anomena amb un objecte que conté la configuració de Popper per defecte de Bootstrap. Us ajuda a utilitzar i combinar el valor predeterminat amb la vostra pròpia configuració. La funció ha de retornar un objecte de configuració per a 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.
Utilitzant la funció ambpopperConfig
var tooltip = new bootstrap.Tooltip(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
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ó .
espectacle
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.tooltip
que 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.
tooltip.show()
amagar
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.tooltip
que es produeixi l'esdeveniment). Això es considera una activació "manual" de la informació sobre eines.
tooltip.hide()
alternar
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.tooltip
o ). hidden.bs.tooltip
Això es considera una activació "manual" de la informació sobre eines.
tooltip.toggle()
disposar
Amaga i destrueix la informació sobre eines d'un element (elimina les dades emmagatzemades a l'element DOM). Els consells sobre eines que utilitzen la delegació (que es creen amb l' selector
opció ) no es poden destruir individualment en elements activadors descendents.
tooltip.dispose()
habilitar
Ofereix la possibilitat de mostrar la informació sobre eines d'un element. Els consells sobre eines estan activats de manera predeterminada.
tooltip.enable()
desactivar
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.
tooltip.disable()
toggleEnabled
Activa o desactiva la possibilitat de mostrar o amagar la informació sobre eines d'un element.
tooltip.toggleEnabled()
actualitzar
Actualitza la posició de la informació sobre eines d'un element.
tooltip.update()
getInstance
Mètode estàtic que us permet obtenir la instància d'informació eines associada a un element DOM
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
getOrCreateInstance
Mètode estàtic que us permet obtenir la instància d'informació eines associada a un element DOM o crear-ne una de nova en cas que no s'hagi inicialitzat
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
Esdeveniments
Tipus d'esdeveniment | Descripció |
---|---|
show.bs.tooltip |
Aquest esdeveniment s'activa immediatament quan show es crida al mètode d'instància. |
shown.bs.tooltip |
Aquest esdeveniment s'activa quan la informació sobre eines s'ha fet visible per a l'usuari (esperarà que finalitzin les transicions CSS). |
hide.bs.tooltip |
Aquest esdeveniment s'activa immediatament quan hide s'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). |
inserted.bs.tooltip |
Aquest esdeveniment s'activa després de l' show.bs.tooltip esdeveniment quan s'ha afegit la plantilla d'informació eines al DOM. |
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)
myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
// do something...
})
tooltip.hide()