HTML要素.dispatchEvent()

// イベントを発火する
element.dispatchEvent(イベントオブジェクト);

// カスタムイベントを作成する
var event = new CustomEvent("イベント名", { detail: データ });

// 標準のイベントを作成する
var event = new Event("イベント名");

<button id="btn">クリック</button>
<button id="autoBtn">自動クリック</button>
<div id="app"></div>
<p id="output"></p>

同じ処理は次のようにも書けます。

var btn = document.getElementById("btn");
var autoBtn = document.getElementById("autoBtn");
var app = document.getElementById("app");
var output = document.getElementById("output");

// ボタンにクリックイベントを登録する
btn.addEventListener("click", function() {
	output.textContent = "ボタンがクリックされました";
});

// dispatchEvent() で標準イベントを手動で発火する
autoBtn.addEventListener("click", function() {
	var clickEvent = new Event("click");
	btn.dispatchEvent(clickEvent); // btnのクリックリスナーが実行される
});

// カスタムイベントを作成してデータを渡す
app.addEventListener("userLogin", function(e) {
	output.textContent = e.detail.name + "がログインしました";
});

// カスタムイベントを発火し、detailにデータを含める
var loginEvent = new CustomEvent("userLogin", {
	detail: { name: "五条悟", role: "admin" }
});
app.dispatchEvent(loginEvent);

サンプルページはこちら

ミス1: dispatchEventの前にaddEventListenerを登録していない

『dispatchEvent()』はその時点でHTML要素に登録済みのリスナーだけを実行します。リスナーより先に発火しても何も起きないため、必ずリスナーを登録してから発火します。

var btn = document.getElementById("btn");
// NG: リスナーを登録する前にdispatchEventを呼んでいる
btn.dispatchEvent(new Event("click"));
btn.addEventListener("click", function() {
	console.log("クリックされました"); // 実行されない
});

修正後は次の通りです。

var btn = document.getElementById("btn");
// OK: リスナーを先に登録してからdispatchEventを呼ぶ
btn.addEventListener("click", function() {
	console.log("クリックされました"); // 実行される
});
btn.dispatchEvent(new Event("click"));

ミス2: CustomEventとEventの使い分け

標準の『Event』には『detail』プロパティが存在しないため、データを渡そうとしても『undefined』になります。データをリスナー側に渡したい場合は『detail』プロパティをサポートする『CustomEvent』を使います。

// NG: Eventにはdetailプロパティがないのでundefinedになる
var ev = new Event("userLogin");
document.dispatchEvent(ev);
document.addEventListener("userLogin", function(e) {
	console.log(e.detail); // undefined
});

修正後は次の通りです。

// OK: データを渡すにはCustomEventを使う
var ev = new CustomEvent("userLogin", { detail: { name: "五条悟" } });
document.dispatchEvent(ev);
document.addEventListener("userLogin", function(e) {
	console.log(e.detail.name); // 『五条悟』と出力される
});

『HTML要素.dispatchEvent()』はイベントをプログラムから発火するメソッドです。ユーザーの操作なしにイベントリスナーを実行できるため、テストの自動化やコンポーネント間の通信に活用できます。

『new CustomEvent()』を使うと、独自のイベント名を定義し、『detail』プロパティに任意のデータを含めることができます。リスナー側では『event.detail』でデータを参照できるため、HTML要素間でデータをやり取りする仕組みとして使えます。

『HTML要素.dispatchEvent()』で発火したイベントは、『HTML要素.addEventListener()』で登録したリスナーのみを実行します。ブラウザのデフォルト動作は発生しないため、例えばリンクに対して『click』イベントを発火してもページ遷移は起きません。バブリングを有効にしたい場合は、オプションに『{ bubbles: true }』を指定してください。