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) (логическое значение). Путь — это изначально пустой список.

 

 

 

Атрибут 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.

 

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

Метод 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/

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

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

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