Hoppa till huvudinnehållet Hoppa till dokumentnavigering
in English

Verktygstips

Dokumentation och exempel för att lägga till anpassade Bootstrap-verktygstips med CSS och JavaScript med CSS3 för animationer och data-bs-attribut för lokal titellagring.

Översikt

Saker att veta när du använder verktygstipsplugin:

  • Verktygstips förlitar sig på tredje parts bibliotek Popper för positionering. Du måste inkludera popper.min.js före bootstrap.js eller använda bootstrap.bundle.min.js/ bootstrap.bundle.jssom innehåller Popper för att verktygstips ska fungera!
  • Verktygstips är opt-in av prestandaskäl, så du måste initiera dem själv .
  • Verktygstips med noll-längd titlar visas aldrig.
  • Ange container: 'body'för att undvika att problem återges i mer komplexa komponenter (som våra indatagrupper, knappgrupper, etc).
  • Att trigga verktygstips på dolda element kommer inte att fungera.
  • Verktygstips för .disabledeller disabledelement måste utlösas på ett omslagselement.
  • När de utlöses från hyperlänkar som sträcker sig över flera rader kommer verktygstips att centreras. Använd white-space: nowrap;på din <a>s för att undvika detta beteende.
  • Verktygstips måste döljas innan deras motsvarande element har tagits bort från DOM.
  • Verktygstips kan triggas tack vare ett element inuti en skugga DOM.
Som standard använder den här komponenten den inbyggda innehållsrensaren, som tar bort alla HTML-element som inte är uttryckligen tillåtna. Se avsnittet desinficering i vår JavaScript-dokumentation för mer information.
Animeringseffekten av denna komponent beror på prefers-reduced-motionmediefrågan. Se avsnittet för reducerad rörelse i vår tillgänglighetsdokumentation .

Har du allt det där? Bra, låt oss se hur de fungerar med några exempel.

Exempel: Aktivera verktygstips överallt

Ett sätt att initiera alla verktygstips på en sida är att välja dem efter deras data-bs-toggleattribut:

var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl)
})

Exempel

Håll muspekaren över länkarna nedan för att se verktygstips:

Platshållartext för att visa några inlinelänkar med verktygstips. Det här är nu bara filler, ingen mördare. Innehåll placerat här bara för att efterlikna närvaron av verklig text . Och allt det bara för att ge dig en uppfattning om hur verktygstips skulle se ut när de används i verkliga situationer. Så förhoppningsvis har du nu sett hur dessa verktygstips om länkar kan fungera i praktiken, när du väl använder dem på din egen webbplats eller ditt projekt.

Håll muspekaren över knapparna nedan för att se de fyra verktygstipsriktningarna: topp, höger, botten och vänster. Vägbeskrivningarna speglas när du använder Bootstrap i 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>

Och med anpassad HTML tillagd:

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

Med en SVG:

Sass

Variabler

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

Användande

Verktygstipspluginen genererar innehåll och uppmärkning på begäran och placerar som standard verktygstips efter deras utlösarelement.

Aktivera verktygstipset via JavaScript:

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Brädda autoochscroll

Verktygstipsets position försöker automatiskt ändras när en överordnad behållare har overflow: autoeller overflow: scrollgillar vår .table-responsive, men behåller fortfarande den ursprungliga placeringens placering. För att lösa detta, ställ in boundaryalternativet (för vändningsmodifieraren som använder popperConfigalternativet) till valfritt HTMLElement för att åsidosätta standardvärdet, 'clippingParents', såsom document.body:

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
  boundary: document.body // or document.querySelector('#boundary')
})

Pålägg

Den nödvändiga markeringen för ett verktygstips är bara ett dataattribut och titlepå HTML-elementet vill du ha ett verktygstips. Den genererade markeringen av ett verktygstips är ganska enkel, även om den kräver en position (som standard inställd på topav plugin).

Få verktygstips att fungera för användare av tangentbord och hjälpmedel

Du bör bara lägga till verktygstips till HTML-element som traditionellt är tangentbordsfokuserade och interaktiva (som länkar eller formulärkontroller). Även om godtyckliga HTML-element (som <span>s) kan göras fokuserbara genom att lägga till tabindex="0"attributet, kommer detta att lägga till potentiellt irriterande och förvirrande tabbstopp på icke-interaktiva element för tangentbordsanvändare, och de flesta hjälpmedelstekniker meddelar för närvarande inte verktygstipset i denna situation. Dessutom, lita inte enbart på hoversom utlösare för ditt verktygstips, eftersom detta kommer att göra dina verktygstips omöjliga att utlösa för tangentbordsanvändare.

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

Inaktiverade element

Element med disabledattributet är inte interaktiva, vilket innebär att användare inte kan fokusera, hålla muspekaren eller klicka på dem för att utlösa ett verktygstips (eller popover). Som en lösning bör du trigga verktygstipset från ett omslag <div>eller <span>, idealiskt gjort tangentbordsfokuserbart med 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>

alternativ

Alternativ kan skickas via dataattribut eller JavaScript. För dataattribut, lägg till alternativnamnet till data-bs-, som i data-bs-animation="". Se till att ändra fallets typ av alternativnamnet från camelCase till kebab-case när du skickar alternativen via dataattribut. Använd till exempel istället för att data-bs-customClass="beautifier"använda data-bs-custom-class="beautifier".

sanitizeObservera att alternativen , sanitizeFn, och av säkerhetsskäl allowListinte kan tillhandahållas med dataattribut.
namn Typ Standard Beskrivning
animation booleskt true Använd en CSS-tonningsövergång på verktygstipset
container sträng | element | falsk false

Lägger till verktygstipset till ett specifikt element. Exempel: container: 'body'. Det här alternativet är särskilt användbart eftersom det låter dig placera verktygstipset i dokumentflödet nära det utlösande elementet - vilket kommer att förhindra verktygstipset från att flyta bort från det utlösande elementet under en fönsterstorleksändring.

delay nummer | objekt 0

Fördröjning av att visa och dölja verktygstipset (ms) - gäller inte manuell triggertyp

Om ett nummer tillhandahålls tillämpas fördröjning på både hide/show

Objektstrukturen är:delay: { "show": 500, "hide": 100 }

html booleskt false

Tillåt HTML i verktygstipset.

Om sant, kommer HTML-taggar i verktygstipset titleatt renderas i verktygstipset. Om det är falskt kommer innerTextegenskapen att användas för att infoga innehåll i DOM.

Använd text om du är orolig för XSS-attacker.

placement sträng | fungera 'top'

Så här placerar du verktygstipset - auto | topp | botten | vänster | höger.
När autodet är specificerat kommer det dynamiskt att omorientera verktygstipset.

När en funktion används för att bestämma placeringen anropas den med verktygstipset DOM-nod som sitt första argument och det utlösande elementet DOM-nod som sin andra. Kontexten thisär inställd på verktygstipsinstansen.

selector sträng | falsk false Om en väljare tillhandahålls kommer verktygstipsobjekt att delegeras till de angivna målen. I praktiken används detta för att även tillämpa verktygstips på dynamiskt tillagda DOM-element ( jQuery.onstöd). Se detta och ett informativt exempel .
template sträng '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'

Basera HTML för att använda när du skapar verktygstipset.

Verktygstipsen titlekommer att injiceras i .tooltip-inner.

.tooltip-arrowkommer att bli verktygstipsets pil.

Det yttersta omslagselementet ska ha .tooltipklassen och role="tooltip".

title sträng | element | fungera ''

Standardtitelvärde om titleattributet inte finns.

Om en funktion ges kommer den att anropas med dess thisreferensuppsättning till elementet som verktygstipset är kopplat till.

trigger sträng 'hover focus'

Hur verktygstips utlöses - klicka på | sväva | fokus | manuell. Du kan passera flera triggers; separera dem med ett mellanslag.

'manual'indikerar att verktygstipset kommer att triggas programmatiskt via metoderna .show(), .hide()och ; .toggle()detta värde kan inte kombineras med någon annan trigger.

'hover'på egen hand kommer att resultera i verktygstips som inte kan triggas via tangentbordet, och bör endast användas om alternativa metoder för att förmedla samma information till tangentbordsanvändare finns.

fallbackPlacements array ['top', 'right', 'bottom', 'left'] Definiera reservplaceringar genom att tillhandahålla en lista över placeringar i array (i prioritetsordning). För mer information se Poppers beteendedokumentation
boundary sträng | element 'clippingParents' Bräddningsbegränsningsgräns för verktygstipset (gäller endast Poppers preventOverflow-modifierare). Som standard är det 'clippingParents'och kan acceptera en HTMLElement-referens (endast via JavaScript). För mer information se Poppers detectOverflow -dokument .
customClass sträng | fungera ''

Lägg till klasser i verktygstipset när det visas. Observera att dessa klasser kommer att läggas till utöver de klasser som anges i mallen. För att lägga till flera klasser, separera dem med mellanslag: 'class-1 class-2'.

Du kan också skicka en funktion som ska returnera en enda sträng som innehåller ytterligare klassnamn.

sanitize booleskt true Aktivera eller inaktivera saneringen. Om aktiverat 'template'och 'title'alternativ kommer att saneras. Se avsnittet desinficering i vår JavaScript-dokumentation .
allowList objekt Standardvärde Objekt som innehåller tillåtna attribut och taggar
sanitizeFn null | fungera null Här kan du tillhandahålla din egen desinficeringsfunktion. Detta kan vara användbart om du föredrar att använda ett dedikerat bibliotek för att utföra sanering.
offset array | sträng | fungera [0, 0]

Förskjutning av verktygstipset i förhållande till dess mål. Du kan skicka en sträng i dataattribut med kommaseparerade värden som:data-bs-offset="10,20"

När en funktion används för att bestämma offset, anropas den med ett objekt som innehåller popperplaceringen, referensen och popper rects som dess första argument. Det utlösande elementets DOM-nod skickas som det andra argumentet. Funktionen måste returnera en matris med två siffror: .[skidding, distance]

För mer information se Poppers offset -dokument .

popperConfig null | objekt | fungera null

För att ändra Bootstraps standard Popper-konfiguration, se Poppers konfiguration .

När en funktion används för att skapa Popper-konfigurationen, anropas den med ett objekt som innehåller Bootstraps standard Popper-konfiguration. Det hjälper dig att använda och slå samman standarden med din egen konfiguration. Funktionen måste returnera ett konfigurationsobjekt för Popper.

Dataattribut för enskilda verktygstips

Alternativ för individuella verktygstips kan alternativt specificeras genom användning av dataattribut, som förklarats ovan.

Använder funktion medpopperConfig

var tooltip = new bootstrap.Tooltip(element, {
  popperConfig: function (defaultBsPopperConfig) {
    // var newPopperConfig = {...}
    // use defaultBsPopperConfig if needed...
    // return newPopperConfig
  }
})

Metoder

Asynkrona metoder och övergångar

Alla API - metoder är asynkrona och startar en övergång . De återvänder till den som ringer så snart övergången har påbörjats men innan den slutar . Dessutom kommer ett metodanrop på en övergångskomponent att ignoreras .

Se vår JavaScript-dokumentation för mer information .

show

Visar ett elements verktygstips. Återgår till den som ringer innan verktygstipset faktiskt har visats (dvs innan shown.bs.tooltiphändelsen inträffar). Detta anses vara en "manuell" triggning av verktygstipset. Verktygstips med noll-längd titlar visas aldrig.

tooltip.show()

Dölj

Döljer ett elements verktygstips. Återgår till den som ringer innan verktygstipset faktiskt har dolts (dvs innan hidden.bs.tooltiphändelsen inträffar). Detta anses vara en "manuell" triggning av verktygstipset.

tooltip.hide()

växla

Växlar ett elements verktygstips. Återgår till den som ringer innan verktygstipset faktiskt har visats eller dolt (dvs innan händelsen shown.bs.tooltipeller hidden.bs.tooltipinträffar). Detta anses vara en "manuell" triggning av verktygstipset.

tooltip.toggle()

kassera

Döljer och förstör ett elements verktygstips (tar bort lagrad data på DOM-elementet). Verktygstips som använder delegering (som skapas med alternativet selector) kan inte förstöras individuellt på underliggande triggerelement.

tooltip.dispose()

Gör det möjligt

Ger ett elements verktygstips möjligheten att visas. Verktygstips är aktiverade som standard.

tooltip.enable()

inaktivera

Tar bort möjligheten för ett elements verktygstips att visas. Verktygstipset kommer bara att kunna visas om det återaktiveras.

tooltip.disable()

toggleEnabled

Växlar möjligheten för ett elements verktygstips att visas eller döljas.

tooltip.toggleEnabled()

uppdatering

Uppdaterar positionen för ett elements verktygstips.

tooltip.update()

getInstance

Statisk metod som låter dig få verktygstipsinstansen associerad med ett DOM-element

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance

getOrCreateInstance

Statisk metod som låter dig få verktygstipsinstansen associerad med ett DOM-element, eller skapa en ny om den inte initierades

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance

evenemang

Event typ Beskrivning
show.bs.tooltip Denna händelse aktiveras omedelbart när showinstansmetoden anropas.
shown.bs.tooltip Denna händelse utlöses när verktygstipset har gjorts synligt för användaren (väntar på att CSS-övergångar ska slutföras).
hide.bs.tooltip Denna händelse aktiveras omedelbart när hideinstansmetoden har anropats.
hidden.bs.tooltip Den här händelsen aktiveras när verktygstipset har döljts för användaren (väntar på att CSS-övergångar ska slutföras).
inserted.bs.tooltip Denna händelse aktiveras efter show.bs.tooltiphändelsen när verktygstipsmallen har lagts till i DOM.
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
  // do something...
})

tooltip.hide()