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 ⁨2015年7月⁩.

メモ: この機能はウェブワーカー内で利用可能です。

removeEventListener() はEventTarget インターフェイスのメソッドで、以前にEventTarget.addEventListener() で登録されたイベントリスナーを取り外します。取り外されるイベントリスナーはイベントの型、イベントリスナー関数そのもの、照合プロセスに影響を与えるさまざまな任意のオプションを使用して識別します。取り外すイベントリスナーの照合を参照してください。

removeEventListener() を呼び出したときの引数でEventTarget に登録されているイベントリスナーが特定できなかった場合は、何も起こりません。

イベントリスナーがEventTarget の他のリスナーのイベント処理中に外された場合、イベントによって起動させることはありません。しかし、再接続は可能です。

警告:リスナーがcapture フラグを設定したものと設定しないものの 2 つ登録されている場合、それぞれを別々に取り外す必要があります。キャプチャするリスナーを取り外しても、同じリスナーのキャプチャしないバージョンには影響しませんし、その逆も同様です。

イベントリスナーを取り外すには、AbortSignal をaddEventListener() に渡して、後でそのシグナルを所有するコントローラーでabort() を呼び出して行うことも可能です。

構文

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

引数

type

文字列で、イベントリスナーを取り外すイベントの種類を表します。

listener

イベントターゲットから取り外すイベントハンドラーのイベントリスナー関数です。

options省略可

イベントリスナーに関する特性を指定する、オプションのオブジェクトです。

次のオプションが使用できます。

capture: 論理値で、取り外すイベントリスナーがキャプチャリスナーとして登録されているか否かを指定します。この引数がない場合、既定の値としてfalse が想定される。

useCapture省略可

取り外すイベントリスナーがキャプチャリスナーとして登録されているかを指定します。この引数を省略した場合は、既定値のfalse であるとみなします。

返値

なし。

取り外すイベントリスナーの照合

以前にaddEventListener() を呼び出して追加したイベントリスナーがある場合、最終的にそれを取り外す必要がある場合があります。当然ながら、同じtype とlistener 引数をremoveEventListener() には指定する必要があります。しかし、options やuseCapture 引数はどうでしょうか。

addEventListener() は、オプションが異なれば同じリスナーを同じ種類に複数回追加することができますが、removeEventListener() がチェックするオプションはcapture/useCapture フラグのみとなります。この値はremoveEventListener() で一致するためには一致していなければなりませんが、他の値は一致していなくてもかまいません。

例えば、以下のaddEventListener() で考えましょう。

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

そして、以下 2 つのremoveEventListener() の呼び出しについて考えましょう。

element.removeEventListener("mousedown", handleMouseDown, false); // 失敗element.removeEventListener("mousedown", handleMouseDown, true); // 成功

1 番目の呼び出しは、useCapture の値が異なるため失敗します。2 番目は、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); // 失敗

この点については、いくつかのブラウザーのリリースで一貫性がないことに注意してください。特に理由がない限り、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);});