Метод add и приоритеты обработчиков

В библиотеке PixiJS система событий построена вокруг интерактивных объектов, наследующихся от PIXI.InteractiveTarget, таких как Sprite, Container или Graphics. Одним из центральных инструментов для работы с событиями является метод add, позволяющий регистрировать обработчики событий.

Основы метода add

Метод add используется для привязки функции-обработчика к конкретному событию объекта. Сигнатура метода выглядит следующим образом:

interactiveObject.add(eventType, handler, options);
  • eventType — строка, указывающая тип события ("pointerdown", "pointerup", "pointerover", "pointerout", "click" и т.д.).
  • handler — функция, которая будет вызвана при возникновении события.
  • options — необязательный объект с настройками привязки обработчика.

Пример привязки простого обработчика:

sprite.add('pointerdown', (event) => {
    console.log('Sprite был нажат');
});

В данном случае sprite становится интерактивным, если ранее не был установлен флаг interactive = true. Если это не сделать, событие не сработает:

sprite.interactive = true;

Параметры и объект options

Объект options расширяет возможности метода add. Наиболее значимые поля:

  • priority — числовой приоритет обработчика. Чем выше значение, тем раньше сработает обработчик при одном событии.
  • once — если true, обработчик автоматически удаляется после первого вызова.
  • capture — включает фазу захвата события (аналогично DOM).

Пример использования:

sprite.add('pointerdown', handleClick, { priority: 10, once: true });

В этом примере обработчик handleClick сработает первым среди всех обработчиков события pointerdown на этом объекте и будет вызван только один раз.

Приоритеты обработчиков

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

  1. Обработчики с большим числом приоритета вызываются раньше.
  2. При равных приоритетах обработчики срабатывают в порядке их добавления.
  3. Приоритеты можно использовать для решения конфликтов между обработчиками на одном объекте или в иерархии контейнеров.

Пример с несколькими обработчиками:

sprite.add('pointerdown', () => console.log('Обработчик 1'), { priority: 5 });
sprite.add('pointerdown', () => console.log('Обработчик 2'), { priority: 10 });
sprite.add('pointerdown', () => console.log('Обработчик 3'));

Вывод в консоль будет следующим:

Обработчик 2
Обработчик 1
Обработчик 3

Так как Обработчик 2 имеет наивысший приоритет, он сработает первым, даже если был добавлен позже.

Связь с фазами событий

PixiJS наследует концепцию фаз событий из DOM:

  • Capture phase — событие обходит контейнеры сверху вниз.
  • Bubble phase — событие поднимается обратно снизу вверх после обработки дочерних объектов.

При использовании options.capture = true обработчик сработает на фазе захвата, до того как событие дойдет до дочерних интерактивных объектов:

container.add('pointerdown', () => console.log('Capture phase'), { capture: true });
child.add('pointerdown', () => console.log('Bubble phase'));

Удаление обработчиков

Для корректного управления событиями после добавления полезно знать метод remove:

sprite.remove('pointerdown', handleClick);

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

Практическое применение приоритетов

При работе со сложной интерактивной сценой приоритеты позволяют:

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

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

uiButton.add('pointerdown', fastAction, { priority: 100 });
menuButton.add('pointerdown', menuOpen, { priority: 50 });

Так кнопка быстрого действия всегда обрабатывается первой, даже если наложена на другие элементы интерфейса.

Рекомендации по организации

  • Использовать приоритеты только там, где порядок вызова критичен.
  • Для большинства интерактивных объектов достаточно простого add без опций.
  • Комбинировать once и priority для временных обработчиков с гарантированным порядком срабатывания.
  • Учитывать фазы capture и bubble при работе с контейнерами, чтобы избежать непредсказуемого поведения событий.

Метод add в PixiJS вместе с параметром priority обеспечивает гибкую и мощную систему управления событиями, которая подходит как для простых интерфейсов, так и для сложных игровых сцен.

Оглавление