Zenn
📕

[保存版]HTML Living Standardで定義されているイベントハンドラ全70種

に公開1件
HTML
JavaScript
event
whatwg
tech

こんにちは、yamanakaです。

Web開発をしているとたくさんのイベントに出会うと思います。
それぞれのイベントがどんなときに使えるのか気になりますよね。

今回はHTML Living Standardに記載のイベントハンドラについて、コード例とすぐに試せるCodePenをあわせて図鑑的にまとめてみました！

あなたは70種類すべて知っているでしょうか？

イベントが必要なとき、UI/UXを考えるときにこの記事を参考にしてもらえると嬉しいです。

マウスイベント

onclick

  • イベントの発生タイミング: 要素がマウスポインターでクリックされた（左ボタンで押されて離された）時。
  • どういったときに使えるか: ボタンのクリック、リンクの実行、メニューの表示/非表示など、ウェブページで最も一般的に使用されるインタラクション。

ondblclick

  • イベントの発生タイミング: 要素がマウスポインターでダブルクリックされた時。
  • どういったときに使えるか: リストの項目を編集モードにする、画像を全画面表示するなど、通常のクリックとは異なるアクションを割り当てたい場合。

onmousedown / onmouseup

  • イベントの発生タイミング:
    • onmousedown: マウスのボタンが要素上で押された時。
    • onmouseup: マウスのボタンが要素上で離された時。
  • どういったときに使えるか: ドラッグ操作の実装（onmousedownで開始、onmouseupで終了）、押している間だけ何かを続ける処理（例: ゲームの射撃ボタン）などに使えます。onclickは押して離す一連の動作で発生しますが、これらのイベントは個別の動作を検知します。

onmousemove

  • イベントの発生タイミング: マウスポインターが要素の上で移動した時。
  • どういったときに使えるか: マウスカーソルの座標を取得して何かを動かす（例: ドラッグ＆ドロップ、お絵かきアプリの描画）、要素に追従するツールチップの表示など。非常に高い頻度で発生するため、処理が重くならないよう注意が必要です。

onmouseenter / onmouseleave

  • イベントの発生タイミング:
    • onmouseenter: マウスポインターが要素の領域内に入った時。
    • onmouseleave: マウスポインターが要素の領域外に出た時。
  • どういったときに使えるか: ドロップダウンメニューの表示/非表示、マウスが乗ったボタンのデザイン変更など。子要素に移動してもイベントは発生しないため、onmouseover/onmouseoutよりも直感的に扱えることが多いです。

onauxclick

  • イベントの発生タイミング: マウスの主ボタン（通常は左ボタン）以外のボタンがクリックされた時。一般的にはマウスホイールのクリック（中央ボタン）や、多ボタンマウスの補助ボタンが対象となります。
  • どういったときに使えるか: ウェブアプリケーションで、中央クリックに特別な機能（例: タブで開く以外のカスタムアクション、3Dビューの操作など）を割り当てたい場合に使用します。

キーボードイベント

onkeydown / onkeyup

  • イベントの発生タイミング:
    • onkeydown: キーが押された時。キーを押し続けている間、連続して発生します。
    • onkeyup: 押されていたキーが離された時。
  • どういったときに使えるか:
    • onkeydown: ゲームのキャラクター操作、特定のキー（例: Enterキー）でフォームを送信する、ショートカットキーの実装など。
    • onkeyup: 入力が完了したタイミングで何かをしたい時（例: 検索ボックスで入力後に検索候補を更新する）。

フォームイベント

フォーム要素 (<input>, <select>, <textarea>, <form>など) に関連するイベントです。

onchange

  • イベントの発生タイミング: フォーム要素の値が変更され、かつその要素からフォーカスが外れた時。チェックボックスやラジオボタンの場合は、選択状態が変わった瞬間に発生します。
  • どういったときに使えるか: <select>でオプションを選択した直後にページの内容を更新する、入力フィールドの内容が確定した後にバリデーション（入力値の検証）を行うなど。

oninput

  • イベントの発生タイミング: <input>, <textarea> などの値が変更された瞬間。文字の入力、削除、貼り付けなど、値が変わるたびに発生します。
  • どういったときに使えるか: 入力中にリアルタイムで文字数をカウントする、検索ボックスに入力されるたびに即座に検索候補を表示するなど、onchangeよりも即時性が求められる場合に最適です。

onsubmit

  • イベントの発生タイミング: <form> 要素が送信される時（送信ボタンがクリックされるか、フォーム内でEnterキーが押された時など）。
  • どういったときに使えるか: フォームが送信される直前に入力内容を検証（バリデーション）し、問題があれば送信をキャンセルする、Ajaxを使ってページをリロードせずにサーバーにデータを送信するなど。

onbeforeinput

  • イベントの発生タイミング: 編集可能な要素（<input>, <textarea>, contenteditable属性を持つ要素）の値が、実際に変更される直前に発生します。このイベントはキャンセル可能です。
  • どういったときに使えるか: ユーザーの入力をDOMに反映する前に検証し、許可しない文字（例: 数字のみのフィールドに文字が入力された）の入力を未然に防ぎたい場合に使います。oninputイベントよりも先に発生するのが特徴です。

onformdata

  • イベントの発生タイミング: <form>要素が送信されるプロセスの中で、ブラウザが送信用のFormDataオブジェクトを構築した直後に発生します。このイベントはsubmitイベントの前に発生します。
  • どういったときに使えるか: フォームがサーバーに送信される直前に、プログラムで送信内容を動的に追加・変更したい場合に非常に強力です。例えば、ユーザーには見えていないトラッキング用のIDを追加したり、入力されたデータを特定の形式に加工してから送信したりできます。

メディアイベント

<audio> や <video> 要素に関連するイベントです。

onplay / onpause

  • イベントの発生タイミング:
    • onplay: メディアの再生が開始された、または再開された時。
    • onpause: メディアの再生が一時停止された時。
  • どういったときに使えるか: 再生状態に合わせて、カスタムの再生/一時停止ボタンの表示を切り替える、再生が始まったら関連情報を表示するなど。

onended

  • イベントの発生タイミング: メディアの再生が最後まで終了した時。
  • どういったときに使えるか: 動画の再生終了後に「もう一度見る」ボタンを表示する、プレイリストの次の曲を自動的に再生するなど。

ontimeupdate

  • イベントの発生タイミング: メディアの現在の再生位置 (currentTime プロパティ) が変化した時。通常、1秒間に数回の頻度で発生します。
  • どういったときに使えるか: カスタムの再生プログレスバーを更新する、動画の特定の位置で字幕や注釈を表示するなど。

その他のメディア関連イベント

  • onemptied
    • イベントの発生タイミング: メディアデータが空になった時に発生します。これは、ネットワークエラーが発生した場合や、メディアのソース (src) が動的に変更された直後などに起こります。
    • どういったときに使えるか: メディアの読み込みに致命的な問題が発生したことを検知し、ユーザーにエラーメッセージを表示したり、代替コンテンツを読み込んだりする処理に使用できます。
  • onplaying
    • イベントの発生タイミング: バッファリング（データの一時読み込み）やシーク（再生位置の移動）が完了し、再生が実際に開始または再開された時に発生します。
      どういったときに使えるか: onplayイベントがユーザーの「再生」という 意図 を示すのに対し、* onplayingは実際に映像や音声が動き出した 事実 を示します。そのため、「バッファリング中...」といったローディング表示を非表示にする、最も正確なタイミングとして利用できます。
  • onprogress
    • イベントの発生タイミング: ブラウザがメディアデータをダウンロードしている間、断続的に発生します。
    • どういったときに使えるか: メディアプレーヤーのプログレスバー（再生バー）上で、どこまでデータがダウンロードされたかを示す「バッファリング済み範囲」を視覚的に更新するために使用されます。これにより、ユーザーはどこまでシーク可能かを把握できます。
  • onstalled
    • イベントの発生タイミング: メディアデータのダウンロードが予期せず停滞した時に発生します。ネットワーク接続が遅い、または不安定な場合に起こり得ます。
    • どういったときに使えるか: ネットワーク接続が不安定であることを検知し、ユーザーに通知したり、低画質のストリームに切り替えるなどの対策を講じる際のデバッグや監視に役立ちます。
  • onsuspend
    • イベントの発生タイミング: メディアデータの読み込みが完了する前に、意図的に中断された時に発生します。例えば、データがすべてダウンロードされた後や、ページから離れる際などに発生することがあります。
    • どういったときに使えるか: データの読み込みが完了したことを（間接的に）検知したり、リソースの読み込み状態をデバッグしたりするのに使用できます。

（onstalled、onemptiedなどはエラーケースなのであまり起こりません）

ドラッグ＆ドロップイベント

ondragstart / ondrop / ondragover

  • イベントの発生タイミング:
    • ondragstart: ドラッグ可能な要素 (draggable="true") でドラッグ操作が開始された時。
    • ondrag: ドラッグしている間継続的に発生する。
    • ondragenter: ドロップエリアに要素が入った時。
    • ondragover: ドラッグ中の要素が、ドロップ可能な要素の上に重なっている間、連続して発生。
    • ondragleave: ドラッグ中の要素が、ドロップ可能な要素の上から出た時。
    • ondragend: ドラッグが終わった時。
    • ondrop: ドラッグ中の要素が、ドロップ可能な要素の上で離された（ドロップされた）時。
  • どういったときに使えるか: ファイルアップローダー、タスク管理ツールのかんばんボード、アイテムの並べ替えなど、直感的なUIを実装する際に使われます。

その他の主要なイベント

oncopy / oncut / onpaste

  • イベントの発生タイミング:
    • oncopy: ユーザーが要素のコンテンツをコピーした時 (Ctrl+C など)。
    • oncut: ユーザーが要素のコンテンツを切り取った時 (Ctrl+X など)。
    • onpaste: ユーザーが要素にコンテンツを貼り付けた時 (Ctrl+V など)。
  • どういったときに使えるか: コピーされたテキストに著作権情報を追加する、特定の入力フィールドへの貼り付けを禁止する、貼り付けられたデータを整形するなど。

onselect

  • イベントの発生タイミング: <input> や <textarea> のテキストが選択された時。
  • どういったときに使えるか: テキストが選択されたときに、そのテキストを引用するボタンを表示するなど、選択範囲に対するアクションを提供したい場合。

onabort

  • イベントの発生タイミング: 画像の読み込みなど、リソースの読み込みが完了する前に、ユーザーの操作（例: ブラウザの停止ボタンを押す）やスクリプトによって中断された時に発生します。
  • どういったときに使えるか: 大きな画像の読み込みがキャンセルされたことをユーザーに通知したり、読み込み失敗時の代替処理を行ったりする場合に使用できます。

oncontextmenu

  • イベントの発生タイミング: 要素の上でマウスが右クリックされ、ブラウザのコンテキストメニューが表示される直前に発生します。
  • どういったときに使えるか: ウェブアプリケーションに独自の右クリックメニューを実装したい場合や、ページの右クリックを禁止したい場合に使用します。イベントハンドラ内で event.preventDefault() を呼び出すことで、デフォルトのメニュー表示をキャンセルできます。

oninvalid

  • イベントの発生タイミング: フォームの送信時、入力要素が制約（例: required, pattern, type="email" など）を満たしていない場合に発生します。
  • どういったときに使えるか: ブラウザ標準のバリデーションエラーメッセージを、より分かりやすい独自のメッセージにカスタマイズしたい場合に使用します。

onreset

  • イベントの発生タイミング: <form> 要素上でリセットボタン (<input type="reset"> または <button type="reset">) がクリックされた時に発生します。
  • どういったときに使えるか: フォームがリセットされる直前にユーザーに確認を求めたり、フォームのリセットと同時にUIの状態を初期化したりする場合に使えます。

onscrollend

  • イベントの発生タイミング: ユーザーがスクロール操作を完了した時に発生します。onscroll イベントがスクロール中に連続して発生するのに対し、onscrollend はスクロールが止まったことを検知するのに便利です。
  • どういったときに使えるか: スクロールが止まったらヘッダーを再表示する、スクロール位置に基づいて分析データを送信する、「トップへ戻る」ボタンの表示/非表示を切り替えるなど。

ontoggle

  • イベントの発生タイミング: <details> 要素が開かれたり閉じられたりした時に発生します。
  • どういったときに使えるか: アコーディオンUIで、パネルが開かれた時だけ内部のコンテンツを遅延読み込み（lazy loading）したり、開閉に合わせてアニメーションを実行したりする場合に便利です。

onwheel

  • イベントの発生タイミング: 要素の上でマウスホイールが回転した時に発生します。
    どういったときに使えるか: 地図の拡大・縮小、画像のズーム、スライダーの値を細かく調整するなど、* デフォルトのスクロール以外のインタラクションを実装したい場合に使用します。

onsecuritypolicyviolation

  • イベントの発生タイミング: 文書のContent Security Policy (CSP)に違反する処理がブロックされた時に発生します。例えば、許可されていないドメインからスクリプトや画像を読み込もうとした場合などです。
  • どういったときに使えるか: 意図しないリソースの読み込みやインラインスクリプトの実行といったCSP違反を検知し、デバッグやセキュリティ監視のために分析サーバーへレポートを送信するのに使います。

onslotchange

  • イベントの発生タイミング: Shadow DOM 内の <slot> 要素に含まれるノード（DOMツリー）が変更された時に発生します。
  • どういったときに使えるか: Web Components を作成する際、コンポーネントの利用者がコンポーネントの特定のスロットに要素を追加・削除したことをコンポーネント自身が検知し、それに応じて内部のレンダリングを更新するなどの処理に使います。

onbeforematch

  • イベントの発生タイミング: CSSのcontent-visibility: hidden-matchable;が設定された非表示の要素が、ブラウザのページ内検索（Ctrl+Fなど）に一致する直前に発生します。
  • どういったときに使えるか: 長いリストや文書で、初期表示では要素をレンダリングせずにおき、ユーザーが検索して初めてその要素を表示・レンダリングする、といったパフォーマンス最適化に使えます。イベント発生時にコンテンツの読み込みなどを行えます。

onbeforetoggle

  • イベントの発生タイミング: Popover APIを利用したポップオーバー要素や、<details>要素の表示状態が切り替わる直前に発生します。このイベントはpreventDefault()でキャンセル可能です。
  • どういったときに使えるか: ポップオーバーやアコーディオンが開く直前に、コンテンツを非同期で読み込んだり、特定の条件を満たさない場合に開くのをキャンセルしたりできます。

oncancel / onclose (主に<dialog>要素)

  • イベントの発生タイミング:
    • oncancel: <dialog>要素が表示されている状態で、ユーザーがEscキーを押して閉じた（キャンセルした）時に発生します。
    • onclose: <dialog>が閉じた後に発生します。閉じる理由（Escキー、dialog.close()メソッドの呼び出しなど）は問いません。
  • どういったときに使えるか:
    • oncancel: ユーザーが明示的に操作を「キャンセル」したことを区別して処理したい場合（例: 入力内容を破棄する）。
    • onclose: ダイアログが閉じる際の共通のクリーンアップ処理（例: イベントリスナーの削除、一時データのクリア）を行いたい場合。

メディアイベントのグループ

oncanplay, ondurationchange, onloadedmetadata, onratechange, onseeked, onseeking, onvolumechange, onwaiting など、多くのイベントは <video> や <audio> 要素の状態変化を監視するために使われます。以下にまとめて例を示します。

  • イベントの発生タイミング:
    • onloadstart: 読み込み開始時
    • ondurationchange: 全長が判明・変更された時
    • onloadedmetadata: メタデータ（長さ、寸法など）の読み込み完了時
    • onloadeddata: 現在の再生位置のデータ読み込み完了時
    • oncanplay: 再生できる状態になった時
    • oncanplaythrough: スムーズな再生が可能と判断された時
    • onseeking: シーク（再生位置の移動）開始時
    • onseeked: シーク完了時
    • onwaiting: バッファリングで再生が中断した時
    • onratechange: 再生速度が変更された時
    • onvolumechange: 音量が変更された時
  • どういったときに使えるか: カスタムのビデオプレーヤーUIを作成する際に、これらのイベントを組み合わせて、ローディング表示、プログレスバー、再生時間、再生速度、音量などをきめ細かく制御します。

oncuechange (テキストトラック)

  • イベントの発生タイミング: <video>や<audio>要素に追加されたテキストトラック（字幕やキャプションなど）で、現在アクティブなキュー（表示されるべきテキストの区間）が変更された時に発生します。
  • どういったときに使えるか: ブラウザ標準の字幕表示を使わずに、独自のUIで字幕を表示したい場合や、字幕のタイミングに合わせてページ上の他の要素（例: 地図上のマーカー、関連情報パネル）を動的に更新したい場合に使います。

WebGL

oncontextlost / oncontextrestored

  • イベントの発生タイミング:
    • oncontextlost: WebGLのレンダリングコンテキストが失われた時に発生します。これは、GPUドライバのクラッシュやアップデート、OSの省電力モードへの移行、他のアプリケーションによるGPUリソースの大規模な使用など、様々な理由で起こり得ます。
    • oncontextrestored: 失われたWebGLコンテキストが復元された時に発生します。
  • どういったときに使えるか: WebGLを利用した3Dアプリケーションやゲームの堅牢性を高めるために不可欠です。oncontextlostで描画ループを停止し、oncontextrestoredでテクスチャやシェーダーなどのリソースを再作成して描画を再開する、といった処理を行います。

（コンテキストが中断されたり、リストアされたときのイベントなので通常見られません）

実験的であったり廃止されたもの

oncommand (廃止)

  • イベントの発生タイミング・用途: このイベントは、かつてHTML5で提案されていたコマンドAPIの一部でしたが、現在は廃止されており、どの主要なブラウザでもサポートされていません。 現代のウェブ開発で使用することはありません。

onwebkit... イベント群

  • イベントの発生タイミング:
    • onwebkitanimationstart: CSSアニメーションの開始時。
    • onwebkitanimationiteration: CSSアニメーションが反復する時。
    • onwebkitanimationend: CSSアニメーションの終了時。
    • onwebkittransitionend: CSSトランジションの終了時。
  • どういったときに使えるか: これらは、古いWebKitベースのブラウザ（古いChromeやSafariなど）との後方互換性のために存在した、ベンダープレフィックス付きのイベントです。現代のブラウザはプレフィックスなしの標準イベント（onanimationstart, ontransitionendなど）をサポートしているため、そちらを使用すべきです。

おわりに

以上がすべてのイベントハンドラです。あなたは何個知っていましたか？
よかったらコメントしたり、シェアしたりしてもらえると嬉しいです！☺️

Discussion