Fara í aðalefni Farðu í skjalaleiðsögn
Check
in English

Verkfæraráð

Skjöl og dæmi til að bæta við sérsniðnum Bootstrap verkfæraleiðbeiningum með CSS og JavaScript með því að nota CSS3 fyrir hreyfimyndir og data-bs-eiginleika fyrir staðbundna titilgeymslu.

Á þessari síðu

Yfirlit

Hlutir sem þarf að vita þegar þú notar tooltip viðbótina:

  • Verkfæraráð treysta á þriðja aðila bókasafnið Popper fyrir staðsetningu. Þú verður að hafa popper.min.js á undan bootstrap.js, eða nota einn bootstrap.bundle.min.jssem inniheldur Popper.
  • Verkfæraráð eru valin af frammistöðuástæðum, svo þú verður að frumstilla þær sjálfur .
  • Verkfæraleiðbeiningar með núlllengdar titlum birtast aldrei.
  • Tilgreindu container: 'body'til að forðast að skila vandamálum í flóknari íhlutum (eins og inntakshópum okkar, hnappahópum osfrv.).
  • Það virkar ekki að kveikja á ábendingum um falda þætti.
  • Verkfæraleiðbeiningar fyrir .disabledeða disabledþætti verða að vera virkjaðar á umbúðaeiningu.
  • Þegar kveikt er á tenglum sem spanna margar línur verða verkfæraábendingar miðaðar. Notaðu white-space: nowrap;á þinn <a>s til að forðast þessa hegðun.
  • Ábendingar verða að vera falin áður en samsvarandi þættir þeirra hafa verið fjarlægðir úr DOM.
  • Hægt er að kveikja á verkfærum þökk sé frumefni inni í skugga DOM.

Áttu allt það? Frábært, við skulum sjá hvernig þeir virka með nokkrum dæmum.

Sjálfgefið er að þessi hluti notar innbyggt efnishreinsiefni, sem fjarlægir alla HTML þætti sem eru ekki beinlínis leyfðir. Sjáðu hreinsiefnishlutann í JavaScript skjölunum okkar fyrir frekari upplýsingar.
Hreyfiáhrif þessa íhluts eru háð prefers-reduced-motionmiðlunarfyrirspurninni. Sjá kaflann um minni hreyfingu í aðgengisskjölunum okkar .

Dæmi

Virkjaðu verkfæraábendingar

Eins og getið er hér að ofan verður þú að frumstilla verkfæraábendingar áður en hægt er að nota þær. Ein leið til að frumstilla allar verkfæraábendingar á síðu væri að velja þær eftir data-bs-toggleeiginleikum þeirra, eins og svo:

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

Farðu yfir tenglana hér að neðan til að sjá verkfæraleiðbeiningar:

Staðsetningartexti til að sýna nokkra innbyggða tengla með verkfæraleiðbeiningum. Þetta er nú bara filler, enginn killer. Efni sett hér bara til að líkja eftir tilvist raunverulegs texta . Og allt það bara til að gefa þér hugmynd um hvernig verkfæraábendingar myndu líta út þegar þær eru notaðar í raunverulegum aðstæðum. Svo vonandi hefurðu nú séð hvernig þessar verkfæraábendingar um tengla geta virkað í reynd, þegar þú hefur notað þær á eigin síðu eða verkefni.

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>
Ekki hika við að nota annað hvort titleeða data-bs-titleí HTML. Þegar titleþað er notað mun Popper skipta því sjálfkrafa út fyrir data-bs-titleþegar þátturinn er sýndur.

Sérsniðin verkfæraráð

Bætt við í v5.2.0

Þú getur sérsniðið útlit ábendinga með því að nota CSS breytur . Við stillum sérsniðinn flokk með data-bs-custom-class="custom-tooltip"til að stækka sérsniðið útlit okkar og notum það til að hnekkja staðbundinni CSS breytu.

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

Leiðbeiningar

Færðu bendilinn yfir hnappana hér að neðan til að sjá fjórar leiðbeiningar á tólum: efst, hægri, neðst og til vinstri. Leiðbeiningar eru speglaðar þegar Bootstrap er notað í RTL.

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

Og með sérsniðnu HTML bætt við:

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

Með SVG:

CSS

Breytur

Bætt við í v5.2.0

Sem hluti af CSS breytum í þróun Bootstrap, nota verkfæraábendingar nú staðbundnar CSS breytur á .tooltiptil að auka rauntíma aðlögun. Gildi fyrir CSS breyturnar eru stillt í gegnum Sass, þannig að Sass aðlögun er enn studd líka.

  --#{$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 breytur

$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

Notkun

The tooltip tappi býr til efni og álagningu á eftirspurn og setur sjálfgefið verkfæraábendingar á eftir kveikjuhlutanum.

Kveiktu á tóli í gegnum JavaScript:

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

Staðsetning ábendinga reynir að breytast sjálfkrafa þegar foreldri ílát hefur overflow: autoeða overflow: scrolllíkar við .table-responsive, en heldur samt staðsetningu upprunalegu staðsetningunnar. Til að leysa þetta skaltu stilla boundaryvalmöguleikann (fyrir snúningsbreytinguna sem notar popperConfigvalkostinn) á hvaða HTMLElement sem er til að hnekkja sjálfgefnu gildinu, 'clippingParents', eins og document.body:

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

Markup

Nauðsynleg merking fyrir verkfæraleiðbeiningar er aðeins dataeiginleiki og titleá HTML-einingunni viltu hafa verkfæraleiðbeiningar. Mynduð merking tækjaráðs er frekar einföld, þó hún krefjist stöðu (sjálfgefið, stillt á topaf viðbótinni).

Gerir verkfæraábendingar virka fyrir notendur lyklaborðs og hjálpartækja

Þú ættir aðeins að bæta tólaábendingum við HTML þætti sem venjulega eru með lyklaborðsfókus og gagnvirkir (eins og tenglar eða formstýringar). Þrátt fyrir að hægt sé að gera handahófskennda HTML þætti (eins og <span>s) fókusanlega með því að bæta tabindex="0"eigindinni við, mun þetta bæta við hugsanlega pirrandi og ruglingslegum flipastoppum á ógagnvirka þætti fyrir lyklaborðsnotendur og flestar hjálpartækni tilkynnir ekki um verkfæraábendingu í þessum aðstæðum. Að auki skaltu ekki treysta eingöngu á hoverkveikjuna fyrir tólaábendingar þínar, þar sem þetta mun gera tólaábendingar þínar ómögulegar fyrir lyklaborðsnotendur.

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

Óvirkir þættir

Þættir með disabledeigindinni eru ekki gagnvirkir, sem þýðir að notendur geta ekki einbeitt sér, sveiflað eða smellt á þá til að kalla fram verkfæraábendingu (eða sprettiglugga). Sem lausn, þú vilt kveikja á tóli frá umbúðum <div>eða <span>, helst gert lyklaborðsfókus með því að nota 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>

Valmöguleikar

Þar sem hægt er að senda valkosti í gegnum gagnaeiginleika eða JavaScript geturðu bætt valkostsheiti við data-bs-, eins og í data-bs-animation="{value}". Gakktu úr skugga um að breyta tilfelli tegundar valmöguleikans úr " camelCase " í " kebab-case " þegar þú sendir valkostina í gegnum gagnaeiginleika. Notaðu til dæmis data-bs-custom-class="beautifier"í staðinn fyrir data-bs-customClass="beautifier".

Frá og með Bootstrap 5.2.0 styðja allir íhlutir tilrauna frátekinn gagnaeiginleika data-bs-configsem getur hýst einfalda íhlutastillingu sem JSON streng. Þegar eining hefur data-bs-config='{"delay":0, "title":123}'og eiginleika verður data-bs-title="456"lokagildið og aðskildu gagnaeiginirnar munu hnekkja gildum sem gefin eru á . Að auki geta núverandi gagnaeiginleikar hýst JSON gildi eins og .title456data-bs-configdata-bs-delay='{"show":0,"hide":150}'

Athugaðu að af öryggisástæðum er ekki hægt að útvega valkostina sanitize, sanitizeFn, og allowListmeð því að nota gagnaeiginleika.
Nafn Tegund Sjálfgefið Lýsing
allowList mótmæla Sjálfgefið gildi Hlutur sem inniheldur leyfilega eiginleika og merki.
animation Boolean true Notaðu CSS fade umskipti á tólabendinguna.
boundary strengur, þáttur 'clippingParents' Yfirflæðisþvingunarmörk tólabendingarinnar (á aðeins við um breytibúnað Poppers preventOverflow). Sjálfgefið er 'clippingParents'og getur samþykkt HTMLElement tilvísun (aðeins með JavaScript). Nánari upplýsingar er að finna í detectOverflow skjölum Popper .
container strengur, þáttur, rangur false Bætir ábendingunni við ákveðinn þátt. Dæmi: container: 'body'. Þessi valkostur er sérstaklega gagnlegur þar sem hann gerir þér kleift að staðsetja tólaskýringuna í flæði skjalsins nálægt kveikjueiningunni - sem kemur í veg fyrir að tólábendingin svífi í burtu frá kveikjueiningunni meðan á stærð gluggans stendur.
customClass strengur, virka '' Bættu flokkum við verkfæraleiðbeiningarnar þegar þær eru sýndar. Athugaðu að þessum flokkum verður bætt við til viðbótar öllum flokkum sem tilgreindir eru í sniðmátinu. Til að bæta við mörgum flokkum skaltu aðskilja þá með bilum: 'class-1 class-2'. Þú getur líka sent aðgerð sem ætti að skila einum streng sem inniheldur fleiri flokksnöfn.
delay tala, hlutur 0 Seinkað að sýna og fela tólabendinguna (ms) – á ekki við um handvirka kveikjugerð. Ef númer er gefið upp er seinkun beitt á bæði fela/sýna. Uppbygging hlutar er: delay: { "show": 500, "hide": 100 }.
fallbackPlacements fylki ['top', 'right', 'bottom', 'left'] Skilgreindu varastaðsetningar með því að gefa upp lista yfir staðsetningar í fylki (í forgangsröð). Nánari upplýsingar er að finna í hegðunarskjölum Poppers .
html Boolean false Leyfa HTML í tóli. Ef satt er, verða HTML merki í tólabendingunni titlebirt í tólabendingunni. Ef það er rangt verður innerTexteignin notuð til að setja efni inn í DOM. Notaðu texta ef þú hefur áhyggjur af XSS árásum.
offset fylki, strengur, fall [0, 0] Offseting á tóli miðað við markmið hans. Þú getur sent streng í gagnaeiginleikum með kommum aðskilin gildi eins og: data-bs-offset="10,20". Þegar fall er notað til að ákvarða offsetið er það kallað með hlut sem inniheldur popper staðsetningu, tilvísun og popper rects sem fyrstu rök. Kveikjuþátturinn DOM hnútur er samþykktur sem önnur rök. Fallið verður að skila fylki með tveimur tölum: sleppa , fjarlægð . Nánari upplýsingar er að finna í Offset-skjölum Poppers .
placement strengur, virka 'top' Hvernig á að staðsetja tólið: sjálfvirkt, efst, neðst, til vinstri, hægri. Þegar autoþað er tilgreint mun það breyta tólabendingunni á virkan hátt. Þegar fall er notað til að ákvarða staðsetninguna er það kallað með tooltip DOM hnútnum sem fyrstu röksemd og kveikjuþáttinn DOM hnút sem seinni. Samhengið thiser stillt á tooltip tilvikið.
popperConfig núll, hlutur, fall null Til að breyta sjálfgefna Popper stillingu Bootstrap, sjáðu stillingar Popper . Þegar aðgerð er notuð til að búa til Popper stillinguna er hún kölluð með hlut sem inniheldur sjálfgefna Popper stillingu Bootstrap. Það hjálpar þér að nota og sameina sjálfgefið við þína eigin stillingu. Aðgerðin verður að skila stillingarhlut fyrir Popper.
sanitize Boolean true Virkja eða slökkva á sótthreinsun. Ef virkjað 'template', 'content'og 'title'valkostir verða sótthreinsaðir.
sanitizeFn núll, virka null Hér getur þú útvegað þína eigin sótthreinsunaraðgerð. Þetta getur verið gagnlegt ef þú vilt frekar nota sérstakt bókasafn til að framkvæma hreinsun.
selector strengur, falskur false Ef valkostur er til staðar verður verkfæravísahlutum úthlutað til tilgreindra skotmarka. Í reynd er þetta notað til að nota tólaábendingar til að bæta við DOM þætti ( jQuery.onstuðningur). Sjá þetta tölublað og fróðlegt dæmi .
template strengur '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' Grunn HTML til að nota þegar þú býrð til verkfæraábendingu. Verkfæraráðinu titleverður sprautað inn í .tooltip-inner. .tooltip-arrowverður ör á tóli. Ysta umbúðaþátturinn ætti að hafa .tooltipflokkinn og role="tooltip".
title strengur, þáttur, fall '' Sjálfgefið titilgildi ef titleeigind er ekki til staðar. Ef fall er gefið upp verður það kallað með thistilvísuninni stillt á þáttinn sem popover er tengdur við.
trigger strengur 'hover focus' Hvernig ábending er sett af stað: smella, sveima, fókus, handvirkt. Þú gætir farið framhjá mörgum kveikjum; aðskilja þá með bili. 'manual'gefur til kynna að ábendingin verði sett af stað forritunarlega með .tooltip('show'), .tooltip('hide')og .tooltip('toggle')aðferðunum; ekki er hægt að sameina þetta gildi við neina aðra kveikju. 'hover'ein og sér mun leiða til verkfæraábendinga sem ekki er hægt að kveikja á með lyklaborðinu og ætti aðeins að nota ef aðrar aðferðir eru til staðar til að miðla sömu upplýsingum fyrir lyklaborðsnotendur.

Gagnaeiginleikar fyrir einstakar verkfæraábendingar

Að öðrum kosti er hægt að tilgreina valkosti fyrir einstakar verkfæraábendingar með því að nota gagnaeiginleika, eins og útskýrt er hér að ofan.

Að nota aðgerð meðpopperConfig 

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

Aðferðir

Ósamstilltar aðferðir og umskipti

Allar API aðferðir eru ósamstilltar og hefja umskipti . Þeir snúa aftur til þess sem hringir um leið og umskiptin eru hafin en áður en þeim lýkur . Að auki verður aðferðakall á umbreytingarhluta hunsað .

Sjá JavaScript skjölin okkar fyrir frekari upplýsingar .

Aðferð Lýsing
disable Fjarlægir möguleikann á að sýna ábendingu frumefnis. Aðeins er hægt að sýna verkfæraráðið ef það er virkjað aftur.
dispose Felur og eyðileggur verkfæraábendingu frumefnis (Fjarlægir vistuð gögn á DOM-einingunni). Verkfæraábendingar sem nota úthlutun (sem eru búnar til með valmöguleikanum selector) er ekki hægt að eyða fyrir sig á afkvæma kveikjuþáttum.
enable Gefur verkfæri frumefnis möguleika á að vera sýndur. Verkfæraleiðbeiningar eru sjálfgefnar virkar.
getInstance Statísk aðferð sem gerir þér kleift að fá tólatilvikið tengt DOM-einingu, eða búa til nýjan ef það var ekki frumstillt.
getOrCreateInstance Statísk aðferð sem gerir þér kleift að fá tólatilvikið tengt DOM-einingu, eða búa til nýjan ef það var ekki frumstillt.
hide Felur ábendingu frumefnis. Snýr aftur til þess sem hringir áður en verkfæraráðið hefur verið falið (þ.e. áður en hidden.bs.tooltipatburðurinn á sér stað). Þetta er talið „handvirk“ kveikja á tólabendingunni.
setContent Gefur leið til að breyta innihaldi tólabendingarinnar eftir frumstillingu hans.
show Sýnir verkfæraábendingu frumefnis. Snýr aftur til þess sem hringir áður en verkfæraráðið hefur verið sýnt (þ.e. áður en shown.bs.tooltipatburðurinn á sér stað). Þetta er talið „handvirk“ kveikja á tólabendingunni. Verkfæraleiðbeiningar með núlllengdar titlum birtast aldrei.
toggle Breytir ábendingum frumefnis. Snýr aftur til þess sem hringir áður en verkfæraábendingin hefur verið sýnd eða falin (þ.e. áður en atburðurinn shown.bs.tooltipeða hidden.bs.tooltipá sér stað). Þetta er talið „handvirk“ kveikja á tólabendingunni.
toggleEnabled Skiptir um möguleikann á því að sýna eða fela verkfæraleiðbeiningar þáttar.
update Uppfærir staðsetningu ábendinga frumefnis. 
const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })
Aðferðin setContenttekur við objectrökum, þar sem hver eignarlykill er gildur stringvalmynd innan popover sniðmátsins, og hvert tengt eignargildi getur verið string| element| function| null

Viðburðir

Viðburður Lýsing
hide.bs.tooltip Þessi atburður er ræstur strax þegar hidetilviksaðferðin hefur verið kölluð.
hidden.bs.tooltip Þessi atburður er ræstur þegar búið er að fela sprettigluggann fyrir notandanum (bíður eftir að CSS umbreytingum ljúki).
inserted.bs.tooltip Þessi atburður er ræstur eftir show.bs.tooltipatburðinn þegar sniðmát fyrir verkfæraleiðbeiningar hefur verið bætt við DOM.
show.bs.tooltip Þessi atburður ræsir strax þegar showtilviksaðferðin er kölluð.
shown.bs.tooltip Þessi atburður er ræstur þegar sprettiglugginn hefur verið gerður sýnilegur notanda (mun bíða eftir að CSS umbreytingum ljúki). 
const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

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

tooltip.hide()