Event

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.

Event インターフェイスは DOM で発生するイベントを表します。

ユーザーの操作によって発生するイベント(マウスボタンのクリック、キーボードを叩くなど)もありますし、非同期タスクの進捗を表すための API によって生成されるイベントもあります。要素の HTMLElement.click() の呼び出しや、イベントを定義し、 EventTarget.dispatchEvent() を使用して指定されたターゲットに送信するなどのようにプログラムから起動されるものもあります。

イベントには様々な型があり、イベントによっては基本の Event インターフェイスを基にした他のインターフェイスを使用することもあります。 Event 自体は、すべてのイベントで共通のプロパティやメソッドを持っています。

多くの DOM 要素は、これらのイベントを受け入れる(または「待ち受けする」)ように設定することができ、それに応じてコードを実行してイベントを処理する(または「取り扱う」)ことができます。イベントハンドラーはふつう、様々な HTML 要素<button>, <div>, <span>, など)に EventTarget.addEventListener() を使用して結び付けられ(または「装着され」)、これが一般に古い HTML のイベントハンドラー属性を使用する方法を置き換えています。さらに、このようなハンドラーは正しく追加されたら、必要に応じて removeEventListener() を使用して切り離すことができます。

メモ: 1 つの要素が、まったく同じイベントに対して複数のハンドラーを持つこともできます。特に、別々の独立したコードモジュールが、それぞれ独立した目的のためにハンドラーを装着する場合(例えば、広告モジュールと統計モジュールの両方がビデオ視聴を監視しているウェブページ)です。

数多くの入れ子になった要素があり、それぞれに独自のイベントハンドラーがあった場合、イベントの処理はとても複雑になります。特に、親要素が子要素と全く同じイベントを受け取る場合、「空間的に」重なり合っているので、技術的にはイベントは両方で発生し、そのようなイベントの処理順序は、トリガーされた各ハンドラーのイベントのバブリングとキャプチャの設定次第で決まります。

Event を基にしたインターフェイス

コンストラクター

Event()

Event オブジェクトを生成して、呼び出し元に返します。

インスタンスプロパティ

Event.bubbles 読取専用

論理値で、イベントが DOM を通してバブリングするかどうかを示します。

Event.cancelable 読取専用

論理値で、イベントがキャンセル可能かを示します。

Event.composed 読取専用

論理値で、シャドウ DOM と 通常の DOM の間の境界を越えてイベントがバブリングできるかどうかを示します。

Event.currentTarget 読取専用

イベントが現在登録されているターゲットへの参照。これは、現在イベントの送信先として予定されているオブジェクトです。これは再ターゲティングによって、途中で変更される可能性があります。

Event.defaultPrevented 読取専用

このイベントをキャンセルするために event.preventDefault() が呼び出されたかどうかを示します。

Event.eventPhase 読取専用

イベントフローのどのフェーズで処理されているかを示します。 NONE, CAPTURING_PHASE, AT_TARGET, BUBBLING_PHASE のうちのいずれかの数値です。

Event.srcElement 非標準

Event.target の、(古いバージョンの Microsoft Internet Explorer 由来の) 標準外の別名であり、ウェブの互換性の目的で一部の他のブラウザーでも対応が始められています。

Event.target 読取専用

イベントが最初に送出されたターゲットへの参照。

Event.timeStamp 読取専用

イベントが生成された時刻をミリ秒単位で示します。仕様書ではこの値を元期からの経過時間としていますが、実際のブラウザーでの定義は様々です。また、値を DOMHighResTimeStamp に変更する作業が進行中です。

Event.type 読取専用

イベントの種類を識別する名前です。

古い標準外のプロパティ

Event.cancelBubble 非推奨;

Event.stopPropagation() の過去の別名であり、そちらを使用してください。イベントハンドラーから戻る前に値 true を設定すると、イベントの伝播を抑制します。

Event.explicitOriginalTarget 非標準 読取専用

イベントの明確な最初のターゲットです。

Event.originalTarget 非標準 読取専用

イベントの再ターゲティング前の最初のターゲットです。

Event.returnValue 非推奨;

過去のプロパティで、既存のサイトが動作するように対応されているものです。代わりに Event.preventDefault() および Event.defaultPrevented を使用してください。

Event.scoped 読取専用 非推奨;

論理値で、指定されたイベントがシャドウルートを通過して標準 DOM までバブリングするかどうかを示します。代わりに composed を使用してください。

インスタンスメソッド

Event.composedPath()

(リスナーが呼び出されるオブジェクトへの)イベントのパスを返します。これはシャドウルートの ShadowRoot.mode が閉じた状態で作成されたシャドウツリーのノードは含みません。

Event.preventDefault()

(キャンセル可能な場合)イベントをキャンセルします。

Event.stopImmediatePropagation()

この特定のイベントにおいて、他のすべてのイベントリスナーの呼び出しを防止します。これには、同じ要素に装着されたリスナーだけでなく、後で(例えばキャプチャ段階で)到達する要素に装着されたリスナーも含みます。

Event.stopPropagation()

この DOM 内でこれ以上イベントが伝播することを停止します。

非推奨のメソッド

Event.initEvent() 非推奨;

生成されたイベントの値を初期化します。イベントがすでに配信されている場合は、何も行いません。代わりにコンストラクター (Event()) を使用してください。

仕様書

Specification
DOM Standard
# interface-event

ブラウザーの互換性

BCD tables only load in the browser

関連情報