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

Обзор

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

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

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

Примеры

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

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

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

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

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

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

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

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

.custom-tooltip {
  --bs-tooltip-bg: var(--bd-violet-bg);
  --bs-tooltip-color: var(--bs-white);
}

<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

Переменные

Как часть развивающегося подхода 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)

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

Разметка

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

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

<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, где последний заданный ключ-значение переопределяет другие.

4 459 / 5 000 | allowList | object | Значение по умолчанию | Объект, содержащий разрешенные атрибуты и теги. | | animation | boolean | true | Применить CSS-переход с затуханием к подсказке. | | boundary | string, element | 'clippingParents' | Граница ограничения переполнения подсказки (применяется только к модификатору Popper preventOverflow). По умолчанию это 'clippingParents', и он может принимать ссылку HTMLElement (только через JavaScript). Для получения дополнительной информации см. документацию Popper’s. | | 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 (https://popper.js.org/docs/v2/modifiers/flip/#fallbackplacements). | | html | boolean | false | Разрешить HTML во всплывающей подсказке. Если true, HTML-теги в title всплывающей подсказки будут отображаться во всплывающей подсказке. Если false, свойство innerText будет использоваться для вставки содержимого в DOM. Используйте text, если вы беспокоитесь об атаках XSS. | | offset | array, string, function | [0, 6] | Смещение подсказки относительно ее цели. Вы можете передать строку в атрибутах данных со значениями, разделенными запятыми, например: data-bs-offset="10,20". Когда функция используется для определения смещения, она вызывается с объектом, содержащим размещение popper, ссылку и прямоугольники popper в качестве первого аргумента. Узел DOM-элемента триггера передается в качестве второго аргумента. Функция должна возвращать массив с двумя числами: skidding, distance. Для получения дополнительной информации см. offset docs Popper. | | placement | string, function | 'top' | Как расположить подсказку: авто, сверху, снизу, слева, справа. Если указано auto, подсказка будет динамически переориентирована. Когда функция используется для определения размещения, она вызывается с узлом DOM подсказки в качестве первого аргумента и узлом DOM элемента-триггера в качестве второго. Контекст this устанавливается на экземпляр подсказки. | | popperConfig | null, object, function | null | Чтобы изменить конфигурацию Popper по умолчанию Bootstrap, см. Конфигурация Popper. Когда функция используется для создания конфигурации Popper, она вызывается с объектом, который содержит конфигурацию Popper по умолчанию Bootstrap. Это помогает вам использовать и объединять конфигурацию по умолчанию с вашей собственной. Функция должна возвращать объект конфигурации для 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
  }
})

Методы

const tooltip = bootstrap.Tooltip.getInstance('#example') // Возвращает экземпляр всплывающей подсказки Bootstrap

// setContent example
tooltip.setContent({ '.tooltip-inner': 'another title' })

События

const myTooltipEl = document.getElementById('myTooltip')
const tooltip = bootstrap.Tooltip.getOrCreateInstance(myTooltipEl)

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

tooltip.hide()