Info-bulles
Documentation et exemples pour l'ajout d'info-bulles Bootstrap personnalisées avec CSS et JavaScript à l'aide de CSS3 pour les animations et data-bs-attributes pour le stockage de titre local.
Aperçu
Choses à savoir lors de l'utilisation du plugin d'info-bulle :
- Les info-bulles s'appuient sur la bibliothèque tierce Popper pour le positionnement. Vous devez inclure popper.min.js avant bootstrap.js ou utiliser
bootstrap.bundle.min.js
/bootstrap.bundle.js
qui contient Popper pour que les infobulles fonctionnent ! - Les info-bulles sont facultatives pour des raisons de performances, vous devez donc les initialiser vous -même.
- Les info-bulles avec des titres de longueur nulle ne sont jamais affichées.
- Spécifiez
container: 'body'
pour éviter les problèmes de rendu dans des composants plus complexes (comme nos groupes d'entrée, groupes de boutons, etc.). - Le déclenchement d'info-bulles sur des éléments masqués ne fonctionnera pas.
- Les info-bulles pour les éléments
.disabled
oudisabled
doivent être déclenchées sur un élément wrapper. - Lorsqu'elles sont déclenchées à partir d'hyperliens qui s'étendent sur plusieurs lignes, les info-bulles seront centrées. Utilisez
white-space: nowrap;
sur vos<a>
s pour éviter ce comportement. - Les info-bulles doivent être masquées avant que leurs éléments correspondants aient été supprimés du DOM.
- Les info-bulles peuvent être déclenchées grâce à un élément à l'intérieur d'un shadow DOM.
prefers-reduced-motion
requête multimédia. Voir la section mouvement réduit de notre documentation sur l'accessibilité ..
Vous avez tout ça ? Super, voyons comment ils fonctionnent avec quelques exemples.
Exemple : Activer les info-bulles partout
Une façon d'initialiser toutes les info-bulles sur une page serait de les sélectionner par leur data-bs-toggle
attribut:
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
return new bootstrap.Tooltip(tooltipTriggerEl)
})
Exemples
Passez la souris sur les liens ci-dessous pour afficher les info-bulles :
Placeholder text to demonstrate some inline links with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of real text. And all that just to give you an idea of how tooltips would look when used in real-world situations. So hopefully you've now seen how these tooltips on links can work in practice, once you use them on your own site or project.
Survolez les boutons ci-dessous pour voir les quatre directions des info-bulles : haut, droite, bas et gauche. Les directions sont mises en miroir lors de l'utilisation de Bootstrap dans 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>
Et avec le code HTML personnalisé ajouté :
<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>
Avec un SVG:
Sass
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;
Usage
Le plug-in d'info-bulle génère du contenu et du balisage à la demande, et place par défaut les info-bulles après leur élément déclencheur.
Déclenchez l'info-bulle via JavaScript :
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Débordement auto
et scroll
La position de l'info-bulle tente de changer automatiquement lorsqu'un conteneur parent a overflow: auto
ou overflow: scroll
ressemble à notre .table-responsive
, mais conserve toujours le positionnement de l'emplacement d'origine. Pour résoudre ce problème, définissez l' boundary
option (pour le modificateur flip utilisant l' popperConfig
option) sur n'importe quel HTMLElement pour remplacer la valeur par défaut, 'clippingParents'
, telle que document.body
:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
boundary: document.body // or document.querySelector('#boundary')
})
Balisage
Le balisage requis pour une info-bulle n'est qu'un data
attribut et title
sur l'élément HTML, vous souhaitez avoir une info-bulle. Le balisage généré d'une info-bulle est assez simple, bien qu'il nécessite une position (par défaut, définie toppar le plugin).
Faire en sorte que les info-bulles fonctionnent pour les utilisateurs de clavier et de technologie d'assistance
Vous ne devez ajouter des info-bulles qu'aux éléments HTML qui sont traditionnellement accessibles au clavier et interactifs (tels que des liens ou des contrôles de formulaire). Bien que des éléments HTML arbitraires (tels que s) puissent être rendus focalisables en ajoutant l' <span>
s) puissent être rendus focalisables en ajoutant l' tabindex="0"
attribut, cela ajoutera des taquets de tabulation potentiellement gênants et déroutants sur les éléments non interactifs pour les utilisateurs de clavier, et la plupart des technologies d'assistance n'annoncent actuellement pas l'info-bulle dans cette situation. De plus, ne comptez pas uniquement sur hover
le déclencheur de votre info-bulle, car cela rendra vos info-bulles impossibles à déclencher pour les utilisateurs de clavier.
<!-- 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>
Eléments désactivés
Les éléments avec l' disabled
attribut ne sont pas interactifs, ce qui signifie que les utilisateurs ne peuvent pas se concentrer, survoler ou cliquer dessus pour déclencher une info-bulle (ou popover). Comme solution de contournement, vous souhaiterez déclencher l'info-bulle à partir d'un wrapper <div>
ou <span>
, idéalement rendu focusable au clavier à l'aide de 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>
Options
Les options peuvent être transmises via des attributs de données ou JavaScript. Pour les attributs de données, ajoutez le nom de l'option à data-bs-
, comme dans data-bs-animation=""
. Assurez-vous de changer le type de casse du nom de l'option de camelCase à kebab-case lors du passage des options via les attributs de données. Par exemple, au lieu d'utiliser data-bs-customClass="beautifier"
, utilisez data-bs-custom-class="beautifier"
.
sanitize
, sanitizeFn
, et ne peuvent pas être fournies à l'aide d'attributs de données allowList
Nom | Type | Défaut | Description |
---|---|---|---|
animation |
boolean | true |
Appliquer une transition de fondu CSS à l'info-bulle |
container |
string | element | false | false |
Ajoute l'info-bulle à un élément spécifique. Exemple : |
delay |
number | object | 0 |
Délai d'affichage et de masquage de l'info-bulle (ms) - ne s'applique pas au type de déclenchement manuel Si un nombre est fourni, un délai est appliqué à la fois pour masquer/afficher La structure de l'objet est |
html |
boolean | false |
Autoriser HTML dans l'info-bulle. Si true, les balises HTML dans l'info-bulle Utilisez du texte si vous craignez les attaques XSS. |
placement |
string | function | 'top' |
Comment positionner l'infobulle - auto | haut | bas | gauche | droit. Lorsqu'une fonction est utilisée pour déterminer le placement, elle est appelée avec le nœud DOM de l'info-bulle comme premier argument et le nœud DOM de l'élément déclencheur comme second. Le |
selector |
string | false | false |
Si un sélecteur est fourni, les objets d'info-bulle seront délégués aux cibles spécifiées. En pratique, cela est utilisé pour appliquer également des info-bulles aux éléments DOM ajoutés dynamiquement ( jQuery.on support). Voir ceci et un exemple informatif. |
template |
string | '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' |
HTML de base à utiliser lors de la création de l'info-bulle. Les info-bulles
L'élément wrapper le plus externe doit avoir la |
title |
string | element | function | '' |
Valeur de titre par défaut si Si une fonction est donnée, elle sera appelée avec sa |
trigger |
string | 'hover focus' |
Comment l'info-bulle est déclenchée - cliquez sur | planer | concentrer | Manuel. Vous pouvez passer plusieurs déclencheurs ; séparez-les par un espace.
|
fallbackPlacements |
array | ['top', 'right', 'bottom', 'left'] |
Définissez les emplacements de remplacement en fournissant une liste d'emplacements dans le tableau (par ordre de préférence). Pour plus d'informations, reportez-vous à la documentation sur le comportement de Popper |
boundary |
string | element | 'clippingParents' |
Limite de contrainte de débordement de l'info-bulle (s'applique uniquement au modificateur preventOverflow de Popper). Par défaut, c'est 'clippingParents' et peut accepter une référence HTMLElement (via JavaScript uniquement). Pour plus d'informations, reportez-vous à la documentation detectOverflow de Popper. |
customClass |
string | function | '' |
Ajoutez des classes à l'info-bulle lorsqu'elle s'affiche. Notez que ces classes seront ajoutées en plus de toutes les classes spécifiées dans le modèle. Pour ajouter plusieurs classes, séparez-les par des espaces : Vous pouvez également passer une fonction qui doit renvoyer une seule chaîne contenant des noms de classe supplémentaires. |
sanitize |
boolean | true |
Activez ou désactivez la désinfection. Si activé 'template' et les 'title' options seront désinfectées. Voir la section désinfectant dans notre documentation JavaScript. |
allowList |
object | Default value | Objet qui contient des attributs et des balises autorisés |
sanitizeFn |
null | function | null |
Ici, vous pouvez fournir votre propre fonction de désinfection. Cela peut être utile si vous préférez utiliser une bibliothèque dédiée pour effectuer la désinfection. |
offset |
array | string | function | [0, 0] |
Décalage de l'info-bulle par rapport à sa cible. Vous pouvez transmettre une chaîne dans les attributs de données avec des valeurs séparées par des virgules comme Lorsqu'une fonction est utilisée pour déterminer le décalage, elle est appelée avec un objet contenant le placement du popper, la référence et les rectangles du popper comme premier argument. Le nœud DOM de l'élément déclencheur est passé comme deuxième argument. La fonction doit retourner un tableau avec deux nombres Pour plus d'informations, reportez-vous à la documentation de décalage de popper. |
popperConfig |
null | object | function | null |
Pour modifier la configuration Popper par défaut de Bootstrap, consultez Popper's configuration. Lorsqu'une fonction est utilisée pour créer la configuration Popper, elle est appelée avec un objet qui contient la configuration Popper par défaut de Bootstrap. Il vous aide à utiliser et à fusionner la valeur par défaut avec votre propre configuration. La fonction doit renvoyer un objet de configuration pour Popper. |
Attributs de données pour les info-bulles individuelles
Les options des info-bulles individuelles peuvent également être spécifiées via l'utilisation d'attributs de données, comme expliqué ci-dessus.
Utilisation de la fonction avec popperConfig
var tooltip = new bootstrap.Tooltip(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
Méthodes
Méthodes et transitions asynchrones
Toutes les méthodes API sont asynchrones et démarrent une transition . Ils reviennent à l'appelant dès que la transition est commencée mais avant qu'elle ne se termine . De plus, un appel de méthode sur un composant en transition sera ignoré.
Consultez notre documentation JavaScript pour plus d'informations.
afficher
Révèle l'info-bulle d'un élément. Revient à l'appelant avant que l'info-bulle ne soit réellement affichée (c'est-à-dire avant que l' shown.bs.tooltip
événement ne se produise). Ceci est considéré comme un déclenchement "manuel" de l'info-bulle. Les info-bulles avec des titres de longueur nulle ne sont jamais affichées.
tooltip.show()
cacher
Masque l'info-bulle d'un élément. Retourne à l'appelant avant que l'info-bulle n'ait été masquée (c'est-à-dire avant que l' hidden.bs.tooltip
événement ne se produise). Ceci est considéré comme un déclenchement "manuel" de l'info-bulle.
tooltip.hide()
basculer
Bascule l'info-bulle d'un élément. Revient à l'appelant avant que l'info-bulle n'ait été réellement affichée ou masquée (c'est-à-dire avant que l' événement shown.bs.tooltip
ou ne hidden.bs.tooltip
se produise). Ceci est considéré comme un déclenchement "manuel" de l'info-bulle.
tooltip.toggle()
disposer
Masque et détruit l'info-bulle d'un élément (supprime les données stockées sur l'élément DOM). Les info-bulles qui utilisent la délégation (qui sont créées à l'aide the selector
option) ) ne peuvent pas être détruites individuellement sur les éléments déclencheurs descendants.
tooltip.dispose()
permettre
Donne à l'info-bulle d'un élément la possibilité d'être affichée. Les info-bulles sont activées par défaut.
tooltip.enable()
désactiver
Supprime la possibilité d'afficher l'info-bulle d'un élément. L'info-bulle ne pourra s'afficher que si elle est réactivée.
tooltip.disable()
toggleEnabled
Active/désactive la possibilité d'afficher ou de masquer l'info-bulle d'un élément.
tooltip.toggleEnabled()
mettre à jour
Met à jour la position de l'info-bulle d'un élément.
tooltip.update()
getInstance
Méthode statique qui permet d'obtenir l'instance d'infobulle associée à un élément DOM
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
getOrCreateInstance
Méthode statique qui vous permet d'obtenir l'instance d'info-bulle associée à un élément DOM, ou d'en créer une nouvelle au cas où elle n'aurait pas été initialisée
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
Evènements
Type d'évènement | Description |
---|---|
show.bs.tooltip |
Cet événement se déclenche immédiatement lorsque la showméthode d'instance est appelée. |
shown.bs.tooltip |
Cet événement est déclenché lorsque l'info-bulle a été rendue visible à l'utilisateur (il attendra que les transitions CSS soient terminées). |
hide.bs.tooltip |
Cet événement est déclenché immédiatement lorsque la hideméthode d'instance a été appelée. |
hidden.bs.tooltip |
Cet événement est déclenché lorsque l'info-bulle a fini d'être masquée pour l'utilisateur (attendra que les transitions CSS soient terminées). |
inserted.bs.tooltip |
Cet événement est déclenché après l' show.bs.tooltipévénement lorsque le modèle d'info-bulle a été ajouté au DOM. |
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)
myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
// do something...
})
tooltip.hide()