Værktøjstip
Dokumentation og eksempler på tilføjelse af brugerdefinerede Bootstrap-værktøjstip med CSS og JavaScript ved hjælp af CSS3 til animationer og data-bs-attributter til lokal titellagring.
Oversigt
Ting at vide, når du bruger værktøjstip-plugin:
- Værktøjstip er afhængige af 3. parts bibliotek Popper til positionering. Du skal inkludere popper.min.js før bootstrap.js eller bruge
bootstrap.bundle.min.js
/bootstrap.bundle.js
som indeholder Popper for at værktøjstip skal virke! - Værktøjstip er opt-in af ydeevnemæssige årsager, så du skal selv initialisere dem .
- Værktøjstip med titler på nul længde vises aldrig.
- Angiv
container: 'body'
for at undgå gengivelse af problemer i mere komplekse komponenter (såsom vores inputgrupper, knapgrupper osv.). - At udløse værktøjstip på skjulte elementer vil ikke fungere.
- Værktøjstip til
.disabled
ellerdisabled
elementer skal udløses på et indpakningselement. - Når de udløses fra hyperlinks, der spænder over flere linjer, vil værktøjstip blive centreret. Brug
white-space: nowrap;
på dine<a>
s for at undgå denne adfærd. - Værktøjstip skal skjules, før deres tilsvarende elementer er blevet fjernet fra DOM.
- Værktøjstip kan udløses takket være et element inde i en skygge-DOM.
prefers-reduced-motion
medieforespørgslen. Se afsnittet om
reduceret bevægelse i vores tilgængelighedsdokumentation .
Har du alt det? Godt, lad os se, hvordan de fungerer med nogle eksempler.
Eksempel: Aktiver værktøjstip overalt
En måde at initialisere alle værktøjstip på en side ville være at vælge dem efter deres data-bs-toggle
egenskab:
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
return new bootstrap.Tooltip(tooltipTriggerEl)
})
Eksempler
Hold markøren over nedenstående links for at se værktøjstip:
Pladsholdertekst for at demonstrere nogle inline-links med værktøjstip. Dette er nu bare fyldstof, ingen dræber. Indhold placeret her blot for at efterligne tilstedeværelsen af ægte tekst . Og alt det bare for at give dig en idé om, hvordan værktøjstip ville se ud, når de bruges i virkelige situationer. Så forhåbentlig har du nu set, hvordan disse værktøjstip om links kan fungere i praksis, når du først har brugt dem på dit eget websted eller dit eget projekt.
Hold markøren over knapperne nedenfor for at se de fire værktøjstip-retninger: top, højre, bund og venstre. Retninger spejles, når du bruger 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>
Og med tilpasset HTML tilføjet:
<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;
Brug
Værktøjstip-pluginnet genererer indhold og opmærkning efter behov og placerer som standard værktøjstip efter deres udløserelement.
Udløs værktøjstippet via JavaScript:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Overløb auto
ogscroll
Værktøjstip-position forsøger automatisk at ændre sig, når en overordnet container har overflow: auto
eller overflow: scroll
kan lide vores .table-responsive
, men beholder stadig den oprindelige placerings placering. For at løse dette skal du indstille boundary
indstillingen (for vendemodifikatoren, der bruger popperConfig
indstillingen) til ethvert HTMLElement for at tilsidesætte standardværdien, 'clippingParents'
, såsom document.body
:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
boundary: document.body // or document.querySelector('#boundary')
})
Markup
Den nødvendige markering for et værktøjstip er kun en data
attribut, og title
på HTML-elementet ønsker du at have et værktøjstip. Den genererede markering af et værktøjstip er ret enkel, selvom den kræver en position (som standard indstillet til top
af plugin).
Få værktøjstip til at fungere for brugere af tastatur og hjælpemidler
Du bør kun tilføje værktøjstip til HTML-elementer, der traditionelt er tastaturfokuserbare og interaktive (såsom links eller formularkontrolelementer). Selvom vilkårlige HTML-elementer (såsom <span>
s) kan gøres fokusbare ved at tilføje tabindex="0"
attributten, vil dette tilføje potentielt irriterende og forvirrende tabulatorstop på ikke-interaktive elementer for tastaturbrugere, og de fleste hjælpeteknologier annoncerer i øjeblikket ikke værktøjstip i denne situation. Derudover skal du ikke stole udelukkende på hover
som udløser for dit værktøjstip, da dette vil gøre dine værktøjstip umulige at udløse for tastaturbrugere.
<!-- 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>
Deaktiverede elementer
Elementer med disabled
attributten er ikke interaktive, hvilket betyder, at brugere ikke kan fokusere, svæve eller klikke på dem for at udløse et værktøjstip (eller popover). Som en løsning vil du gerne udløse værktøjstippet fra en indpakning <div>
eller <span>
, ideelt lavet tastaturfokuserbart ved hjælp af 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>
Muligheder
Indstillinger kan videregives via dataattributter eller JavaScript. For dataattributter skal du tilføje indstillingsnavnet til data-bs-
, som i data-bs-animation=""
. Sørg for at ændre sagstypen for indstillingsnavnet fra camelCase til kebab-case, når du videregiver mulighederne via dataattributter. Brug f.eks. i stedet for at data-bs-customClass="beautifier"
bruge data-bs-custom-class="beautifier"
.
sanitize
Bemærk, at valgmulighederne ,
sanitizeFn
, og
af sikkerhedsmæssige årsager
allowList
ikke kan leveres ved hjælp af dataattributter.
Navn | Type | Standard | Beskrivelse |
---|---|---|---|
animation |
boolesk | true |
Anvend en CSS-fade-overgang til værktøjstip |
container |
streng | element | falsk | false |
Føjer værktøjstip til et bestemt element. Eksempel: |
delay |
nummer | objekt | 0 |
Forsinket visning og skjulning af værktøjstip (ms) - gælder ikke for manuel triggertype Hvis et nummer er angivet, anvendes forsinkelse på både skjul/show Objektstrukturen er: |
html |
boolesk | false |
Tillad HTML i værktøjstippet. Hvis det er sandt, vil HTML-tags i værktøjstippet Brug tekst, hvis du er bekymret for XSS-angreb. |
placement |
streng | fungere | 'top' |
Sådan placeres værktøjstip - auto | top | nederst | venstre | ret. Når en funktion bruges til at bestemme placeringen, kaldes den med værktøjstip DOM-knudepunktet som dets første argument og det udløsende element DOM-noden som dets andet. Konteksten |
selector |
streng | falsk | false |
Hvis der er angivet en vælger, vil værktøjstip-objekter blive uddelegeret til de angivne mål. I praksis bruges dette til også at anvende værktøjstip til dynamisk tilføjede DOM-elementer ( jQuery.on understøttelse). Se dette og et informativt eksempel . |
template |
snor | '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' |
Base HTML til brug ved oprettelse af værktøjstip. Værktøjstip
Det yderste indpakningselement skal have |
title |
streng | element | fungere | '' |
Standard titelværdi, hvis Hvis en funktion er givet, vil den blive kaldt med dens |
trigger |
snor | 'hover focus' |
Hvordan værktøjstip udløses - klik | svæv | fokus | brugervejledning. Du kan passere flere triggere; adskille dem med et mellemrum.
|
fallbackPlacements |
array | ['top', 'right', 'bottom', 'left'] |
Definer reserveplaceringer ved at angive en liste over placeringer i matrix (i præferencerækkefølge). For mere information henvises til Poppers adfærdsdokumentation |
boundary |
streng | element | 'clippingParents' |
Overløbsbegrænsningsgrænse for værktøjstip (gælder kun for Poppers preventOverflow-modifikator). Som standard er 'clippingParents' og kan det acceptere en HTMLElement-reference (kun via JavaScript). For mere information henvises til Poppers detectOverflow-dokumenter . |
customClass |
streng | fungere | '' |
Tilføj klasser til værktøjstippet, når det vises. Bemærk, at disse klasser vil blive tilføjet ud over de klasser, der er angivet i skabelonen. For at tilføje flere klasser skal du adskille dem med mellemrum: Du kan også sende en funktion, der skal returnere en enkelt streng, der indeholder yderligere klassenavne. |
sanitize |
boolesk | true |
Aktiver eller deaktiver desinficering. Hvis aktiveret, 'template' og 'title' indstillinger vil blive renset. Se afsnittet om desinfektion i vores JavaScript-dokumentation . |
allowList |
objekt | Standard værdi | Objekt som indeholder tilladte attributter og tags |
sanitizeFn |
null | fungere | null |
Her kan du levere din egen desinficeringsfunktion. Dette kan være nyttigt, hvis du foretrækker at bruge et dedikeret bibliotek til at udføre desinficering. |
offset |
række | streng | fungere | [0, 0] |
Forskydning af værktøjstip i forhold til dets mål. Du kan sende en streng i dataattributter med kommaseparerede værdier som: Når en funktion bruges til at bestemme forskydningen, kaldes den med et objekt, der indeholder popperplaceringen, referencen og popper rects som dets første argument. Det udløsende element DOM-node sendes som det andet argument. Funktionen skal returnere en matrix med to tal: . For mere information henvises til Poppers offset-dokumenter . |
popperConfig |
null | objekt | fungere | null |
For at ændre Bootstraps standard Popper -konfiguration, se Poppers konfiguration . Når en funktion bruges til at oprette Popper-konfigurationen, kaldes den med et objekt, der indeholder Bootstraps standard Popper-konfiguration. Det hjælper dig med at bruge og flette standarden med din egen konfiguration. Funktionen skal returnere et konfigurationsobjekt for Popper. |
Dataattributter for individuelle værktøjstip
Valgmuligheder for individuelle værktøjstip kan alternativt specificeres ved brug af dataattributter, som forklaret ovenfor.
Bruger funktion medpopperConfig
var tooltip = new bootstrap.Tooltip(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
Metoder
Asynkrone metoder og overgange
Alle API - metoder er asynkrone og starter en overgang . De vender tilbage til den, der ringer, så snart overgangen er startet, men før den slutter . Derudover vil et metodekald på en overgangskomponent blive ignoreret .
at vise
Viser et elements værktøjstip. Vender tilbage til den, der ringer, før værktøjstip faktisk er blevet vist (dvs. før shown.bs.tooltip
hændelsen indtræffer). Dette betragtes som en "manuel" udløsning af værktøjstip. Værktøjstip med titler på nul længde vises aldrig.
tooltip.show()
skjule
Skjuler et elements værktøjstip. Vender tilbage til den, der ringer, før værktøjstip rent faktisk er blevet skjult (dvs. før hidden.bs.tooltip
hændelsen indtræffer). Dette betragtes som en "manuel" udløsning af værktøjstip.
tooltip.hide()
skifte
Skifter et elements værktøjstip. Vender tilbage til den, der ringer, før værktøjstip faktisk er blevet vist eller skjult (dvs. før hændelsen shown.bs.tooltip
eller hidden.bs.tooltip
indtræffer). Dette betragtes som en "manuel" udløsning af værktøjstip.
tooltip.toggle()
bortskaffe
Skjuler og ødelægger et elements værktøjstip (fjerner lagrede data på DOM-elementet). Værktøjstip, der bruger delegering (som oprettes ved hjælp af selector
muligheden ), kan ikke individuelt destrueres på efterkommer-triggerelementer.
tooltip.dispose()
aktivere
Giver et elements værktøjstip mulighed for at blive vist. Værktøjstip er aktiveret som standard.
tooltip.enable()
deaktivere
Fjerner muligheden for, at et elements værktøjstip vises. Værktøjstippet vil kun kunne vises, hvis det er genaktiveret.
tooltip.disable()
toggleAktiveret
Skifter muligheden for, at et elements værktøjstip vises eller skjules.
tooltip.toggleEnabled()
opdatering
Opdaterer placeringen af et elements værktøjstip.
tooltip.update()
getInstance
Statisk metode, som giver dig mulighed for at få værktøjstip-instansen tilknyttet et DOM-element
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
getOrCreateInstance
Statisk metode, som giver dig mulighed for at få værktøjstip-instansen tilknyttet et DOM-element, eller oprette en ny, hvis den ikke blev initialiseret
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
Begivenheder
Begivenhedstype | Beskrivelse |
---|---|
show.bs.tooltip |
Denne hændelse udløses med det samme, når show instansmetoden kaldes. |
shown.bs.tooltip |
Denne hændelse udløses, når værktøjstippet er gjort synligt for brugeren (vil vente på, at CSS-overgange er fuldført). |
hide.bs.tooltip |
Denne hændelse udløses straks, når hide instansmetoden er blevet kaldt. |
hidden.bs.tooltip |
Denne hændelse udløses, når værktøjstip er færdig med at blive skjult for brugeren (vil vente på, at CSS-overgange er fuldført). |
inserted.bs.tooltip |
Denne hændelse udløses efter show.bs.tooltip hændelsen, når værktøjstip-skabelonen er blevet tilføjet til DOM. |
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)
myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
// do something...
})
tooltip.hide()