Preskoči na glavni sadržaj Preskoči na navigaciju dokumenata
Check

Dokumentacija i primjeri za dodavanje prilagođenih Bootstrap opisa alata sa CSS-om i JavaScript-om koristeći CSS3 za animacije i data-bs-atribute za lokalno skladištenje naslova.

Pregled

Stvari koje trebate znati kada koristite dodatak za opis alata:

  • Alati se oslanjaju na biblioteku treće strane Popper za pozicioniranje. Morate uključiti popper.min.js prije bootstrap.jsili koristiti onaj bootstrap.bundle.min.jskoji sadrži Popper.
  • Alati su uključeni iz razloga performansi, tako da ih morate sami inicijalizirati .
  • Alati sa naslovima nulte dužine se nikada ne prikazuju.
  • Odredite container: 'body'kako biste izbjegli probleme s prikazivanjem u složenijim komponentama (kao što su naše grupe za unos, grupe dugmadi, itd.).
  • Aktiviranje opisa alata na skrivenim elementima neće raditi.
  • Oznake za .disabledili disabledelemente moraju se pokrenuti na elementu omotača.
  • Kada se aktiviraju od hiperveza koje se protežu na više redova, opisi alata će biti centrirani. Koristite white-space: nowrap;na vašem <a>s da biste izbjegli ovo ponašanje.
  • Alati moraju biti skriveni prije nego što se njihovi odgovarajući elementi uklone iz DOM-a.
  • Alati se mogu pokrenuti zahvaljujući elementu unutar DOM-a u sjeni.

Imaš sve to? Sjajno, da vidimo kako rade na nekim primjerima.

Prema zadanim postavkama, ova komponenta koristi ugrađenu dezinfekciju sadržaja, koja uklanja sve HTML elemente koji nisu eksplicitno dozvoljeni. Za više detalja pogledajte odjeljak za dezinfekciju u našoj JavaScript dokumentaciji .
Efekt animacije ove komponente ovisi o prefers-reduced-motionmedijskom upitu. Pogledajte odjeljak o smanjenom pokretu u našoj dokumentaciji o pristupačnosti .

Primjeri

Omogući opise alata

Kao što je gore spomenuto, morate inicijalizirati opise alata prije nego što se mogu koristiti. Jedan od načina da se inicijaliziraju svi opisi alata na stranici bio bi da ih odaberete prema njihovom data-bs-toggleatributu, na primjer:

const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))

Zadržite pokazivač miša preko linkova ispod da vidite opise alata:

Tekst čuvara mjesta za demonstriranje nekih inline veza s opisima alata. Ovo je sada samo punilo, ne ubica. Sadržaj postavljen ovdje samo da oponaša prisustvo pravog teksta . I sve to samo da bismo vam dali ideju kako bi opisi izgledali kada se koriste u stvarnim situacijama. Dakle, nadamo se da ste sada vidjeli kako ovi savjeti o vezama mogu funkcionirati u praksi, nakon što ih koristite na vlastitom web mjestu ili projektu.

html
<p class="muted">Placeholder text to demonstrate some <a href="#" data-bs-toggle="tooltip" data-bs-title="Default tooltip">inline links</a> with tooltips. This is now just filler, no killer. Content placed here just to mimic the presence of <a href="#" data-bs-toggle="tooltip" data-bs-title="Another tooltip">real text</a>. 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 <a href="#" data-bs-toggle="tooltip" data-bs-title="Another one here too">these tooltips on links</a> can work in practice, once you use them on <a href="#" data-bs-toggle="tooltip" data-bs-title="The last tip!">your own</a> site or project.
</p>
Slobodno koristite bilo koji titleili data-bs-titleu svom HTML-u. Kada titlese koristi, Popper će ga automatski zamijeniti data-bs-titlekada se element renderira.

Prilagođeni alati

Dodato u v5.2.0

Možete prilagoditi izgled opisa alata koristeći CSS varijable . Postavljamo prilagođenu klasu sa data-bs-custom-class="custom-tooltip"za opseg našeg prilagođenog izgleda i koristimo je za nadjačavanje lokalne CSS varijable.

.custom-tooltip {
  --bs-tooltip-bg: var(--bs-primary);
}
html
<button type="button" class="btn btn-secondary"
        data-bs-toggle="tooltip" data-bs-placement="top"
        data-bs-custom-class="custom-tooltip"
        data-bs-title="This top tooltip is themed via CSS variables.">
  Custom tooltip
</button>

Upute

Zadržite pokazivač iznad dugmadi ispod da vidite četiri smjera opisa alata: gore, desno, dolje i lijevo. Uputstva se preslikavaju kada koristite Bootstrap u RTL-u.

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" data-bs-title="Tooltip on top">
  Tooltip on top
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" data-bs-title="Tooltip on right">
  Tooltip on right
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" data-bs-title="Tooltip on bottom">
  Tooltip on bottom
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" data-bs-title="Tooltip on left">
  Tooltip on left
</button>

I sa dodanim prilagođenim HTML-om:

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" data-bs-title="<em>Tooltip</em> <u>with</u> <b>HTML</b>">
  Tooltip with HTML
</button>

Sa SVG:

CSS

Varijable

Dodato u v5.2.0

Kao dio Bootstrap-ovog evoluirajućeg pristupa CSS varijabli, opisi alata sada koriste lokalne CSS varijable .tooltipza poboljšanu prilagodbu u realnom vremenu. Vrijednosti za CSS varijable se postavljaju putem Sass-a, tako da je i Sass prilagođavanje i dalje podržano.

  --#{$prefix}tooltip-zindex: #{$zindex-tooltip};
  --#{$prefix}tooltip-max-width: #{$tooltip-max-width};
  --#{$prefix}tooltip-padding-x: #{$tooltip-padding-x};
  --#{$prefix}tooltip-padding-y: #{$tooltip-padding-y};
  --#{$prefix}tooltip-margin: #{$tooltip-margin};
  @include rfs($tooltip-font-size, --#{$prefix}tooltip-font-size);
  --#{$prefix}tooltip-color: #{$tooltip-color};
  --#{$prefix}tooltip-bg: #{$tooltip-bg};
  --#{$prefix}tooltip-border-radius: #{$tooltip-border-radius};
  --#{$prefix}tooltip-opacity: #{$tooltip-opacity};
  --#{$prefix}tooltip-arrow-width: #{$tooltip-arrow-width};
  --#{$prefix}tooltip-arrow-height: #{$tooltip-arrow-height};
  

Sass varijable

$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:                    null; // TODO: remove this in v6

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
// fusv-disable
$tooltip-arrow-color:               null; // Deprecated in Bootstrap 5.2.0 for CSS variables
// fusv-enable

Upotreba

Dodatak za opis alata generira sadržaj i oznake na zahtjev, a prema zadanim postavkama postavlja opise alata nakon njihovog elementa okidača.

Aktivirajte opis alata putem JavaScripta:

const exampleEl = document.getElementById('example')
const tooltip = new bootstrap.Tooltip(exampleEl, options)
Overflow autoandscroll

Položaj opisa alata pokušava se automatski promijeniti kada roditeljski kontejner ima overflow: autoili overflow: scrollkao naš .table-responsive, ali i dalje zadržava pozicioniranje originalnog položaja. Da biste ovo riješili, postavite boundaryopciju (za modifikator okretanja koji koristi popperConfigopciju) na bilo koji HTMLElement da nadjača zadanu vrijednost, 'clippingParents'kao što je document.body:

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

Markup

Potrebna oznaka za opis alata je samo dataatribut i titlena HTML elementu želite da imate opis alata. Generirana oznaka opisa alata je prilično jednostavna, iako zahtijeva poziciju (podrazumevano, postavljena na topdodatak).

Omogućavanje rada savjeta za korisnike tipkovnice i pomoćne tehnologije

Trebali biste dodati samo opise alata HTML elementima koji su tradicionalno fokusirani na tipkovnicu i interaktivni (kao što su veze ili kontrole obrasca). Iako se proizvoljni HTML elementi (kao što je <span>s) mogu fokusirati dodavanjem tabindex="0"atributa, ovo će dodati potencijalno dosadne i zbunjujuće tab stope na neinteraktivnim elementima za korisnike tastature, a većina pomoćnih tehnologija trenutno ne najavljuje opis alata u ovoj situaciji. Osim toga, nemojte se oslanjati samo na hoverokidač za svoj opis alata, jer će to učiniti da vaše opise alata nije moguće pokrenuti korisnicima tipkovnice.

<!-- HTML to write -->
<a href="#" data-bs-toggle="tooltip" data-bs-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>

Onemogućeni elementi

Elementi sa disabledatributom nisu interaktivni, što znači da korisnici ne mogu da se fokusiraju, lebde ili kliknu na njih da bi pokrenuli opis alata (ili skočni prozor). Kao zaobilazno rešenje, poželećete da pokrenete tooltip iz omotača <div>ili <span>, idealno napravljenog za fokusiranje na tastaturi koristeći tabindex="0".

html
<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" data-bs-title="Disabled tooltip">
  <button class="btn btn-primary" type="button" disabled>Disabled button</button>
</span>

Opcije

Kako se opcije mogu proslijediti putem atributa podataka ili JavaScripta, možete dodati naziv opcije u data-bs-, kao u data-bs-animation="{value}". Obavezno promijenite tip slučaja naziva opcije iz “ camelCase ” u “ kebab-case ” prilikom prosljeđivanja opcija putem atributa podataka. Na primjer, koristite data-bs-custom-class="beautifier"umjesto data-bs-customClass="beautifier".

Od Bootstrapa 5.2.0, sve komponente podržavaju eksperimentalni atribut rezerviranih podataka data-bs-configkoji može smjestiti jednostavnu konfiguraciju komponente kao JSON string. Kada element ima atribute data-bs-config='{"delay":0, "title":123}'i data-bs-title="456", konačna titlevrijednost će biti 456, a zasebni atributi podataka će nadjačati vrijednosti date na data-bs-config. Osim toga, postojeći atributi podataka mogu sadržavati JSON vrijednosti poput data-bs-delay='{"show":0,"hide":150}'.

Imajte na umu da se iz sigurnosnih razloga opcije sanitize, sanitizeFni allowListne mogu dostaviti korištenjem atributa podataka.
Ime Tip Default Opis
allowList objekt Zadana vrijednost Objekt koji sadrži dozvoljene atribute i oznake.
animation boolean true Primijenite CSS fade prijelaz na opis alata.
boundary string, element 'clippingParents' Granica ograničenja prelivanja u opisu alata (odnosi se samo na Popperov modifikator preventOverflow). Podrazumevano, on je 'clippingParents'i može prihvatiti referencu HTMLElementa (samo putem JavaScripta). Za više informacija pogledajte Popper's detectOverflow dokumente .
container string, element, false false Dodaje opis alata određenom elementu. Primjer: container: 'body'. Ova opcija je posebno korisna jer vam omogućava da pozicionirate opis alata u toku dokumenta u blizini elementa za okidanje - što će spriječiti da opis alata odlebdi od elementa za okidanje tokom promjene veličine prozora.
customClass niz, funkcija '' Dodajte klase u opis alata kada se prikaže. Imajte na umu da će ove klase biti dodane kao dodatak svim klasama navedenim u predlošku. Da biste dodali više klasa, razdvojite ih razmacima: 'class-1 class-2'. Također možete proslijediti funkciju koja bi trebala vratiti jedan string koji sadrži dodatna imena klasa.
delay broj, objekat 0 Odgoda prikazivanja i skrivanja opisa alata (ms)—ne odnosi se na tip ručnog okidača. Ako je naveden broj, kašnjenje se primjenjuje i na sakrivanje/prikaži. Struktura objekta je: delay: { "show": 500, "hide": 100 }.
fallbackPlacements niz ['top', 'right', 'bottom', 'left'] Definirajte rezervne položaje pružanjem liste plasmana u nizu (po redoslijedu želje). Za više informacija pogledajte Popperove dokumente o ponašanju .
html boolean false Dozvolite HTML u opisu alata. Ako je tačno, HTML oznake u opisu alata titleće se prikazati u opisu alata. Ako je netačno, innerTextsvojstvo će se koristiti za umetanje sadržaja u DOM. Koristite tekst ako ste zabrinuti zbog XSS napada.
offset niz, niz, funkcija [0, 0] Pomak opisa alata u odnosu na cilj. Možete proslijediti niz u atributima podataka sa vrijednostima odvojenim zarezima kao što su: data-bs-offset="10,20". Kada se funkcija koristi za određivanje pomaka, ona se poziva s objektom koji sadrži popper položaj, referencu i popper rects kao prvi argument. Okidač elementa DOM čvor se prosljeđuje kao drugi argument. Funkcija mora vratiti niz sa dva broja: klizanje , udaljenost . Za više informacija pogledajte Popperove ofset dokumente .
placement niz, funkcija 'top' Kako pozicionirati tooltip: automatski, gore, dolje, lijevo, desno. Kada autoje navedeno, dinamički će preusmjeriti opis alata. Kada se funkcija koristi za određivanje položaja, ona se poziva sa DOM čvorom sa opisom alata kao prvim argumentom i pokretačkim elementom DOM čvorom kao drugim. Kontekst thisje postavljen na instancu opisa alata.
popperConfig null, objekt, funkcija null Da biste promijenili Bootstrap-ovu zadanu Popper konfiguraciju, pogledajte Popperovu konfiguraciju . Kada se funkcija koristi za kreiranje Popper konfiguracije, ona se poziva sa objektom koji sadrži Bootstrap-ovu zadanu Popper konfiguraciju. Pomaže vam da koristite i spojite zadanu s vlastitom konfiguracijom. Funkcija mora vratiti konfiguracijski objekt za Popper.
sanitize boolean true Omogućite ili onemogućite dezinfekciju. Ako je aktivirano 'template', 'content'i 'title'opcije će biti sanirane.
sanitizeFn null, funkcija null Ovdje možete ponuditi vlastitu funkciju dezinfekcije. Ovo može biti korisno ako više volite koristiti namjensku biblioteku za dezinfekciju.
selector string, false false Ako je osiguran selektor, objekti opisa alata će biti delegirani navedenim ciljevima. U praksi, ovo se koristi i za primenu opisa alata na dinamički dodane DOM elemente ( jQuery.onpodrška). Pogledajte ovo izdanje i informativni primjer .
template string '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' Osnovni HTML za korištenje prilikom kreiranja opisa alata. Opis alata titleće biti ubrizgan u .tooltip-inner. .tooltip-arrowće postati strelica u opisu alata. Najudaljeniji element omotača trebao bi imati .tooltipklasu i role="tooltip".
title string, element, funkcija '' Zadana vrijednost naslova ako titleatribut nije prisutan. Ako je data funkcija, ona će biti pozvana sa svojom thisreferencom postavljenom na element za koji je skočni prozor povezan.
trigger string 'hover focus' Kako se pokreće opis alata: kliknite, lebdite, fokus, ručno. Možete proslijediti više okidača; odvojite ih razmakom. 'manual'označava da će se opis alata pokrenuti programski putem metoda .tooltip('show'), .tooltip('hide')and ; .tooltip('toggle')ova vrijednost se ne može kombinirati ni sa jednim drugim okidačem. 'hover'samo po sebi će rezultirati opisima alata koji se ne mogu pokrenuti putem tastature, i treba ih koristiti samo ako postoje alternativni načini za prenošenje istih informacija za korisnike tastature.

Atributi podataka za pojedinačne opise alata

Opcije za pojedinačne opise alata mogu se alternativno specificirati korištenjem atributa podataka, kao što je gore objašnjeno.

Korištenje funkcije sapopperConfig

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

Metode

Asinhrone metode i prijelazi

Sve API metode su asinhrone i pokreću tranziciju . Oni se vraćaju pozivaocu čim prijelaz započne, ali prije nego što se završi . Osim toga, poziv metode na prelaznu komponentu će biti zanemaren .

Pogledajte našu JavaScript dokumentaciju za više informacija .

Metoda Opis
disable Uklanja mogućnost prikaza opisa elementa. Alat će se moći prikazati samo ako je ponovo omogućen.
dispose Sakriva i uništava opis elementa (uklanja pohranjene podatke na DOM elementu). Oznake alata koje koriste delegiranje (koje su kreirane pomoću opcije selector) ne mogu se pojedinačno uništiti na elementima okidača potomaka.
enable Daje mogućnost prikaza alata elementa. Objašnjenja su podrazumevano omogućena.
getInstance Statička metoda koja vam omogućava da dobijete instancu opisa alata pridruženu DOM elementu ili kreirate novu u slučaju da nije inicijalizirana.
getOrCreateInstance Statička metoda koja vam omogućava da dobijete instancu opisa alata pridruženu DOM elementu ili kreirate novu u slučaju da nije inicijalizirana.
hide Sakriva opis elementa. Vraća se pozivaocu prije nego što je opis alata zapravo skriven (tj. prije nego što se hidden.bs.tooltipdogađaj dogodi). Ovo se smatra "ručnim" pokretanjem opisa alata.
setContent Daje način za promjenu sadržaja opisa alata nakon njegove inicijalizacije.
show Otkriva opis elementa. Vraća se pozivaocu prije nego što je opis alata zapravo prikazan (tj. prije nego što se shown.bs.tooltipdogađaj dogodi). Ovo se smatra "ručnim" pokretanjem opisa alata. Alati sa naslovima nulte dužine se nikada ne prikazuju.
toggle Prebacuje opis elementa. Vraća se pozivaocu prije nego što je opis alata zapravo prikazan ili skriven (tj. prije nego se dogodi događaj shown.bs.tooltipili ). hidden.bs.tooltipOvo se smatra "ručnim" pokretanjem opisa alata.
toggleEnabled Uključuje mogućnost prikaza ili sakrivanja opisa elementa.
update Ažurira poziciju opisa elementa.
const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })
Metoda setContentprihvaća objectargument, gdje je svaki ključ svojstva valjani stringselektor unutar predloška iskačućeg prikaza, a svaka srodna vrijednost svojstva može biti string| element| function| null

Događaji

Događaj Opis
hide.bs.tooltip Ovaj događaj se pokreće odmah kada se hidepozove metoda instance.
hidden.bs.tooltip Ovaj događaj se pokreće kada skočni prozor završi sa sakrivanjem od korisnika (će sačekati da se CSS tranzicije dovrše).
inserted.bs.tooltip Ovaj događaj se pokreće nakon show.bs.tooltipdogađaja kada je predložak opisa alata dodan u DOM.
show.bs.tooltip Ovaj događaj se aktivira odmah kada showse pozove metoda instance.
shown.bs.tooltip Ovaj događaj se pokreće kada skočni prozor postane vidljiv korisniku (će čekati da se CSS tranzicije dovrše).
const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

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

tooltip.hide()