Popisy
Dokumentácia a príklady na pridávanie vlastných tipov pre bootstrap s CSS a JavaScript pomocou CSS3 pre animácie a data-bs-atribútov pre lokálne ukladanie titulkov.
Prehľad
Čo by ste mali vedieť pri používaní doplnku tooltip:
- Pri určovaní polohy sa popisy spoliehajú na knižnicu Popper tretej strany . Aby popisky fungovali, musíte zahrnúť popper.min.js pred bootstrap.js alebo použiť
bootstrap.bundle.min.js
/bootstrap.bundle.js
ktorý obsahuje Popper! - Popisy sú aktivované z dôvodov výkonu, takže ich musíte inicializovať sami .
- Popisy s názvami s nulovou dĺžkou sa nikdy nezobrazujú.
- Špecifikujte
container: 'body'
, aby ste sa vyhli problémom s vykresľovaním v zložitejších komponentoch (ako sú naše vstupné skupiny, skupiny tlačidiel atď.). - Spúšťanie popisov na skrytých prvkoch nebude fungovať.
- Popisy prvkov
.disabled
alebodisabled
prvkov musia byť spustené na prvku obalu. - Pri spustení z hypertextových odkazov, ktoré presahujú viacero riadkov, budú popisy nástrojov vycentrované. Použite
white-space: nowrap;
na<a>
s, aby ste sa vyhli tomuto správaniu. - Popisy nástrojov musia byť skryté pred odstránením príslušných prvkov z modelu DOM.
- Popisy nástrojov možno spustiť vďaka prvku vo vnútri tieňového modelu DOM.
prefers-reduced-motion
mediálneho dopytu. Pozrite si
časť so zníženým pohybom v našej dokumentácii o prístupnosti .
Máš to všetko? Skvelé, pozrime sa, ako fungujú s niekoľkými príkladmi.
Príklad: Povoľte popisy všade
Jedným zo spôsobov, ako inicializovať všetky popisy na stránke, je vybrať ich podľa ich data-bs-toggle
atribútu:
var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
return new bootstrap.Tooltip(tooltipTriggerEl)
})
Príklady
Umiestnením kurzora myši na odkazy nižšie zobrazíte popisy:
Zástupný text na demonštráciu niektorých vložených odkazov s popismi. Toto je teraz len výplň, žiadny zabijak. Obsah, ktorý je tu umiestnený, len napodobňuje prítomnosť skutočného textu . A to všetko len preto, aby ste mali predstavu o tom, ako by popisky vyzerali pri použití v reálnych situáciách. Dúfame, že ste teraz videli, ako môžu tieto tipy na odkazy fungovať v praxi, keď ich použijete na svojej vlastnej stránke alebo projekte.
Umiestnením kurzora myši na tlačidlá nižšie zobrazíte štyri smery popisov: hore, vpravo, dole a vľavo. Pokyny sa zrkadlia pri použití Bootstrapu v 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>
A s pridaným vlastným HTML:
<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>
S SVG:
Sass
Premenné
$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;
Použitie
Doplnok tooltip generuje obsah a značky na požiadanie a v predvolenom nastavení umiestňuje popisky za ich spúšťací prvok.
Spustite popis pomocou JavaScriptu:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Pretečenie auto
ascroll
Pozícia popisku sa pokúsi automaticky zmeniť, keď má nadradený kontajneroverflow: auto
alebo sa mu overflow: scroll
páči náš .table-responsive
, ale stále si zachováva pôvodné umiestnenie. Ak to chcete vyriešiť, nastavte boundary
voľbu (pre modifikátor prevrátenia pomocou popperConfig
voľby) na ľubovoľný HTMLElement, čím prepíšete predvolenú hodnotu, 'clippingParents'
ako napríklad document.body
:
var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, {
boundary: document.body // or document.querySelector('#boundary')
})
Označenie
Požadované označenie pre popis je iba data
atribút a title
na elemente HTML chcete mať popis. Vygenerované označenie popisku je pomerne jednoduché, hoci vyžaduje pozíciu (v predvolenom nastavení top
ju doplnok nastaví na hodnotu).
Zabezpečte, aby popisy fungovali pre používateľov klávesnice a asistenčných technológií
Popisy nástrojov by ste mali pridávať len k prvkom HTML, ktoré sú tradične zamerané na klávesnicu a sú interaktívne (napríklad odkazy alebo ovládacie prvky formulárov). Hoci ľubovoľné prvky HTML (napríklad <span>
s) je možné upraviť tak, aby bolo možné zamerať ich pridaním tabindex="0"
atribútu, pre používateľov klávesnice to pridajú potenciálne nepríjemné a mätúce zarážky tabulátora na neinteraktívnych prvkoch a väčšina asistenčných technológií v súčasnosti v tejto situácii neoznamuje popis. Okrem toho sa nespoliehajte iba na hover
spúšťač pre váš popis, pretože to znemožní spustenie vašich popisov pre používateľov klávesnice.
<!-- 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>
Zakázané prvky
Prvky s disabled
atribútom nie sú interaktívne, čo znamená, že používatelia na ne nemôžu zaostriť, umiestniť kurzor myši alebo kliknúť na ne, aby vyvolali popis (alebo kontextové okno). Ako riešenie budete chcieť spustiť popis z obalu <div>
alebo <span>
, ideálne tak, aby bolo možné zamerať sa na klávesnicu pomocou 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>
možnosti
Možnosti môžu byť odovzdané prostredníctvom dátových atribútov alebo JavaScriptu. Pre atribúty údajov pripojte názov voľby k data-bs-
, ako v data-bs-animation=""
. Pri odovzdávaní možností cez dátové atribúty nezabudnite zmeniť typ prípadu názvu možnosti z camelCase na kebab-case. Napríklad namiesto použitia data-bs-customClass="beautifier"
použite data-bs-custom-class="beautifier"
.
sanitize
,
sanitizeFn
, a
dodať pomocou atribútov údajov.allowList
názov | Typ | Predvolené | Popis |
---|---|---|---|
animation |
boolovská hodnota | true |
Na popis použite prechod zoslabovania CSS |
container |
reťazec | prvok | falošný | false |
Pridá popis ku konkrétnemu prvku. Príklad: |
delay |
číslo | objekt | 0 |
Oneskorenie zobrazenia a skrytia tooltipu (ms) – netýka sa manuálneho typu spúšťania Ak je zadané číslo, oneskorenie sa použije na skrytie/zobrazenie Štruktúra objektu je: |
html |
boolovská hodnota | false |
Povoliť HTML v popise. Ak je pravda, značky HTML v popise Ak sa obávate útokov XSS, použite text. |
placement |
reťazec | funkciu | 'top' |
Ako umiestniť popis – auto | hore | dole | vľavo | správny. Keď sa na určenie umiestnenia použije funkcia, volá sa s popisom uzla DOM ako jej prvým argumentom a spúšťacím prvkom uzlom DOM ako jej druhým. Kontext |
selector |
reťazec | falošný | false |
Ak je k dispozícii selektor, objekty popisov budú delegované na zadané ciele. V praxi sa to používa aj na aplikáciu tooltipov na dynamicky pridávané prvky DOM ( jQuery.on podpora). Pozrite si tento a informatívny príklad . |
template |
reťazec | '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' |
Základný kód HTML, ktorý sa má použiť pri vytváraní popisu. Popis
Prvok vonkajšieho obalu by mal mať |
title |
reťazec | prvok | funkciu | '' |
Predvolená hodnota názvu, ak Ak je zadaná funkcia, zavolá sa so svojou |
trigger |
reťazec | 'hover focus' |
Ako sa spúšťa popis – kliknite | vznášať sa | zameranie | Manuálny. Môžete prejsť viacerými spúšťačmi; oddeľte ich medzerou.
|
fallbackPlacements |
pole | ['top', 'right', 'bottom', 'left'] |
Definujte záložné umiestnenia poskytnutím zoznamu umiestnení v poli (v poradí podľa preferencie). Ďalšie informácie nájdete v dokumentoch o správaní Poppera |
boundary |
reťazec | prvok | 'clippingParents' |
Hranica obmedzenia pretečenia popisku (platí len pre Popperov modifikátor preventOverflow). V predvolenom nastavení je 'clippingParents' a môže akceptovať referenciu HTMLElement (iba cez JavaScript). Ďalšie informácie nájdete v dokumentoch Popper's detectOverflow . |
customClass |
reťazec | funkciu | '' |
Keď sa zobrazí popis, pridajte triedy. Všimnite si, že tieto triedy budú pridané k všetkým triedam špecifikovaným v šablóne. Ak chcete pridať viacero tried, oddeľte ich medzerami: Môžete tiež odovzdať funkciu, ktorá by mala vrátiť jeden reťazec obsahujúci ďalšie názvy tried. |
sanitize |
boolovská hodnota | true |
Povoliť alebo zakázať dezinfekciu. Ak je aktivovaný 'template' a 'title' možnosti budú dezinfikované. Pozrite si sekciu dezinfekcie v našej dokumentácii JavaScript . |
allowList |
objekt | Predvolená hodnota | Objekt, ktorý obsahuje povolené atribúty a značky |
sanitizeFn |
null | funkciu | null |
Tu si môžete dodať vlastnú funkciu dezinfekcie. To môže byť užitočné, ak uprednostňujete použitie špeciálnej knižnice na vykonanie dezinfekcie. |
offset |
pole | reťazec | funkciu | [0, 0] |
Odsadenie popisku vzhľadom na jeho cieľ. V atribútoch údajov môžete zadať reťazec s hodnotami oddelenými čiarkou, ako sú: Keď sa funkcia používa na určenie posunu, volá sa s objektom obsahujúcim umiestnenie popper, referenciu a popper rects ako svoj prvý argument. Uzol DOM spúšťacieho prvku sa odovzdá ako druhý argument. Funkcia musí vrátiť pole s dvoma číslami: . Ďalšie informácie nájdete v dokumentoch Popper's ofset . |
popperConfig |
null | objekt | funkciu | null |
Ak chcete zmeniť predvolenú konfiguráciu Popper pre Bootstrap, pozrite si Konfiguráciu Poppera . Keď sa funkcia používa na vytvorenie konfigurácie Popper, volá sa s objektom, ktorý obsahuje predvolenú konfiguráciu Popper Bootstrapu. Pomôže vám použiť a zlúčiť predvolené nastavenie s vašou vlastnou konfiguráciou. Funkcia musí vrátiť konfiguračný objekt pre Popper. |
Atribúty údajov pre jednotlivé popisy
Možnosti pre jednotlivé popisy nástrojov možno alternatívne špecifikovať pomocou atribútov údajov, ako je vysvetlené vyššie.
Použitie funkcie spopperConfig
var tooltip = new bootstrap.Tooltip(element, {
popperConfig: function (defaultBsPopperConfig) {
// var newPopperConfig = {...}
// use defaultBsPopperConfig if needed...
// return newPopperConfig
}
})
Metódy
Asynchrónne metódy a prechody
Všetky metódy API sú asynchrónne a spúšťajú prechod . Vrátia sa k volajúcemu hneď po spustení prechodu, ale skôr, ako sa skončí . Okrem toho bude volanie metódy na prechodovom komponente ignorované .
šou
Zobrazí popis prvku. Vráti sa k volajúcemu skôr, ako sa skutočne zobrazil popis (tj predtým, ako shown.bs.tooltip
dôjde k udalosti). Toto sa považuje za „manuálne“ spustenie popisku. Popisy s názvami s nulovou dĺžkou sa nikdy nezobrazujú.
tooltip.show()
skryť
Skryje popis prvku. Vráti sa k volajúcemu skôr, ako bol popis skutočne skrytý (tj pred výskytom hidden.bs.tooltip
udalosti). Toto sa považuje za „manuálne“ spustenie popisku.
tooltip.hide()
prepnúť
Prepína popis prvku. Vráti sa k volajúcemu skôr, ako sa popis skutočne zobrazí alebo skryje (tj predtým, ako nastane udalosť shown.bs.tooltip
alebo ). hidden.bs.tooltip
Toto sa považuje za „manuálne“ spustenie popisku.
tooltip.toggle()
disponovať
Skryje a zničí popis prvku (odstráni uložené údaje v prvku DOM). Popisy, ktoré používajú delegovanie (ktoré sú vytvorené pomocou voľby ) selector
, nemožno jednotlivo zničiť na podradených spúšťacích prvkoch.
tooltip.dispose()
povoliť
Umožňuje zobraziť popis prvku. Popisy nástrojov sú predvolene povolené.
tooltip.enable()
zakázať
Odstráni možnosť zobrazenia popisu prvku. Popis bude možné zobraziť iba vtedy, ak bude znova povolený.
tooltip.disable()
toggleEnabled
Prepína možnosť zobrazenia alebo skrytia popisku prvku.
tooltip.toggleEnabled()
aktualizovať
Aktualizuje polohu popisku prvku.
tooltip.update()
getInstance
Statická metóda, ktorá vám umožňuje získať inštanciu popisu priradenú k prvku DOM
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
getOrCreateInstance
Statická metóda, ktorá vám umožňuje získať inštanciu popisu priradenú k prvku DOM alebo vytvoriť novú v prípade, že nebola inicializovaná
var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance
Diania
Typ udalosti | Popis |
---|---|
show.bs.tooltip |
Táto udalosť sa spustí okamžite po show zavolaní metódy inštancie. |
shown.bs.tooltip |
Táto udalosť sa spustí, keď sa popis zobrazí používateľovi (bude čakať na dokončenie prechodov CSS). |
hide.bs.tooltip |
Táto udalosť sa spustí okamžite po hide zavolaní metódy inštancie. |
hidden.bs.tooltip |
Táto udalosť sa spustí, keď skončí skrytie popisu pred používateľom (bude čakať na dokončenie prechodov CSS). |
inserted.bs.tooltip |
Táto udalosť sa spustí po show.bs.tooltip udalosti, keď bola šablóna popisu pridaná do modelu DOM. |
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)
myTooltipEl.addEventListener('hidden.bs.tooltip', function () {
// do something...
})
tooltip.hide()