EventTarget: метод removeEventListener()

Baseline Widely available

This feature is well established and works across many devices and browser versions. It’s been available across browsers since September 2021.

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

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

Если слушатель событий удаляется в то время, когда другой слушатель обрабатывает событие, он не будет вызван. Однако его можно зарегистрировать повторно.

Предупреждение: Если слушатель зарегистрирован дважды, с флагом capture и без него, то необходимо удалять каждого слушателя по отдельности. Удаление слушателя захвата события не повлияет на слушателя всплытия этого события, и наоборот.

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

Синтаксис

removeEventListener(type, listener)
removeEventListener(type, listener, options)
removeEventListener(type, listener, useCapture)

Параметры

type

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

listener

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

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

Объект настроек, описывающий характеристики обработчика события:

capture: Логическое значение, определяющее зарегистрирован ли удаляемый слушатель событий на фазу захвата или нет. Если этот параметр опущен, то применяется значение по умолчанию false.

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

Логическое значение, определяющее зарегистрирован ли удаляемый слушатель событий на фазу захвата или нет. Если этот параметр опущен, то применяется значение по умолчанию false.

Возвращаемое значение

Нет.

Определение слушателя событий для удаления

Иногда возникает необходимость удалить зарегистрированного с помощью addEventListener() слушателя событий.

Очевидно, что для removeEventListener() нужно указать те же параметры type и listener. Но что делать с параметрами options или useCapture?

addEventListener() позволяет добавить одного и того же слушателя для одного типа событий более одного раза если отличаются настройки. При удалении слушателя removeEventListener() проверяет только флаг capture/useCapture. Его значение должно совпасть, а другие настройки не учитываются.

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

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

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

element.removeEventListener("mousedown", handleMouseDown, false); // Не сработает
element.removeEventListener("mousedown", handleMouseDown, true); // Выполнится успешно

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

Теперь рассмотрим такой случай:

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

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

Теперь рассмотрим вызовы removeEventListener() с разными параметрами. Те из них, в которых capture или useCapture установлены в true, не сработают, остальные выполнятся успешно.

Только настройка capture имеет значение при вызове removeEventListener().

element.removeEventListener("mousedown", handleMouseDown, { passive: true }); // Выполнится успешно
element.removeEventListener("mousedown", handleMouseDown, { capture: false }); // Выполнится успешно
element.removeEventListener("mousedown", handleMouseDown, { capture: true }); // Не сработает
element.removeEventListener("mousedown", handleMouseDown, { passive: false }); // Выполнится успешно
element.removeEventListener("mousedown", handleMouseDown, false); // Выполнится успешно
element.removeEventListener("mousedown", handleMouseDown, true); // Не сработает

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

Пример

В этом примере показано как можно добавить слушателя событий 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);
});

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

Specification
DOM Standard # ref-for-dom-eventtarget-removeeventlistener②

Совместимость с браузерами

BCD tables only load in the browser

Смотрите также

EventTarget.addEventListener()