Mga tooltip

Dokumentasyon at mga halimbawa para sa pagdaragdag ng mga custom na Bootstrap tooltip na may CSS at JavaScript gamit ang CSS3 para sa mga animation at data-bs-attribute para sa lokal na imbakan ng pamagat.

Sa pahinang ito

Pangkalahatang-ideya

Mga bagay na dapat malaman kapag ginagamit ang tooltip plugin:

Ang mga tooltip ay umaasa sa 3rd party na library na Popper para sa pagpoposisyon. Dapat mong isama ang popper.min.js bago ang bootstrap.js o gamitin ang bootstrap.bundle.min.js/ bootstrap.bundle.jsna naglalaman ng Popper upang gumana ang mga tooltip!
Ang mga tooltip ay nag-opt-in para sa mga dahilan ng pagganap, kaya dapat mong simulan ang mga ito sa iyong sarili .
Ang mga tooltip na may zero-length na mga pamagat ay hindi kailanman ipinapakita.
Tukuyin container: 'body'upang maiwasan ang pag-render ng mga problema sa mas kumplikadong mga bahagi (tulad ng aming mga pangkat ng input, mga pangkat ng button, atbp).
Ang pag-trigger ng mga tooltip sa mga nakatagong elemento ay hindi gagana.
Ang mga tooltip para sa .disabledo mga disabledelemento ay dapat na ma-trigger sa isang elemento ng wrapper.
Kapag na-trigger mula sa mga hyperlink na sumasaklaw sa maraming linya, ang mga tooltip ay igigitna. Gamitin white-space: nowrap;sa iyong <a>s upang maiwasan ang pag-uugaling ito.
Dapat itago ang mga tooltip bago maalis ang mga kaukulang elemento nito sa DOM.
Maaaring ma-trigger ang mga tooltip salamat sa isang elemento sa loob ng shadow DOM.

Bilang default, ginagamit ng component na ito ang built-in na content sanitizer, na nag-aalis ng anumang elemento ng HTML na hindi tahasang pinapayagan. Tingnan ang seksyon ng sanitizer sa aming dokumentasyon ng JavaScript para sa higit pang mga detalye.

Ang epekto ng animation ng bahaging ito ay nakasalalay sa prefers-reduced-motionquery ng media. Tingnan ang seksyon ng pinababang paggalaw ng aming dokumentasyon ng accessibility .

Nakuha ang lahat ng iyon? Mahusay, tingnan natin kung paano gumagana ang mga ito sa ilang mga halimbawa.

Halimbawa: Paganahin ang mga tooltip sa lahat ng dako

Ang isang paraan upang simulan ang lahat ng mga tooltip sa isang pahina ay ang piliin ang mga ito ayon sa kanilang data-bs-togglekatangian:

var tooltipTriggerList = [].slice.call(document.querySelectorAll('[data-bs-toggle="tooltip"]'))
var tooltipList = tooltipTriggerList.map(function (tooltipTriggerEl) {
  return new bootstrap.Tooltip(tooltipTriggerEl)
})

Mga halimbawa

Mag-hover sa mga link sa ibaba upang makita ang mga tooltip:

Mag-hover sa mga button sa ibaba upang makita ang apat na direksyon ng tooltip: itaas, kanan, ibaba, at kaliwa. Ang mga direksyon ay sinasalamin kapag gumagamit ng Bootstrap sa 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>

At may idinagdag na custom na 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>

Sa isang SVG:

Sass

Mga variable

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

Paggamit

Ang tooltip plugin ay bumubuo ng content at markup on demand, at bilang default ay naglalagay ng mga tooltip pagkatapos ng kanilang trigger element.

I-trigger ang tooltip sa pamamagitan ng JavaScript:

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)

Umaapaw `auto`at`scroll`

Ang posisyon ng tooltip ay sumusubok na awtomatikong magbago kapag ang isang pangunahing container ay mayroon overflow: autoo overflow: scrollnagustuhan ang aming .table-responsive, ngunit pinapanatili pa rin ang pagpoposisyon ng orihinal na placement. Upang malutas ito, itakda ang boundaryopsyon (para sa flip modifier gamit ang popperConfigopsyon) sa anumang HTMLElement upang i-override ang default na halaga, 'clippingParents', gaya ng document.body:

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

Markup

Ang kinakailangang markup para sa isang tooltip ay isang datakatangian lamang at titlesa HTML element na nais mong magkaroon ng isang tooltip. Ang nabuong markup ng isang tooltip ay medyo simple, bagama't nangangailangan ito ng isang posisyon (bilang default, nakatakda sa toppamamagitan ng plugin).

Ang paggawa ng mga tooltip ay gumagana para sa mga gumagamit ng keyboard at pantulong na teknolohiya

Dapat ka lang magdagdag ng mga tooltip sa mga elemento ng HTML na tradisyonal na nakatuon sa keyboard at interactive (tulad ng mga link o mga kontrol sa form). Bagama't ang mga di-makatwirang elemento ng HTML (tulad ng <span>s) ay maaaring gawing focusable sa pamamagitan ng pagdaragdag ng tabindex="0"attribute, magdaragdag ito ng potensyal na nakakainis at nakakalito na mga tab stop sa mga hindi interactive na elemento para sa mga user ng keyboard, at karamihan sa mga pantulong na teknolohiya ay kasalukuyang hindi nag-aanunsyo ng tooltip sa sitwasyong ito. Bukod pa rito, huwag umasa lamang hoverbilang trigger para sa iyong tooltip, dahil gagawin nitong imposibleng ma-trigger ang iyong mga tooltip para sa mga user ng keyboard.

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

Mga elementong may kapansanan

Ang mga elementong may disabledkatangian ay hindi interactive, ibig sabihin, ang mga user ay hindi maaaring tumuon, mag-hover, o mag-click sa mga ito upang mag-trigger ng tooltip (o popover). Bilang isang solusyon, gugustuhin mong i-trigger ang tooltip mula sa isang wrapper <div>o <span>, perpektong ginawang keyboard-focusable gamit ang 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>

Mga pagpipilian

Maaaring ipasa ang mga opsyon sa pamamagitan ng mga katangian ng data o JavaScript. Para sa mga katangian ng data, idagdag ang pangalan ng opsyon sa data-bs-, tulad ng sa data-bs-animation="". Siguraduhing baguhin ang uri ng kaso ng pangalan ng opsyon mula sa camelCase patungo sa kebab-case kapag ipinapasa ang mga opsyon sa pamamagitan ng mga katangian ng data. Halimbawa, sa halip na gamitin ang data-bs-customClass="beautifier", gamitin ang data-bs-custom-class="beautifier".

Tandaan na para sa mga kadahilanang pangseguridad ang sanitize, sanitizeFn, at mga allowListopsyon ay hindi maibibigay gamit ang mga katangian ng data.

Pangalan	Uri	Default	Paglalarawan
`animation`	boolean	`true`	Maglapat ng CSS fade transition sa tooltip
`container`	string \| elemento \| mali	`false`	Idinaragdag ang tooltip sa isang partikular na elemento. Halimbawa: `container: 'body'`. Ang pagpipiliang ito ay partikular na kapaki-pakinabang dahil pinapayagan ka nitong iposisyon ang tooltip sa daloy ng dokumento malapit sa nagti-trigger na elemento - na pipigil sa tooltip na lumutang palayo sa nagti-trigger na elemento sa panahon ng pagbabago ng laki ng window.
`delay`	numero \| bagay	`0`	Pagkaantala sa pagpapakita at pagtatago ng tooltip (ms) - hindi nalalapat sa manu-manong uri ng pag-trigger Kung may ibinigay na numero, ilalapat ang pagkaantala sa parehong itago/ipakita Ang istraktura ng bagay ay:`delay: { "show": 500, "hide": 100 }`
`html`	boolean	`false`	Payagan ang HTML sa tooltip. Kung totoo, ang mga HTML na tag sa tooltip `title`ay ire-render sa tooltip. Kung false, `innerText`gagamitin ang property para magpasok ng content sa DOM. Gumamit ng text kung nag-aalala ka tungkol sa mga pag-atake ng XSS.
`placement`	string \| function	`'top'`	Paano iposisyon ang tooltip - auto \| tuktok \| ibaba \| kaliwa \| tama. Kapag `auto`tinukoy, dynamic nitong i-reorient ang tooltip. Kapag ginamit ang isang function upang matukoy ang placement, tinatawag itong tooltip DOM node bilang unang argumento nito at ang triggering element na DOM node bilang pangalawa nito. Nakatakda ang `this`konteksto sa instance ng tooltip.
`selector`	string \| mali	`false`	Kung may ibibigay na tagapili, ang mga bagay sa tooltip ay idelegado sa mga tinukoy na target. Sa pagsasagawa, ito ay ginagamit upang ilapat din ang mga tooltip sa dynamic na idinagdag na mga elemento ng DOM ( `jQuery.on`suporta). Tingnan ito at isang halimbawang nagbibigay-kaalaman .
`template`	string	`'<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'`	Base HTML na gagamitin kapag gumagawa ng tooltip. Ang mga tooltip `title`ay ilalagay sa `.tooltip-inner`. `.tooltip-arrow`ay magiging arrow ng tooltip. Ang pinakamalawak na elemento ng wrapper ay dapat magkaroon ng `.tooltip`klase at `role="tooltip"`.
`title`	string \| elemento \| function	`''`	Default na halaga ng pamagat kung `title`walang katangian. Kung ang isang function ay ibinigay, ito ay tatawagin kasama ang `this`reference na nakatakda sa elemento kung saan ang tooltip ay naka-attach sa.
`trigger`	string	`'hover focus'`	Paano na-trigger ang tooltip - i-click ang \| mag-hover \| focus \| manwal. Maaari kang magpasa ng maraming trigger; paghiwalayin sila ng isang puwang. `'manual'`ay nagpapahiwatig na ang tooltip ay ma-trigger sa pamamagitan ng programmatically sa pamamagitan ng `.show()`, `.hide()`at mga `.toggle()`pamamaraan; hindi maaaring isama ang halagang ito sa anumang iba pang trigger. `'hover'`magreresulta sa sarili nitong mga tooltip na hindi ma-trigger sa pamamagitan ng keyboard, at dapat lang gamitin kung may mga alternatibong pamamaraan para sa paghahatid ng parehong impormasyon para sa mga user ng keyboard.
`fallbackPlacements`	array	`['top', 'right', 'bottom', 'left']`	Tukuyin ang mga fallback na placement sa pamamagitan ng pagbibigay ng listahan ng mga placement sa array (ayon sa kagustuhan). Para sa higit pang impormasyon sumangguni sa mga doc ng pag-uugali ng Popper
`boundary`	string \| elemento	`'clippingParents'`	Overflow constraint na hangganan ng tooltip (nalalapat lang sa preventOverflow modifier ng Popper). Bilang default, ito `'clippingParents'`ay at maaaring tumanggap ng isang HTMLElement reference (sa pamamagitan lamang ng JavaScript). Para sa higit pang impormasyon sumangguni sa detectOverflow docs ng Popper .
`customClass`	string \| function	`''`	Magdagdag ng mga klase sa tooltip kapag ipinakita ito. Tandaan na ang mga klase na ito ay idaragdag bilang karagdagan sa anumang mga klase na tinukoy sa template. Upang magdagdag ng maraming klase, paghiwalayin ang mga ito ng mga puwang: `'class-1 class-2'`. Maaari ka ring magpasa ng function na dapat magbalik ng isang string na naglalaman ng mga karagdagang pangalan ng klase.
`sanitize`	boolean	`true`	Paganahin o huwag paganahin ang sanitization. Kung na-activate `'template'`at `'title'`ang mga opsyon ay ma-sanitize. Tingnan ang seksyon ng sanitizer sa aming dokumentasyon ng JavaScript .
`allowList`	bagay	Default na halaga	Bagay na naglalaman ng mga pinapayagang katangian at tag
`sanitizeFn`	null \| function	`null`	Dito maaari kang magbigay ng iyong sariling sanitize function. Maaari itong maging kapaki-pakinabang kung mas gusto mong gumamit ng nakalaang library para magsagawa ng sanitization.
`offset`	array \| string \| function	`[0, 0]`	Offset ng tooltip na nauugnay sa target nito. Maaari kang magpasa ng string sa mga katangian ng data na may mga halagang pinaghihiwalay ng kuwit tulad ng:`data-bs-offset="10,20"` Kapag ang isang function ay ginamit upang matukoy ang offset, ito ay tinatawag na may isang bagay na naglalaman ng popper placement, ang reference, at popper rects bilang ang unang argumento nito. Ang triggering element na DOM node ay ipinasa bilang pangalawang argumento. Ang function ay dapat magbalik ng array na may dalawang numero: .`[skidding, distance]` Para sa higit pang impormasyon sumangguni sa mga offset na doc ng Popper .
`popperConfig`	null \| bagay \| function	`null`	Upang baguhin ang default na Popper config ng Bootstrap, tingnan ang configuration ng Popper . Kapag ang isang function ay ginamit upang lumikha ng Popper configuration, ito ay tinatawag na may isang object na naglalaman ng default na Popper configuration ng Bootstrap. Tinutulungan ka nitong gamitin at pagsamahin ang default sa sarili mong configuration. Ang function ay dapat magbalik ng configuration object para sa Popper.

Mga katangian ng data para sa mga indibidwal na tooltip

Ang mga opsyon para sa mga indibidwal na tooltip ay maaaring tukuyin sa pamamagitan ng paggamit ng mga katangian ng data, gaya ng ipinaliwanag sa itaas.

Paggamit ng function na may`popperConfig`

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

Paraan

Mga asynchronous na pamamaraan at paglipat

Ang lahat ng mga pamamaraan ng API ay asynchronous at nagsisimula ng isang paglipat . Bumalik sila sa tumatawag sa sandaling magsimula ang paglipat ngunit bago ito matapos . Bilang karagdagan, babalewalain ang isang method call sa isang transitioning component .

Tingnan ang aming dokumentasyon ng JavaScript para sa higit pang impormasyon .

palabas

Nagpapakita ng tooltip ng isang elemento. Bumabalik sa tumatawag bago aktwal na naipakita ang tooltip (ibig sabihin, bago shown.bs.tooltipmangyari ang kaganapan). Ito ay itinuturing na isang "manual" na pag-trigger ng tooltip. Ang mga tooltip na may zero-length na mga pamagat ay hindi kailanman ipinapakita.

tooltip.show()

tago

Itinatago ang tooltip ng isang elemento. Bumabalik sa tumatawag bago pa talaga naitago ang tooltip (ibig sabihin, bago hidden.bs.tooltipmangyari ang kaganapan). Ito ay itinuturing na isang "manual" na pag-trigger ng tooltip.

tooltip.hide()

magpalipat-lipat

I-toggle ang tooltip ng isang elemento. Bumabalik sa tumatawag bago ang tooltip ay aktwal na naipakita o naitago (ibig sabihin, bago mangyari ang shown.bs.tooltipo hidden.bs.tooltipkaganapan). Ito ay itinuturing na isang "manual" na pag-trigger ng tooltip.

tooltip.toggle()

itapon

Itinatago at sinisira ang tooltip ng isang elemento (Tinatanggal ang nakaimbak na data sa elemento ng DOM). Ang mga tooltip na gumagamit ng delegasyon (na ginawa gamit ang selectoropsyon ) ay hindi maaaring isa-isang sirain sa mga elemento ng descendant na trigger.

tooltip.dispose()

paganahin

Nagbibigay sa tooltip ng elemento ng kakayahang ipakita. Ang mga tooltip ay pinagana bilang default.

tooltip.enable()

huwag paganahin

Tinatanggal ang kakayahang ipakita ang tooltip ng isang elemento. Maipapakita lang ang tooltip kung ito ay muling pinagana.

tooltip.disable()

toggleEnabled

I-toggle ang kakayahang ipakita o itago ang tooltip ng isang elemento.

tooltip.toggleEnabled()

update

Ina-update ang posisyon ng tooltip ng isang elemento.

tooltip.update()

getInstance

Static na paraan na nagbibigay-daan sa iyong makuha ang tooltip instance na nauugnay sa isang elemento ng DOM

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance

getOrCreateInstance

Static na paraan na nagbibigay-daan sa iyong makuha ang tooltip instance na nauugnay sa isang elemento ng DOM, o gumawa ng bago kung sakaling hindi ito nasimulan

var exampleTriggerEl = document.getElementById('example')
var tooltip = bootstrap.Tooltip.getOrCreateInstance(exampleTriggerEl) // Returns a Bootstrap tooltip instance

Mga kaganapan

Uri ng kaganapan	Paglalarawan
`show.bs.tooltip`	Agad na gagana ang kaganapang ito kapag `show`tinawag ang paraan ng instance.
`shown.bs.tooltip`	Ang kaganapang ito ay pinapagana kapag ang tooltip ay ginawang nakikita ng user (maghihintay na makumpleto ang mga transition ng CSS).
`hide.bs.tooltip`	Agad na pinapagana ang kaganapang ito kapag `hide`tinawag na ang paraan ng instance.
`hidden.bs.tooltip`	Ang kaganapang ito ay pinapagana kapag ang tooltip ay tapos nang itago mula sa user (maghihintay para sa mga transition ng CSS na makumpleto).
`inserted.bs.tooltip`	Ang kaganapang ito ay pinapagana pagkatapos ng `show.bs.tooltip`kaganapan kapag ang template ng tooltip ay naidagdag sa DOM.

var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

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

tooltip.hide()