MDN’s new design is in Beta! A sneak peek:



Web平台提供了多种方式来获取 DOM events 的通知。种常见的风格是:广义 addEventListener() 和一组特定的on-event处理程序。本页重点介绍后者如何工作的细节。

注册on-event 处理程序

事件处理程序是由DOM元素(包括交互式的 - 例如链接,按钮,图像,表单 - 和不是)提供的一组属性,基本文档本身等,以帮助管理该元素对事件的反应,像点击,检测按下的键,获得焦点等,并且它们通常被相应地命名,诸如onclick,onkeypress,onfocus等。

You can specify an on<...> event handler for a particular event (such as click) for a given object in different ways:

  • Using an HTML attribute named on{eventtype} on an element, for example:
    <button onclick="return handleClick(event);">,
  • Or by setting the corresponding property from JavaScript, for example:
    document.getElementById("mybutton").onclick = function(event) { ... }.

Note that each object can have only one on-event handler for a given event (though that handler could call multiple sub-handlers). This is why addEventListener() is often the better way to get notified of events, especially when wishing to apply various event handlers independently from each other, even for the same event and/or to the same element.

Also note that on-event handlers are called automatically, not at the programmer's will (although you can, like  mybutton.onclick(myevent); ) since they serve more as placeholders to which a real handler function can be assigned.


Event handlers can also be set using properties on many non-element objects that generate events, including window, document, XMLHttpRequest, and others, for example:

xhr.onprogress = function() { ... }


HTML的 on<...> 属性值 和相应JavaScript

A handler registered via an on<...> attribute will be available via the corresponding on<...>property, but not the other way around:

<div id="a" onclick="alert('old')">Open the Developer Tools Console to see the output.</div>

window.onload = function () {
  var div = document.getElementById("a");
  console.log("Attribute reflected as a property: ", div.onclick.toString());
  // Prints: function onclick(event) { alert('old') }
  div.onclick = function() { alert('new') };
  console.log("Changed property to: ", div.onclick.toString());
  // Prints: function () { alert('new') }
  console.log("Attribute value is unchanged: ", div.getAttribute("onclick"));
  // Prints: alert('old')

For historical reasons, some attributes/properties on the <body> and <frameset> elements actually set event handlers on their parent Window object. (The HTML specification names these: onbluronerroronfocusonloadonscroll.)

事件处理程序的参数,this 绑定和返回值

When the event handler is specified as an HTML attribute, the specified code is wrapped into a function with the following parameters:

  • event - for all event handlers, except onerror.
  • eventsourcelinenocolno, and error for the onerror event handler. Note that the eventparameter actually contains the error message as string.

When the event handler is invoked, the this keyword inside the handler is set to the DOM element on which the handler is registered. For more details see the this keyword documentation.

The return value from the handler determines if the event is cancelled. The specific handling of the return value depends on the kind of event, for details see "The event handler processing algorithm" in the HTML specification.


TBD (non-capturing listener)


The term event handler may be used to refer to:

  • any function or object registered to be notified of events,
  • or, more specifically, to the mechanism of registering event listeners via on... attributes in HTML or properties in web APIs, such as <button onclick="alert(this)"> or window.onload = function() { /* ... */ }.

When discussing the various methods of listening to events,

  • event listener refers to a function or object registered via EventTarget.addEventListener(),
  • whereas event handler refers to a function registered via on... attributes or properties.


Specification Status Comment
WHATWG HTML Living Standard
event handlers
Living Standard  
event handlers


Feature Chrome Firefox (Gecko) Internet Explorer Opera Safari (WebKit)
Basic support (Yes) (Yes) (Yes) (Yes) (Yes)
Feature Android Firefox Mobile (Gecko) IE Mobile Opera Mobile Safari Mobile
Basic support (Yes) (Yes) (Yes) (Yes) (Yes)

Event handler changes in Firefox 9

In order to better match the specifications, and improve cross-browser compatibility, the way event handlers were implemented at a fundamental level changed in Gecko 9.0 (Firefox 9.0 / Thunderbird 9.0 / SeaMonkey 2.6).

Specifically, in the past, event handlers were not correctly implemented as standard IDL attributes. In Gecko 9.0, this was changed. Because of this, certain behaviors of event handlers in Gecko have changed. In particular, they now behave in all the ways standard IDL attributes behave. In most cases, this shouldn't affect web or add-on content at all; however, there are a few specific things to watch out for.

Detecting the presence of event handler properties

You can now detect the presence of an event handler property (that is, for example, onload), using the JavaScript in operator. For example:

if ("onsomenewfeature" in window) {
  /* do something amazing */

Event handlers and prototypes

You can't set or access the values of any IDL-defined attributes on DOM prototype objects; that means you can't, for example, change Window.prototype.onload anymore. In the past, event handlers (onload, etc) weren't really implemented as IDL attributes in Gecko, so you were able to do this for those. Now you can't. This improves compatibility.


 此页面的贡献者: Le-Fu, xgqfrms-GitHub, ziyunfei, Darrel.Hsu
 最后编辑者: Le-Fu,