イベントオブジェクト


解説

jQueryのイベントシステムは W3Cの規格に基づいて実装されています。
イベントオブジェクトは、イベントハンドラの引数として渡されます。

イベント発生時には、イベントの種別や環境によって、さまざまな名称や状態でイベントオブジェクトが渡されます。

jQuery はこの違いを吸収し、イベントオブジェクトに対する統一されたインターフェースを提供します。 また、ネイティブイベントのほとんどのプロパティはマージされますので、それを使用することもできます。

jQuery のイベントオブジェクトを生成し、使用する例は、jQuery.Event(src) を参照してください。


イベントオブジェクトが持つプロパティとメソッドは次の通りです。

プロパティ

  • currentTarget : イベントのバブリングフェーズにおける現在のDOM要素
  • data : バインド時に渡されたデータ
  • pageX : イベント発生時の、マウスポインタのドキュメントの左端からの位置
  • pageY : イベント発生時の、マウスポインタのドキュメントの上端からの位置
  • namespace : イベントの名前空間
  • relatedTarget : 発生したイベントに関係する他のDOM要素(存在する場合のみ)
  • result : イベントハンドラが最後に返した値
  • target : イベント発生対象のDOM要素
  • timeStamp : イベント発生時のエポック秒(ミリ秒)
  • type : イベントの種別
  • which : キーボードイベントで押されたキーのコード

メソッド

関連


currentTarget

version 1.3 以降

イベントのバブリングフェーズにおける現在のDOM要素です。
つまり、イベントハンドラ内の this と同じオブジェクトです。

例:#parent_1 のクリックイベントの event.currentTarget の id を表示します。
バブリングフェーズにおけるイベントを捕捉するため、#child_1 をクリックしても表示されることを確認してください。
また、event.target (イベント発生対象のDOM要素) との違いを確認してください。

$("#parent_1").click(function(event){
    alert(
        "event.currentTarget: " + event.currentTarget.id + "\n" +
        "event.target:        " + event.target.id
    );
})

event.currentTarget テスト

#parent_1
#child_1

data

version 1.1 以降

イベントハンドラのバインド時に渡されたデータを返します。

例1:文字列をクリックすると、その要素を指定された速度と不透明度でフェードします。

$("#event_data li").bind(
    "click",                        // click イベントにバインド
    {speed:"slow", opacity:0.2},    // 第2引数に、速度と不透明度のデータを指定
    function(event){
        // event.data で、バインド時に渡されたデータを参照
        $(this).fadeTo(event.data.speed, event.data.opacity);
    }
);

event.data テスト

  • jQuery
  • prototype.js
  • Ext
  • script.aculo.us
  • YUI

pageX

version 1.0.4 以降

イベント発生時の、マウスポインタのドキュメントの左端からの位置を返します。

例:マウスの位置を表示します。

$("#test_pageX").bind("mouseenter mouseleave mousemove", function(event){
    $(".log", this).text("event.pageX: " + event.pageX + " " + "event.pageY: " + event.pageY);
})

event.pageX テスト

id=test_pageX


pageY

version 1.0.4 以降

イベント発生時の、マウスポインタのドキュメントの上端からの位置を返します。

例:マウスの位置を表示します。

$("#test_pageY").bind("mouseenter mouseleave mousemove", function(event){
    $(".log", this).text("event.pageX: " + event.pageX + " " + "event.pageY: " + event.pageY);
})

event.pageY テスト

id=pageY


namespace

version 1.4.3 以降

発生したイベントの名前空間を返します。
例えば、イベントハンドラで、異なる名前空間によって、処理を振り分ける場合等に使用します。

例:#namespace_test に発生したイベントの名前空間を取得し、toggleメソッドの duration として設定して実行。

// "toggle.fast" "toggle.slow" イベントをバインド
$("#namespace_test").bind("toggle.fast toggle.slow", function(event) {
    $("#namespace_view").text(event.namespace);
    $(this).toggle(event.namespace);    // 名前空間を取得し、toggleメソッドの duration として設定
});

// "toggle.fast" イベントをトリガ
$("#toggle_fast").click(function(event) {
    $("#namespace_test").trigger("toggle.fast");
});

// "toggle.slow" イベントをトリガ
$("#toggle_slow").click(function(event) {
    $("#namespace_test").trigger("toggle.slow");
});

event.namespace テスト

#namespace_test


event.namespace:

relatedTarget

version 1.1.4 以降

発生したイベントに関係する他のDOM要素(存在する場合のみ)を返します。
例えば、mouseout イベントの場合は、マウスポインタが該当要素から外れた直後に、マウスポインタがある要素になります。

例:#parent_2 要素の mouseout イベント発生時における event.relatedTarget 要素の id を表示します。

$("#parent_2").mouseout(function(event) {
    $("#test_relatedTarget_view").text("event.relatedTarget: " + event.relatedTarget.id);
})

event.relatedTarget テスト

#parent_2
#child_2

event.relatedTarget:


result

version 1.3 以降

イベントハンドラが最後に返した値です、
最後に返した値が無い場合は、 undefined になります。

例:「event.result テスト」 をクリックすると、バインドされている2つのイベントハンドラに渡された event.result を表示します。

// --- clickHandler1 ---
$("#test_event_result").click(function(event) {
    // このイベントで直前に返した値がないため、event.result は未定義 (undefined)となる。
    $(".log", this)
        .append("clickHandler1 - event.result : " + event.result + "<br />");
    
   return "clickHandler1";
});

// --- clickHandler2 ---
$("#test_event_result").click(function(event) {
    // event.result は clickHandler1 が返した値 "clickHandler1" となる。
    $(".log", this)
        .append("clickHandler2 - event.result (clickHandler): " + event.result);
});

event.result テスト


target

version 1.0 以降

イベント発生対象のDOM要素です。

例:#parent_3 のクリックイベントの event.target の id を表示します。
バブリングフェーズにおけるイベントを捕捉するため、#child_3 をクリックしても表示されることを確認してください。
また、event.currentTarget (イベントのバブリングフェーズにおける現在のDOM要素) との違いを確認してください。

$("#parent_3").click(function(event){
    alert(
        "event.target:        " + event.target.id + "\n" +
        "event.currentTarget: " + event.currentTarget.id
    );
})

event.target テスト

#parent_3
#child_3

timeStamp

version 1.2.6 以降

イベント発生時のエポック秒(ミリ秒)です。
(エポック秒 = 1970年1月1日0時0分0秒からの秒数)

例:「event.timeStamp テスト」をクリックすると、前回クリックした時からの差分を表示します。
x 秒ぴったりを目指せ!

var last;
$("#test_timeStamp").click(function(event) {
    if(last) {
        var diff = event.timeStamp - last;
        var mod = diff % 1000;

        $(".log", this).prepend(
            mod == 0 ?
                "<em>" + (diff / 1000) + " 秒ぴったり!!!(" + diff + ")</em>" :
            mod <= 10 || (diff < 1000 && diff >= 990) ?
                "前のクリックから " + diff + " ミリ秒 おしい!" :
            "前のクリックから " + diff + " ミリ秒"
        ).prepend("<br />");

    } else {
        $(".log", this).prepend("<br />もう一度クリック!");
    }
    last = event.timeStamp;
});

event.timeStamp テスト

x 秒ぴったりを目指せ!


type

version 1.0 以降

イベントの種別を表す文字列です。

例:「event.type テスト」にバインドされている、いずれかのイベントが発生した時に、イベント種別を表示します。

$("#test_type").bind("click dblclick mouseenter mouseleave", function(event) {
    $(".log", this).prepend("<br/>event.type: " + event.type);
});

event.type テスト


which

version 1.1.3 以降

キーボードイベントで押されたキーのコードを返します。
(マウスボタン等のボタンコードも返しますが、正規化できていないため使用しないでください。version 1.4.2)

例:テキストフィールドに文字を打つと、キーコードを表示します。

$("#test_which").bind("keydown", function(event) {
    $(".log", this)
        .prepend("<br/> + 
            " event.type: "  + event.type +
            " event.which: " + event.which
        );
});

event.which テスト


preventDefault()

version 1.0 以降

イベントのデフォルトの動作を停止します。

例:#preventdefaultのリンクをクリックした場合は、event.preventDefault()が実行され、リンク先のページに遷移しません。

$("#preventdefault").click(function(event) {
    // 背景色を緑にする
    $(this).css("backgroundColor", "#ecffed");

    // a 要素のデフォルトの動作を停止
    event.preventDefault();
})


isDefaultPrevented()

version 1.3 以降

preventDefault() が呼び出されたかどうかを返します。

例えば、カスタムイベントでデフォルトの動作を定義している場合は、trigger メソッドでイベントを発火後、このメソッドでデフォルトの動作を実行するかどうかを判断できます。

文字列をクリックすると、その文字列を背景色に設定します。(カスタムイベントのデフォルト動作) 最後の行だけ、アラートを表示し、デフォルトの動作を停止します。

// 最後の行だけ、アラートを表示し、デフォルトの動作を停止
$("#test_isDefaultPrevented li:last").bind("colorClickEvent", function(event, colorText) {
    alert(colorText);
    event.preventDefault();  // デフォルトの動作を停止
});

// --- カスタムイベント colorClickEvent の定義 ---
$("#test_isDefaultPrevented li").click(function(event) {
    var colorText = $(this).text();

    // イベントの発火
    var colorClickEvent = jQuery.Event("colorClickEvent");
    $(this).trigger(colorClickEvent, [colorText]);

    // デフォルトの動作
    if(!colorClickEvent.isDefaultPrevented()) {
        // デフォルトの動作が停止されていなければ背景色を変える
        $(this).css("background-color", colorText);
    }
});

isDefaultPrevented() テスト

  • lightgreen
  • yellow
  • #6495ed
  • #c0c0c0
  • orange

stopImmediatePropagation()

version 1.3 以降

イベントのバブリングを停止します。また、呼び出された以降の、バインドされている他のイベントハンドラを実行しないようにします。

例:"#child_4"をクリックすると、クリックイベントが上位の"#parent_4"まで伝播しますが、 "#stopImmediatePropagation"をクリックした場合は、event.stopImmediatePropagation()が実行され、クリックイベントが上位の"#stopImmediatePropagation"まで伝播しません。
また、他のイベントハンドラの実行を停止するため、"Other binding event!" は表示されません。

$("#parent_4").click(function(event){
    alert(event.target.id == event.currentTarget.id ? "parent_4 clicked!" : "click event bubbling!");
});

$("#child_4").click(function(event){
    alert("child_4 clicked!");
});

$("#stopImmediatePropagation").click(function(event) {
    alert("stopImmediatePropagation clicked!");
    
    // イベントバブリングと、他のイベントハンドラの実行を停止
    event.stopImmediatePropagation();
});

// このイベントハンドラは実行されない
$("#stopImmediatePropagation").click(function(event) {
    alert("Other binding event!");
});

stopImmediatePropagation() テスト

#parent_4
#child_4
#stopImmediatePropagation

isImmediatePropagationStopped()

version 1.3 以降

stopImmediatePropagation() が呼び出されたかどうかを返します。

例:stopImmediatePropagation() の状態を表示します。

$("#test_isImmediatePropagationStopped").click(function(event) {
    alert(event.isImmediatePropagationStopped());  // false
    event.stopImmediatePropagation();
    alert(event.isImmediatePropagationStopped());  // true
});

isImmediatePropagationStopped() テスト


stopPropagation()

version 1.0 以降

イベントのバブリングを停止します。

例:"#child_5"をクリックすると、クリックイベントが上位の"#parent_5"まで伝播しますが、 "#stopPropagation"をクリックした場合は、event.stopPropagation()が実行され、クリックイベントが上位の"#parent_5"まで伝播しません。

$("#parent_5").click(function(event) {
    alert(event.target.id == event.currentTarget.id ? "parent_5 clicked!" : "click event bubbling!");
});

$("#child_5").click(function(event) {
    alert("child_5 clicked!");
});

$("#stopPropagation").click(function(event) {
    alert("stopPropagation clicked!");
    
    // イベントバブリングを停止
    event.stopPropagation();
});

stopPropagation() テスト

#parent_5
#child_5
#stopPropagation

isPropagationStopped()

version 1.3 以降

stopPropagation() が呼び出されたかどうかを返します。

例:バグリングが停止されていた場合に、イベントハンドラ名を表示します。
clickHandler2 で stopPropagation() を呼び出し、バグリングを停止するので、clickHandler3 は表示されません。

// clickHandler1
$("#test_isPropagationStopped").click(function(event) {
    if(!event.isPropagationStopped()) {
        $(".log", this).append("clickHandler1<br/>");
    }
});

// clickHandler2
$("#test_isPropagationStopped").click(function(event) {
    if(!event.isPropagationStopped()) {
        $(".log", this).append("clickHandler2<br/>");
    }
    event.stopPropagation();
});

// clickHandler3
$("#test_isPropagationStopped").click(function(event) {
    if(!event.isPropagationStopped()) {
        $(".log", this).append("clickHandler3<br/>");
    }
});

isPropagationStopped() テスト