Встроенные плагины

Система плагинов в Tippy.js позволяет расширять поведение тултипов без усложнения базового API. Плагины подключаются опционально и активируются только при необходимости, что снижает общий размер бандла и повышает гибкость конфигурации.

Каждый плагин представляет собой объект с определённой структурой:

  • name — уникальное имя плагина
  • defaultValue — значение по умолчанию для соответствующей опции
  • fn(instance) — функция инициализации, получающая экземпляр Tippy

Внутри fn можно подписываться на жизненный цикл тултипа, изменять поведение, добавлять обработчики событий.

Пример подключения плагинов:

import tippy, {followCursor, sticky} from 'tippy.js';

tippy('.btn', {
  followCursor: true,
  sticky: true,
  plugins: [followCursor, sticky],
});

Без добавления плагина в массив plugins соответствующая опция работать не будет.

Плагин followCursor

Позволяет тултипу следовать за курсором мыши вместо привязки к элементу.

Ключевые особенности:

  • динамическое позиционирование
  • поддержка различных режимов поведения
  • интеграция с Popper.js

Варианты значений:

  • true — тултип полностью следует за курсором
  • "horizontal" — движение только по горизонтали
  • "vertical" — движение только по вертикали
  • "initial" — позиция фиксируется при первом появлении

Пример:

tippy('.item', {
  content: 'Подсказка',
  followCursor: 'horizontal',
  plugins: [followCursor],
});

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

Плагин sticky

Обеспечивает «прилипание» тултипа к элементу при изменении его размеров или позиции.

Назначение:

  • корректное позиционирование при анимациях
  • поддержка динамически изменяемых DOM-элементов

Значения:

  • true — обновление позиции при любом изменении
  • "reference" — отслеживание только элемента-источника
  • "popper" — отслеживание самого тултипа

Пример:

tippy('.dynamic', {
  content: 'Динамический элемент',
  sticky: true,
  plugins: [sticky],
});

Плагин использует requestAnimationFrame для постоянной проверки изменений, что делает его ресурсоёмким.

Плагин animateFill

Добавляет анимацию заливки фона тултипа.

Особенности:

  • визуально плавное появление
  • требует дополнительного CSS
  • работает только с определёнными темами

Пример:

import 'tippy.js/dist/backdrop.css';
import 'tippy.js/animations/shift-away.css';

tippy('.btn', {
  content: 'Анимация',
  animateFill: true,
  plugins: [animateFill],
});

Важно подключение соответствующих стилей, иначе эффект не будет виден.

Плагин inlinePositioning

Обеспечивает корректное позиционирование тултипов для inline-элементов, которые могут переноситься на новую строку.

Проблема, которую решает: обычный тултип позиционируется относительно всей bounding box области, что может приводить к некорректному отображению при переносе текста.

Пример:

tippy('.inline-text', {
  content: 'Подсказка',
  inlinePositioning: true,
  plugins: [inlinePositioning],
});

Плагин анализирует положение курсора и выбирает наиболее подходящий сегмент текста.

Плагин followCursor + inlinePositioning

Комбинация этих плагинов часто используется для интерактивных текстов:

tippy('.text', {
  content: 'Интерактив',
  followCursor: true,
  inlinePositioning: true,
  plugins: [followCursor, inlinePositioning],
});

Позволяет добиться точного позиционирования даже в сложных текстовых блоках.

Плагин delegate

Используется для делегирования тултипов, когда элементы создаются динамически.

Преимущества:

  • уменьшение количества обработчиков
  • поддержка динамического DOM
  • высокая производительность

Пример:

import {delegate} from 'tippy.js';

delegate('body', {
  target: '.dynamic-item',
  content: 'Делегированный тултип',
});

Тултип будет применяться ко всем элементам .dynamic-item, включая добавленные позже.

Плагин singleton

Позволяет использовать один экземпляр тултипа для нескольких элементов.

Назначение:

  • экономия ресурсов
  • плавные переходы между элементами

Пример:

import {createSingleton} from 'tippy.js';

const instances = tippy('.items', {
  content: 'Элемент',
});

createSingleton(instances, {
  delay: 500,
});

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

Плагин hideOnEsc

Добавляет возможность закрытия тултипа по нажатию клавиши Escape.

tippy('.esc', {
  content: 'ESC для закрытия',
  hideOnClick: true,
});

Хотя это поведение часто встроено, плагин может использоваться для расширенного контроля.

Плагин lifecycle hooks

Некоторые плагины используют хуки жизненного цикла:

  • onCreate
  • onShow
  • onHide
  • onDestroy

Пример внутри плагина:

const myPlugin = {
  name: 'custom',
  defaultValue: true,
  fn(instance) {
    return {
      onShow() {
        console.log('Показ');
      },
    };
  },
};

Это позволяет внедрять дополнительную логику без изменения основного кода.

Комбинирование плагинов

Плагины могут работать совместно, но важно учитывать:

  • порядок подключения
  • возможные конфликты
  • влияние на производительность

Пример комплексной конфигурации:

tippy('.complex', {
  content: 'Комплексный тултип',
  followCursor: true,
  sticky: true,
  inlinePositioning: true,
  plugins: [followCursor, sticky, inlinePositioning],
});

Каждый подключённый плагин добавляет обработчики и вычисления, что требует балансировки между функциональностью и производительностью.

Оптимизация использования плагинов

  • подключение только необходимых плагинов
  • избегание sticky и followCursor на большом количестве элементов
  • использование делегирования вместо множества экземпляров
  • минимизация перерисовок

Грамотное использование встроенных плагинов позволяет создавать сложные интерфейсы с минимальными затратами кода, сохраняя при этом высокую производительность и читаемость проекта.

Оглавление