in English

Sfaturi instrumente

Documentație și exemple pentru adăugarea de sfaturi personalizate Bootstrap cu CSS și JavaScript folosind CSS3 pentru animații și atribute de date pentru stocarea locală a titlurilor.

Prezentare generală

Lucruri de știut atunci când utilizați pluginul tooltip:

  • Sfaturile cu instrumente se bazează pe biblioteca terță parte Popper pentru poziționare. Trebuie să includeți popper.min.js înainte de bootstrap.js sau să utilizați bootstrap.bundle.min.js/ bootstrap.bundle.jscare conține Popper pentru ca sfaturile instrumente să funcționeze!
  • Dacă construiți JavaScript din sursă, este nevoieutil.js de .
  • Sfaturile instrumente sunt înscrise din motive de performanță, așa că trebuie să le inițializați singur .
  • Sfaturile instrumente cu titluri de lungime zero nu sunt niciodată afișate.
  • Specificați container: 'body'pentru a evita problemele de randare în componente mai complexe (cum ar fi grupurile noastre de intrare, grupurile de butoane etc.).
  • Declanșarea indicațiilor de instrucțiuni pentru elementele ascunse nu va funcționa.
  • Sfaturile instrumente pentru .disabledsau disabledelemente trebuie să fie declanșate pe un element de înveliș.
  • Când sunt declanșate de la hyperlinkuri care se întind pe mai multe linii, sfaturile instrumente vor fi centrate. Folosește -l white-space: nowrap;pe tine <a>pentru a evita acest comportament.
  • Sfaturile cu instrumente trebuie ascunse înainte ca elementele lor corespunzătoare să fie eliminate din DOM.
  • Sfaturile cu instrumente pot fi declanșate datorită unui element din interiorul unui DOM umbră.
În mod implicit, această componentă folosește dezinfectantul de conținut încorporat, care exclude orice elemente HTML care nu sunt permise în mod explicit. Consultați secțiunea dezinfectant din documentația noastră JavaScript pentru mai multe detalii.
Efectul de animație al acestei componente depinde de prefers-reduced-motioninterogarea media. Consultați secțiunea cu mișcare redusă a documentației noastre de accesibilitate .

Ai toate astea? Grozav, să vedem cum funcționează cu câteva exemple.

Exemplu: activați sfaturi cu instrumente peste tot

O modalitate de a inițializa toate sfaturile instrumente dintr-o pagină ar fi să le selectați după data-toggleatributul lor:

$(function () {
  $('[data-toggle="tooltip"]').tooltip()
})

Exemple

Treceți cu mouse-ul peste linkurile de mai jos pentru a vedea sfaturi despre instrumente:

Text substituent pentru a demonstra câteva legături inline cu sfaturi pentru instrumente. Acesta este acum doar umplutură, nu ucigaș. Conținut plasat aici doar pentru a imita prezența textului real . Și toate acestea doar pentru a vă oferi o idee despre cum ar arăta sfaturile instrumente atunci când sunt utilizate în situații reale. Așa că sperăm că acum ați văzut cum aceste sfaturi despre linkuri pot funcționa în practică, odată ce le utilizați pe propriul site sau proiect.

Treceți cu mouse-ul peste butoanele de mai jos pentru a vedea cele patru indicații de indicații: sus, dreapta, jos și stânga.

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

Și cu HTML personalizat adăugat:

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

Utilizare

Pluginul de indicații cu instrumente generează conținut și markup la cerere și, în mod implicit, plasează indicatorii de informații după elementul de declanșare.

Declanșați balonul cu ajutorul JavaScript:

$('#example').tooltip(options)
Debordare autoșiscroll

Poziția balonului explicativ încearcă să se schimbe automat atunci când un container părinte are overflow: autosau îi overflow: scrollplace .table-responsive, dar păstrează totuși poziționarea destinației inițiale. Pentru a rezolva, setați boundaryopțiunea la orice altceva decât valoarea implicită 'scrollParent', cum ar fi 'window':

$('#example').tooltip({ boundary: 'window' })

Markup

Markupul necesar pentru un balon explicativ este doar un dataatribut și titlepe elementul HTML doriți să aveți un balon explicativ. Markupul generat al unui tooltip este destul de simplu, deși necesită o poziție (în mod implicit, setată topde plugin).

Faceți ca sfaturile instrumente să funcționeze pentru utilizatorii de tastatură și de tehnologie de asistență

Ar trebui să adăugați doar sfaturi pentru elementele HTML care sunt în mod tradițional focalizate pe tastatură și interactive (cum ar fi link-uri sau comenzi de formular). Deși elementele HTML arbitrare (cum ar fi <span>s) pot fi făcute focalizabile prin adăugarea tabindex="0"atributului, acest lucru va adăuga tabulaturi potențial enervante și confuze pe elementele neinteractive pentru utilizatorii de tastatură, iar majoritatea tehnologiilor de asistență nu anunță în prezent indicația în această situație. În plus, nu vă bazați exclusiv hoverca declanșator pentru indicația dvs. cu instrumente, deoarece acest lucru va face ca acestea să fie imposibil de declanșat pentru utilizatorii de tastatură.

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

Elemente dezactivate

Elementele cu disabledatributul nu sunt interactive, ceea ce înseamnă că utilizatorii nu pot să se concentreze, să plaseze cursorul sau să facă clic pe ele pentru a declanșa un balon explicativ (sau popover). Ca o soluție, veți dori să declanșați sfatul cu instrumente dintr-un înveliș <div>sau <span>, în mod ideal, care poate fi focalizat pe tastatură folosind tabindex="0", și să înlocuiți pointer-eventselementul dezactivat.

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

Opțiuni

Opțiunile pot fi transmise prin atribute de date sau JavaScript. Pentru atributele datelor, adăugați numele opțiunii la data-, ca în data-animation="".

Rețineți că, din motive de securitate sanitize, opțiunile sanitizeFnși whiteListnu pot fi furnizate utilizând atribute de date.
Nume Tip Mod implicit Descriere
animaţie boolean Adevărat Aplicați o tranziție de estompare CSS la balonul explicativ
recipient șir | element | fals fals

Adaugă indicația la un anumit element. Exemplu: container: 'body'. Această opțiune este deosebit de utilă prin faptul că vă permite să poziționați balonul în fluxul documentului în apropierea elementului de declanșare - ceea ce va împiedica balonul să plutească departe de elementul de declanșare în timpul unei redimensionări a ferestrei.
întârziere număr | obiect 0

Întârziere afișarea și ascunderea balonului explicativ (ms) - nu se aplică tipului de declanșare manuală

Dacă este furnizat un număr, se aplică întârziere atât pentru ascunde/afișare

Structura obiectului este:delay: { "show": 500, "hide": 100 }
html boolean fals

Permiteți HTML în sfatul instrumentului.

Dacă este adevărat, etichetele HTML din balonul explicativ titlevor fi redate în balonul explicativ. Dacă este fals, textmetoda jQuery va fi folosită pentru a insera conținut în DOM.

Folosiți text dacă vă îngrijorează atacurile XSS.
plasare șir | funcţie 'top'

Cum se poziționează indicatorul - auto | sus | jos | stânga | dreapta.
Când autoeste specificat, acesta va reorienta în mod dinamic indicația.

Când o funcție este utilizată pentru a determina plasarea, aceasta este apelată cu nodul DOM ca prim argument și elementul de declanșare nodul DOM ca al doilea. Contextul thiseste setat la instanța descrierii.
selector șir | fals fals Dacă este furnizat un selector, obiectele de tip tooltip vor fi delegate țintelor specificate. În practică, aceasta este folosită și pentru a aplica sfaturi pentru elementele DOM adăugate dinamic ( jQuery.onsuport). Vedeți acesta și un exemplu informativ .
șablon şir '<div class="tooltip" role="tooltip"><div class="arrow"></div><div class="tooltip-inner"></div></div>'

HTML de bază de utilizat la crearea descrierii explicative.

Indicațiile titleinstrumente vor fi injectate în .tooltip-inner.

.arrowva deveni săgeata descrierii.

Elementul de înveliș exterior ar trebui să aibă .tooltipclasa și role="tooltip".
titlu șir | element | funcţie ''

Valoarea implicită a titlului dacă titleatributul nu este prezent.

Dacă este dată o funcție, aceasta va fi apelată cu thisreferința ei setată la elementul la care este atașat tooltip.
declanșatorul şir „focalizare”

Cum se declanșează balonul - faceți clic pe | hover | focus | manual. Puteți trece mai multe declanșatoare; separați-le cu un spațiu.

'manual'indică faptul că indicația va fi declanșată programatic prin metodele și .tooltip('show'); această valoare nu poate fi combinată cu niciun alt declanșator..tooltip('hide').tooltip('toggle')

'hover'pe cont propriu va avea ca rezultat sfaturi de instrumente care nu pot fi declanșate prin intermediul tastaturii și ar trebui utilizate numai dacă sunt prezente metode alternative de transmitere a aceleiași informații pentru utilizatorii de tastatură.
decalaj număr | șir | funcţie 0

Decalaj al indicației explicative în raport cu ținta acestuia.

Când o funcție este folosită pentru a determina offset-ul, este apelată cu un obiect care conține datele offset ca prim argument. Funcția trebuie să returneze un obiect cu aceeași structură. Elementul de declanșare nodul DOM este transmis ca al doilea argument.

Pentru mai multe informații, consultați documentele despre offset ale lui Popper .
plasare de rezervă șir | matrice „întoarce” Permiteți să specificați ce poziție va folosi Popper în cazul de rezervă. Pentru mai multe informații, consultați documentele de comportament ale lui Popper
customClass șir | funcţie ''

Adăugați clase la sfatul instrument atunci când este afișat. Rețineți că aceste clase vor fi adăugate în plus față de orice clase specificate în șablon. Pentru a adăuga mai multe clase, separați-le cu spații: 'a b'.

De asemenea, puteți transmite o funcție care ar trebui să returneze un singur șir care conține nume de clasă suplimentare.
limite șir | element 'scrollParent' Limita constrângerii de depășire a balonului explicativ. Acceptă valorile 'viewport', 'window', 'scrollParent', sau o referință HTMLElement (numai JavaScript). Pentru mai multe informații, consultați documentele Popper preventOverflow .
dezinfecta boolean Adevărat Activați sau dezactivați igienizarea. Dacă sunt activate 'template'și 'title'opțiunile vor fi dezinfectate. Consultați secțiunea dezinfectant din documentația noastră JavaScript .
Lista albă obiect Valoare implicită Obiect care conține atribute și etichete permise
igienizaFn nul | funcţie nul Aici vă puteți furniza propria funcție de dezinfectare. Acest lucru poate fi util dacă preferați să utilizați o bibliotecă dedicată pentru a efectua igienizarea.
popperConfig nul | obiect nul Pentru a schimba configurația implicită Popper a Bootstrap, consultați configurația lui Popper

Atribute de date pentru sfaturi instrumentale individuale

Opțiunile pentru sfaturi instrumente individuale pot fi specificate alternativ prin utilizarea atributelor de date, așa cum s-a explicat mai sus.

Metode

Metode și tranziții asincrone

Toate metodele API sunt asincrone și încep o tranziție . Ei revin la apelant imediat ce tranziția este începută, dar înainte ca aceasta să se încheie . În plus, un apel de metodă pentru o componentă de tranziție va fi ignorat .

Consultați documentația noastră JavaScript pentru mai multe informații .

$().tooltip(options)

Atașează un handler tooltip la o colecție de elemente.

.tooltip('show')

Dezvăluie explicația unui element. Se întoarce la apelant înainte ca indicația să fie afișată efectiv (adică înainte de apariția shown.bs.tooltipevenimentului). Aceasta este considerată o declanșare „manuală” a descrierii explicative. Sfaturile instrumente cu titluri de lungime zero nu sunt niciodată afișate.

$('#element').tooltip('show')

.tooltip('hide')

Ascunde explicația unui element. Se întoarce la apelant înainte ca indicația să fie ascunsă (adică înainte de apariția hidden.bs.tooltipevenimentului). Aceasta este considerată o declanșare „manuală” a descrierii explicative.

$('#element').tooltip('hide')

.tooltip('toggle')

Comută în lista de informații despre un element. Revine la apelant înainte ca balonul să fie afișat sau ascuns (adică înainte ca evenimentul shown.bs.tooltipsau să hidden.bs.tooltipapară). Aceasta este considerată o declanșare „manuală” a descrierii explicative.

$('#element').tooltip('toggle')

.tooltip('dispose')

Ascunde și distruge sfatul instrument al unui element. Sfaturile instrumente care utilizează delegarea (care sunt create folosind opțiunea selector) nu pot fi distruse individual pe elementele de declanșare descendente.

$('#element').tooltip('dispose')

.tooltip('enable')

Oferă un sfat instrument al unui element posibilitatea de a fi afișat. Sfaturile instrumente sunt activate în mod implicit.

$('#element').tooltip('enable')

.tooltip('disable')

Elimină capacitatea de afișare a indicației unui element. Indicatorul va putea fi afișat numai dacă este reactivat.

$('#element').tooltip('disable')

.tooltip('toggleEnabled')

Comută posibilitatea ca indicația unui element să fie afișată sau ascunsă.

$('#element').tooltip('toggleEnabled')

.tooltip('update')

Actualizează poziția descrierii unui element.

$('#element').tooltip('update')

Evenimente

Tip de eveniment Descriere
arată.bs.tooltip Acest eveniment se declanșează imediat când showeste apelată metoda instanței.
afișat.bs.tooltip Acest eveniment este declanșat când balonul explicativ a fost făcut vizibil pentru utilizator (va aștepta finalizarea tranzițiilor CSS).
ascunde.bs.tooltip Acest eveniment este declanșat imediat când hidemetoda instanței a fost apelată.
hidden.bs.tooltip Acest eveniment este declanșat când sfarsitul explicativ a terminat de ascuns utilizatorului (va aștepta finalizarea tranzițiilor CSS).
introdus.bs.tooltip Acest eveniment este declanșat după show.bs.tooltipeveniment, când șablonul de indicații explicative a fost adăugat la DOM. 
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})