Свои события в ActionScript 3

Свои события в ActionScript 3наследник Event, clone() и путь к CustomEvent в TypeScript

Свой класс события в AS3 пишется за пять минут и ломается на первой ретрансляции, если забыть clone(). Разбираем модель событий Flash и переносим её на EventTarget и CustomEvent.

Раздел
ActionScript 3
Стек
ActionScript 3EventDispatcherTypeScriptEventTarget
Уровень
Средний
Опубликовано
Обновлено
Чтение
9 мин
Коротко
  • Данные события кладите в поля наследника Event.
  • Без clone() ретрансляция падает с ошибкой #1034.
  • bubbles работает только в списке отображения.
  • В JS это CustomEvent с detail и класс extends EventTarget.
Как решаем
  1. Создайте наследник Event с константой типа и полями
  2. Переопределите clone(), копируя все поля и флаги
  3. Модель без сцены наследуйте от EventDispatcher
  4. Снимайте обработчики явно, слабую ссылку берите как страховку
  5. В TypeScript опишите карту событий и перегрузки

Зачем свои события, а не колбэки#

В ActionScript 3 вся платформа построена на модели событий DOM Level 3: загрузчики, таймеры, кнопки и сцена сообщают о происходящем через dispatchEvent. Когда в проекте появляется своя модель, например табло очков, корзина или очередь загрузок, хочется, чтобы она общалась с интерфейсом тем же способом. Колбэк в свойстве объекта позволяет подписать только одного слушателя, а событие можно слушать из любого числа мест, с приоритетами и без жёсткой связи между классами.

Стандартного Event хватает, если достаточно самого факта: «табло обновилось». Но обычно вместе с фактом нужно передать данные: новое значение, разницу, причину. Можно, конечно, в обработчике сходить обратно к источнику через event.target и прочитать свойство, но это снова связывает классы. Правильный путь: свой класс события с полями данных. Тот же приём мы использовали, когда разбирали прогресс загрузки XML, где данные о байтах едут прямо в событии.

Наследник Event с полем данных#

Минимальный класс события состоит из трёх частей: константы с именем типа, полей с данными и конструктора, который передаёт type, bubbles и cancelable в super. К ним обязательно добавляется переопределение clone(), а toString() через formatToString сильно облегчает отладку в trace.

ActionScript 3
package com.example.events {
    import flash.events.Event;

    public class ScoreEvent extends Event {
        public static const SCORE_CHANGE:String = "scoreChange";

        public var score:int;
        public var delta:int;

        public function ScoreEvent(type:String, score:int, delta:int,
                                   bubbles:Boolean = false, cancelable:Boolean = false) {
            super(type, bubbles, cancelable);
            this.score = score;
            this.delta = delta;
        }

        // без этого переопределения повторная отправка события сломается
        override public function clone():Event {
            return new ScoreEvent(type, score, delta, bubbles, cancelable);
        }

        override public function toString():String {
            return formatToString("ScoreEvent", "type", "score", "delta", "bubbles");
        }
    }
}

Строковую константу стоит держать в самом классе события: опечатка в ScoreEvent.SCORE_CHANGE ловится компилятором, а опечатка в строке "scoreChange" молча оставит обработчик без вызовов. Поля можно сделать read-only через геттеры, если события расходятся по многим модулям и вы не хотите, чтобы кто-то их менял по дороге.

Почему без clone() всё ломается#

Самая известная ловушка своих событий проявляется не сразу. Пока событие отправляется один раз, всё работает и без clone(). Проблема возникает, когда обработчик пересылает полученное событие дальше, например контроллер ретранслирует событие модели наверх: dispatchEvent(e). У такого события уже есть target, и Flash Player перед повторной отправкой вызывает у него clone().

Если метод не переопределён, работает реализация базового класса, и она возвращает обычный Event без ваших полей. Слушатель, объявленный как function onScore(e:ScoreEvent), получает объект не того типа, и плеер падает с TypeError: Error #1034: приведение типа не удалось. Найти причину по такому сообщению трудно, потому что ошибка возникает далеко от места, где класс события написан неполно.

Правило простое: каждый наследник Event переопределяет clone() и копирует в новый экземпляр все поля, включая bubbles и cancelable. Если поле хранит изменяемый объект, решите заранее, нужна ли глубокая копия, или ссылка на общий объект допустима.

Раз уж речь о флагах, стоит упомянуть cancelable. Если событие создано с cancelable = true, любой слушатель может вызвать preventDefault(), а отправитель узнает об этом по результату: dispatchEvent вернёт false. Так удобно строить «вопросительные» события: модель спрашивает, можно ли закрыть окно с несохранёнными данными, и отменяет действие, если кто-то из подписчиков возразил. Проверить отмену изнутри обработчика позволяет isDefaultPrevented(). Без cancelable вызов preventDefault() ничего не делает, и это ещё одна причина передавать флаг в clone(): потеряв его при копировании, вы молча отключите отмену для всех, кто слушает ретранслированное событие.

bubbles и EventDispatcher вне списка отображения#

Флаг bubbles работает только для объектов в списке отображения. Событие, отправленное с DisplayObject на сцене, проходит три фазы: захват от stage вниз, цель и всплытие обратно вверх по родителям. У модели вроде ScoreBoard родителей нет, поэтому bubbles = true на ней ничего не меняет: событие получают только те, кто подписался на сам объект.

Модели, которые не наследуют DisplayObject, делают источником событий двумя способами:

  • Наследование. Класс расширяет EventDispatcher и получает addEventListener, dispatchEvent, hasEventListener и willTrigger без лишнего кода.
  • Композиция. Если базовый класс уже занят, класс реализует IEventDispatcher, создаёт внутри new EventDispatcher(this) и делегирует ему вызовы. Аргумент this нужен, чтобы в event.target оказался ваш объект, а не служебный диспетчер.
  • Метаданные [Event]. Тег над классом не влияет на работу плеера, но даёт подсказки в Flex и IDE, какие события объект умеет отправлять.
ActionScript 3
package com.example.model {
    import flash.events.EventDispatcher;
    import flash.events.IEventDispatcher;
    import com.example.events.ScoreEvent;

    [Event(name="scoreChange", type="com.example.events.ScoreEvent")]
    public class ScoreBoard extends EventDispatcher {
        private var _score:int = 0;

        public function add(delta:int):void {
            _score += delta;
            dispatchEvent(new ScoreEvent(ScoreEvent.SCORE_CHANGE, _score, delta));
        }
    }
}

// подписка из экрана игры: слабая ссылка не удержит экран в памяти
board.addEventListener(ScoreEvent.SCORE_CHANGE, onScore, false, 0, true);

function onScore(e:ScoreEvent):void {
    scoreLabel.text = String(e.score);
}

Если вам нужно не всплытие, а централизованная обработка множества похожих источников, посмотрите заметку про один цикл ENTER_FRAME: подход с единым центром часто проще, чем десятки подписок.

Слабые ссылки и утечки памяти#

Пятый параметр addEventListener, useWeakReference, отвечал на вечный вопрос Flash-разработчика: почему экран, который давно убрали со сцены, продолжает жить в памяти. Источник событий хранит ссылку на функцию-обработчик, а через неё и на объект, которому принадлежит метод. Если источник живёт долго (сцена, глобальная модель, таймер), подписавшийся экран не будет собран, пока подписку не снимут.

Слабая ссылка не мешает сборщику мусора удалить слушателя. Но у неё есть обратная сторона: анонимная функция, подписанная со слабой ссылкой, больше нигде не хранится и может исчезнуть при ближайшей сборке, после чего обработчик перестаёт вызываться без всякой ошибки. Поэтому мы использовали слабые ссылки только с методами объектов и всё равно писали явный removeEventListener в методе уничтожения экрана. Слабая ссылка была страховкой, а не заменой аккуратной отписке. Похожие правила об уборке за собой есть и в заметке про свой класс твинов.

Что изменилось к 2026 году#

Flash Player снят с поддержки 31 декабря 2020 года, но модель событий из AS3 почти без изменений живёт в браузере, потому что обе выросли из одной спецификации DOM. Разница в деталях:

ActionScript 3JavaScript и TypeScript
Наследник Event с полямиCustomEvent с полем detail или наследник Event
Обязательный clone()Не нужен; переотправить объект во время его обработки нельзя, создайте новое событие
extends EventDispatcherextends EventTarget, конструктор доступен во всех актуальных браузерах и в Node.js
useWeakReferenceОпция signal с AbortController для отписки пачкой
Метаданные [Event]Карта событий и типизированные перегрузки в TypeScript
JavaScript
class ScoreBoard extends EventTarget {
  #score = 0;

  add(delta) {
    this.#score += delta;
    this.dispatchEvent(new CustomEvent('score-change', {
      detail: { score: this.#score, delta },
    }));
  }
}

const board = new ScoreBoard();
const subscription = new AbortController();

board.addEventListener('score-change', (e) => {
  scoreLabel.textContent = String(e.detail.score);
}, { signal: subscription.signal });

board.add(10);

// экран закрыли: снимаем все обработчики, подписанные с этим signal
subscription.abort();

Если вызвать dispatchEvent с событием, которое прямо сейчас обрабатывается, браузер бросит InvalidStateError, поэтому ретрансляцию пишут через новый объект события. Слабых ссылок в подписках нет, но AbortController решает ту же задачу аккуратнее: один abort() снимает все обработчики компонента. В TypeScript к этому добавляется строгая типизация, которую во Flash давали только метаданные и дисциплина:

JavaScript
type ScoreDetail = { score: number; delta: number };

interface ScoreBoardEventMap {
  'score-change': CustomEvent<ScoreDetail>;
  'reset': Event;
}

// слияние интерфейса с классом добавляет типизированные перегрузки
interface ScoreBoard {
  addEventListener<K extends keyof ScoreBoardEventMap>(
    type: K,
    listener: (ev: ScoreBoardEventMap[K]) => void,
    options?: boolean | AddEventListenerOptions
  ): void;
  removeEventListener<K extends keyof ScoreBoardEventMap>(
    type: K,
    listener: (ev: ScoreBoardEventMap[K]) => void,
    options?: boolean | EventListenerOptions
  ): void;
}

class ScoreBoard extends EventTarget {
  #score = 0;

  add(delta: number): void {
    this.#score += delta;
    this.dispatchEvent(new CustomEvent<ScoreDetail>('score-change', {
      detail: { score: this.#score, delta },
    }));
  }
}

const board = new ScoreBoard();
board.addEventListener('score-change', (e) => {
  console.log(e.detail.score); // тип number, без приведения
});
// board.addEventListener('score-chnage', ...) не скомпилируется

Мы проверили этот пример компилятором TypeScript в строгом режиме: опечатка в имени события и обращение к несуществующему полю detail ловятся на этапе сборки. Для событий интерфейса в DOM работает тот же CustomEvent, а слушать их на общем предке удобно приёмом, описанным в заметке про делегирование событий.

3фазы события: захват, цель, всплытие
#1034ошибка приведения типа без clone()
detailполе данных в CustomEvent

«Слабая ссылка была страховкой, а не заменой аккуратной отписке от событий.»

Главный вывод заметки

Вопросы и ответы

Вопросы и ответы

Обязательно ли переопределять toString() в своём событии?
Нет, на работу события это не влияет. Но с formatToString вывод trace показывает тип и значения полей вашего события, а не только имя базового класса, и отлаживать цепочки ретрансляций становится заметно проще.
Почему bubbles: true не работает на моей модели?
Всплытие идёт по родителям в списке отображения. У класса, унаследованного от EventDispatcher, родителей нет, поэтому событие получают только прямые подписчики. Нужна иерархия, сделайте ретрансляцию вручную или используйте общий объект-шину.
Что выбрать в JavaScript: CustomEvent или свой наследник Event?
CustomEvent с detail проще и не требует отдельного класса. Свой наследник Event удобен, когда у события много полей или методы. В TypeScript оба варианта типизируются через карту событий и перегрузки addEventListener.
Есть ли в JavaScript аналог useWeakReference?
Прямого аналога в addEventListener нет. Обработчики снимают через removeEventListener или опцию signal с AbortController, которая отписывает всё разом. Для особых случаев существуют WeakRef и FinalizationRegistry, но в коде интерфейсов они почти не нужны.
Заметка обновлена 12 ноября 2026: код проверен на актуальных версиях, добавлены современные варианты.

Читайте также