Подключение плагинов

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

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

Структура плагина

Плагин — это объект с обязательным свойством name и методом fn, который вызывается при инициализации тултипа:

const myPlugin = {
  name: 'myPlugin',
  defaultValue: true,
  fn(instance) {
    return {
      onShow() {
        console.log('Tooltip shown');
      }
    };
  }
};

Ключевые элементы:

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

Подключение встроенных плагинов

Некоторые возможности в Tippy.js реализованы через встроенные плагины, которые необходимо импортировать отдельно.

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

import tippy, { animateFill } from 'tippy.js';
import 'tippy.js/dist/backdrop.css';
import 'tippy.js/animations/shift-away.css';

tippy('.btn', {
  content: 'Tooltip',
  animateFill: true,
  plugins: [animateFill],
});

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

  • Плагин передаётся через массив plugins
  • Необходимо включать соответствующие CSS-файлы
  • Без подключения плагина опция не будет работать

Подключение нескольких плагинов

Можно одновременно использовать несколько плагинов:

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

tippy('.element', {
  content: 'Комбинированный тултип',
  animateFill: true,
  followCursor: true,
  plugins: [animateFill, followCursor],
});

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

Глобальное подключение плагинов

Чтобы не указывать плагины при каждом вызове tippy, используется глобальная конфигурация:

tippy.setDefaultProps({
  plugins: [animateFill],
});

После этого все тултипы автоматически получают подключённый плагин.

Работа с пользовательскими опциями плагина

Плагин может добавлять собственные настройки, доступные в конфигурации:

const colorPlugin = {
  name: 'colorPlugin',
  defaultValue: 'blue',
  fn(instance) {
    return {
      onCreate() {
        instance.popper.style.backgroundColor = instance.props.colorPlugin;
      }
    };
  }
};

tippy('.box', {
  content: 'Цветной тултип',
  colorPlugin: 'red',
  plugins: [colorPlugin],
});

Важно:

  • имя опции совпадает с name плагина
  • значение доступно через instance.props

Жизненный цикл и хуки

Плагины могут вмешиваться в различные этапы работы тултипа:

Основные хуки:

  • onCreate — при создании экземпляра
  • onShow — перед показом
  • onMount — после добавления в DOM
  • onHide — перед скрытием
  • onDestroy — при удалении

Пример:

const logPlugin = {
  name: 'logPlugin',
  fn() {
    return {
      onShow() {
        console.log('Показ тултипа');
      },
      onHide() {
        console.log('Скрытие тултипа');
      }
    };
  }
};

Условное подключение плагинов

Плагины можно добавлять динамически в зависимости от условий:

const plugins = [];

if (window.innerWidth > 768) {
  plugins.push(followCursor);
}

tippy('.adaptive', {
  content: 'Адаптивный тултип',
  plugins,
});

Такой подход полезен для оптимизации поведения на разных устройствах.

Ленивое подключение (lazy loading)

При работе с большими приложениями плагины можно загружать по требованию:

async function initTooltip() {
  const { followCursor } = await import('tippy.js');

  tippy('.lazy', {
    content: 'Ленивая загрузка',
    followCursor: true,
    plugins: [followCursor],
  });
}

Это уменьшает первоначальный размер бандла.

Ограничения и особенности

  • Плагин не может напрямую изменять DOM вне контекста тултипа без явного доступа
  • Необходимо следить за конфликтами имён
  • Избыточное количество плагинов может влиять на производительность
  • CSS-зависимости нужно подключать вручную

Практика комбинирования плагинов

Часто используются комбинации:

  • animateFill + inertia — плавные анимации
  • followCursor + delay — интерактивные подсказки
  • пользовательские плагины + встроенные — расширение логики
tippy('.combo', {
  content: 'Продвинутый тултип',
  inertia: true,
  followCursor: 'initial',
  plugins: [followCursor],
});

Отладка плагинов

Для анализа работы плагина удобно:

  • логировать instance
  • проверять instance.props
  • использовать хуки для отслеживания состояния
fn(instance) {
  console.log(instance);
}

Расширение через плагины как основной подход

В Tippy.js плагины являются предпочтительным способом добавления функциональности. Вместо изменения ядра или создания обёрток, логика изолируется в независимых модулях, что делает код:

  • модульным
  • переиспользуемым
  • легко тестируемым

Такая архитектура позволяет строить сложные интерфейсы с минимальными зависимостями и высокой гибкостью настройки.

Оглавление