Saltar al contingut principal Saltar a la navegació de documents
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-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.jsque 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 .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 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.
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-bs-toggleatribut:

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 autoiscroll

La posició de la informació sobre eines intenta canviar automàticament quan un contenidor principaloverflow: autoo overflow: scrollagrada el nostre .table-responsive, però encara manté la posició de la ubicació original. Per resoldre-ho, establiu l' boundaryopció (per al modificador de volteig que utilitza l' popperConfigopció) 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 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-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' 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".

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

Tingueu en compte que, per motius de seguretat, les opcions sanitize, sanitizeFn, i allowListno 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: 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.

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:delay: { "show": 500, "hide": 100 }

html booleà false

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, innerTextla propietat s'utilitzarà per inserir contingut al DOM.

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 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 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.onsuport). 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 titles'injectarà al fitxer .tooltip-inner.

.tooltip-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".

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

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.

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

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: 'class-1 class-2'.

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:data-bs-offset="10,20"

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: .[skidding, distance]

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

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.tooltipque 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.tooltipo ). hidden.bs.tooltipAixò 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' selectoropció ) 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 showes 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 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).
inserted.bs.tooltip Aquest esdeveniment s'activa després de l' show.bs.tooltipesdeveniment 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()