Преминете към основното съдържание Преминете към навигацията с документи
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="". Уверете се, че сте променили типа case на името на опцията от camelCase на kebab-case, когато предавате опциите чрез атрибути на данни. Например, вместо да използвате data-bs-customClass="beautifier", използвайте data-bs-custom-class="beautifier".

Обърнете внимание, че от съображения за сигурност опциите sanitize, sanitizeFn, и allowListне могат да бъдат предоставени с помощта на атрибути на данни.
Име Тип По подразбиране Описание
animation булево true Приложете CSS избледняващ преход към подсказката
container низ | елемент | невярно false

Добавя подсказката към конкретен елемент. Пример: container: 'body'. Тази опция е особено полезна, тъй като ви позволява да позиционирате подсказката в потока на документа близо до задействащия елемент - което ще попречи на подсказката да изплува от задействащия елемент по време на преоразмеряване на прозореца.

delay номер | обект 0

Забавяне на показването и скриването на подсказката (ms) - не се отнася за тип ръчно задействане

Ако е предоставен номер, забавянето се прилага и за скриване/показване

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

html булево false

Разрешете HTML в подсказката.

Ако е вярно, HTML таговете в подсказката titleще бъдат изобразени в подсказката. Ако е невярно, 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'] Дефинирайте резервни разположения, като предоставите списък с разположения в масив (по ред на предпочитанията). За повече информация вижте документите за поведение на Popper
boundary низ | елемент 'clippingParents' Граница на ограничението за препълване на подсказката (отнася се само за модификатора на PrevenOverflow на Popper). По подразбиране той е '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"

Когато функция се използва за определяне на отместването, тя се извиква с обект, съдържащ разположението на popper, препратката и popper rects като първи аргумент. Задействащият елемент DOM възел се предава като втори аргумент. Функцията трябва да върне масив с две числа: .[skidding, distance]

За повече информация вижте офсетните документи на 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 методи са асинхронни и стартират преход . Те се връщат при повикващия веднага щом преходът започне, но преди да приключи . В допълнение, извикване на метод на преходен компонент ще бъде игнорирано .

Вижте нашата 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()

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