Widget Factory

全てのjQuery UI ウィジットとで使用されているものと同じ基盤となる仕組みを使用して、jQueryプラグインを作成することが出来ます。

$.widget( name [, base ], prototype )

キー説明
name

型:String

名前空間を含む、生成するウィジットの名前を指定します。

base

型:Function()

継承するベースとなるウィジットを指定します。 これは"new"によってインスタンス化できるコンストラクタでなくてはなりません。 デフォルトはjQuery.Widgetになっています。

prototype

型:PlainObject

ウィジットのためのプロトタイプとして使用するオブジェクトを指定します。

$.Widgetオブジェクトを継承して、新しいウィジットを作成することが可能です。 また、存在するjQuery UIやサードパーティのウィジットを継承することも可能です。

継承先と同じ名前のウィジットを定義することで、所定の位置にウィジットを拡張することが出来ます。

jQuery UIの状態を維持するため、典型的なjQueryプラグインとは若干異なる使用パターンを持っている ウィジェットが多く含まれています。 全てのjQuery UIのウィジットは同じパターンを使用し、それはwidget factoryによって定義されています。
そのため、もし1つのウィジットの使用方法を学ぶのであれば、それは全てのウィジットの使用方法を学ぶことに繋がります。

※注:このドキュメントでは、例としてプログレスバーを取り上げますが、 記法は全てのウィジットで共通です。

初期化

ウィジェットの状態を追跡するために、ウィジェットの完全なライフサイクルを把握する必要があります。 ウィジェットが初期化された時にライフサイクルが開始されます。 ウィジェットを初期化するには、単に1つまたは複数の要素に対して、プラグインを呼び出します。

$( "#elem" ).progressbar();

この場合、"elem"というid属性を持つ要素のjQueryオブジェクト内の各要素が初期化されます。 引数無しでprogressbar()を呼び出したため、ウィジットはデフォルトのオプションで初期化されます。 デフォルトのオプションを上書きするために、初期化時にオプションのセットを渡すことが出来ます。

$( "#elem" ).progressbar({ value: 20 });

初期化時に必要なだけオプションを渡すことができますが、 いくつかの渡す事が出来ないオプションは、初期値が使用されます。

オプションはウィジットの状態の一部で、初期化の後にoptionメソッドを使って設定することが可能です。

メソッド

ウィジェットが初期化されると、その状態を参照または上でウィジェットを操作することが出来ます。 全てのアクションは初期化後に、メソッド呼び出しの型を取ります。 ウィジット上でメソッドを呼び出すために、メソッド名をjQueryプラグインに渡します。 例えば、プログレスバー・ウィジットのvalue()メソッドを呼び出すためには、次のようにします。

$( "#elem" ).progressbar( "value" );

もし、メソッドが引数を受け付ける場合、メソッド名の後にそれを渡すことが出来ます。 例えば、value()メソッドに引数として40を渡す場合は、次のようにします。

$( "#elem" ).progressbar( "value", 40 );

jQueryのメソッドのように、多くのウィジットのメソッドはメソッドチェーンのためにjQueryオブジェクトを返します。

$( "#elem" )
  .progressbar( "value", 90 )
  .addClass( "almost-done" );

各ウィジットは、widgetから提供された機能がベースとなった独自のメソッドのセットを持っています。 しかし、以下に記載されているメソッドの中には、全てのウィジットに存在するメソッドもあります。

イベント

すべてのウィジェットには、状態が変更された事を通知するように、様々な動作に関連付けられているイベントがあります。 ほとんどのウィジットで、イベントがトリガされた際のイベント名に、プレフィックスとしてウィジット名が付けられています。 例えば、プログレスバーの値が変更される度にトリガされるchangeイベントを、下記のように登録することが出来ます。

$( "#elem" ).bind( "progressbarchange", function() {
  alert( "値が変更されました!" );
});

各イベントはオプションとして公開され、対応するコールバックを持っています。 progressbarchangeイベントを登録する代わりに、次のようにchangeコールバックをフックさせることが出来ます。

$( "#elem" ).progressbar({
  change: function() {
    alert( "値が変更されました!" );
  }
});

全てのウィジットは、インスタンス化される際にトリガされるcreateイベントを持っています。

オプション 説明
disabled

trueを指定すると、jQueryウィジェットを無効にします。

型:Boolean
初期値:false

hide

hideアニメーションの指定をします。

型:Boolean or Number or String or Object
初期値:null

Boolean
falseを指定すると、アニメーションがOFFになります。 trueを指定すると、デフォルトのフェードアウトアニメーションが適用されます。
Number
指定されたミリ秒で、デフォルトのイージングでフェードアウトアニメーションが適用されます。
String
指定されたエフェクト名で要素が非表示になります。 "slideUp"のようなjQueryの組み込みメソッド、または"fold"のようなjQuery UIのエフェクトのどちらかのエフェクト名を指定します。 どちらを指定しても、Durationとイージングはデフォルトのものが適用されます。
Object
オブジェクト型を指定した場合、effect、duration、easingのプロパティが提供されます。 effectプロパティはjQueryメソッド名が指定されればそれを使用し、それ以外の場合はjQuery UIのエフェクト名とみなします。 jQuery UIのエフェクトを使用する場合、追加の設定がサポートされるため、それらの設定を読みこめばエフェクト名として渡されます。 もし、durationまたはeasingが省略された場合はデフォルト値が使用されます。 もし、effedctが省略された場合は"fadeOut"が使用されます。
show

showアニメーションの指定をします。

型:Boolean or Number or String or Object
初期値:null

Boolean
falseを指定すると、アニメーションがOFFになります。 trueを指定すると、デフォルトのフェードインアニメーションが適用されます。
Number
指定されたミリ秒で、デフォルトのイージングでフェードインアニメーションが適用されます。
String
指定されたエフェクト名で要素が表示されます。 "slideDown"のようなjQueryの組み込みメソッド、または"fold"のようなjQuery UIのエフェクトのどちらかのエフェクト名を指定します。 どちらを指定しても、Durationとイージングはデフォルトのものが適用されます。
Object
オブジェクト型を指定した場合、effect、duration、easingのプロパティが提供されます。 effectプロパティはjQueryメソッド名が指定されればそれを使用し、それ以外の場合はjQuery UIのエフェクト名とみなします。 jQuery UIのエフェクトを使用する場合、追加の設定がサポートされるため、それらの設定を読みこめばエフェクト名として渡されます。 もし、durationまたはeasingが省略された場合はデフォルト値が使用されます。 もし、effedctが省略された場合は"fadeIn"が使用されます。
メソッド 説明
_create() _create()メソッドは、ウィジェットのコンストラクタに該当します。 受け取るパラメータはありませんが、this.elementとthis.optionsがすでに設定されていて参照が可能です。
_delay(fn [,delay])
1.9追加
戻り値:Number
指定された遅延時間後に与えられた関数を呼び出します。 clearTimeout()で使用するためのタイムアウトIDを返します。
fn
型:Function() or String
呼び出す関数、またはウィジェット内の関数の文字列を指定します。
delay
型:Number
遅延させる時間をミリ秒単位で指定します。初期値は0です。
_destroy()
1.9追加
パブリックのdestory()メソッドは全ての共通データ、イベント等をクリーンアップし、 その後にウィジェット固有のクリーンアップ処理を_destory()メソッドに委任します。
//1.8
$.widget( "demo.widget", {
  destroy: function() {
    // 基盤のdestoryメソッドを実行
    $.Widget.prototype.destroy.call( this );
    // ウィジット独自のクリーンアップ処理
    ...
  }
});
//1.9~
$.widget( "demo.widget", {
  _destroy: function() {
    // ウィジット独自のクリーンアップ処理
    ...
  }
});
_focusable
(element)
1.9追加

フォーカスとui-state-focusクラスを適用する要素を指定します。 このイベントハンドラはdestoryメソッドにより自動的に削除されます。

element
フォーカスを適用したい要素(jQuery要素)を指定します。
_getCreate
EventData()
1.9追加

戻り値:Object

全てのウィジェットはcreateイベントをトリガします。 初期状態であれば、そのイベントでの戻り値はありませんが、このメソッドによって createイベントデータをオブジェクトとして返すことが可能です。

_getCreate
Options()

戻り値:Object

ウィジェットがインスタンス化される際に、オプションを定義するためのカスタムメソッドを定義することができます。 デフォルトのオプションを上書きしたものが返されます。

_hide
(element, option [, callback ])
1.9追加
組み込みエフェクト、またはカスタムエフェクトを使用して要素を表示します。
element
型:jQuery
非表示にする要素を指定します。
option
型:Object
要素をどのように非表示にするかの設定を定義します。
callback
型:Function()
要素が完全に非表示にされた後に実行したい関数を指定します。
_hoverable
( element )
1.9追加

ホバーとui-state-hoverクラスを適用する要素を指定します。 このイベントハンドラはdestoryメソッドにより自動的に削除されます。

element
ホバーを適用したい要素(jQuery要素)を指定します。
_init() ウィジェットは、createとは別に初期化の概念があります。 プラグインは、引数無し、または1つのオプションハッシュを引数として呼び出され、 ウィジェットの作成中にこの処理が含まれます。
※翻訳に自信無し
注:引数なしでウィジットのために連続的な処理が必要な場合、初期化時に行うべきです。
_off
( element, eventName )
1.9追加
特定の要素(群)のイベントハンドラを削除します。
element
型:jQuery
イベントハンドラを削除する要素を指定します。 _on()メソッドとは異なり、要素の指定は必須です。
eventName
型:String
1つ、または複数の空白区切りのイベントタイプを文字列で指定します。
_on
([element], handlers)
1.9追加
特定の要素(群)にイベントハンドラを登録します。 デリゲーションには、セレクタを介した内部イベント名(例:"click .foo")がサポートされます。 _on()メソッドは幾つかの利点をもたらしてくれます。
  • ハンドラ内で、適切なthisコンテキストを維持します。
  • disabled状態、またはui-state-disabledクラスが適用されている時はイベントを実行されません。
  • イベントハンドラには自動的に名前空間が適用され、またクリーンアップ時に自動的に削除されます。
element
型:jQuery
イベントハンドラを登録する要素(jQuery要素)を指定します。 もし、指定がない場合は、this.element(プラグイン指定した要素自身)が対象になります。
handlers
型:Object
マップ値を指定します。 キーには、イベントタイプとデリゲーションのための任意のセレクタ名の文字列を指定します。
値には、イベント時に実行するハンドラ関数を指定します。
this._on( someElement, {
  mousedown: function( event ) {
    this._handleDown();
  },
  mouseup: "_handleUp",
  "click .other-element": function( event ) {
    this._handleClick( event.target );
  }
});
_setOption
(key, value)
_setOptions()メソッドによってそれぞれ個別に呼び出されるメソッドです。 ウイジェットの状態はこの変更を元に更新されるべきです。
key
型:String
オプション名を指定します。
value
型:Object
オプションにセットする値を指定します。
_setOptions
(options)

option()メソッド(呼び出しの型に関係なく)が呼び出される度に、実行されるメソッドです。 (※翻訳に自信無し)複数のオプションを変更するために、集中的な処理を遅らせることが出来る場合に上書きすると便利です。

options
型:Object
オプションにセットするキーと値のペアとなるマップ値を指定します。
_show
(element, option [, callback ])
1.9追加
組み込みエフェクト、またはカスタムエフェクトを使用して要素を表示します。
element
型:jQuery
表示する要素を指定します。
option
型:Object
要素をどのように表示するかの設定を定義します。
callback
型:Function()
要素が完全に表示された後に実行したい関数を指定します。
_super()
1.9追加
任意の指定された引数を使用し、親ウィジェットから同じ名前のメソッドを呼び出します。 本質的には、.call()メソッドになります。
_superApply
( arguments )
1.9追加
任意の指定された引数を使用し、親ウィジェットから同じ名前のメソッドを呼び出します。 本質的には、.apply()メソッドになります。
arguments
型:Array
親メソッドに渡す引数を指定します。
_trigger
( type [, event ] [, data ] )

イベントをトリガします。 typeに指定したイベントが、コールバック関数のように呼び出されます。 イベント名は「ウィジット名+type」になります。

dataを提供する場合は、3つの引数を指定する必要があります。 eventが無いのであればnullを指定してください。

type
型:String
コールバックオプションの名前に一致する必要があります。 完全なイベント名は自動的に生成されます。
event
型:Event
このイベントを発生させた元のイベントを指定します。 リスナーにこの情報を提供する際に有用です。
data
型:Object
このイベントに関連するハッシュデータを渡します。
メソッド 説明
destroy() jQueryウィジットの機能を完全に除去します。 戻り値は初期状態の要素になります。
disable() jQueryウィジットを無効化します。
enable() jQueryウィジットを有効化します。
option( optionName )

戻り値:Object

optionNameに指定したオプションの現在の値を取得します。

optionName
型:String
取得したいオプションの名前を指定します。
option()

戻り値:PlainObject

オプションの各キーと値がペアとなったオブジェクトを返します。

option( optionName, value )

引数のoptionNameのオプションに値を設定します。

optionName
型:String
設定したいオプションの名前を指定します。
value
型:Object
設定したい値を指定します。
option( options )

オプションに設定したい各キーと値がペアとなったオブジェクトを指定します。

option
型:Object
設定したいオプションのキーと名前のペアを指定します。
イベント 説明
create( event, ui )

型:widgetcreate

ウィジットが作成される際にトリガされます。

//ウィジットの初期化時にcreateコールバックを指定します。
$( ".selector" ).widget({
  create: function( event, ui ){
    //…
  }
});
//widgetcreate(create)イベントに処理を登録しています。
$(".selector").on("widgetcreate", function(event, ui){
  //…
});

 Back to top

© 2010 - 2017 STUDIO KINGDOM