Verktygstips
Dokumentation och exempel för att lägga till anpassade Bootstrap-verktygstips med CSS och JavaScript med CSS3 för animationer och dataattribut 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.js
som innehåller Popper för att verktygstips ska fungera! - Om du bygger vårt JavaScript från källan kräver
util.js
det . - 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
.disabled
ellerdisabled
element 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.
prefers-reduced-motion
mediefrå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-toggle
attribut:
$(function () {
$('[data-toggle="tooltip"]').tooltip()
})
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.
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="top" title="Tooltip on top">
Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="right" title="Tooltip on right">
Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="bottom" title="Tooltip on bottom">
Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-placement="left" title="Tooltip on left">
Tooltip on left
</button>
Och med anpassad HTML tillagd:
<button type="button" class="btn btn-secondary" data-toggle="tooltip" data-html="true" title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
Tooltip with HTML
</button>
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:
$('#example').tooltip(options)
Brädda auto
ochscroll
Verktygstipsets position försöker automatiskt ändras när en överordnad behållare har overflow: auto
eller overflow: scroll
gillar vår .table-responsive
, men behåller fortfarande den ursprungliga placeringens placering. För att lösa, ställ in boundary
alternativet på något annat än standardvärde, 'scrollParent'
, till exempel 'window'
:
$('#example').tooltip({ boundary: 'window' })
Pålägg
Den nödvändiga markeringen för ett verktygstips är bara ett data
attribut och title
på 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å top
av 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 t.ex. <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å hover
som 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-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="arrow"></div>
<div class="tooltip-inner">
Some tooltip text!
</div>
</div>
Inaktiverade element
Element med disabled
attributet ä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 tangentbordsfokuserat med tabindex="0"
, och åsidosätta pointer-events
på det inaktiverade elementet.
<span class="d-inline-block" tabindex="0" data-toggle="tooltip" title="Disabled tooltip">
<button class="btn btn-primary" style="pointer-events: none;" type="button" disabled>Disabled button</button>
</span>
alternativ
Alternativ kan skickas via dataattribut eller JavaScript. För dataattribut, lägg till alternativnamnet till data-
, som i data-animation=""
.
sanitize
Observera att alternativen ,
sanitizeFn
och
av säkerhetsskäl
whiteList
inte kan tillhandahållas med dataattribut.
namn | Typ | Standard | Beskrivning |
---|---|---|---|
animation | booleskt | Sann | Använd en CSS-tonningsövergång på verktygstipset |
behållare | sträng | element | falsk | falsk | Lägger till verktygstipset till ett specifikt element. Exempel: |
dröjsmål | 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: |
html | booleskt | falsk | Tillåt HTML i verktygstipset. Om sant, kommer HTML-taggar i verktygstipset Använd text om du är orolig för XSS-attacker. |
placering | sträng | fungera | 'topp' | Så här placerar du verktygstipset - auto | topp | botten | vänster | höger. 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 |
väljare | sträng | falsk | falsk | 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.on stöd). Se detta och ett informativt exempel . |
mall | sträng | '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>' |
Basera HTML för att använda när du skapar verktygstipset. Verktygstipsen
Det yttersta omslagselementet ska ha |
titel | sträng | element | fungera | '' | Standardtitelvärde om Om en funktion ges kommer den att anropas med dess |
utlösare | sträng | "sväva fokus" | Hur verktygstips utlöses - klicka på | sväva | fokus | manuell. Du kan passera flera triggers; separera dem med ett mellanslag.
|
offset | nummer | sträng | fungera | 0 | Förskjutning av verktygstipset i förhållande till dess mål. När en funktion används för att bestämma offset, anropas den med ett objekt som innehåller offsetdata som dess första argument. Funktionen måste returnera ett objekt med samma struktur. Det utlösande elementets DOM-nod skickas som det andra argumentet. För mer information se Poppers offset -dokument . |
fallbackPlacering | sträng | array | 'flip' | Tillåt att ange vilken position Popper kommer att använda vid reserv. För mer information se Poppers beteendedokumentation |
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: Du kan också skicka en funktion som ska returnera en enda sträng som innehåller ytterligare klassnamn. |
gräns | sträng | element | 'scrollParent' | Översvämningsbegränsningsgräns för verktygstipset. Accepterar värdena för 'viewport' , 'window' , 'scrollParent' eller en HTMLElement-referens (endast JavaScript). För mer information se Poppers preventOverflow -dokument . |
sanera | booleskt | Sann | Aktivera eller inaktivera saneringen. Om aktiverat 'template' och 'title' alternativ kommer att saneras. Se avsnittet desinficering i vår JavaScript-dokumentation . |
vitlista | 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. |
popperConfig | null | objekt | null | För att ändra Bootstraps standard Popper-konfiguration, se Poppers konfiguration |
Dataattribut för enskilda verktygstips
Alternativ för individuella verktygstips kan alternativt specificeras genom användning av dataattribut, som förklarats ovan.
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 .
$().tooltip(options)
Bifogar en verktygstipshanterare till en elementsamling.
.tooltip('show')
Visar ett elements verktygstips. Återgår till den som ringer innan verktygstipset faktiskt har visats (dvs innan shown.bs.tooltip
händelsen inträffar). Detta anses vara en "manuell" triggning av verktygstipset. Verktygstips med noll-längd titlar visas aldrig.
$('#element').tooltip('show')
.tooltip('hide')
Döljer ett elements verktygstips. Återgår till den som ringer innan verktygstipset faktiskt har dolts (dvs innan hidden.bs.tooltip
händelsen inträffar). Detta anses vara en "manuell" triggning av verktygstipset.
$('#element').tooltip('hide')
.tooltip('toggle')
Växlar ett elements verktygstips. Återgår till den som ringer innan verktygstipset faktiskt har visats eller dolt (dvs innan händelsen shown.bs.tooltip
eller hidden.bs.tooltip
inträffar). Detta anses vara en "manuell" triggning av verktygstipset.
$('#element').tooltip('toggle')
.tooltip('dispose')
Döljer och förstör ett elements verktygstips. Verktygstips som använder delegering (som skapas med alternativet selector
) kan inte förstöras individuellt på underliggande triggerelement.
$('#element').tooltip('dispose')
.tooltip('enable')
Ger ett elements verktygstips möjligheten att visas. Verktygstips är aktiverade som standard.
$('#element').tooltip('enable')
.tooltip('disable')
Tar bort möjligheten för ett elements verktygstips att visas. Verktygstipset kommer bara att kunna visas om det återaktiveras.
$('#element').tooltip('disable')
.tooltip('toggleEnabled')
Växlar möjligheten för ett elements verktygstips att visas eller döljas.
$('#element').tooltip('toggleEnabled')
.tooltip('update')
Uppdaterar positionen för ett elements verktygstips.
$('#element').tooltip('update')
evenemang
Event typ | Beskrivning |
---|---|
visa.bs.verktygstips | Denna händelse aktiveras omedelbart när show instansmetoden anropas. |
visat.bs.verktygstips | 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 hide instansmetoden har anropats. |
dolt.bs.verktygstips | Den här händelsen utlöses när verktygstipset har döljts för användaren (väntar på att CSS-övergångar ska slutföras). |
insatt.bs.verktygstips | Denna händelse aktiveras efter show.bs.tooltip händelsen när verktygstipsmallen har lagts till i DOM. |
$('#myTooltip').on('hidden.bs.tooltip', function () {
// do something...
})