DOM | Интерфейс EventTarget

IDL

[Exposed=( Window , Worker , AudioWorklet )]
interface EventTarget {
   constructor();

   undefined addEventListener(DOMString type, EventListener? callback, optional (AddEventListenerOptions or boolean) options = {});
   undefined removeEventListener(DOMString type, EventListener? callback, optional (EventListenerOptions or boolean) options = {});
   boolean dispatchEvent(Event event);
};

callback interface EventListener {
   undefined handleEvent(Event event);
};

dictionary EventListenerOptions {
   boolean capture = false;
};

dictionary AddEventListenerOptions : EventListenerOptions {
   boolean passive = false;
   boolean once = false;
};

Объект EventTarget представляет цель, которой может быть отправлено событие, когда что-то произошло.

Каждый объект EventTarget имеет связанный «список слушателей событий» (event listener list) (список из нуля или более слушателей событий). Изначально это пустой список.

«Слушатель событий» (event listener) может использоваться для наблюдения за конкретным событием и состоит из:

1. type (строка)
2. callback (null или объект EventListener)
3. capture (a boolean, изначально ложный false)
4. passive (a boolean, изначально ложный false)
5. once (a boolean, изначально ложный false)
6. removed (a boolean for bookkeeping purposes, изначально ложный false)

Примечание! Хотя обратный вызов является объектом EventListener, слушатель событий — это более широкая концепция, как видно выше.

 

С каждым объектом EventTarget также связан алгоритм «получения родителя» (get the parent), который принимает событие event и возвращает объект EventTarget. Если не указано иное, возвращается значение null.

Примечание Узлы, теневые корни и документы переопределяют алгоритм получения родителя.

 

Каждый объект EventTarget может иметь связанный алгоритм «поведения активации» (activation behavior). Алгоритм поведения активации передает событие, как указано в алгоритме отправки.

Примечание Это происходит потому, что пользовательские агенты выполняют определенные действия для определенных объектов EventTarget, например, элемента области area, в ответ на синтетические события MouseEvent, атрибут type которых — click. Веб-совместимость помешала его удалению, и теперь это закрепленный способ определения активации чего-либо. [HTML]

 

Каждый объект EventTarget, который имеет поведение активации, может дополнительно иметь как алгоритм «устаревшей предварительной активации поведения» (legacy-pre-activation behavior), так и алгоритм «устаревшей отмены активации поведения» (legacy-canceled-activation behavior).

Примечание Эти алгоритмы существуют только для флажков и радиоэлементов ввода input и не должны использоваться ни для чего другого. [HTML]

 

 

Чтобы «сгладить» (flatten) параметры options, выполните следующие действия:

1. Если options является логическим, верните options.
2. Вернуть capture options.

 

Чтобы «сгладить больше» (flatten more) параметров options, выполните следующие действия:

1. Пусть захват capture будет результатом параметров options сглаживания.
2. Пусть once и passive будет ложным.
3. Если options - это словарь, то установите passive на passive от options, а once на once от options.
4. Верните capture, passive и once.

 

Конструктор EventTarget() при вызове должен возвращать новый EventTarget.

Примечание Из-за значений по умолчанию, указанных в другом месте, возвращенный EventTarget алгоритм получения родителя вернет null, и у него не будет поведения активации, устаревшего поведения предварительной активации или устаревшего поведения отмененной активации.

Примечание В будущем мы могли бы разрешить настраиваемость алгоритма получение родителя. Сообщите нам, будет ли это полезно для ваших программ. На данный момент все созданные автором EventTarget не участвуют в древовидной структуре.

 

Чтобы «добавить слушатель событий» (add an event listener), учитывая объект EventTarget eventTarget и слушатель событий listener, выполните следующие действия:

1. Если eventTarget является объектом ServiceWorkerGlobalScope, установлен флаг какой-либо оценки ресурса сценария его сервис-воркера, а тип слушателя listener совпадает со значением атрибута type любого из событий сервисного работника, а затем отправляет предупреждение в консоль, что это может не дать ожидаемого получения результата. [SERVICE-WORKERS]
2. Если обратный вызов слушателя listener равен нулю, вернитесь.
3. Если список слушателей событий eventTarget не содержит слушателя событий, тип которого является типом listener, обратный вызов - это обратный вызов listener, а захват - это захват listener, тогда добавьте listener в список слушателей событий eventTarget.

Примечание Концепция добавления слушателя событий существует, чтобы гарантировать, что обработчики событий используют один и тот же путь кода. [HTML]

 

При вызове метода addEventListener (type, callback, options) необходимо выполнить следующие шаги:

1. Пусть capture, passive и once будет результатом сглаживания большего количества вариантов options.
2. Добавьте слушатель событий с этим this и слушатель событий, тип которого - type, обратный вызов - callback, захват - capture, пассивный - passive, и "один раз" - once.

 

Чтобы «удалить слушатель событий» (remove an event listener), учитывая объект EventTarget, eventTarget и слушатель событий, выполните следующие действия:

1. Если eventTarget является объектом ServiceWorkerGlobalScope и набор типов событий для обработки его сервис-воркера содержит type, то отправьте на консоль предупреждение о том, что это может не дать ожидаемых результатов. [SERVICE-WORKERS]
2. Установите для удалённого listener значение true и удалите его из списка слушателей событий eventTarget.

Примечание Это необходимо HTML для определения обработчиков событий. [HTML]

 

Чтобы «удалить все слушатели событий» (remove all event listeners), учитывая объект EventTarget eventTarget, для каждого слушателя listener из списка слушателей событий eventTarget, удалите слушатель событий с eventTarget и listener.

Примечание Это необходимо HTML для определения document.open(). [HTML]

 

При вызове метода removeEventListener(type, callback, options) необходимо выполнить следующие действия:

1. Пусть захват capture будет результатом сглаживания параметров options.
2. Если список слушателей событий этого this содержит слушатель событий, тип которого - type, обратный вызов - callback, а захват - capture, то удалите слушатель событий с этим this и этим слушателем событий.

Примечание Список слушателей событий не будет содержать нескольких слушателей событий с одинаковым типом, обратным вызовом и захватом, поскольку добавление слушателя событий предотвращает это.

 

При вызове метода dispatchEvent(event) необходимо выполнить следующие действия:

1. Если установлен флаг отправки события event или если его флаг инициализации не установлен, то генерируется исключение DOMException "InvalidStateError".
2. Установите для атрибута isTrusted события event значение false.
3. Вернуть в результат отправки события event этого this.

 

Ссылки

DOM стандарт — https://efim360.ru/dom/

Читайте перевод полной версии стандарта «объектной модели документа», чтобы ознакомиться со всеми концепциями и интерфейсами.

DOM — Living Standard — https://dom.spec.whatwg.org

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