EventTarget: метод removeEventListener()

Метод removeEventListener() интерфейса EventTarget удаляет обработчик события, ранее зарегистрированный с помощью EventTarget.addEventListener(), от целевого объекта. Обработчик события, который нужно удалить, идентифицируется по типу события, функции-обработчику и различным необязательным параметрам, которые могут повлиять на процесс сопоставления; см. Сопоставление обработчиков событий для удаления.

Вызов removeEventListener() с аргументами, не идентифицирующими какой-либо зарегистрированный в настоящее время обработчик события на EventTarget, не оказывает никакого эффекта.

Если обработчик события удаляется из объекта EventTarget, в то время как другой обработчик этого объекта обрабатывает событие, он не будет запущен событием. Однако его можно снова подключить.

Обработчики событий также можно удалить, передав AbortSignal в addEventListener(), а затем позже вызвав abort() на контроллере, владеющем этим сигналом.

type

Строка, определяющая тип события, для которого нужно удалить обработчик.

listener

Функция-обработчик события для удаления от целевого объекта.

options Необязательно

Объект опций, определяющий характеристики обработчика.

Доступные параметры:

• capture: Булево значение, определяющее, зарегистрирован ли обработчик как обработчик захвата. Если параметр отсутствует, предполагается значение по умолчанию false.

useCapture Необязательно

Булево значение, определяющее, зарегистрирован ли обработчик как обработчик захвата. Если параметр отсутствует, предполагается значение по умолчанию false.

None.

После добавления обработчика события с помощью вызова addEventListener(), в какой-то момент может потребоваться его удалить. Очевидно, что для этого нужно указать те же параметры type и listener при вызове removeEventListener(). Но что насчёт параметров options или useCapture?

Хотя addEventListener() позволяет добавлять один и тот же обработчик несколько раз для одного типа, если опции различаются, единственный параметр, который removeEventListener() проверяет, — это флаг capture/useCapture.

Его значение должно совпадать для того, чтобы removeEventListener() совпадало, но другие значения не проверяются.

Например, рассмотрим этот вызов addEventListener():

element.addEventListener("mousedown", handleMouseDown, true);

Теперь рассмотрим каждый из этих двух вызовов removeEventListener():

element.removeEventListener("mousedown", handleMouseDown, false); // Fails
element.removeEventListener("mousedown", handleMouseDown, true); // Succeeds

Первый вызов терпит неудачу, потому что значение useCapture не совпадает. Второй вызов успешен, так как useCapture совпадает.

Теперь рассмотрим это:

element.addEventListener("mousedown", handleMouseDown, { passive: true });

Здесь мы передаём объект options, в котором passive задано значением true, в то время как другие параметры оставлены по умолчанию, то есть false.

Теперь рассмотрим каждый из этих вызовов removeEventListener() по очереди. Все вызовы, в которых capture или useCapture имеют значение true, терпят неудачу; остальные вызовы успешны.

Только значение параметра capture имеет значение для removeEventListener().

element.removeEventListener("mousedown", handleMouseDown, { passive: true }); // Succeeds
element.removeEventListener("mousedown", handleMouseDown, { capture: false }); // Succeeds
element.removeEventListener("mousedown", handleMouseDown, { capture: true }); // Fails
element.removeEventListener("mousedown", handleMouseDown, { passive: false }); // Succeeds
element.removeEventListener("mousedown", handleMouseDown, false); // Succeeds
element.removeEventListener("mousedown", handleMouseDown, true); // Fails

Стоит отметить, что некоторые версии браузеров имели несоответствия в этом аспекте, и, если у вас нет конкретных причин для другого поведения, рекомендуется использовать те же значения, которые были использованы при вызове addEventListener() при вызове removeEventListener().

В этом примере показано, как добавить обработчик события на основе mouseover для удаления обработчика события на основе click.

const body = document.querySelector("body");
const clickTarget = document.getElementById("click-target");
const mouseOverTarget = document.getElementById("mouse-over-target");

let toggle = false;
function makeBackgroundYellow() {
  body.style.backgroundColor = toggle ? "white" : "yellow";

  toggle = !toggle;
}

clickTarget.addEventListener("click", makeBackgroundYellow, false);

mouseOverTarget.addEventListener("mouseover", () => {
  clickTarget.removeEventListener("click", makeBackgroundYellow, false);
});

• EventTarget.addEventListener()