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

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

Базовый синтаксис:

tippy(target, {
  // параметры конфигурации
});

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

Основные категории параметров

Объект конфигурации условно делится на несколько логических групп:

1. Контент и отображение

  • content
  • allowHTML
  • maxWidth

2. Позиционирование

  • placement
  • offset
  • popperOptions

3. Поведение

  • trigger
  • hideOnClick
  • interactive
  • delay
  • duration

4. Внешний вид и тема

  • theme
  • animation
  • arrow

5. Жизненный цикл

  • onShow
  • onHide
  • onMount
  • onDestroy

6. Дополнительные возможности

  • followCursor
  • sticky
  • appendTo

Свойство content

Определяет содержимое тултипа.

tippy(button, {
  content: 'Текст подсказки'
});

Возможные значения:

  • строка
  • HTML-элемент
  • функция (возвращающая содержимое)

Пример с функцией:

tippy(button, {
  content(reference) {
    return `ID: ${reference.id}`;
  }
});

allowHTML

Управляет интерпретацией HTML внутри content.

tippy(button, {
  content: '<strong>Жирный текст</strong>',
  allowHTML: true
});

Если false, HTML будет экранирован.

placement

Определяет позицию тултипа относительно целевого элемента.

Возможные значения:

  • top, bottom, left, right
  • top-start, top-end и т.д.
tippy(button, {
  placement: 'right'
});

trigger

Определяет событие, вызывающее показ тултипа.

tippy(button, {
  trigger: 'mouseenter focus'
});

Возможные значения:

  • mouseenter
  • focus
  • click
  • manual

Можно комбинировать события через пробел.

delay

Задержка перед показом и скрытием.

tippy(button, {
  delay: [500, 200]
});

Формат:

  • число — одинаковая задержка
  • массив [show, hide]

duration

Длительность анимации.

tippy(button, {
  duration: [300, 250]
});

animation

Определяет тип анимации.

tippy(button, {
  animation: 'scale'
});

Другие варианты:

  • fade
  • shift-away
  • shift-toward

theme

Позволяет задать CSS-тему.

tippy(button, {
  theme: 'light'
});

Используется вместе с кастомными стилями:

.tippy-box[data-theme~='light'] {
  background-color: white;
  color: black;
}

arrow

Добавляет стрелку к тултипу.

tippy(button, {
  arrow: true
});

Можно передать HTML:

arrow: '<svg>...</svg>'

interactive

Разрешает взаимодействие с содержимым тултипа.

tippy(button, {
  interactive: true
});

Без этого тултип скрывается при наведении на него.

hideOnClick

Определяет поведение при клике.

tippy(button, {
  hideOnClick: true
});

Варианты:

  • true
  • false
  • 'toggle'

offset

Смещение тултипа относительно базовой позиции.

tippy(button, {
  offset: [0, 10]
});

Формат:

  • [skidding, distance]

appendTo

Определяет контейнер, в который будет добавлен тултип.

tippy(button, {
  appendTo: document.body
});

Возможны варианты:

  • DOM-элемент
  • функция

popperOptions

Позволяет напрямую управлять поведением Popper.js.

tippy(button, {
  popperOptions: {
    modifiers: [
      {
        name: 'preventOverflow',
        options: {
          padding: 10
        }
      }
    ]
  }
});

Используется для тонкой настройки позиционирования.

followCursor

Тултип следует за курсором.

tippy(button, {
  followCursor: true
});

Дополнительные значения:

  • 'horizontal'
  • 'vertical'
  • 'initial'

sticky

Обновляет позицию при изменении DOM.

tippy(button, {
  sticky: true
});

maxWidth

Ограничивает ширину тултипа.

tippy(button, {
  maxWidth: 250
});

Жизненный цикл: обработчики событий

Tippy.js предоставляет набор хуков:

onShow

Вызывается перед показом:

tippy(button, {
  onShow(instance) {
    console.log('Показывается');
  }
});

onHide

onHide(instance) {
  console.log('Скрывается');
}

onMount

Срабатывает после добавления в DOM:

onMount(instance) {
  console.log('Добавлен в DOM');
}

onDestroy

onDestroy(instance) {
  console.log('Уничтожен');
}

Динамическое обновление конфигурации

Экземпляр тултипа можно изменять после создания:

const instance = tippy(button, {
  content: 'Привет'
});

instance.setProps({
  content: 'Новое значение'
});

Значения по умолчанию

Каждое свойство имеет значение по умолчанию. Например:

{
  placement: 'top',
  trigger: 'mouseenter focus',
  animation: 'fade'
}

Переопределяются только необходимые параметры.

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

Часто используется объединение конфигураций:

const baseConfig = {
  animation: 'scale',
  theme: 'dark'
};

tippy(button, {
  ...baseConfig,
  content: 'Текст'
});

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

Глобальная конфигурация

Можно задать глобальные значения:

tippy.setDefaultProps({
  delay: 200,
  theme: 'light'
});

Все последующие тултипы будут использовать эти параметры.

Вложенные и сложные структуры

Некоторые свойства принимают объекты:

tippy(button, {
  delay: {
    show: 100,
    hide: 300
  }
});

или массивы:

duration: [400, 200]

Важно учитывать тип данных для каждого параметра.

Приоритет параметров

При конфликте значений применяется следующий порядок:

  1. Параметры конкретного экземпляра
  2. Глобальные настройки (setDefaultProps)
  3. Значения по умолчанию библиотеки

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

tippy(button, {
  content: 'Подсказка',
  placement: 'bottom-start',
  trigger: 'mouseenter focus',
  delay: [200, 100],
  duration: [300, 200],
  animation: 'shift-away',
  theme: 'custom',
  arrow: true,
  interactive: true,
  offset: [0, 8],
  maxWidth: 220,
  hideOnClick: false,
  followCursor: false,
  onShow(instance) {
    console.log('show');
  },
  onHide(instance) {
    console.log('hide');
  }
});

Особенности проектирования конфигурации

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

Расширение через плагины

Некоторые параметры активируются через плагины:

import { followCursor } from 'tippy.js';

tippy(button, {
  followCursor: true,
  plugins: [followCursor]
});

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

Ошибки при работе с конфигурацией

Частые проблемы:

  • неправильный тип значения (string вместо number)
  • забытый allowHTML
  • конфликт interactive и hideOnClick
  • отсутствие плагина для опции

Валидация и отладка

Tippy не выбрасывает строгих ошибок, поэтому важно:

  • проверять значения вручную
  • использовать console.log(instance.props)
  • тестировать разные сценарии

Архитектурная роль конфигурации

Объект конфигурации выступает декларативным описанием поведения тултипа. Он:

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

Грамотно структурированная конфигурация превращает Tippy.js из простой библиотеки подсказок в мощный инструмент управления интерактивными элементами интерфейса.

Оглавление