in English

Падказкі

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

Агляд

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

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

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

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

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

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

Прыклады

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

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

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

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

І з даданнем карыстальніцкага HTML:

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

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

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

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

$('#example').tooltip(options)
Пераліў autoіscroll

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

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

Разметка

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

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

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

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

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

Элементы з disabledатрыбутам не з'яўляюцца інтэрактыўнымі, што азначае, што карыстальнікі не могуць сфакусавацца, навесці курсор або націснуць на іх, каб выклікаць падказку (або ўсплывальнае акно). У якасці абыходнага шляху вы захочаце запусціць падказку з абалонкі <div>або <span>, у ідэале зробленай з дапамогай клавіятуры tabindex="0", і перавызначыць pointer-eventsна адключаным элеменце.

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

Параметры

Параметры могуць быць перададзены праз атрыбуты дадзеных або JavaScript. Для атрыбутаў дадзеных дадайце назву опцыі да data-, як у data-animation="".

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

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

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

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

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

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

html лагічны ілжывы

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

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

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

размяшчэнне радок | функцыя "топ"

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

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

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

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

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

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

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

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

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

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

трыгер радок "фокус пры навядзенні"

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

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

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

зрушэнне нумар | радок | функцыя 0

Зрушэнне падказкі адносна мэты.

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

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

рэзервовае размяшчэнне радок | масіў "перавярнуць" Дазваляюць вызначыць, якую пазіцыю Попер будзе выкарыстоўваць пры адключэнні. Для атрымання дадатковай інфармацыі звярніцеся да дакументацыі паводзін Попера
customClass радок | функцыя ''

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

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

мяжа радок | элемент 'scrollParent' Мяжа абмежавання перапаўнення падказкі. Прымае значэнні 'viewport', 'window', 'scrollParent'або спасылку HTMLElement (толькі JavaScript). Для атрымання дадатковай інфармацыі звярніцеся да Popper's preventOverflow дакументацыі .
дэзінфікаваць лагічны праўда Уключыце або выключыце дэзінфекцыю. Калі актывавана 'template', і 'title'параметры будуць ачышчаны. Глядзіце раздзел дэзінфікуючых сродкаў у нашай дакументацыі па JavaScript .
белы спіс аб'ект Значэнне па змаўчанні Аб'ект, які змяшчае дазволеныя атрыбуты і тэгі
дэзінфікавацьFn нуль | функцыя нуль Тут вы можаце паставіць сваю ўласную функцыю дэзінфекцыі. Гэта можа быць карысна, калі вы аддаеце перавагу выкарыстоўваць спецыяльную бібліятэку для правядзення дэзінфекцыі.
popperConfig нуль | аб'ект нуль Каб змяніць стандартную канфігурацыю Popper Bootstrap, глядзіце канфігурацыю Popper

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

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

Метады

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

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

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

$().tooltip(options)

Далучае апрацоўшчык падказкі да калекцыі элементаў.

.tooltip('show')

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

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

.tooltip('hide')

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

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

.tooltip('toggle')

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

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

.tooltip('dispose')

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

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

.tooltip('enable')

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

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

.tooltip('disable')

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

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

.tooltip('toggleEnabled')

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

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

.tooltip('update')

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

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

Падзеі

Тып падзеі Апісанне
show.bs.tooltip Гэта падзея запускаецца неадкладна пры showвыкліку метаду асобніка.
паказаны.bs.tooltip Гэта падзея запускаецца, калі падказка становіцца бачнай для карыстальніка (будзе чакаць завяршэння пераходаў CSS).
hide.bs.tooltip Гэта падзея запускаецца адразу пасля hideвыкліку метаду асобніка.
hidden.bs.tooltip Гэта падзея запускаецца, калі падказка перастае быць схаванай ад карыстальніка (будзе чакаць завяршэння пераходаў CSS).
inserted.bs.tooltip Гэта падзея запускаецца пасля show.bs.tooltipпадзеі, калі шаблон падказкі быў дададзены ў DOM.
$('#myTooltip').on('hidden.bs.tooltip', function () {
  // do something...
})