Типизация конфигурации

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

Структура объекта конфигурации

Объект конфигурации Tippy.js представлен как набор ключей с определёнными типами значений:

tippy(targets, {
  content: 'Пример подсказки',
  placement: 'top',
  trigger: 'mouseenter focus',
  animation: 'fade',
  delay: [100, 200],
  interactive: true,
});

Ключевые параметры и их типы:

  1. content — string | HTMLElement | (() => string | HTMLElement) Содержимое тултипа может быть статическим текстом, DOM-элементом или функцией, возвращающей одно из этих значений. Функция полезна для динамически обновляемого контента.

  2. placement — string Возможные значения: 'top' | 'bottom' | 'left' | 'right' | 'auto' и их варианты с -start или -end. Определяет расположение тултипа относительно целевого элемента.

  3. trigger — string Определяет события, которые активируют тултип: 'mouseenter', 'focus', 'click', 'manual'. Может комбинироваться через пробел.

  4. animation — string | false Название анимации или false, если анимацию нужно отключить. Стандартные варианты: 'fade', 'scale', 'shift-away'.

  5. delay — number | [number, number] Задержка перед показом и скрытием тултипа. Если передан массив, первый элемент — задержка показа, второй — скрытия.

  6. interactive — boolean Позволяет взаимодействовать с содержимым тултипа (например, клики внутри тултипа не будут скрывать его).

Типизация функций обратного вызова

Tippy.js поддерживает несколько типов функций обратного вызова (callbacks) с конкретными аргументами:

  • onShow(instance) — вызывается перед показом тултипа. Возвращаемое значение boolean может блокировать показ.
  • onHide(instance) — вызывается перед скрытием. Возвращаемое значение boolean может блокировать скрытие.
  • onMount(instance) — вызывается после вставки тултипа в DOM.
  • onTrigger(instance, event) — вызывается при активации события.
  • onUntrigger(instance, event) — вызывается при деактивации события.

Пример строгой типизации в TypeScript:

import tippy, { Instance, Props } from 'tippy.js';

const tooltip = tippy('#button', {
  content: 'Нажмите сюда',
  onShow(instance: Instance<Props>) {
    console.log('Тултип будет показан');
    return true;
  },
  onHide(instance: Instance<Props>) {
    console.log('Тултип будет скрыт');
    return true;
  },
});

Типизация для динамических опций

Некоторые свойства объекта конфигурации могут принимать функции для динамической генерации значений:

  • content: () => string | HTMLElement
  • placement: (reference: Element, tooltip: HTMLElement) => string
  • delay: (instance: Instance<Props>, event: Event) => number | [number, number]

Это позволяет строить тултипы, которые адаптируются к контексту DOM или состоянию приложения.

Пример использования динамического placement:

tippy('#dynamic', {
  content: 'Динамическое размещение',
  placement(reference, tooltip) {
    return reference.getBoundingClientRect().top < 100 ? 'bottom' : 'top';
  },
});

Наследование и частичная типизация

Tippy.js поддерживает возможность переопределять только часть конфигурации через метод setProps:

tooltip.setProps({
  content: 'Обновлённый текст',
  animation: 'scale',
});

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

Пользовательские типы и расширяемость

Для сложных проектов можно расширять типы Props с добавлением собственных полей. Это позволяет интегрировать тултипы с внутренними состояниями приложения, сохраняя строгую проверку типов:

interface CustomProps extends Props {
  userRole?: string;
}

const tooltip = tippy<HTMLElement, CustomProps>('#custom', {
  content: 'Для администратора',
  userRole: 'admin',
});

Такой подход улучшает читаемость кода и предотвращает ошибки при передаче некорректных данных в конфигурацию.

Вывод

Корректная типизация конфигурации Tippy.js обеспечивает:

  • строгую проверку передаваемых значений;
  • безопасность при работе с динамическими опциями;
  • удобство масштабирования и переиспользования тултипов;
  • интеграцию с TypeScript и другими системами типов.

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

Оглавление