DOM

：

：

EventTarget.addEventListener() メソッド

　編集：2022.09.28 by T.A.

[Edge]。→

EventTarget に指定のイベントが起こるたびに指定の関数処理をさせるように組み込みます。

対象としてよくあるものは Element、Document、Window ですが、イベントに対応したあらゆるオブジェクトが対象になることができます（XMLHttpRequest など）。

addEventListener() は関数または EventListener を実装したオブジェクトを、呼び出される EventTarget における指定されたイベント種別のイベント リスナーのリストに加えることで動作します。

構文
EventTarget.addEventListener(type,listener[,options])
EventTarget.addEventListener(type,listener[,useCapture])
Gecko／Mozilla のみ：非推奨
EventTarget.addEventListener(type,listener[,useCapture,wantsUntrusted])
EventTarget Element、Document、Window ですが、イベントに対応したあらゆるオブジェクトが対象になることができます（XMLHttpRequest など）。
type 組み込むイベントの種類を表す文字列。例→Windowのイベント、Elementのイベント
listener 組み込む処理（コールバック）。指定された型のイベントが発生するときに通知（Event インターフェースを実装しているオブジェクト）を受け取るオブジェクト。これは、EventListener インタフェースを実装するオブジェクト、あるいは、単純に、JavaScript の関数でなければなりません。コールバックについて詳しくは、 を参照してください。
options 省略可。オプション（対象のイベント リスナーの特性）を指定するオブジェクト。
プロパティ説明
capture Boolean 値で、この型のイベントが DOM ツリーで下に位置する EventTarget に配信dispatchされる前に、登録された listener に配信されることを示します。
once Boolean 値で、listener の呼び出しを一回のみのとしたいかどうかを値で指定します。true を指定すると、listener は一度実行された時に自動的に削除されます。
passive Boolean 値で、true ならば、listener で指定された関数が Event.preventDefault() を呼び出さないことを示します。呼び出されたリスナーが preventDefault() を呼び出すと、ユーザー エージェントは何もせず、コンソールに警告を出力します。詳細はパッシブリスナーによるスクロール性能の改善をご覧ください。
mozSystemGroup 非推奨。Boolean 値で、リスナーをシステム グループに追加するべきであることを示します。コードが XBL または Firefox ブラウザーの chrome で実行されている場合のみ利用できます。
useCapture 省略可。Boolean 値。この型のイベントが、DOM ツリー内の下の EventTarget に配信される前に、登録された listener に配信されるかどうかを示します。¶規定値ではfalseのようです。

ツリーを上方向にバブリングしているイベントは、キャプチャーを使用するように指定されたリスナーを起動しません。イベントのバブリングとキャプチャーは、両方の要素がそのイベントのハンドラーを登録している場合に、別の要素内に入れ子になっている要素で発生するイベントを伝播する 2 つの方法です。イベント伝播モードは、要素がイベントを受け取る順番を決定します。詳細な説明は DOM Level 3 Events と JavaScript Event order を参照してください。指定されていない場合、useCapture は既定で false となります。

注： イベントターゲットに登録されたイベント リスナーは、捕捉フェーズやバブリング フェーズではなく、ターゲット フェーズのイベントになります。ターゲット フェーズのイベントは、useCapture 引数にかかわらず、すべてのリスナーを追加された順序で実行します。

注： useCapture はどんなブラウザーでもオプションになっているわけではありません。完全で最大限の互換性を得たいなら、引数を指定するようにしてください。

wantsUntrusted 非推奨。true の場合、このリスナーはウェブ コンテンツによって発火された合成イベント（カスタム イベント）を受け取ります（ブラウザーのクロームでは既定で false ですが、一般のウェブ ページでは true です）。この引数は Gecko でのみ利用可能であり、主にアドオンやブラウザー自身の役に立つものです。
戻り値

undefined。

¶省く

例
シンプルなリスナーの追加
この例は、要素上でのマウスクリックを監視するための addEventListener() の使い方を紹介します。

HTML： 

<table id="outside">
  <tr><td id="t1">one</td></tr>
  <tr><td id="t2">two</td></tr>
</table>

JavaScript： 

// t2 のコンテンツを変更する関数
function modifyText() {
  const t2 = document.getElementById("t2");
  if (t2.firstChild.nodeValue == "three") {
    t2.firstChild.nodeValue = "two";
  } else {
    t2.firstChild.nodeValue = "three";
  }
}

// イベントリスナーを table に追加
const el = document.getElementById("outside");
el.addEventListener("click", modifyText, false);

このコードの中で、modifyText() が addEventListener() を使用して登録された click イベントのリスナーです。表の中のどこかをクリックすると、ハンドラーに上がり、modifyText() を実行します。

¶省く

ハンドラー内での "this" の値

一連の類似した要素に対して一般的なハンドラーを使いたい場合のように、イベントハンドラーが実行される要素を参照したいということがたびたびあります。

addEventListener() を使って要素にハンドラー関数を設定したとき、ハンドラーの中の this の値は要素への参照となります。これはハンドラーに渡された event 引数の currentTarget プロパティの値と同じです。 

my_element.addEventListener('click', function (e) {
  console.log(this.className)           // logs the className of my_element
  console.log(e.currentTarget === this) // logs `true`
})

アロー関数は独自の this コンテキストを持たないことをお忘れなく。 

my_element.addEventListener('click', (e) => {
  console.log(this.className)	// WARNING: `this` is not `my_element`
  console.log(e.currentTarget === this)	// logs `false`
})

HTML： 

<SPAN id=IdSpan>SPAN要素。ここをクリック</SPAN>

JavaScript： 

function Job(eve){
  let Y=eve.target;	//eveに Event オブジェクトが入る。
  alert(eve.type +"："+ Y.tagName); //イベントのタイプとイベントが起きた要素名を表示する。
}
IdSpan.addEventListener("click", Job) //clickイベントの組み込み。

表示結果： 

click：SPAN
イベント処理

HTML： 

<DIV id=IdDropZone>ここにドロップしてください</DIV>

JavaScript： 

function DropJob(Ev){
  //EvにはDragEventが入る
}
IdDropZone.addEventListener("drop",DropJob);
このように、Ev には各イベント オブジェクトが入る。
イベントの組み込み方法

HTML： 

<SPAN id=IdSpan>SPAN要素。ここでクリックしてみて</SPAN>

JavaScript： 方法1 

function Job(eve){  //イベントが起きたら処理する関数：eveにはEventオブジェクトが入るようです。
  let Y=eve.target; //イベントが起きた要素オブジェクトを取得。
  alert(Y.tagName +"："+ eve.type); //表示：タグ名、イベントのタイプ。
}
IdSpan.addEventListener('click', Job); //SPAN要素にclickイベントを割り当てる。

JavaScript： 方法2 

IdSpan.addEventListener('click', function(eve){ //SPAN要素にclickイベントを割り当てる：その処理～
  let Y=eve.target;                 //イベントが起きた要素オブジェクトを取得。
  alert(Y.tagName +"："+ eve.type); //表示：要素名、イベントのタイプ。
});

JavaScript： 方法3：アロー関数式を使用。 

IdSpan.addEventListener('click', eve =>{ //SPAN要素にclickイベントを割り当てる：その処理～第1引数はEventオブジェクトが入るようです。
  let Y=eve.target;                 //イベントが起きた要素オブジェクトを取得。
  alert(Y.tagName +"："+ eve.type); //表示：要素名、イベントのタイプ。
});

JavaScript： 方法4：アロー関数式を使用。あまり意味は無いですが。 

let Job=eve => { //SPAN要素にclickイベントを割り当てる：その処理：第1引数はEventオブジェクトが入るようです。
  let Y=eve.target;                 //イベントが起きた要素オブジェクトを取得。
  alert(Y.tagName +"："+ eve.type); //表示：要素名、イベントのタイプ。
};	//「;」必須。
IdSpan.addEventListener('click', Job);

↑Job を let で宣言してますけど、var、const も可能です。

addEventListener() では同じイベントに複数の関数を割り当てられるようです。特定のイベントを削除する場合は removeEventListener() を使用します。

JavaScript： onイベント名 での指定方法。on○○に対応しているイベントのみ。 

function Job(eve){
  処理
}
IdSpan.onclick=Job; //但し、割り当てられるのは 1 つのみ。

他にも、 

IdSpan.onclick=function(eve){処理}; //関数式使用。

IdSpan.onclick=eve => {処理}; //アロー関数式使用。
useCapture

HTML： 

<DIV id=IdDiv>[DIV要素。個々でクリックしてみて
  <SPAN>[SPAN要素。ここでクリックしてみて]</SPAN>
  終わり]
</DIV>

JavaScript： 

IdSpan.addEventListener('click', function(eve){ //SPAN要素にclickイベントを割り当てる：その処理～
  let Y=eve.target;                 //イベントが起きた要素オブジェクトを取得。
  alert(Y.tagName +"："+ eve.type); //表示：要素名、イベントのタイプ。
}, false); //キャプチャーしない？

IdSpan.addEventListener('click', function(eve){ //SPAN要素にclickイベントを割り当てる：その処理～
  let Y=eve.target;                 //イベントが起きた要素オブジェクトを取得。
  alert(Y.tagName +"："+ eve.type); //表示：要素名、イベントのタイプ。
}, true); //キャプチャーする？

どちらも変わらないようですが。

HTML： 

<DIV id=IdDiv>[DIV要素。個々でクリックしてみて
  <SPAN id=IdSpan>[SPAN要素。ここでクリックしてみて]</SPAN>
  終わり]
</DIV>

JavaScript： 

function Job(eve){
  let Y=eve.target;
  alert(Y.tagName +"："+ eve.type +"："+ eve.eventPhase);
}
IdDiv.addEventListener('click', Job, true);
IdSpan.addEventListener('click', Job, true)

こうclickイベントを組み込むのに意味はないだろうけど、違いが出ました。

これでSPAN要素をクリックしてみると、最初にEvent.eventPhaseの値が「1」と出ますね。その次に「2」と出ました。

useCaptureを、DIV、SPAN両方にfalseまたは省略の場合はSPANクリックでEvent.eventPhaseは「2」次に「3」が出ました。

テスト