ウェブプラットフォームでは、DOM イベントの通知を受け取るための方法をいくつか提供しています。よく使われる方法は2つあり、 {{domxref("EventTarget.addEventListener", "addEventListener()")}} と、特定の onevent ハンドラーです。このページでは、後者がどのように機能するのかについて注目します。
onevent ハンドラーは特定の DOM 要素のプロパティで、その要素がイベントに対してどのように反応するかを管理します。要素には、対話的なもの (リンク、ボタン、画像、フォームなど) と対話的ではないもの (基本の <body> 要素など) があります。イベントとは、以下のようなアクションのことです。
onevent ハンドラーは通常、onclick, onkeypress, onfocus など、反応するイベントに従って名前が付けられています。
on<…> イベントハンドラーを指定することで、指定されたオブジェクトの特定のイベント ({{event("click")}} など) に対してさまざまな方法で指定することができます。
on<eventtype> という名前の HTML {{Glossary("attribute", "属性")}}を追加する方法。<button onclick="handleClick()">,document.querySelector("button").onclick = function(event) { … }.onevent イベントハンドラープロパティは、1 つのイベントハンドラーを割り当てることができる一種のプレースホルダーとして機能します。与えられたオブジェクト上の同じイベントに対して複数のハンドラーをインストールできるようにするには、その addEventListener() メソッドを呼び出して、オブジェクト上の与えられたイベントに対するハンドラーのリストを管理することができます。ハンドラーは、その {{domxref("EventTarget.removeEventListener", "removeEventListener()")}} 関数を呼び出すことで、オブジェクトから削除することができます。
要素に適用されるイベントが発生すると、そのイベントハンドラーが次々と呼び出され、イベントを処理できるようになります。自分で呼び出す必要はありませんが、多くの場合、イベントの発生を簡単にシミュレートするために呼び出すことができます。例えば、ボタンオブジェクト myButton を指定した場合、 myButton.onclick(myEventObject) を実行することでイベントハンドラーを直接呼び出すことができます。イベントハンドラーがイベントオブジェクトからデータにアクセスしない場合は、 onclick() を呼び出すときにイベントを省略することができます。
これは、イベントハンドラーのいずれかがイベントオブジェクト自身に対して {{domxref("Event.stopPropagation", "stopPropagation()")}} を呼び出すことでイベントの処理を明示的に停止しない限り、すべてのハンドラーが呼び出されるまで続きます。
イベントハンドラーはまた、 {{ domxref("window") }}, {{ domxref("document") }}, {{ domxref("XMLHttpRequest") }} などを含む、イベントを生成する多くの要素以外のオブジェクトのプロパティを使用して設定することもできます。例えば、 progress イベントが XMLHttpRequest のインスタンスで発生した場合は次のようになります。
const xhr = new XMLHttpRequest();
xhr.onprogress = function() { … };
HTML 要素には onevent という名前の属性があり、これを利用して HTML コード内に直接イベントのハンドラーを登録することができます。要素が HTML から構築されると、その onevent 属性の値がその要素を表す DOM オブジェクトにコピーされるので、JavaScript を使って属性の値にアクセスすると、HTML で設定された値が得られます。
HTML の属性値への更なる変更は {{domxref("Element/setAttribute", "setAttribute")}} メソッドで行うことができます。 JavaScript プロパティを変更しても効果あありません。
このような HTML 文書があったとします。
<p>Demonstrating quirks of <code>on<em>event</em></code> HTML attributes on
<a onclick="log('Click!')">these three words</a>.
</p>
<div></div>
この JavaScript は、 HTML 属性の値が JavaScript オブジェクトのプロパティの変更によって影響を受けないことを示しています。
let logElement = document.querySelector('div');
let el = document.querySelector("a");
function log(msg) { logElement.innerHTML += `${msg}<br>` };
function anchorOnClick(event) { log("Changed onclick handler") };
// Original Handler
log(`Element's onclick as a JavaScript property: <code> ${el.onclick.toString()} </code>`);
//Changing handler using .onclick
log('<br>Changing onclick handler using <strong> onclick property </strong> ');
el.onclick = anchorOnClick;
log(`Changed the property to: <code> ${el.onclick.toString()} </code>`);
log(`But the HTML attribute is unchanged: <code> ${el.getAttribute("onclick")} </code><br>`);
//Changing handler using .setAttribute
log('<hr/><br> Changing onclick handler using <strong> setAttribute method </strong> ');
el.setAttribute("onclick", 'anchorOnClick(event)');
log(`Changed the property to: <code> ${el.onclick.toString()} </code>`);
log(`Now even the HTML attribute has changed: <code> ${el.getAttribute("onclick")} </code><br>`);
{{ EmbedLiveSample('HTML_onevent_attributes', '', '', '', 'Web/Guide/Events/Event_handlers') }}
歴史的な理由から、{{HTMLElement("body")}} および {{HTMLElement("frameset")}} 要素の一部の属性/プロパティは、実際にはその親 {{domxref("Window")}} オブジェクトにイベントハンドラーを設定します。(HTML 仕様はこれらを {{domxref("GlobalEventHandlers/onblur", "onblur")}}, {{domxref("GlobalEventHandlers/onerror", "onerror")}}, {{domxref("GlobalEventHandlers/onfocus", "onfocus")}}, {{domxref("GlobalEventHandlers/onload", "onload")}}, {{domxref("GlobalEventHandlers/onscroll", "onscroll")}} と命名しています。)
イベントハンドラーが HTML 属性として指定されている場合、指定されたコードは次の引数を持つ関数にラップされます。
event - {domxref("GlobalEventHandlers.onerror", "onerror")}} を除くすべてのイベントハンドラー。event, source, lineno, colno, error - {{domxref("GlobalEventHandlers.onerror", "onerror")}} のイベントハンドラー。なお、 event 引数には、実際にはエラーメッセージが文字列として含まれています。イベントハンドラーが呼び出されると、ハンドラー内の this キーワードは、ハンドラーが登録されている DOM 要素に設定されます。詳しくは、this キーワードのドキュメントを参照してください。
ハンドラーからの返値は、イベントが取り消されるかどうかを決定します。返値値の具体的な処理はイベントの種類によって異なります。詳細については、HTML 仕様の「イベントハンドラー処理アルゴリズム」を参照してください。
作成中 (非捕獲リスナー)
イベントハンドラーという用語は、次のように使用されます。
<button onclick="alert(this)"> や window.onload = function() { … }など、HTML の on… 属性または Web API のプロパティを介してイベントリスナーを登録するメカニズム。イベントを待ち受けするためのさまざまな方法を議論するときは、
on... 属性またはプロパティを介して登録された関数を指します。| 仕様書 | 状態 | 備考 |
|---|---|---|
| {{SpecName('HTML WHATWG', 'webappapis.html#event-handler-attributes', 'event handlers')}} | {{Spec2('HTML WHATWG')}} | |
| {{SpecName('HTML5 W3C', 'webappapis.html#event-handler-attributes', 'event handlers')}} | {{Spec2('HTML5 W3C')}} |
JavaScript の {{jsxref("Operators/in", "in")}} 演算子でイベントハンドラープロパティの存在を検出することができます。例えば、以下のようになります。
if ("onsomenewfeature" in window) {
/* do something amazing */
}
DOM プロトタイプオブジェクトには、IDL で定義された属性の値を設定したり、アクセスしたりすることはできません。つまり、例えば Window.prototype.onload を変更することはできません。以前は、 Gecko では イベントハンドラー (onload など) が IDL 属性として実装されていなかったので可能だったのですが、現在はできなくなりました。これにより互換性が向上します。