jQuery()の挙動を解読する(18) $(args).trigger()、$(args).triggerHandler()、$.event.trigger() 解読 ──jQuery解読(29)

• 「jQuery解読によるJavascript学習」関連エントリイ一覧 in this Blog

jQuery Event 解読 contents
全てのエントリイが ver1.2.2 対応に改訂済みです。

1. Eventオブジェクトの抽象性と特定化・個別化の必要性
2. Event API の概要と $(args).eventtype() メソッド解読
3. $(args).bind()、$(args).one()、$(args).toggle()、$(args).hover() 解読
4. $.event クラスメソッドの概要と $.event.add()、$.data() 解読
5. $.event.handle()、$.event.fix() 解読
6. $(args).trigger()、$(args).triggerHandler()、$.event.trigger() 解読
7. $(args).unbind()、$.event.remove()、$.removeData() 解読
8. $(document).ready(f)、bindReady()、$.ready() 解読
9. $.event.special[t].setup()、$.event.special[t].mouseenter()、$.event.special[t].mouseleave() 解読 (t="type")──これらのメソッドは ver1.2.2 で追加された
10. 終わりに

$(args).trigger()、$(args).triggerHandler()

これらのメソッドに該当するコードは jQuery.js ver1.2.2 の 2205-2215 行です。2214 行だけが1.2.1とことなる箇所で新規追加行になります。バグフィックスと言うところでしょう。

2205: trigger: function( type, data, fn ) {
2206: 　return this.each(function(){
2207: 　　jQuery.event.trigger( type, data, this, true, fn );
2208: 　});
2209: },
2210:
2211: triggerHandler: function( type, data, fn ) {
2212: 　if ( this[0] )
2213: 　　return jQuery.event.trigger( type, data, this[0], false, fn );
2214:　 return undefined;
2215: },

これらのインスタンスメソッドは、全く同様の引数をとり、共に対象要素に登録されている、type で指定されたイベントタイプに対応するイベントハンドラー関数を起動します。しかし、微妙に異なる引数(上のピンク色の２箇所)を $.event.trigger() に渡してこのクラスメソッドを起動し、このメソッドに全ての処理を委ねた上で処理結果を return します。したがってこれらの２つのインスタンスメソッドの挙動を知るには $.event.trigger メソッドを理解する必要があります。

しかしその前に、２つのメソッドの差異を外観しておきます。

• trigger インスタンスメソッドはその対象要素の各々に対して、jQuery.event.trigger メソッドを適用し、各々の結果を返します。他方、triggerHandler インスタンスメソッドは、対象要素の最初の１つの要素に対してだけ作用し結果を返します。 return 値は全て jQuery インスタンスです。
  なお、何故対象ノードを複数( trigger )と１つだけ( triggerHandler )に分けたのか、その理由は分かりません。triggerHandler() メソッドでも trigger() メソッド同様に、複数の要素ノードを対象として作動するようにしても問題はないと思われるのですが．．。
• trigger インスタンスメソッドは、対象要素に登録され、type で指定されたイベントタイプに対応するイベントハンドラー関数を起動し、かつ jQuery.event.trigger メソッドに渡される４番目の引数を true とすることにより、当該イベント発生時のブラウザ固有の動きを抑制しません。
• 他方、triggerHandler インスタンスメソッドは、対象要素に登録されているイベントタイプに対応するイベントハンドラー関数を起動させる点は trigger メソッドと同様ですが、jQuery.event.trigger メソッドに渡される４番目の引数を false とすることにより、type で指定されたイベントタイプに対応するブラウザ固有の動きを抑制します。

▲ToTop

$(args).trigger() と $(args).triggerHandler() の実例

更に、$.event.trigger() クラスメソッドの解読を行う前に、これらのインスタンスメソッドの実例を見ておきます。これらのメソッドが何を行うのか理解することが先決であり、本家 jQuery サイトにいくつかの例示がありますが、第三引数の fn を与えた例はなく、また例そのものが分かりやすいとは言えないからです。

独自に作成した $(args).trigger() メソッドの実例

例は、$(args).trigger() メソッドの引数が１つだけ、２つ及び３つの場合の各々の違いが分かるように３パターン作成し、更にtriggerされるイベントタイプも click、dblclick 及び mouseover の３種類とし、合計９つのパターンの例を作成しました。

複雑な挙動をするtrigger()インスタンスメソッドを十分に理解するには、これだけの例が必要でした。

使い方

• 下のカラーボックス上ではそれぞれの説明にあるマウスイベントタイプが発生します。この場合に起こることは、それぞれのボックスにバインドされたイベントハンドラーが、各々のイベント発生によって働いただけに過ぎません。
• これらの３つのボックスには同じ class 名 "Box" が振ってあり、トリガーメソッドの対象としてこの class 名をもつ３つのボックスを指定してあります。つまり jQuery(".Box").trigger(･･･)です。trigger() メソッドはこれらの３つの要素ノードにバインドされた、異なるイベントタイプのイベントハンドラーを励起させ得ることになります。
• カラーボックスの下にあるボタンが triggerメソッドを起動させる起動ボタンです。縦４行、横３列の10個のボタンがありますが、一番下のボタンは初期化ボタンで、他の各行は trigger メソッドの引数が異なり、各列はトリガーするイベントが異なります。各々はボタン名に書いてあるような設定となっており、各々のボタンに記されているような trigger() インスタンスメソッドがバインドされています。これらのボタンをクリックすると各々にバインドされた異なる trigger メソッドが呼び出され、trigger対象要素ノードにバインドされているイベントハンドラーをトリガー（励起）させます。
• １行目のボタンをクリックすると、３つの trigger メソッド対象要素ノードから、対象となるイベントタイプがバインドされている要素ノードだけのイベントがトリガーされます。当該イベントタイプがバインドされていない他の２つの要素ノードのイベントハンドラーは起動されません。
• ２行目のボタンには第２引数が与えられています。ここでも対象となるイベントハンドラーがバインドされている要素ノードだけが反応します。第２引数はトリガー先のイベントに情報などを付加する働きをし、各々のボタンをクリックするとボックスの下に文字列が現れます。これが付加された情報です。なお、再びクリックすると付加された文字列が消えるような toggle() メソッドが設定されています。
• ３行目のボタンは、３つの引数を与えた trigger メソッドをバインドしたものです。このボタンで初めて、triggerメソッドの対象要素ノードが３つのボタンであったことが明示的に明らかにされます。第３引数の fn 関数はイベントタイプに無関係に triggerメソッドの対象要素ノードの全てに作用するため、３行目のどのボタンをクリックしても、３つのボックスの背景色が同一色に変化します。
• しかし、その場合であっても trigger メソッドは、第１引数で指定されたイベントタイプがバインドされた要素ノードのイベントハンドラー関数だけを起動させるので、当該イベントタイプがバインドされた要素ノードのイベントハンドラーしか起動されません。
  ここで興味深いことが確認できます。ブルーボックスには click イベントがバインドされており、３行のボタンの第１列に登録されている trigger メソッドは イベントタイプ click を起動します。
  この結果、clickイベントがバインドされているボックス、ブルーボックス及びレッドボックスのイベントハンドラーが反応します。（レッドボックスにはダブルクリックで付加される文字を消すためにクリックイベントがバインドされています。）
  従って、例えばレッドボックスをダブルクリックした後に、第１列目の３つのいずれかのボタンをクリックすると、ブルーとレッドの２つのボックスのクリックイベントが励起（トリガー）されます。レッドボックスのその他の場合によるダブルクリック後においても同様です。

Box A：このボックスを click すると一旦透明化され、その後元に戻ります。

Box B：このボックスを double click するとボックス内に文字が増え、その後このボックスをクリックすると増えた文字が消えます。

Box C：このボックスに mouseover し続けると透明度が変化しながら上下にスライドし続けます。

1-1 trigger("click"）　1-2 trigger( "dblclick"）　1-3 trigger("mouseover")

2-1 trigger("click",data)
再度クリックすると
付加した文字を消します。 2-2 trigger("dblclick",data)
再度クリックすると
付加した文字を消します。 2-3 trigger("mouseover",data)
再度クリックすると
付加した文字を消します。

3-1 trigger("click",data,fn) 3-2 trigger("dblclick",data,fn) 3-3 trigger("mouseover",data,fn)

全てのカラーボックスと付加された文字列を初期化する

▲ToTop

$(args).triggerHandler() メソッドの実例

triggerHandler() メソッドは、後に $.event.trigger() メソッドの解読でその仕組みを明らかにしますが、trigger メソッドと異なるのは、ブラウザ既定の動作を停止させる点です。

ですから、既定の動作を持たないタイプのイベントがバインドされた要素ノードを対象として、このメソッドを適用しても何も意味がありません。

ここに既定の動作を持つイベントタイプには何があるのか、その点は不明です。分かっていることはfocus()、blur()、click()などの、a タグやinput、textarea タグなどが元々有しているメソッド名と一致するイベントタイプが「ブラウザ既定の動作を有する」ということが出来るであろうことです。

さて、実例を作ってみようとしたのですが、jQuery本家サイト以上のそれは作れませんでしたので、本家サイトの例を引用して解説しようと思います。

本家サイトからの引用サンプル

Button1 .trigger("focus") Button2 .triggerHandler("focus")
  

1. input ボックスにはイベントタイプ focus のイベントハンドラーが登録されています。ハンドラー関数によりフォーカスが input ボックスに移ると Focused! という文字を表示してから、フェードアウトします。
   そのことを確認するには input ボックス内でマウスをクリックすれば分かります。その末尾に Focused! と表示され、その後1.5秒掛けてフェードアウトします。これが設定されている focus イベントの発生と実行です。
2. 次に、マウスを input ボックス外でクリックしてフォーカスをはずしてから、Button1 をクリックします。すると inputタグ既定の focus イベントが起動して、 Focused! と表示し、かつ trigger されたイベントハンドラーが Focused! と表示します。つまり２つの Focused! が表示されます。そして共に1.5秒間でフェードアウトします。この時、input ボックスがフォーカスされ、マウスカーソルがその中で点滅していることを確認できます。
   ここでは、input タグに設定された focus イベントのデフォルト動作（＝フォーカスすると言う動作）が trigger() メソッドによって行われ、同時に trigger() メソッドによってイベントハンドラー関数が起動されたため、２つの文字が表示されたことになります。
   なお、これまでのことはIEでの確認です。Firefox と Opera ではこの違いが出現せず、trigger() でも triggerHandler() でも結果は変わりませんでした。理由は不明です。
3. 次に、念のために input ボックス外でクリックしてフォーカスをはずしてから、Button2 をクリックします。すると focus イベントハンドラーが起動して、Focused! と表示され1.5秒間でフェードアウトします。しかし、今度は input タグ内にフォーカスは当たっていません。input ボックス内でマウスカーソルは点滅していません。また表示される Focused! も１つだけです。
   これで triggerHandler() メソッドと trigger() メソッドとの効果の違いが確認出来ました。

▲ToTop

$.event.trigger()

愈々、trigger() 及び triggerHandler() がどのようにして作用しているのか、その挙動を探ります。これらの２つのメソッドから呼び出される $.event.trigger() を解読します。

$.event.trigger() の引数について

trigger() クラスメソッドは type、data、elem、donative 及び extra の５つの引数を取ります。

これらは順に、

• tyoe: 励起させたいイベントタイプ
• data: type イベント発生時のイベントオブジェクト並びに trigger により励起させるハンドラー関数で利用させる引数によって構成される配列オブジェクト
• elem: type イベントを発生させる要素ノード（トリガー先とでも言うべきか）
• donative: typeイベントによるブラウザのデフォルト動作を行わせるか（true）、行わせないか（false）を指定する真偽値
• extra: trigger() メソッドによって type イベントを発生させた時に起動させる、イベントハンドラー関数とは別の、独自に指定する関数

を意味しています。

1.　第２引数 data の処理

data 引数を配列にし、data がなければ空の配列を作り data に代入する。data には trigger メソッドを起動させたイベントオブジェクトなどを記述する。

1962: trigger: function(type, data, elem, donative, extra) {
1963: 　// Clone the incoming data, if any
1964: 　data = jQuery.makeArray(data || []);
1965:

2.　トリガー対象 (elem) が指定されていない場合の処理

第３引数の elem がない場合の処理です。この場合において、当該頁にイベントが登録されていれば、全てのノードを対象としてtrigger()メソッドを再帰呼び出しし、イベントが全く登録されていなければ何もしません。

1966: 　// Handle a global trigger
1967: 　if ( !elem ) {　//elem が指定されていなければ
1968: 　　// Only trigger if we've ever bound an event for it
1969: 　　if ( this.global[type] )　//typeイベントが登録されていれば
　　　　　　// 全てのノードを対象として trigger クラスメソッドを再帰呼び出しする。
1970: 　　　jQuery("*").add([window, document]).trigger(type, data);
1971:

3.　１つの対象ノードに対する処理 (1) イベントハンドラー起動前の処理

1972: 　// Handle triggering a single element
　　　　// １の要素ノードを trigger 対象とする。
1973: 　} else {

　/* elem がテキストやコメントだった場合
　 * 何もせずに undefined を返す。
　 */ 
1974: // don't do events on text and comment nodes
1975: if ( elem.nodeType == 3 || elem.nodeType == 8 )
1976: return undefined;
1977:
　/* elem[type] が関数ならば fn = true、違えば fn = false とする。
　 * この elem[type] は突然登場し、このメソッド以外では使われていない。
　 * これはブラウザ固有の type メソッドが elem に指定されている場合に
　 * 部分であり、2010-2017 行に連動する。
　 */
1978: 　　var val, ret, fn = jQuery.isFunction( elem[ type ] || null ),

　/* data 配列が空ならば、あるいは data 配列の最初の要素に preventDefault
　 * プロパティがなければ（つまりそれがイベントオブジェクトでなければ）
　 * evt = true とする。その他の場合には evt = false とする。
　 * こうすることにより、イベントオブジェクトが第一引数にない場合において
　 * var evt = true としてダミーイベントを用意する準備をしている。
　 */
1979:　　 // Check to see if we need to provide a fake event, or not
1980: 　　evt = !data[0] || !data[0].preventDefault;
1981:

　// ダミーのイベントオブジェクトを作って data 配列の先頭要素とする。
　// その type プロパティは type、target プロパティは elem とする。
1982: 　　// Pass along a fake event
1983: 　　if ( evt )
1984: 　　　data.unshift( this.fix({ type: type, target: elem }) );
1985:

　/* data の最初の要素としてユーザーが指示したイベントオブジェクト、
　 * 又は 1721 行で作ったダミーのイベントオブジェクトの、type 
　 * プロパティを type とする。
　 * これは専らダミーイベントへの対応策であって、イベントオブジェクトの
　 * type プロパティを与える目的のための行である。そうしないとダミーイベ
　 * ントとして用を為さないから。
　 */
1986: 　　// Enforce the right trigger type
1987: 　　data[0].type = type;
1988:

4.　１つの対象ノードに対する処理 (2) イベントハンドラー関数の起動その１

elem に対応する cache.id オブジェクトの "handle" プロパティ値が存在し、それが関数であれば、data を引数とする関数を elem のメソッドとして実行する。ここに data[0] はこれまでの処理でイベントオブジェクトとなっている。

これにより指定した type イベントに対応して登録されているイベントハンドラー関数が呼び出され、実行される。なお、当該関数の返値がvalに代入される。

1989: 　　// Trigger the event
1990: 　　if ( jQuery.isFunction( jQuery.data(elem, "handle") ) )
1991: 　　　val = jQuery.data(elem, "handle").apply( elem, data );
1992:

5.　１つの対象ノードに対する処理 (3) イベントハンドラー関数の起動その２

(1)fn が存在せず、(2)elemに "on"+type 属性があり、(3)その属性値である関数を data を引数として実行して return 値が false ならばval に false を代入する。

これにより"on"+type 属性値である関数が励起・実行される。しかし、この行の起動を確認することは出来なかった。

1993: 　　// Handle triggering native .onfoo handlers
1994: 　　if ( !fn && elem["on"+type] && elem["on"+type].apply( elem, data ) === false )
1995: 　　val = false;
1996:

6.　１つの対象ノードに対する処理 (4) 固有に指定した関数 extra の起動

　// まずダミーイベントが設定されていれば、それを data 配列から削除する。
1997: 　　// Extra functions don't get the custom event object
1998: 　　if ( evt )
1999: 　　　data.shift();
2000:

　/* 次の部分は ver 1.2.2で大きく変わった箇所です。
　 * extra が既述されていてそれが関数の場合に、 val の値があれば data 配列に
　 * その値を結合し、なければ data のままで、その配列を引数として当該関数を実
　 * 行し、retに実行結果を返す。
　 * この場合、1998-1999 行によりダミーイベントは削除されている一方、最初に
　 * data にイベントオブジェクトが記述されていれば、それが引数として使われる。
　 */
2001: 　　// Handle triggering of extra function
2002: 　　if ( extra && jQuery.isFunction( extra ) ) {
2003: 　　　// call the extra function and tack the current return value on the end for possible inspection
2004: 　　　ret = extra.apply( elem, val == null ? data : data.concat( val ) );

　/* もし何かが返されれば、それを優先的に val に代入してvalを上書きする。
2005: 　　　// if anything is returned, give it precedence and have it overwrite the previous value
2006: 　　　if (ret !== undefined)
2007: 　　　　val = ret;
2008: 　　}

7.　１つの対象ノードに対する処理 (5) ブラウザ固有のメソッドの扱い

(1)fn が存在し、(2)donative が trueで、(3)val も true で、(4)elem が a 要素でなく、(5)type が click でないならば、triggerd の値を true としてから、elem[type]()メソッドを実行する。

この部分は donative に関わる部分、つまりブラウザ固有の動きをさせるか、させないかを決める部分である。

trigger() インスタンスメソッドの場合には donative = true として jQuery.event.trigger() メソッドが起動されるので、elem[type]() が実行される。しかし、triggerHandler() メソッドの場合には donative = false として jQuery.event.trigger() メソッドが起動されるため、ブラウザ固有のメソッドすなわち elem[ type ]() は起動されない。

2010: 　　// Trigger the native events (except for clicks on links)
2011: 　　　if ( fn && donative !== false && val !== false && !(jQuery.nodeName(elem, 'a') && type == "click") ) {
　　　　　　//次の行は1843行（in add() クラスメソッド）に関わる。
2012: 　　　　this.triggered = true;
2013: 　　　　try {
2014:	　　　　elem[ type ]();
2015 　　　　 // prevent IE from throwing an error for some hidden elements
2016 　　　　 } catch (e) {}
2017: 　　　}
2018:
2019: 　　　this.triggered = false;
2020: 　}

8.　１つの対象ノードに対する処理 (6) 終了処理

2021:
2022: 　return val;
2023: },
2024: