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

IDL

[Exposed=( Window , Worker , AudioWorklet )]
interface Event {
   constructor(DOMString type, optional EventInit eventInitDict = {});

   readonly attribute DOMString type;
   readonly attribute EventTarget? target;
   readonly attribute EventTarget? srcElement; // исторический
   readonly attribute EventTarget? currentTarget;
   sequence<EventTarget> composedPath();

   const unsigned short NONE = 0;
   const unsigned short CAPTURING_PHASE = 1;
   const unsigned short AT_TARGET = 2;
   const unsigned short BUBBLING_PHASE = 3;
   readonly attribute unsigned short eventPhase;

   undefined stopPropagation();
   attribute boolean cancelBubble; // исторический псевдоним .stopPropagation
   undefined stopImmediatePropagation();

   readonly attribute boolean bubbles;
   readonly attribute boolean cancelable;
            attribute boolean returnValue; // исторический
   undefined preventDefault();
   readonly attribute boolean defaultPrevented;
   readonly attribute boolean composed;

   [LegacyUnforgeable] readonly attribute boolean isTrusted;
   readonly attribute DOMHighResTimeStamp timeStamp;

   undefined initEvent(DOMString type, optional boolean bubbles = false, optional boolean cancelable = false); // исторический
};

dictionary EventInit {
   boolean bubbles = false;
   boolean cancelable = false;
   boolean composed = false;
};

Объект Event просто называется «событием» (event). Это позволяет сигнализировать о том, что что-то произошло, например, что изображение завершило загрузку.

«Потенциальная цель события» (potential event target) — null или объект EventTarget.

У события есть связанная «цель» (target) (потенциальная цель события). Если не указано иное, она не имеет значения (null).

У события есть связанная «родственная цель» (relatedTarget) (потенциальная цель события). Если не указано иное, она не имеет значения (null).

Примечание Другие спецификации используют relatedTarget для определения атрибута relatedTarget. [UIEVENTS]

У события есть связанный «список сенсорных целей» (touch target list) (список из нуля или более потенциальных целей события). Если не указано иное, это пустой список.

Примечание Список сенсорных целей предназначен исключительно для определения интерфейса TouchEvent и связанных интерфейсов. [TOUCH-EVENTS]

У события есть связанный «путь» (path). Путь — это список структур. Каждая структура состоит из «цели вызова» (invocation target) (объект EventTarget), из «цели вызова в теневом дереве» (invocation-target-in-shadow-tree) (логическое значение), из «цели с поправкой на тень» (shadow-adjusted target) (потенциальная цель события), из  «родственной цели» (relatedTarget) (потенциальная цель события), из «списка сенсорных целей» (touch target list) (список потенциальных целей событий), из «корня закрытого дерева» (root-of-closed-tree) (логическое значение) и из «слота в закрытом дереве» (slot-in-closed-tree) (логическое значение). Путь — это изначально пустой список.

 

Для веб-разработчиков (не нормативно)

event = new Event(type [, eventInitDict])

Возвращает новое событие event, для которого задано значение атрибута type как type. Аргумент eventInitDict позволяет устанавливать атрибуты bubbles и cancelable через элементы объекта с тем же именем.

event . type

Возвращает тип события event, например. «click», «hashchange» или «submit» (щелкнуть, изменить хэш или отправить)

event . target

Возвращает объект, которому отправлено событие event (его цель).

event . currentTarget

Возвращает объект, чей обратный вызов слушателя событий вызывается в данный момент.

event . composedPath()

Возвращает объекты цели вызова пути события event (объекты, для которых будут вызываться слушатели), за исключением любых узлов в теневых деревьях, для которых режим теневого корня «closed» (закрыт), которые недоступны из currentTarget события event.

event . eventPhase

Возвращает фазу события, которая может быть одной из NONE, CAPTURING_PHASE, AT_TARGET и BUBBLING_PHASE.

event . stopPropagation()

При отправке в дереве, вызов этого метода предотвращает достижение событием event каких-либо объектов, кроме текущего объекта.

event . stopImmediatePropagation()

Вызов этого метода предотвращает попадание события event в какие-либо зарегистрированные слушатели событий после завершения выполнения текущего, а при отправке в дереве также предотвращает достижение событием event любых других объектов.

event . bubbles

Возвращает истину или ложь в зависимости от того, как было инициализировано событие event. Истина, если событие event проходит через предков своей цели в обратном древовидном порядке, и ложь в противном случае.

event . cancelable

Возвращает истину или ложь в зависимости от того, как было инициализировано событие event. Его возвращаемое значение не всегда имеет смысл, но true может указывать на то, что часть операции, во время которой было отправлено событие event, может быть отменена путем вызова метода preventDefault().

event . preventDefault()

Если вызывается, когда значение атрибута cancelable равно true, и при выполнении слушателя для события event с passive значением false, сигнализирует операции, которая вызвала отправку события, что его необходимо отменить.

event . defaultPrevented

Возвращает true, если preventDefault() был успешно вызван для обозначения отмены, и false в противном случае.

event . composed

Возвращает истину или ложь в зависимости от того, как было инициализировано событие event. Истина, если событие event вызывает слушателей за узлом ShadowRoot, который является корнем его цели, и ложь в противном случае.

event . isTrusted

Возвращает true, если событие event было отправлено пользовательским агентом, и false в противном случае.

event . timeStamp

Возвращает отметку времени события event как количество миллисекунд, измеренных относительно начала отсчета времени.

 

 

Атрибут type должен возвращать значение, которым он был инициализирован. При создании события атрибут должен быть инициализирован пустой строкой.

Атрибут получателя target при вызове, должен возвращать цель этого (this).

Атрибут получателя srcElement при вызове, должен возвращать цель этого (this).

Атрибут currentTarget должен возвращать значение, которым он был инициализирован. При создании события атрибут должен быть инициализирован нулевым значением (null).

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

1. Пусть composedPath будет пустым списком.
2. Пусть path будет путём этого this.
3. Если path пустой, тогда верните composedPath.
4. Пусть currentTarget будет значением атрибута currentTarget этого this.
5. Добавить currentTarget в composedPath.
6. Пусть currentTargetIndex будет "0".
7. Пусть currentTargetHiddenSubtreeLevel будет "0".
8. Пусть index будет размером − 1 пути path.
9. Пока index больше или равен 0:
   1. Если path[index] корня закрытого дерева истинен, то увеличьте currentTargetHiddenSubtreeLevel на 1.
   2. Если path[index] цели вызова является currentTarget, тогда установите currentTargetIndex на index и break.
   3. Если path[index] слота в закрытом дереве истинен, то уменьшите currentTargetHiddenSubtreeLevel на 1.
   4. Уменьшить index на 1.
10. Пусть currentHiddenLevel и maxHiddenLevel будут currentTargetHiddenSubtreeLevel.
11. Установите index на currentTargetIndex − 1.
12. Пока index больше или равен 0:
   1. Если path[index] корня закрытого дерева истинен, то увеличьте currentHiddenLevel на 1.
   2. Если currentHiddenLevel меньше или равен maxHiddenLevel, тогда добавляйте path[index] цели вызова в начало composedPath.
   3. Если path[index] слота в закрытом дереве истинен, то:
      1. Уменьшите currentHiddenLevel на 1.
      2. Если currentHiddenLevel меньше maxHiddenLevel, установите для maxHiddenLevel значение currentHiddenLevel.
   4. Уменьшить index на 1.
13. Установить currentHiddenLevel и maxHiddenLevel на currentTargetHiddenSubtreeLevel.
14. Установить index на currentTargetIndex + 1.
15. Пока index меньше размера пути path:
   1. Если path[index] слота в закрытом дереве истинен, увеличьте currentHiddenLevel на 1.
   2. Если currentHiddenLevel меньше или равен maxHiddenLevel, тогда добавьте path[index] цели вызова к composedPath.
   3. Если path[index] корня закрытого дерева истинен, то:
      1. Уменьшите currentHiddenLevel на 1.
      2. Если currentHiddenLevel меньше maxHiddenLevel, тогда установите maxHiddenLevel на currentHiddenLevel.
   4. Увеличить index на 1.
16. Вернуть composedPath.

 

Атрибут eventPhase должен возвращать значение, которым он был инициализирован, которое должно быть одним из следующих:

NONE (числовое значение 0)

На этом этапе находятся события, которые в настоящее время не отправляются.

CAPTURING_PHASE (числовое значение 1)

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

AT_TARGET (числовое значение 2)

Когда событие отправлено, оно будет в этой фазе на своей цели.

BUBBLING_PHASE (числовое значение 3)

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

Первоначально атрибут должен быть инициализирован как NONE.

 

Каждое событие имеет следующие связанные флаги, которые изначально не установлены:

Название флага Описание
stop propagation flag флаг остановки распространения
stop immediate propagation flag флаг немедленной остановки распространения
canceled flag флаг отмены
in passive listener flag флаг «в пассивном слушателе»
composed flag флаг составной
initialized flag флаг инициализации
dispatch flag флаг отправки

Метод stopPropagation() при вызове должен установить флаг остановки распространения этого this.

Получатель атрибута cancelBubble при вызове должен возвращать значение true, если установлен флаг остановки распространения этого this, и false в противном случае.

Установщик атрибута cancelBubble при вызове должен установить флаг остановки распространения этого this, если заданное значение истинно, и ничего не делать в противном случае.

При вызове метода stopImmediatePropagation() он должен установить флаг остановки распространения этого this и флаг остановки немедленного распространения этого this.

Атрибуты bubbles и cancelable должны возвращать значения, которыми они были инициализированы.

Чтобы «установить флаг отмены» (set the canceled flag) для данного события event, если значение атрибута cancelable события event истинно и флаг пассивного слушателя события event не установлен, установите флаг отмены события event и ничего не делайте в противном случае.

Получатель атрибута returnValue при вызове должен возвращать false, если установлен флаг отмены этого this, и true в противном случае.

Установщик атрибута returnValue при вызове должен установить флаг отмены с this, если заданное значение ложно, и ничего не делать в противном случае.

Метод preventDefault() при вызове должен установить флаг отмены с этим this.

Примечание Существуют сценарии, в которых вызов preventDefault() не имеет никакого эффекта. Пользовательским агентам рекомендуется регистрировать точную причину в консоли разработчика, чтобы облегчить отладку.

Получатель атрибута defaultPrevented при вызове должен возвращать true, если установлен флаг отмены этого this, и false в противном случае.

Получатель атрибута composed при вызове должен возвращать true, если установлен составной флаг этого this, и false в противном случае.

 

Атрибут isTrusted должен возвращать значение, которым он был инициализирован. При создании события атрибут должен иметь значение false.

Примечание isTrusted — это удобство, которое указывает, отправлено ли событие пользовательским агентом (в отличие от использования dispatchEvent()). Единственное устаревшее исключение — это click(), который заставляет пользовательский агент отправлять событие, атрибут isTrusted которого инициализируется значением false.

Атрибут timeStamp должен возвращать значение, которым он был инициализирован.

 

Чтобы «инициализировать» (initialize) событие event с типом type, пузырьками bubbles и возможностью отмены cancelable, выполните следующие действия:

1. Установить флаг инициализации для события event.
2. Снять флаг остановки распространения, флаг немедленной остановки распространения и флаг отмены для события event.
3. Установите для атрибута isTrusted события event значение false.
4. Установите для цели события event значение null.
5. Установите для атрибута type события event значение type.
6. Установите атрибут bubbles события event на bubbles.
7. Установите для атрибута cancelable события event значение cancelable.

 

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

1. Если установлен флаг отправки этого this, вернитесь.
2. Инициализируйте этот объект this с type, bubbles, и cancelable.

Примечание! Поскольку у событий есть конструкторы, initEvent() избыточен и не может быть настроен composed. Он должен поддерживаться для устаревшего контента.

 

Ссылки

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

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

DOMLiving Standardhttps://dom.spec.whatwg.org

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

Поделись записью