Перайсці да асноўнага зместу Перайсці да навігацыі па дакументах
in English

Падказкі

Дакументацыя і прыклады для дадання карыстацкіх падказак Bootstrap з CSS і JavaScript з выкарыстаннем CSS3 для анімацыі і атрыбутаў data-bs для лакальнага захоўвання загалоўкаў.

Агляд

Што трэба ведаць пры выкарыстанні плагіна падказкі:

  • Падказкі абапіраюцца на староннію бібліятэку Popper для пазіцыянавання. Вы павінны ўключыць popper.min.js перад bootstrap.js або выкарыстоўваць bootstrap.bundle.min.js/ bootstrap.bundle.js, які змяшчае Popper, каб падказкі працавалі!
  • Усплывальныя падказкі з'яўляюцца выбарнымі з меркаванняў прадукцыйнасці, таму вы павінны ініцыялізаваць іх самастойна .
  • Падказкі з загалоўкамі нулявой даўжыні ніколі не адлюстроўваюцца.
  • Укажыце container: 'body', каб пазбегнуць праблем з візуалізацыяй больш складаных кампанентаў (напрыклад, нашых груп уводу, груп кнопак і г.д.).
  • Запуск падказак на схаваных элементах не будзе працаваць.
  • Падказкі для элементаў .disabledабо disabledпавінны запускацца на элеменце-абгортцы.
  • Пры запуску з гіперспасылак, якія ахопліваюць некалькі радкоў, падказкі будуць па цэнтры. Выкарыстоўвайце white-space: nowrap;на вашым <a>s, каб пазбегнуць такіх паводзін.
  • Усплывальныя падказкі павінны быць схаваныя, перш чым адпаведныя элементы будуць выдалены з DOM.
  • Усплывальныя падказкі могуць быць запушчаны дзякуючы элементу ўнутры ценявога DOM.
Па змаўчанні гэты кампанент выкарыстоўвае ўбудаваны сродак ачысткі змесціва, які выдаляе любыя элементы HTML, якія відавочна не дазволены. Больш падрабязную інфармацыю глядзіце ў раздзеле дэзінфікуючых сродкаў у нашай дакументацыі па JavaScript .
Анімацыйны эфект гэтага кампанента залежыць ад prefers-reduced-motionмедыя-запыту. Глядзіце раздзел аб паменшаным руху нашай дакументацыі па спецыяльных магчымасцях .

Зразумеў усё? Выдатна, давайце паглядзім, як яны працуюць, на некаторых прыкладах.

Прыклад: уключыце падказкі ўсюды

Адзін са спосабаў ініцыялізаваць усе падказкі на старонцы - выбраць іх па data-bs-toggleатрыбутах:

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

Прыклады

Навядзіце курсор на спасылкі ніжэй, каб убачыць падказкі:

Тэкст-запаўняльнік для дэманстрацыі некаторых убудаваных спасылак з падказкамі. Цяпер гэта проста напаўняльнік, а не забойца. Змесціва, размешчанае тут толькі для імітацыі прысутнасці сапраўднага тэксту . І ўсё гэта толькі для таго, каб даць вам уяўленне аб тым, як будуць выглядаць падказкі пры выкарыстанні ў рэальных сітуацыях. Так што, спадзяюся, вы ўбачылі, як гэтыя ўсплывальныя падказкі па спасылках могуць працаваць на практыцы, калі вы выкарыстоўваеце іх на ўласным сайце або ў праекце.

Навядзіце курсор мышы на кнопкі ніжэй, каб убачыць чатыры ўсплывальныя падказкі: зверху, справа, знізу і злева. Напрамкі адлюстроўваюцца пры выкарыстанні Bootstrap у 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>

І з даданнем карыстальніцкага 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>

З SVG:

Сас

Пераменныя

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

Выкарыстанне

Убудова ўсплывальнай падказкі стварае кантэнт і разметку па патрабаванні і па змаўчанні размяшчае ўсплывальныя падказкі пасля элемента запуску.

Запусціць падказку праз JavaScript:

var exampleEl = document.getElementById('example')
var tooltip = new bootstrap.Tooltip(exampleEl, options)
Пераліў autoіscroll

Пазіцыя ўсплываючай падказкі спрабуе аўтаматычна змяніцца, калі бацькоўскі кантэйнер мае overflow: autoабо overflow: scrollяк наш .table-responsive, але пры гэтым захоўваецца зыходнае размяшчэнне. Каб вырашыць гэтую праблему, усталюйце boundaryпараметр (для мадыфікатара перавароту з дапамогай popperConfigпараметра) у любы HTMLElement, каб перавызначыць значэнне па змаўчанні 'clippingParents', напрыклад document.body:

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

Разметка

Неабходная разметка для ўсплываючай падказкі - гэта толькі dataатрыбут, а titleна элемент HTML вы хочаце мець падказку. Створаная разметка ўсплываючай падказкі даволі простая, хаця для яе патрабуецца пазіцыя (па змаўчанні, усталяваная topўбудовай).

Стварэнне ўсплывальных падказак для карыстальнікаў клавіятуры і дапаможных тэхналогій

Вы павінны дадаваць падказкі толькі да элементаў HTML, якія традыцыйна функцыянуюць з дапамогай клавіятуры і інтэрактыўныя (напрыклад, спасылкі або элементы кіравання формамі). Нягледзячы на ​​тое, што адвольныя элементы HTML (напрыклад, <span>s) можна зрабіць фокуснымі, дадаўшы tabindex="0"атрыбут, гэта дадасць патэнцыйна раздражняльныя і заблытаныя прыпынкі табуляцыі на неінтэрактыўныя элементы для карыстальнікаў клавіятуры, і большасць дапаможных тэхналогій у цяперашні час не аб'яўляюць падказку ў гэтай сітуацыі. Акрамя таго, не спадзявайцеся толькі на hoverтое, што гэта будзе трыгер для вашай усплывальнай падказкі, бо гэта зробіць вашыя падказкі немагчымымі для запуску для карыстальнікаў клавіятуры.

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

Адключаныя элементы

Элементы з disabledатрыбутам не з'яўляюцца інтэрактыўнымі, што азначае, што карыстальнікі не могуць сфакусавацца, навесці курсор або націснуць на іх, каб выклікаць падказку (або ўсплывальнае акно). У якасці абыходнага шляху вы захочаце запусціць падказку з абалонкі <div>або <span>, у ідэале, з дапамогай клавіятуры з дапамогай 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>

Параметры

Параметры могуць быць перададзены праз атрыбуты дадзеных або JavaScript. Для атрыбутаў дадзеных дадайце назву опцыі да data-bs-, як у data-bs-animation="". Не забудзьцеся змяніць тып рэгістра назвы опцыі з camelCase на kebab-case пры перадачы опцый праз атрыбуты даных. Напрыклад, замест выкарыстання data-bs-customClass="beautifier"выкарыстоўвайце data-bs-custom-class="beautifier".

Звярніце ўвагу, што з меркаванняў бяспекі параметры sanitize, sanitizeFn, і allowListне могуць быць прадастаўлены з выкарыстаннем атрыбутаў даных.
Імя Тып Па змаўчанні Апісанне
animation лагічны true Прымяніце пераход знікнення CSS да падказкі
container радок | элемент | ілжывы false

Дадае падказку да пэўнага элемента. Прыклад: container: 'body'. Гэтая опцыя асабліва карысная тым, што яна дазваляе размясціць падказку ў патоку дакумента побач з запускаючым элементам, што не дазволіць усплывальнай падказцы адплываць ад запускаючага элемента падчас змены памеру акна.

delay нумар | аб'ект 0

Затрымка паказу і хавання ўсплывальнай падказкі (мс) - не прымяняецца да ручнога тыпу трыгера

Калі ўказана лічба, затрымка прымяняецца як для схавання, так і для паказу

Структура аб'екта:delay: { "show": 500, "hide": 100 }

html лагічны false

Дазволіць HTML у падказцы.

Калі ісціна, тэгі HTML ва ўсплывальнай падказцы titleбудуць адлюстроўвацца ў падказцы. Калі false, innerTextуласцівасць будзе выкарыстоўвацца для ўстаўкі змесціва ў DOM.

Выкарыстоўвайце тэкст, калі вы турбуецеся аб атаках XSS.

placement радок | функцыя 'top'

Як размясціць падказку - аўто | уверх | унізе | злева | справа.
Калі autoпазначана, гэта будзе дынамічна пераарыентаваць падказку.

Калі функцыя выкарыстоўваецца для вызначэння размяшчэння, яна выклікаецца з вузлом DOM падказкі ў якасці першага аргумента і вузлом DOM элемента запуску ў якасці другога. Кантэкст thisусталяваны для асобніка падказкі.

selector радок | ілжывы false Калі прадастаўляецца селектар, аб'екты ўсплывальнай падказкі будуць дэлегаваны ўказаным мэтам. На практыцы гэта таксама выкарыстоўваецца для прымянення падказак да дынамічна даданых элементаў DOM ( jQuery.onпадтрымка). Глядзіце гэта і інфарматыўны прыклад .
template радок '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>'

Базавы HTML для выкарыстання пры стварэнні падказкі.

Падказка titleбудзе ўстаўлена ў .tooltip-inner.

.tooltip-arrowстане стрэлкай падказкі.

Самы знешні элемент-абгортка павінен мець .tooltipклас і role="tooltip".

title радок | элемент | функцыя ''

Значэнне назвы па змаўчанні, калі titleатрыбут адсутнічае.

Калі функцыя зададзена, яна будзе выклікана са thisспасылкай, усталяванай на элемент, да якога далучана ўсплывальная падказка.

trigger радок 'hover focus'

Як спрацоўвае падказка - націсніце | лунаць | фокус | кіраўніцтва. Вы можаце перадаць некалькі трыгераў; падзяліце іх прабелам.

'manual'паказвае, што падказка будзе запушчана праграмна праз метады .show(), .hide()і ; .toggle()гэта значэнне не можа спалучацца з любым іншым трыгерам.

'hover'сам па сабе прывядзе да ўсплывальных падказак, якія нельга выклікаць праз клавіятуру, і іх варта выкарыстоўваць толькі пры наяўнасці альтэрнатыўных метадаў перадачы той жа інфармацыі для карыстальнікаў клавіятуры.

fallbackPlacements масіў ['top', 'right', 'bottom', 'left'] Вызначце рэзервовыя месцы размяшчэння, прадставіўшы спіс месцаў размяшчэння ў масіве (у парадку перавагі). Для атрымання дадатковай інфармацыі звярніцеся да дакументацыі паводзін Попера
boundary радок | элемент 'clippingParents' Мяжа абмежавання перапаўнення падказкі (прымяняецца толькі да мадыфікатара preventOverflow Попера). Па змаўчанні гэта 'clippingParents'і можа прымаць спасылку HTMLElement (толькі праз JavaScript). Для атрымання дадатковай інфармацыі звярніцеся да дакументаў Popper's detectOverflow .
customClass радок | функцыя ''

Дадавайце класы да падказкі, калі яна паказваецца. Звярніце ўвагу, што гэтыя класы будуць дададзены ў дадатак да любых класаў, указаных у шаблоне. Каб дадаць некалькі класаў, падзяліце іх прабеламі: 'class-1 class-2'.

Вы таксама можаце перадаць функцыю, якая павінна вяртаць адзіны радок, які змяшчае дадатковыя імёны класаў.

sanitize лагічны true Уключыце або выключыце дэзінфекцыю. Калі актывавана 'template', і 'title'параметры будуць ачышчаны. Глядзіце раздзел дэзінфікуючых сродкаў у нашай дакументацыі па JavaScript .
allowList аб'ект Значэнне па змаўчанні Аб'ект, які змяшчае дазволеныя атрыбуты і тэгі
sanitizeFn нуль | функцыя null Тут вы можаце паставіць сваю ўласную функцыю дэзінфекцыі. Гэта можа быць карысна, калі вы аддаеце перавагу выкарыстоўваць спецыяльную бібліятэку для правядзення дэзінфекцыі.
offset масіў | радок | функцыя [0, 0]

Зрушэнне падказкі адносна мэты. Вы можаце перадаць радок у атрыбутах дадзеных са значэннямі, падзеленымі коскамі, напрыклад:data-bs-offset="10,20"

Калі функцыя выкарыстоўваецца для вызначэння зрушэння, яна выклікаецца з аб'ектам, які змяшчае размяшчэнне попера, спасылку і прамастаянні попера ў якасці першага аргумента. Запускаючы элемент DOM вузел перадаецца ў якасці другога аргумента. Функцыя павінна вяртаць масіў з двума лікамі: .[skidding, distance]

Для атрымання дадатковай інфармацыі звярніцеся да афсетнай дакументацыі Попера .

popperConfig нуль | аб'ект | функцыя null

Каб змяніць стандартную канфігурацыю Popper для Bootstrap, глядзіце канфігурацыю Popper .

Калі функцыя выкарыстоўваецца для стварэння канфігурацыі Popper, яна выклікаецца з аб'ектам, які змяшчае канфігурацыю Popper па змаўчанні Bootstrap. Гэта дапаможа вам выкарыстоўваць і аб'яднаць стандартную канфігурацыю з вашай уласнай канфігурацыяй. Функцыя павінна вяртаць аб'ект канфігурацыі для Popper.

Атрыбуты дадзеных для асобных падказак

Варыянты для асобных усплывальных падказак можна ў якасці альтэрнатывы задаць з дапамогай выкарыстання атрыбутаў даных, як тлумачылася вышэй.

Выкарыстанне функцыі зpopperConfig

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

Метады

Асінхронныя метады і пераходы

Усе метады API асінхронныя і пачынаюць пераход . Яны вяртаюцца да абанента, як толькі пачынаецца пераход, але да яго заканчэння . Акрамя таго, выклік метаду пераходнага кампанента будзе ігнаравацца .

Для атрымання дадатковай інфармацыі глядзіце нашу дакументацыю па JavaScript .

паказаць

Адкрывае падказку элемента. Вяртаецца да абанента да таго, як была фактычна паказана ўсплывальная падказка (г.зн. да таго , як shown.bs.tooltipадбудзецца падзея). Гэта лічыцца «ручным» запускам падказкі. Падказкі з загалоўкамі нулявой даўжыні ніколі не адлюстроўваюцца.

tooltip.show()

схаваць

Хавае падказку элемента. Вяртаецца да абанента да таго, як падказка была фактычна схавана (г.зн. да таго, як hidden.bs.tooltipадбылася падзея). Гэта лічыцца «ручным» запускам падказкі.

tooltip.hide()

пераключаць

Пераключае падказку элемента. Вяртаецца да абанента да таго, як падказка была фактычна паказана або схавана (г.зн. да таго , як адбудзецца падзея shown.bs.tooltipабо ). hidden.bs.tooltipГэта лічыцца «ручным» запускам падказкі.

tooltip.toggle()

распараджацца

Хавае і знішчае ўсплывальную падказку элемента (выдаляе захаваныя даныя на элеменце DOM). Усплывальныя падказкі, якія выкарыстоўваюць дэлегаванне (якія ствараюцца з выкарыстаннем опцыі selector), не могуць быць індывідуальна знішчаны на нашчадных трыгерных элементах.

tooltip.dispose()

уключыць

Дае магчымасць паказу падказкі элемента. Падказкі ўключаны па змаўчанні.

tooltip.enable()

адключыць

Выдаляе магчымасць паказу падказкі элемента. Усплываючая падказка можа быць паказана, толькі калі яна зноў уключана.

tooltip.disable()

пераключацьУключана

Уключае магчымасць паказваць або хаваць падказку элемента.

tooltip.toggleEnabled()

абнаўленне

Абнаўляе пазіцыю падказкі элемента.

tooltip.update()

getInstance

Статычны метад, які дазваляе атрымаць асобнік усплывальнай падказкі, звязаны з элементам DOM

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

getOrCreateInstance

Статычны метад, які дазваляе вам атрымаць асобнік падказкі, звязаны з элементам DOM, або стварыць новы, калі ён не быў ініцыялізаваны

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

Падзеі

Тып падзеі Апісанне
show.bs.tooltip Гэта падзея запускаецца неадкладна пры showвыкліку метаду асобніка.
shown.bs.tooltip Гэта падзея запускаецца, калі падказка становіцца бачнай для карыстальніка (будзе чакаць завяршэння пераходаў CSS).
hide.bs.tooltip Гэта падзея запускаецца адразу пасля hideвыкліку метаду асобніка.
hidden.bs.tooltip Гэта падзея запускаецца, калі ўсплываючая падказка перастае быць схаванай ад карыстальніка (будзе чакаць завяршэння пераходаў CSS).
inserted.bs.tooltip Гэта падзея запускаецца пасля show.bs.tooltipпадзеі, калі шаблон падказкі быў дададзены ў DOM.
var myTooltipEl = document.getElementById('myTooltip')
var tooltip = new bootstrap.Tooltip(myTooltipEl)

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

tooltip.hide()