Breaking changes

Библиотека Tippy.js претерпела ряд значительных изменений, которые могут сломать старый код при обновлении. Разбор этих breaking changes позволяет правильно адаптировать приложения, использующие тултипы, и избежать неожиданных ошибок в работе интерфейса.

1. Удаление поддержки tippy() без аргументов

Ранее можно было вызывать tippy() без указания DOM-элемента, а тултип применялся к document.body или к элементам, определяемым позже. В новых версиях это больше не поддерживается:

// Старый синтаксис
tippy();

// Новый синтаксис требует явного селектора или элемента
tippy('#myButton', {
  content: 'Привет!',
});

Последствия: любой вызов tippy() без аргументов теперь приводит к ошибке. Необходимо убедиться, что элемент существует в DOM перед инициализацией.

2. Изменение API для popperOptions

Ранее можно было напрямую передавать настройки Popper.js через popperOptions:

tippy('#button', {
  popperOptions: {
    modifiers: [{ name: 'offset', options: { offset: [0, 20] } }]
  }
});

В новых версиях структура модификаторов изменилась, а старые названия опций могут быть не распознаны. Новая форма соответствует Popper 2 API:

tippy('#button', {
  popperOptions: {
    modifiers: [
      {
        name: 'offset',
        options: { offset: [0, 20] }
      }
    ]
  }
});

Ключевой момент: необходимо проверять документацию Popper.js для актуальной структуры модификаторов при обновлении Tippy.js.

3. Исключение встроенных анимаций

Tippy.js ранее включал анимации 'shift', 'scale', 'fade', 'perspective'. В последних версиях некоторые из них были удалены или переименованы. Теперь поддерживаются только:

  • 'fade'
  • 'scale'
  • 'shift-away'
  • 'shift-toward'
// Было
tippy('#btn', { animation: 'perspective' }); // больше не работает

// Нужно
tippy('#btn', { animation: 'shift-away' });

Следствие: при обновлении проекта анимации могут перестать работать, если не скорректировать конфигурацию.

4. Новая обработка контента

Ранее content мог принимать функцию, возвращающую строку или элемент, либо напрямую DOM-элемент. В новых версиях Tippy.js требуется, чтобы функция возвращала обязательно строку или Node. Любые нестандартные объекты вызывают ошибки.

// Старый вариант
tippy('#btn', {
  content: () => document.querySelector('#tooltipContent')
});

// Новый вариант
tippy('#btn', {
  content: () => document.querySelector('#tooltipContent').cloneNode(true)
});

Особенность: клонирование необходимо для избежания конфликтов с уже вставленным элементом в DOM.

5. Изменение событийных хуков

Хуки жизненного цикла, такие как onShow, onHide, onMount, теперь требуют использования современного синтаксиса с объектом instance и событиями:

// Старый синтаксис
tippy('#btn', {
  onShow() { console.log('Показан'); }
});

// Новый синтаксис
tippy('#btn', {
  onShow(instance) {
    console.log('Показан', instance);
  }
});

Ключевой момент: обработчики теперь получают аргумент instance, который предоставляет доступ к текущему тултипу, его элементу и методам управления.

6. Удаление trigger: 'manual' в пользу instance.show() / instance.hide()

Ранее можно было создавать тултипы с триггером 'manual', и управлять их состоянием вручную через события. В новых версиях использование 'manual' устарело:

// Старый вариант
tippy('#btn', { trigger: 'manual' });

// Новый вариант
const tip = tippy('#btn', { trigger: 'mouseenter' })[0];
tip.show(); // вручную показываем
tip.hide(); // вручную скрываем

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

7. Упрощение импорта

Ранее Tippy.js требовал отдельного импорта CSS и JS через разные файлы. Теперь рекомендуется использовать модульный подход:

import tippy from 'tippy.js';
import 'tippy.js/dist/tippy.css';

Преимущество: упрощается интеграция с современными сборщиками вроде Webpack или Vite. Старые глобальные вызовы window.tippy работают не во всех случаях.

8. Работа с порталами (appendTo)

Опция appendTo теперь принимает либо CSS-селектор, либо функцию, возвращающую DOM-элемент. Старые строки вроде 'parent' или 'body' могут быть несовместимы:

// Новый вариант
tippy('#btn', {
  appendTo: () => document.body
});

Ключевой момент: это изменение важно при работе с модальными окнами и динамически создаваемыми контейнерами.

9. Изменения в interactive тултипах

Если тултип был интерактивным (interactive: true), то управление фокусом теперь реализовано через модификатор Popper.js preventOverflow и новый API для delay:

tippy('#btn', {
  interactive: true,
  delay: [100, 300] // задержка показа и скрытия
});

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

Эти изменения являются наиболее критичными при обновлении Tippy.js. Они требуют проверки всех существующих вызовов tippy(), корректировки параметров и обновления обработчиков событий. Игнорирование breaking changes может привести к ошибкам отображения тултипов, некорректной работе анимаций и нарушению взаимодействия с элементами интерфейса.

Оглавление