Перейти к основному содержанию Перейти к навигации по документации

Всплывающие подсказки

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

Обзор

Что нужно знать при использовании плагина всплывающей подсказки:

  • Всплывающие подсказки полагаются на стороннюю библиотеку Popper для позиционирования. Вы должны включить popper.min.js перед bootstrap.js или использовать один bootstrap.bundle.min.js, который содержит Popper.
  • Всплывающие подсказки используются по соображениям производительности, поэтому Вы должны инициализировать их самостоятельно.
  • Всплывающие подсказки с заголовками нулевой длины никогда не отображаются.
  • Укажите container: 'body', чтобы избежать проблем с рендерингом в более сложных компонентах (например, в наших группах ввода, группах кнопок и т.д.).
  • Всплывающие подсказки для скрытых элементов работать не будут.
  • Всплывающие подсказки для элементов .disabled или disabled должны запускаться для элемента оболочки.
  • При запуске от гиперссылок, охватывающих несколько строк, всплывающие подсказки будут центрированы. Используйте white-space: nowrap; на Ваших <a>, чтобы избежать такого поведения.
  • Всплывающие подсказки необходимо скрыть до того, как соответствующие элементы будут удалены из модели DOM.
  • Всплывающие подсказки могут запускаться благодаря элементу внутри теневой модели DOM.

Получил все это? Отлично, давайте посмотрим, как они работают, на нескольких примерах.

По умолчанию этот компонент использует встроенное средство очистки содержимого, которое удаляет все элементы HTML, которые не разрешены явно. Дополнительные сведения смотрите в разделе очистки в нашей документации по JavaScript.
Эффект анимации этого компонента зависит от медиазапроса prefers-reduced-motion. См. раздел с уменьшенным движением в нашей документации по специальным возможностям.

Примеры

Включить всплывающие подсказки

Как упоминалось выше, вы должны инициализировать всплывающие подсказки, прежде чем их можно будет использовать. Один из способов инициализировать все всплывающие подсказки на странице — выбрать их по их атрибуту data-bs-toggle, например:

const tooltipTriggerList = document.querySelectorAll('[data-bs-toggle="tooltip"]')
const tooltipList = [...tooltipTriggerList].map(tooltipTriggerEl => new bootstrap.Tooltip(tooltipTriggerEl))

Подсказки к ссылкам

Наведите курсор на ссылки ниже, чтобы увидеть всплывающие подсказки:

Текст-заполнитель для демонстрации некоторых встроенных ссылок с подсказками. Теперь это просто наполнитель, а не убийца. Контент размещен здесь только для того, чтобы имитировать присутствие настоящего текста. И все это только для того, чтобы дать вам представление о том, как будут выглядеть всплывающие подсказки при использовании в реальных ситуациях. Итак, надеюсь, теперь вы увидели, как эти всплывающие подсказки для ссылок могут работать на практике, после того, как вы используете их на своем сайте или проекте.

html
<p class="muted">Текст-заполнитель для демонстрации некоторых <a href="#" data-bs-toggle="tooltip" data-bs-title="подсказок по умолчанию">встроенных ссылок</a> с подсказками. Теперь это просто наполнитель, а не убийца. Контент размещен здесь только для того, чтобы имитировать присутствие <a href="#" data-bs-toggle="tooltip" data-bs-title="Другая всплывающая подсказка">настоящего текста</a>. И все это только для того, чтобы дать вам представление о том, как будут выглядеть всплывающие подсказки при использовании в реальных ситуациях. Итак, надеюсь, теперь вы увидели, как <a href="#" data-bs-toggle="tooltip" data-bs-title="Еще одна здесь тоже">эти всплывающие подсказки для ссылок</a> могут работать на практике, после того, как вы используете их на <a href="#" data-bs-toggle="tooltip" data-bs-title="Последний совет!">своем</a> сайте или проекте.</p>
Не стесняйтесь использовать title или data-bs-title в своем HTML. Когда используется title, Popper автоматически заменяет его на data-bs-title при отображении элемента.

Пользовательские всплывающие подсказки

Добавлено в версии 5.2.0

Вы можете настроить внешний вид всплывающих подсказок с помощью CSS-переменных. Мы устанавливаем пользовательский класс с data-bs-custom-class="custom-tooltip", чтобы ограничить наш пользовательский внешний вид и использовать его для переопределения локальной переменной CSS.

.custom-tooltip {
  --bs-tooltip-bg: var(--bd-violet-bg);
  --bs-tooltip-color: var(--bs-white);
}
html
<button type="button" class="btn btn-secondary"
        data-bs-toggle="tooltip" data-bs-placement="top"
        data-bs-custom-class="custom-tooltip"
        data-bs-title="This top tooltip is themed via CSS variables.">
  Пользовательская подсказка
</button>

Направления

Наведите курсор на кнопки ниже, чтобы увидеть четыре направления подсказок: вверх, вправо, внизу и влево. Направления зеркалируются при использовании Bootstrap в RTL.

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="top" data-bs-title="Подсказка вверху">
  Подсказка вверху
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="right" data-bs-title="Подсказка справа">
  Подсказка справа
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="bottom" data-bs-title="Подсказка внизу">
  Подсказка внизу
</button>
<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-placement="left" data-bs-title="Подсказка слева">
  Подсказка слева
</button>

И с добавленным пользовательским HTML:

<button type="button" class="btn btn-secondary" data-bs-toggle="tooltip" data-bs-html="true" data-bs-title="<em>Подсказка</em> <u>с</u> <b>HTML</b>">
  Всплывающая подсказка с HTML
</button>

С SVG:

CSS

Переменные

Добавлено в версии 5.2.0

Как часть развивающегося подхода Bootstrap к переменным CSS, всплывающие подсказки теперь используют локальные переменные CSS в .tooltip для расширенной настройки в реальном времени. Значения переменных CSS задаются через Sass, поэтому настройка Sass по-прежнему поддерживается.

--#{$prefix}tooltip-zindex: #{$zindex-tooltip};
--#{$prefix}tooltip-max-width: #{$tooltip-max-width};
--#{$prefix}tooltip-padding-x: #{$tooltip-padding-x};
--#{$prefix}tooltip-padding-y: #{$tooltip-padding-y};
--#{$prefix}tooltip-margin: #{$tooltip-margin};
@include rfs($tooltip-font-size, --#{$prefix}tooltip-font-size);
--#{$prefix}tooltip-color: #{$tooltip-color};
--#{$prefix}tooltip-bg: #{$tooltip-bg};
--#{$prefix}tooltip-border-radius: #{$tooltip-border-radius};
--#{$prefix}tooltip-opacity: #{$tooltip-opacity};
--#{$prefix}tooltip-arrow-width: #{$tooltip-arrow-width};
--#{$prefix}tooltip-arrow-height: #{$tooltip-arrow-height};

Sass переменные

$tooltip-font-size:                 $font-size-sm;
$tooltip-max-width:                 200px;
$tooltip-color:                     var(--#{$prefix}body-bg);
$tooltip-bg:                        var(--#{$prefix}emphasis-color);
$tooltip-border-radius:             var(--#{$prefix}border-radius);
$tooltip-opacity:                   .9;
$tooltip-padding-y:                 $spacer * .25;
$tooltip-padding-x:                 $spacer * .5;
$tooltip-margin:                    null; // TODO: remove this in v6

$tooltip-arrow-width:               .8rem;
$tooltip-arrow-height:              .4rem;
// fusv-disable
$tooltip-arrow-color:               null; // Deprecated in Bootstrap 5.2.0 for CSS variables
// fusv-enable

Использование

Плагин всплывающих подсказок генерирует контент и разметку по запросу и по умолчанию размещает всплывающие подсказки после их триггерного элемента. Запустите всплывающую подсказку через JavaScript:

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

Всплывающие подсказки автоматически пытаются изменить положение, когда родительский контейнер имеет overflow: auto или overflow: scroll, но все еще сохраняет исходное положение размещения. Установите опцию boundary (для модификатора flip с использованием опции popperConfig) для любого HTMLElement, чтобы переопределить значение по умолчанию 'clippingParents', например document.body:

const tooltip = new bootstrap.Tooltip('#example', {
  boundary: document.body // или document.querySelector('#boundary')
})

Разметка

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

Сохраняйте всплывающие подсказки доступными для пользователей клавиатуры и вспомогательных технологий, добавляя их только к элементам HTML, которые традиционно ориентированы на клавиатуру и являются интерактивными (например, ссылки или элементы управления формы). В то время как другие элементы HTML можно сделать фокусируемыми, добавив tabindex="0", это может создать раздражающие и запутанные позиции табуляции для неинтерактивных элементов для пользователей клавиатуры, и большинство вспомогательных технологий в настоящее время не объявляют всплывающие подсказки в этой ситуации. Кроме того, не полагайтесь исключительно на hover в качестве триггера для ваших всплывающих подсказок, так как это сделает их невозможными для пользователей клавиатуры.
<!-- HTML для записи -->
<a href="#" data-bs-toggle="tooltip" data-bs-title="Текст всплывающей подсказки!">Наведите на меня</a>

<!-- Generated markup by the plugin -->
<div class="tooltip bs-tooltip-auto" role="tooltip">
  <div class="tooltip-arrow"></div>
  <div class="tooltip-inner">
    Текст всплывающей подсказки!
  </div>
</div>

Отключенные элементы

Элементы с атрибутом disabled не являются интерактивными, то есть пользователи не могут сфокусироваться, навести на них курсор или щелкнуть их, чтобы вызвать всплывающую подсказку (или всплывающее окно). В качестве обходного пути Вы захотите вызвать всплывающую подсказку из оболочки <div> или <span>, в идеале сделанной с фокусировкой на клавиатуре, используя tabindex="0".

html
<span class="d-inline-block" tabindex="0" data-bs-toggle="tooltip" data-bs-title="Отключенная подсказка">
  <button class="btn btn-primary" type="button" disabled>Отключенная кнопка</button>
</span>

Опции

Поскольку параметры можно передавать через атрибуты данных или JavaScript, вы можете добавить имя параметра к data-bs-, как в data-bs-animation="{value}". Обязательно измените тип регистра имени параметра с “camelCase” на “kebab-case” при передаче параметров через атрибуты данных. Например, используйте data-bs-custom-class="beautifier" вместо data-bs-customClass="beautifier".

Начиная с Bootstrap 5.2.0, все компоненты поддерживают экспериментальный зарезервированный атрибут данных data-bs-config, который может содержать простую конфигурацию компонента в виде строки JSON. Когда элемент имеет атрибуты data-bs-config='{"delay":0, "title":123}' и data-bs-title="456", окончательное значение title будет 456, а отдельные атрибуты данных переопределяют значения, указанные в data-bs-config. Кроме того, существующие атрибуты данных могут содержать значения JSON, такие как data-bs-delay='{"show":0,"hide":150}'.

Окончательный объект конфигурации — это объединенный результат data-bs-config, data-bs- и js object, где последний заданный ключ-значение переопределяет другие.

Обратите внимание, что по соображениям безопасности параметры sanitize, sanitizeFn и allowList не могут быть предоставлены с использованием атрибутов данных.
Название Тип По умолчанию Описание
allowList object Значение по умолчанию Объект, который содержит разрешенные атрибуты и теги.
animation boolean true Применить CSS-переход затухания к всплывающей подсказке.
boundary string, element 'clippingParents' Граница ограничения переполнения всплывающей подсказки (применяется только к модификатору Popper preventOverflow). По умолчанию это 'clippingParents', и он может принимать ссылку HTMLElement (только через JavaScript). Для получения дополнительной информации обратитесь к по обнаружению переполнения Popper.
container string, element, false false Добавляет всплывающую подсказку к определенному элементу. Пример: container: 'body'. Этот параметр особенно удобен тем, что позволяет расположить всплывающую подсказку в потоке документа рядом с инициирующим элементом, что предотвратит всплывающую подсказку от инициирующего элемента во время изменения размера окна.
customClass string, function '' Добавляйте классы во всплывающую подсказку, когда она отображается. Обратите внимание, что эти классы будут добавлены в дополнение к любым классам, указанным в шаблоне. Чтобы добавить несколько классов, разделите их пробелами: 'class-1 class-2'. Вы также можете передать функцию, которая должна возвращать одну строку, содержащую дополнительные имена классов.
delay number, object 0 Задержка отображения и скрытия всплывающей подсказки (мс) — не относится к ручному типу триггера. Если указано число, задержка применяется как для скрытия, так и для показа. Структура объекта: delay: { "show": 500, "hide": 100 }.
fallbackPlacements array ['top', 'right', 'bottom', 'left'] Определите резервные места размещения, предоставив список мест размещения в виде массива (в порядке предпочтения). Для получения дополнительной информации обратитесь к документации поведения Popper.
html boolean false Разрешить HTML в подсказке. Если true, теги HTML в title всплывающей подсказки будут отображаться во всплывающей подсказке. Если false, свойство innerText будет использоваться для вставки содержимого в DOM. Используйте текст, если вы беспокоитесь о XSS-атаках.
offset array, string, function [0, 0] Смещение всплывающей подсказки относительно ее цели. Вы можете передать строку в атрибутах данных со значениями, разделенными запятыми, например: data-bs-offset="10,20". Когда функция используется для определения смещения, она вызывается с объектом, содержащим размещение поппера, ссылку и прямоугольники поппера в качестве первого аргумента. Узел триггерного элемента DOM передается в качестве второго аргумента. Функция должна вернуть массив с двумя числами: skidding, distance. Для получения дополнительной информации обратитесь к документации по смещению Popper.
placement string, function 'top' Как расположить всплывающую подсказку: авто, сверху, снизу, слева, справа. Когда указано auto, подсказка будет динамически переориентироваться. Когда функция используется для определения размещения, она вызывается с узлом DOM всплывающей подсказки в качестве первого аргумента и узлом DOM триггерного элемента в качестве второго. Контекст this устанавливается на экземпляр всплывающей подсказки.
popperConfig null, object, function null Чтобы изменить конфигурацию Popper по умолчанию в Bootstrap, смотрите Конфигурация Popper. Когда функция используется для создания конфигурации Popper, она вызывается с объектом, который содержит конфигурацию Bootstrap по умолчанию Popper. Это поможет вам использовать и объединить настройки по умолчанию с вашей собственной конфигурацией. Функция должна возвращать объект конфигурации для Popper.
sanitize boolean true Включите или отключите очистку. Если активированы параметры 'template', 'content' и 'title', они будут очищены.
sanitizeFn null, function null Здесь вы можете указать свою собственную функцию дезинфекции. Это может быть полезно, если вы предпочитаете использовать выделенную библиотеку для выполнения санитарной обработки.
selector string, false false Если предоставлен селектор, объекты всплывающей подсказки будут делегированы указанным целям. На практике это также используется для применения всплывающих подсказок к динамически добавляемым элементам DOM (поддержка jQuery.on). Смотрите эту проблему и информативный пример. Примечание: Атрибут title нельзя использовать в качестве селектора.
template string '<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 string, element, function '' Название всплывающей подсказки. Если задана функция, она будет вызываться со ссылкой this, установленной на элемент, к которому прикреплено всплывающее окно.
trigger string 'hover focus' Как срабатывает всплывающая подсказка: щелчок, наведение, фокус, вручную. Вы можете передать несколько триггеров; разделяйте их пробелом. 'manual' указывает, что всплывающая подсказка будет вызываться программно с помощью методов .tooltip('show'), .tooltip('hide') и .tooltip('toggle'); это значение нельзя комбинировать ни с каким другим триггером. 'hover' сам по себе приведет к всплывающим подсказкам, которые нельзя активировать с помощью клавиатуры, и их следует использовать только в том случае, если существуют альтернативные методы передачи той же информации для пользователей клавиатуры.

Атрибуты данных для отдельных всплывающих подсказок

В качестве альтернативы параметры для отдельных всплывающих подсказок можно указать с помощью атрибутов данных, как описано выше.

Использование функции с popperConfig

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

Методы

Все методы API являются асинхронными и запускают переход. Они возвращаются вызывающей стороне сразу после начала перехода, но до его завершения. Кроме того, вызов метода переходного компонента будет игнорироваться. Подробнее читайте в нашей документации по JavaScript.
Метод Описание
disable Удаляет возможность отображения всплывающей подсказки элемента. Всплывающая подсказка будет отображаться только в том случае, если она снова включена.
dispose Скрывает и уничтожает всплывающую подсказку элемента (удаляет сохраненные данные в элементе DOM). Всплывающие подсказки, использующие делегирование (которые создаются с помощью опции selector) не могут быть уничтожены по отдельности в элементах-триггерах-потомках.
enable Позволяет отображать всплывающую подсказку элемента. Подсказки включены по умолчанию.
getInstance Статический метод, позволяющий получить экземпляр всплывающей подсказки, связанный с элементом DOM, или создать новый, если он не был инициализирован.
getOrCreateInstance Статический метод, позволяющий получить экземпляр всплывающей подсказки, связанный с элементом DOM, или создать новый, если он не был инициализирован.
hide Скрывает всплывающую подсказку элемента. Возвращает вызывающему объекту до того, как всплывающая подсказка будет фактически скрыта (т. е. до того, как произойдет событие hidden.bs.tooltip). Это считается «ручным» срабатыванием всплывающей подсказки.
setContent Дает возможность изменить содержимое всплывающей подсказки после ее инициализации.
show Отображает всплывающую подсказку элемента. Возвращает вызывающему объекту до того, как всплывающая подсказка действительно будет показана (т. е. до того, как произойдет событие shown.bs.tooltip). Это считается «ручным» срабатыванием всплывающей подсказки. Подсказки с заголовками нулевой длины никогда не отображаются.
toggle Переключает всплывающую подсказку элемента. Возвращает вызывающему объекту до того, как всплывающая подсказка действительно будет показана или скрыта (т. е. до того, как произойдет событие shown.bs.tooltip или hidden.bs.tooltip). Это считается «ручным» срабатыванием всплывающей подсказки.
toggleEnabled Переключает возможность отображения или скрытия всплывающей подсказки элемента.
update Обновляет положение всплывающей подсказки элемента.
const tooltip = bootstrap.Tooltip.getInstance('#example') // Возвращает экземпляр всплывающей подсказки Bootstrap

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })
Метод setContent принимает аргумент object, где каждый ключ свойства является допустимым селектором string в шаблоне всплывающей подсказки, а каждое связанное значение свойства может быть string | element | function | null

События

Событие Описание
hide.bs.tooltip Это событие запускается сразу после вызова метода экземпляра hide.
hidden.bs.tooltip Это событие запускается, когда всплывающая подсказка перестает быть скрытым от пользователя (будет ждать завершения переходов CSS).
inserted.bs.tooltip Это событие запускается после события show.bs.tooltip, когда шаблон всплывающей подсказки был добавлен в DOM.
show.bs.tooltip Это событие срабатывает немедленно при вызове метода экземпляра show.
shown.bs.tooltip Это событие запускается, когда всплывающая подсказка становится видимой для пользователя (будет ждать завершения переходов CSS).
const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

myTooltipEl.addEventListener('hidden.bs.tooltip', () => {
  // делайте что-нибудь...
})

tooltip.hide()