ドキュメント

Events/jQuery.Event

From jQuery JavaScript Library

Jump to: navigation, search

jQuery's event system normalizes the event object according to W3C standards. The event object is guaranteed to be passed to the event handler (no checks for window.event required). Most properties from the original event are copied over to our wrapper object.


Contents

jQuery.Event

The object constructor is exposed and can be used when calling trigger.
You don't need to use the new operator, it is optional.

Check trigger's documentation to see how to combine it with your own event object.

Example:

Create a new jQuery.Event object without the new operator.

var e = jQuery.Event("click"); 


Example:

Create a new jQuery.Event object with the new operator.

var e = new jQuery.Event("click"); 


Attributes

event.type

Describes the nature of the event.

Return value: String
Example:

$("a").click(function(event) {
  alert(event.type);
});
Result:
 "click"


event.target

Contains the DOM element that issued the event.
This can be the element that registered for the event or a child of it.

Fixed where necessary (IE, Safari).

Use to implement event delegation.

Return value: Element
Example:

$("a[href=http://google.com]").click(function(event) {
  alert(event.target.href);
});
Result:
"http://google.com"


Example:

Implements a simple event delegation: The click handler is added to an unordered list, and the children of it's li children are hidden. Clicking one of the li children toggles (see toggle()) their children.

function handler(event) {
  var $target = $(event.target);
  if( $target.is("li") ) {
    $target.children().toggle();
  }
}
$("ul").click(handler).find("li > ").hide();


event.data

Contains the optional data passed to jQuery.fn.bind when the current executing handler was bound.

Return value: Anything
Example:

$("a").each(function(i) {
  $(this).bind('click', {index:i}, function(e){
     alert('my index is ' + e.data.index);
  });
});


event.relatedTarget

On mouse movement, contains the DOM element which the mouse was previously on when moving onto or off of an element.

Fixed where necessary.

Return value: Element
Example:

$("a").mouseout(function(event) {
  alert(event.relatedTarget);
});


event.currentTarget

The current DOM element within the event bubbling phase. This attribute will always be equal to the this of the function.

Return value: Element
Example:

$("p").click(function(event) {
  alert( event.currentTarget.nodeName );
});
Result:
"P"


event.pageX/Y

The pageX/Y property pair returns the mouse coordinates relative to the document.

Fixed where necessary (IE).

Return value: String
Example:

$("a").click(function(event) {
  alert("Current mouse position: " + event.pageX + ", " + event.pageY );
});
Result:
"Current mouse position: 130, 640"


event.result

Will contain the last value returned by an event handler (that wasn't undefined).

Return value: Anything
Example:

$("p").click(function(event) {
  return "hey"
});
$("p").click(function(event) {
  alert( event.result );
});
Result:
"hey"


event.timeStamp

The timestamp (in milliseconds) when the event was created.

Return value: Number
Example:

var last;
$("p").click(function(event) {
   if( last )
      alert( "time since last event " + event.timeStamp - last );
   last = event.timeStamp;
});


Methods

event.preventDefault()

Prevents the browser from executing the default action. Use the method isDefaultPrevented to know whether this method was ever called (on that event object).

Fixed where necessary (IE).

Return value: undefined

Example:

Stops the browser from changing the page to the href of any anchors.

$("a").click(function(event){
  event.preventDefault();
  // do something
});


event.isDefaultPrevented()

Returns whether event.preventDefault() was ever called on this event object.

Return value: true/false

Example:

Checks whether event.preventDefault() was called.

$("a").click(function(event){
  alert( event.isDefaultPrevented() );
  event.preventDefault();
  alert( event.isDefaultPrevented() );
});


event.stopPropagation()

Stops the bubbling of an event to parent elements, preventing any parent handlers from being notified of the event.

Note that this will not prevent other handlers on the same element from running. This method works for custom events triggered with trigger, as well.

Use the method event.isPropagationStopped() to know whether this method was ever called (on that event object).

Fixed where necessary (IE).

Return value: undefined

Example:

Prevents other event handlers from being called.

$("p").click(function(event){
  event.stopPropagation();
  // do something
});


event.isPropagationStopped()

Returns whether event.stopPropagation() was ever called on this event object.

Return value: true/false

Example:

Checks whether event.stopPropagation() was called.

$("p").click(function(event){
  alert( event.isPropagationStopped() );
  event.stopPropagation();
  alert( event.isPropagationStopped() );
});


event.stopImmediatePropagation()

Keeps the rest of the handlers from being executed.
This method also stops the bubbling by calling event.stopPropagation().

Use event.isImmediatePropagationStopped() to know whether this method was ever called (on that event object).

Return value: undefined

Example:

Prevents other event handlers from being called.

$("p").click(function(event){
  event.stopImmediatePropagation();
});
$("p").click(function(event){
  // This function won't be executed
});


event.isImmediatePropagationStopped()

Returns whether event.stopImmediatePropagation() was ever called on this event object.

Return value: true/false

Example:

Checks whether event.stopImmediatePropagation() was called.

$("p").click(function(event){
  alert( event.isImmediatePropagationStopped() );
  event.stopImmediatePropagation();
  alert( event.isImmediatePropagationStopped() );
});



Special Events

jQuery has a Special Events API so you can add events with custom functionality, allowing you to bypass some of the internal jQuery event system.

For a custom event you can add add, setup, remove, teardown and handler functions.

For more detail: