JavaScript метод EventTarget.dispatchEvent()

Определение и применение

JavaScript метод dispatchEvent() объекта EventTarget позволяет отправить искусственно созданное событие элементу, синхронно вызывая затронутые прослушиватели событий в соответствующем порядке. Искусственные события всегда имеют значение false в свойстве isTrusted объекта Event.

Метод dispatchEvent() возвращает логическое значение false, если событие отменяется и по крайней мере один из обработчиков событий, обработавших это событие вызвал метод preventDefault(), в противном случае возвращается логическое значение true.

В отличие от нативных событий, которые запускаются DOM и вызывают обработчики событий асинхронно через цикл обработки событий, dispatchEvent() вызывает обработчики событий синхронно. Все применимые обработчики событий будут выполняться и возвращаться до продолжения кода после вызова dispatchEvent(), он является последним шагом процесса create-init-dispatch, который используется для отправки событий в модель событий реализации. Событие может быть создано с помощью конструктора событий:

const event = new Event( typeArg );                  // тип события
const configuredEvent = new Event( typeArg, eventInit ); // тип события и настройки события

Значения параметров конструктора:

Поддержка браузерами

Спецификация: dom.spec.whatwg

✓Поддерживается во всех основных браузерах с 2015 года.

Показать браузеры

ВсеКомпьютерыМобильные

Совместимостьapi.EventTarget.dispatchEvent

Возможность	Компьютеры					Мобильные
	ChromeChrome	EdgeEdge	FirefoxFirefox	OperaOpera	SafariSafari	Chrome AndroidChromeAndroid	Firefox for AndroidFirefoxAndroid	Opera AndroidOperaAndroid	Safari on iOSSafariiOS	Samsung BrowserSamsungAndroid	WebView AndroidWebViewAndroid	WebView on iOSWebViewiOS
dispatchEvent	✓4	✓12	✓2	✓9	✓3.1	✓18	✓4	✓10.1	✓3	✓1.0	✓4	✓3

✓поддерживается◐с ограниченияминет поддержки?нет данных≤31 — не позднее версии 31

JavaScript синтаксис

target.dispatchEvent(event);
const canceled = !target.dispatchEvent(event);

Спецификация

DOM Standard.

Значения параметров

Исключения

Пустая строка в качестве типа допустима для события, созданного конструктором Event. Исключения, возникающие в обработчиках событий, регистрируются как неперехваченные исключения: обработчики выполняются во вложенном стеке вызовов и блокируют вызывающий код до завершения, но исключения на вызывающий код не распространяются.

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

Создание искусственного события

<button data-example-event-0="">Dispatch (click with no bubble)</button>
<button data-example-event-1="">Dispatch (click)</button>
<p>Click me</p>

const p = document.querySelector('p'), // выбираем первый элемент p в документе
    myFunc = function (e) {
        console.log('click', 'bubbles: ' + e.bubbles) // выводим в консоль текстовую информацию и значение свойства bubbles объекта Event
    }

p.addEventListener('click', myFunc, false) // устанавливаем для элемента обработчик события нажатия левой кнопки мыши на элементе (стадия всплытия)
p.addEventListener('click', myFunc, true) // устанавливаем для элемента обработчик события нажатия левой кнопки мыши на элементе (стадия перехвата)

const dispatch = function () {
    const event = new Event('click', { bubbles: false }) // создаем объект события и указываем, что событие не является всплывающим внутри DOM
    p.dispatchEvent(event) // отправляем искусственно созданное событие целевому элементу
}

const dispatch2 = function () {
    const event = new Event('click', { bubbles: true }) // создаем объект события и указываем, что событие является всплывающим внутри DOM
    p.dispatchEvent(event) // отправляем искусственно созданное событие целевому элементу
}

document.querySelector('[data-example-event-0]').addEventListener('click', function (event) {
    dispatch()
})
document.querySelector('[data-example-event-1]').addEventListener('click', function (event) {
    dispatch2()
})

body {
  margin: 16px;
  font:
    16px/1.5 system-ui,
    sans-serif;
  overflow-wrap: anywhere;
}
img,
input,
select,
textarea,
button {
  max-width: 100%;
}

В этом примере мы разместили элемент <p>), с помощью метода querySelector() мы выбрали его и инициализировали переменную этим значением.

С помощью метода addEventListener() устанавливаем для элемента <p> функцию обработчик события "click" (нажатие левой кнопкой мыши на элементе) как для фазы всплытия (bubbling phase), так и для фазы перехвата (capture phase). При срабатывании события "click" на этом элементе будет вызываться функция myFunc, которая будет выводить в консоль текстовую информацию и значение свойства bubbles объекта Event.

Кроме того, мы разместили в документе две кнопки (элемент <button>), которым с помощью метода addEventListener() назначали функции, которые срабатывают при нажатии.

При нажатии на первую кнопку срабатывает функция, которая создает объект события и указывает, что событие не является всплывающим внутри DOM, после этого с использованием метода dispatchEvent() отправляет искусственно созданное событие целевому элементу <p>, в результате чего обработчик события "click" этого элемента будет вызван два раза (для стадии перехвата и всплытия).

При нажатии на вторую кнопку срабатывает аналогичная функция, которая создает объект события и указывает, что событие является всплывающим внутри DOM, после этого с использованием метода dispatchEvent() отправляет искусственно созданное событие целевому элементу <p>, в результате чего обработчик события "click" этого элемента так же будет вызван два раза (для стадии перехвата и всплытия).

Передача пользовательских данных

Вы можете не только создавать искусственные события, но и добавлять пользовательские данные в объект события, для этого существует интерфейс CustomEvent, а свойство detail можно использовать для передачи пользовательских данных.

<p>Данные пользовательского события появятся в консоли.</p>

document.addEventListener('myEvent', (event) => console.log(event.detail))
const event = new CustomEvent('myEvent', { detail: { message: 'Привет', count: 2 } })
document.dispatchEvent(event)

body {
  margin: 16px;
  font:
    16px/1.5 system-ui,
    sans-serif;
  overflow-wrap: anywhere;
}
img,
input,
select,
textarea,
button {
  max-width: 100%;
}

Вызов встроенных событий

Обращаю Ваше внимание на то, что вы можете создавать не только пользовательские события, но и встроенные события - FocusEvent, MouseEvent, WheelEvent, KeyboardEvent и тому подобное, например:

<p>Результат выполнения выводится в консоль под примером.</p>

document.addEventListener('click', (event) =>
    console.log('Событие:', event.type, 'Создано пользователем:', event.isTrusted),
)
const myEvent = new MouseEvent('click', {
    view: window,
    bubbles: true,
    cancelable: true,
})

document.dispatchEvent(myEvent)

body {
  margin: 16px;
  font:
    16px/1.5 system-ui,
    sans-serif;
  overflow-wrap: anywhere;
}
img,
input,
select,
textarea,
button {
  max-width: 100%;
}