Slaan oor na hoofinhoud Slaan oor na dokumentnavigasie
Check
in English

Gereedskapwenke

Dokumentasie en voorbeelde vir die byvoeging van pasgemaakte Bootstrap-nutsmiddelwenke met CSS en JavaScript met behulp van CSS3 vir animasies en data-bs-kenmerke vir plaaslike titelberging.

Op hierdie bladsy

Oorsig

Dinge om te weet wanneer jy die tooltip-inprop gebruik:

  • Gereedskapwenke maak staat op die derdeparty-biblioteek Popper vir posisionering. Jy moet popper.min.js voor insluit bootstrap.js, of een gebruik bootstrap.bundle.min.jswat Popper bevat.
  • Gereedskapwenke is intekening vir prestasieredes, so jy moet dit self inisialiseer .
  • Gereedskapwenke met titels van geen lengte word nooit vertoon nie.
  • Spesifiseer container: 'body'om te verhoed dat probleme in meer komplekse komponente weergegee word (soos ons invoergroepe, knoppiegroepe, ens.).
  • Om gereedskapwenke op verborge elemente te aktiveer, sal nie werk nie.
  • Gereedskapwenke vir .disabledof disabledelemente moet op 'n omhulelement geaktiveer word.
  • Wanneer dit geaktiveer word vanaf hiperskakels wat oor verskeie lyne strek, sal gereedskapwenke gesentreer word. Gebruik white-space: nowrap;op jou <a>s om hierdie gedrag te vermy.
  • Gereedskapwenke moet versteek word voordat hul ooreenstemmende elemente uit die DOM verwyder is.
  • Gereedskapwenke kan geaktiveer word danksy 'n element binne 'n skadu-DOM.

Het jy dit alles? Wonderlik, kom ons kyk hoe hulle werk met 'n paar voorbeelde.

By verstek gebruik hierdie komponent die ingeboude inhoudreiniger, wat enige HTML-elemente wat nie eksplisiet toegelaat word nie, verwyder. Sien die ontsmettingsmiddel-afdeling in ons JavaScript-dokumentasie vir meer besonderhede.
Die animasie-effek van hierdie komponent is afhanklik van die prefers-reduced-motionmedianavraag. Sien die verminderde beweging-afdeling van ons toeganklikheidsdokumentasie .

Voorbeelde

Aktiveer gereedskapwenke

Soos hierbo genoem, moet u gereedskapwenke inisialiseer voordat dit gebruik kan word. Een manier om alle gereedskapwenke op 'n bladsy te inisialiseer, is om hulle volgens hul data-bs-togglekenmerk te kies, soos so:

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

Beweeg oor die skakels hieronder om nutswenke te sien:

Plekhouerteks om 'n paar inlynskakels met nutswenke te demonstreer. Hierdie is nou net vuller, geen moordenaar nie. Inhoud wat hier geplaas word net om die teenwoordigheid van regte teks na te boots . En dit alles net om jou 'n idee te gee van hoe gereedskapwenke sal lyk wanneer dit in werklike situasies gebruik word. So hopelik het jy nou gesien hoe hierdie nutswenke oor skakels in die praktyk kan werk, sodra jy dit op jou eie webwerf of projek gebruik.

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>
Gebruik gerus óf titleóf data-bs-titlein jou HTML. Wanneer titledit gebruik word, sal Popper dit outomaties vervang met data-bs-titlewanneer die element weergegee word.

Gepasmaakte gereedskapwenke

Bygevoeg in v5.2.0

Jy kan die voorkoms van gereedskapwenke aanpas deur CSS-veranderlikes te gebruik . Ons stel 'n pasgemaakte klas met data-bs-custom-class="custom-tooltip"om ons pasgemaakte voorkoms te omvang en gebruik dit om 'n plaaslike CSS-veranderlike te ignoreer.

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

Aanwysings

Beweeg oor die knoppies hieronder om die vier gereedskapwenke-rigtings te sien: bo, regs, onder en links. Aanwysings word weerspieël wanneer Bootstrap in RTL gebruik word.

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

En met persoonlike HTML bygevoeg:

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

Met 'n SVG:

CSS

Veranderlikes

Bygevoeg in v5.2.0

As deel van Bootstrap se ontwikkelende CSS-veranderlikebenadering, gebruik gereedskapwenke nou plaaslike CSS-veranderlikes .tooltipvir verbeterde intydse aanpassing. Waardes vir die CSS-veranderlikes word via Sass ingestel, dus word Sass-aanpassing ook steeds ondersteun.

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

$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

Gebruik

Die tooltip-inprop genereer inhoud en opmaak op aanvraag, en plaas by verstek gereedskapwenke na hul snellerelement.

Aktiveer die nutswenk via JavaScript:

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

Nutswenk-posisie poog om outomaties te verander wanneer 'n ouerhouer ons het overflow: autoof overflow: scrollhou van ons .table-responsive, maar behou steeds die oorspronklike plasing se posisionering. Om dit op te los, stel die boundaryopsie (vir die flip-wysiger wat die popperConfigopsie gebruik) op enige HTMLElement om die verstekwaarde, , te ignoreer 'clippingParents', soos document.body:

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

Opmerk

Die vereiste opmaak vir 'n nutswenk is slegs 'n datakenmerk en titleop die HTML-element wil jy 'n nutswenk hê. Die gegenereerde opmaak van 'n nutswenk is redelik eenvoudig, alhoewel dit 'n posisie vereis (by verstek gestel topdeur die inprop).

Maak gereedskapwenke werk vir sleutelbord- en hulptegnologiegebruikers

Jy moet slegs gereedskapwenke by HTML-elemente voeg wat tradisioneel sleutelbordfokusbaar en interaktief is (soos skakels of vormkontroles). Alhoewel arbitrêre HTML-elemente (soos <span>s) fokusbaar gemaak kan word deur die tabindex="0"kenmerk by te voeg, sal dit potensieel irriterende en verwarrende tabstops op nie-interaktiewe elemente vir sleutelbordgebruikers byvoeg, en die meeste ondersteunende tegnologieë kondig tans nie die nutswenk in hierdie situasie aan nie. Moet ook nie net daarop staatmaak hoveras die sneller vir jou nutswenk nie, want dit sal jou nutswenke onmoontlik maak om vir sleutelbordgebruikers te aktiveer.

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

Gedeaktiveerde elemente

Elemente met die disabledkenmerk is nie interaktief nie, wat beteken dat gebruikers nie kan fokus, beweeg of daarop klik om 'n nutswenk (of popover) te aktiveer nie. As 'n oplossing, sal jy die nutswenk wil aktiveer vanaf 'n omhulsel <div>of <span>, ideaal gemaak sleutelbord-fokusbaar met 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>

Opsies

Aangesien opsies deur data-kenmerke of JavaScript deurgegee kan word, kan jy 'n opsienaam byvoeg data-bs-, soos in data-bs-animation="{value}". Maak seker dat jy die kastipe van die opsienaam verander van " camelCase " na " kebab-case " wanneer die opsies deur data-kenmerke deurgegee word. Gebruik byvoorbeeld in data-bs-custom-class="beautifier"plaas van data-bs-customClass="beautifier".

Vanaf Bootstrap 5.2.0 ondersteun alle komponente 'n eksperimentele gereserveerde data-kenmerk data-bs-configwat eenvoudige komponentkonfigurasie as 'n JSON-string kan huisves. Wanneer 'n element data-bs-config='{"delay":0, "title":123}'en data-bs-title="456"kenmerke het, sal die finale titlewaarde wees 456en die afsonderlike data-kenmerke sal waardes wat op gegee word, ignoreer data-bs-config. Daarbenewens kan bestaande data-kenmerke JSON-waardes soos data-bs-delay='{"show":0,"hide":150}'.

sanitizeLet daarop dat die , sanitizeFn, en allowListopsies om sekuriteitsredes nie met behulp van data-kenmerke verskaf kan word nie.
Naam Tik Verstek Beskrywing
allowList voorwerp Standaard waarde Voorwerp wat toegelate kenmerke en etikette bevat.
animation boolean true Pas 'n CSS-vervaag-oorgang toe op die nutswenk.
boundary string, element 'clippingParents' Oorloopbeperkingsgrens van die nutswenk (is slegs van toepassing op Popper se preventOverflow-wysiger). By verstek is 'clippingParents'en kan dit 'n HTMLElement-verwysing aanvaar (slegs via JavaScript). Vir meer inligting, verwys na Popper se detectOverflow-dokumente .
container string, element, vals false Voeg die nutswenk by 'n spesifieke element. Voorbeeld: container: 'body'. Hierdie opsie is veral nuttig omdat dit jou in staat stel om die nutspunt in die vloei van die dokument naby die snellerelement te plaas - wat sal verhoed dat die nutswenk van die snellerelement wegdryf tydens 'n venstergrootte.
customClass string, funksie '' Voeg klasse by die nutswenk wanneer dit gewys word. Let daarop dat hierdie klasse bygevoeg sal word bykomend tot enige klasse wat in die sjabloon gespesifiseer word. Om veelvuldige klasse by te voeg, skei hulle met spasies: 'class-1 class-2'. Jy kan ook 'n funksie deurgee wat 'n enkele string met bykomende klasname moet terugstuur.
delay nommer, voorwerp 0 Vertraag die wys en versteek van die nutswenk (ms)—is nie van toepassing op handmatige snellertipe nie. As 'n nommer verskaf word, word vertraging toegepas op beide versteek/wys. Voorwerpstruktuur is: delay: { "show": 500, "hide": 100 }.
fallbackPlacements skikking ['top', 'right', 'bottom', 'left'] Definieer terugvalplasings deur 'n lys van plasings in 'n skikking te verskaf (in volgorde van voorkeur). Vir meer inligting, verwys na Popper se gedragsdokumente .
html boolean false Laat HTML toe in die nutswenk. Indien waar, sal HTML-merkers in die nutswenk s'n titlein die nutswenk weergegee word. Indien onwaar, innerTextsal eiendom gebruik word om inhoud in die DOM in te voeg. Gebruik teks as jy bekommerd is oor XSS-aanvalle.
offset skikking, string, funksie [0, 0] Verskuiwing van die nutswenk relatief tot sy teiken. Jy kan 'n string in data-kenmerke met kommageskeide waardes soos: data-bs-offset="10,20". Wanneer 'n funksie gebruik word om die offset te bepaal, word dit opgeroep met 'n objek wat die drukkerplasing, die verwysing en drukkerrekse as sy eerste argument bevat. Die snellerelement DOM-nodus word as die tweede argument deurgegee. Die funksie moet 'n skikking met twee getalle terugstuur: gly , afstand . Vir meer inligting, verwys na Popper se offset-dokumente .
placement string, funksie 'top' Hoe om die nutswenk te plaas: outomaties, bo, onder, links, regs. Wanneer autogespesifiseer word, sal dit die nutswenk dinamies heroriënteer. Wanneer 'n funksie gebruik word om die plasing te bepaal, word dit genoem met die tooltip DOM node as sy eerste argument en die sneller element DOM node as sy tweede. Die thiskonteks is ingestel op die tooltip-instansie.
popperConfig nul, voorwerp, funksie null Sien Popper se konfigurasie om Bootstrap se verstek Popper-konfigurasie te verander . Wanneer 'n funksie gebruik word om die Popper-konfigurasie te skep, word dit genoem met 'n voorwerp wat die Bootstrap se verstek Popper-konfigurasie bevat. Dit help jou om die verstek met jou eie konfigurasie te gebruik en saam te voeg. Die funksie moet 'n konfigurasie-objek vir Popper terugstuur.
sanitize boolean true Aktiveer of deaktiveer die ontsmetting. Indien geaktiveer 'template', 'content'en 'title'opsies sal ontsmet word.
sanitizeFn nul, funksie null Hier kan jy jou eie ontsmettingsfunksie verskaf. Dit kan nuttig wees as jy verkies om 'n toegewyde biblioteek te gebruik om ontsmetting uit te voer.
selector string, vals false As 'n kieser verskaf word, sal tooltip-objekte na die gespesifiseerde teikens gedelegeer word. In die praktyk word dit gebruik om ook gereedskapwenke toe te pas op dinamies bygevoegde DOM-elemente ( jQuery.onondersteuning). Sien hierdie uitgawe en 'n insiggewende voorbeeld .
template string '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' Baseer HTML om te gebruik wanneer die nutswenk geskep word. Die tooltip's titlesal in die .tooltip-inner. .tooltip-arrowsal die nutspunt se pyl word. Die buitenste omhulselelement moet die .tooltipklas en role="tooltip".
title string, element, funksie '' Verstek titelwaarde as titlekenmerk nie teenwoordig is nie. As 'n funksie gegee word, sal dit genoem word met sy thisverwysing ingestel na die element waaraan die popover gekoppel is.
trigger string 'hover focus' Hoe tooltip geaktiveer word: klik, beweeg, fokus, handleiding. Jy kan verskeie snellers slaag; skei hulle met 'n spasie. 'manual'dui aan dat die nutswenk programmaties geaktiveer sal word via die .tooltip('show'), .tooltip('hide')en .tooltip('toggle')metodes; hierdie waarde kan nie met enige ander sneller gekombineer word nie. 'hover'op sy eie sal lei tot gereedskapwenke wat nie via die sleutelbord geaktiveer kan word nie, en moet slegs gebruik word as alternatiewe metodes vir die oordra van dieselfde inligting vir sleutelbordgebruikers teenwoordig is.

Data-kenmerke vir individuele gereedskapwenke

Opsies vir individuele gereedskapwenke kan alternatiewelik gespesifiseer word deur die gebruik van data-kenmerke, soos hierbo verduidelik.

Die gebruik van funksie metpopperConfig 

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

Metodes

Asinchroniese metodes en oorgange

Alle API-metodes is asynchronies en begin 'n oorgang . Hulle keer terug na die oproeper sodra die oorgang begin is, maar voordat dit eindig . Daarbenewens sal 'n metode-oproep op 'n oorgangskomponent geïgnoreer word .

Sien ons JavaScript-dokumentasie vir meer inligting .

Metode Beskrywing
disable Verwyder die vermoë om 'n element se nutswenk te wys. Die nutswenk sal slegs gewys kan word as dit weer geaktiveer is.
dispose Versteek en vernietig 'n element se nutswenk (Verwyder gestoorde data op die DOM-element). Gereedskapwenke wat delegering gebruik (wat met die selectoropsie geskep word ) kan nie individueel op afstammelinge-snellerelemente vernietig word nie.
enable Gee 'n element se nutswenk die vermoë om gewys te word. Gereedskapwenke is by verstek geaktiveer.
getInstance Statiese metode wat jou toelaat om die tooltip-instansie te kry wat met 'n DOM-element geassosieer word, of 'n nuwe een te skep ingeval dit nie geïnisialiseer is nie.
getOrCreateInstance Statiese metode wat jou toelaat om die tooltip-instansie te kry wat met 'n DOM-element geassosieer word, of 'n nuwe een te skep ingeval dit nie geïnisialiseer is nie.
hide Versteek 'n element se nutswenk. Keer terug na die oproeper voordat die nutswenk eintlik versteek is (dws voor die hidden.bs.tooltipgebeurtenis plaasvind). Dit word beskou as 'n "handmatige" sneller van die nutswenk.
setContent Gee 'n manier om die nutswenk se inhoud te verander na die initialisering daarvan.
show Onthul 'n element se nutswenk. Keer terug na die oproeper voordat die nutswenk werklik gewys is (dws voor die shown.bs.tooltipgebeurtenis plaasvind). Dit word beskou as 'n "handmatige" sneller van die nutswenk. Gereedskapwenke met titels van geen lengte word nooit vertoon nie.
toggle Wissel 'n element se nutswenk. Keer terug na die oproeper voordat die nutswenk werklik gewys of versteek is (dws voordat die shown.bs.tooltipof hidden.bs.tooltipgebeurtenis plaasvind). Dit word beskou as 'n "handmatige" sneller van die nutswenk.
toggleEnabled Wissel die vermoë vir 'n element se nutswenk om gewys of versteek te word.
update Dateer die posisie van 'n element se nutswenk op. 
const tooltip = bootstrap.Tooltip.getInstance('#example') // Returns a Bootstrap tooltip instance

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })
Die setContentmetode aanvaar 'n objectargument, waar elke eiendom-sleutel 'n geldige stringkeurder binne die popover-sjabloon is, en elke verwante eienskap-waarde kan wees string| element| function| null

Gebeurtenisse

Gebeurtenis Beskrywing
hide.bs.tooltip Hierdie gebeurtenis word onmiddellik afgevuur wanneer die hideinstansiemetode geroep is.
hidden.bs.tooltip Hierdie gebeurtenis word afgevuur wanneer die popover klaar vir die gebruiker versteek is (sal wag vir CSS-oorgange om te voltooi).
inserted.bs.tooltip Hierdie gebeurtenis word afgevuur na die show.bs.tooltipgebeurtenis wanneer die nutswenk-sjabloon by die DOM gevoeg is.
show.bs.tooltip Hierdie gebeurtenis begin onmiddellik wanneer die showinstansiemetode geroep word.
shown.bs.tooltip Hierdie gebeurtenis word afgevuur wanneer die opspringer sigbaar gemaak is vir die gebruiker (sal wag vir CSS-oorgange om te voltooi). 
const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

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

tooltip.hide()