Подсказки
Документация и примери за добавяне на персонализирани подсказки за 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 в сянка.
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=""
. Уверете се, че сте променили типа case на името на опцията от camelCase на kebab-case, когато предавате опциите чрез атрибути на данни. Например, вместо да използвате data-bs-customClass="beautifier"
, използвайте data-bs-custom-class="beautifier"
.
sanitize
,
sanitizeFn
, и
allowList
не могат да бъдат предоставени с помощта на атрибути на данни.
Име | Тип | По подразбиране | Описание |
---|---|---|---|
animation |
булево | true |
Приложете CSS избледняващ преход към подсказката |
container |
низ | елемент | невярно | false |
Добавя подсказката към конкретен елемент. Пример: |
delay |
номер | обект | 0 |
Забавяне на показването и скриването на подсказката (ms) - не се отнася за тип ръчно задействане Ако е предоставен номер, забавянето се прилага и за скриване/показване Структурата на обекта е: |
html |
булево | false |
Разрешете HTML в подсказката. Ако е вярно, HTML таговете в подсказката Използвайте текст, ако се притеснявате от XSS атаки. |
placement |
низ | функция | 'top' |
Как да позиционирате подсказката - автоматично | отгоре | дъно | наляво | точно. Когато функция се използва за определяне на разположението, тя се извиква с подсказката DOM възел като първи аргумент и задействащия елемент DOM възел като втори. Контекстът |
selector |
низ | невярно | false |
Ако е предоставен селектор, обектите с подсказки ще бъдат делегирани на посочените цели. На практика това се използва и за прилагане на подсказки към динамично добавени DOM елементи ( jQuery.on поддръжка). Вижте това и един информативен пример . |
template |
низ | '<div class="tooltip" role="tooltip"><div class="tooltip-arrow"></div><div class="tooltip-inner"></div></div>' |
Основен HTML, който да се използва при създаване на подсказка. Подсказките
Най-външният обвиващ елемент трябва да има |
title |
низ | елемент | функция | '' |
Стойност на заглавието по подразбиране, ако Ако е дадена функция, тя ще бъде извикана с |
trigger |
низ | 'hover focus' |
Как се задейства подсказка - щракнете върху | кръжи | фокус | ръководство. Можете да подадете няколко тригера; отделете ги с интервал.
|
fallbackPlacements |
масив | ['top', 'right', 'bottom', 'left'] |
Дефинирайте резервни разположения, като предоставите списък с разположения в масив (по ред на предпочитанията). За повече информация вижте документите за поведение на Popper |
boundary |
низ | елемент | 'clippingParents' |
Граница на ограничението за препълване на подсказката (отнася се само за модификатора на PrevenOverflow на Popper). По подразбиране той е 'clippingParents' и може да приеме препратка към HTMLElement (само чрез JavaScript). За повече информация вижте документите на Popper's detectOverflow . |
customClass |
низ | функция | '' |
Добавете класове към подсказката, когато се покаже. Имайте предвид, че тези класове ще бъдат добавени в допълнение към всички класове, посочени в шаблона. За да добавите няколко класа, разделете ги с интервали: Можете също така да подадете функция, която трябва да върне единичен низ, съдържащ допълнителни имена на класове. |
sanitize |
булево | true |
Активирайте или деактивирайте санирането. Ако е активиран 'template' , и 'title' опциите ще бъдат дезинфекцирани. Вижте раздела за дезинфектанти в нашата JavaScript документация . |
allowList |
обект | Стойност по подразбиране | Обект, който съдържа разрешени атрибути и тагове |
sanitizeFn |
нула | функция | null |
Тук можете да предоставите своя собствена функция за дезинфекция. Това може да бъде полезно, ако предпочитате да използвате специална библиотека за извършване на дезинфекция. |
offset |
масив | низ | функция | [0, 0] |
Отместване на подсказката спрямо нейната цел. Можете да подадете низ в атрибути на данни със стойности, разделени със запетая, като: Когато функция се използва за определяне на отместването, тя се извиква с обект, съдържащ разположението на popper, препратката и popper rects като първи аргумент. Задействащият елемент DOM възел се предава като втори аргумент. Функцията трябва да върне масив с две числа: . За повече информация вижте офсетните документи на Popper . |
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 методи са асинхронни и стартират преход . Те се връщат при повикващия веднага щом преходът започне, но преди да приключи . В допълнение, извикване на метод на преходен компонент ще бъде игнорирано .
шоу
Разкрива подсказка на елемент. Връща се към повикващия, преди действително да се покаже подсказката (т.е. преди да 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()
toggleEnabled
Превключва възможността подсказката на даден елемент да бъде показана или скрита.
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()