jQuery UI API - ウィジェットファクトリー(Widget Factory)
カテゴリ
ユーティリティ(Utilities) | ウィジェット(Widgets)
jQuery.widget( name [, base ], prototype ) の使い方
説明:すべての jQuery UI ウィジェットと同じ抽象化を使用して、状態を持つ jQuery プラグインを作成します。
| パラメータ | 型 | 型 |
|---|---|---|
| name | String | 作成するウィジェットの名前。名前空間を含みます。 |
| base | Function() | 継承するベースウィジェット。`new` キーワードでインスタンス化できるコンストラクターである必要があります。デフォルトは jQuery.Widget です。 |
| prototype | PlainObject | ウィジェットのプロトタイプとして使用するオブジェクト。 |
使用できるのは$.Widgetオブジェクトを継承するベースとして使用するか、既存の jQuery UI またはサードパーティ製コントロールから、ゼロから新しいウィジェットを作成することもできます。同じ名前のウィジェットを定義してベースウィジェットを継承すると、ウィジェットを適切に拡張することもできます。
jQuery UI には状態を保持するウィジェットが多数含まれているため、典型的な jQuery プラグインとは少し異なる使用パターンになります。すべての jQuery UI ウィジェットは、ウィジェットファクトリー(Widget Factory)によって定義された同じパターンを使用します。したがって、1 つの使い方を覚えれば、他のウィジェット(Widget)の使い方もわかります。
注:この章ではプログレスバーウィジェット(Progressbar Widget)を例として使用していますが、構文はすべてのウィジェットに適用されます。
初期化
ウィジェットの状態を追跡するには、ウィジェットのライフサイクル全体を理解する必要があります。ライフサイクルはウィジェットの初期化時に始まります。ウィジェットを初期化するには、1 つ以上の要素でプラグインを呼び出すだけです。
$( "#elem" ).progressbar();
これにより、jQuery オブジェクト内の各要素が初期化されます。上記の例では、要素の id は"elem"。
オプション
なぜならprogressbar()呼び出し時に引数を指定しない場合、ウィジェットはデフォルトオプションで初期化されます。初期化時にオプションのセットを渡してデフォルトオプションを上書きできます:
$( "#elem" ).progressbar({ value: 20 });
必要に応じていくつでもオプションを渡すことができ、渡さなかったオプションはすべてデフォルト値が使用されます。
複数のオプション引数を渡すことができ、それらは 1 つのオブジェクトにマージされます($.extend( true, target, object1, objectN ))。これは、すべてのインスタンスでいくつかの設定を上書きし、インスタンス間でオプションを共有する場合に便利です:
var options = { modal: true, show: "slow" };
$( "#dialog1" ).dialog( options );
$( "#dialog2" ).dialog( options, { autoOpen: false });
初期化時に渡されたすべてのオプションはディープコピーされ、後でウィジェットに影響を与えずにオブジェクトを変更できます。配列は唯一の例外で、そのまま参照されます。この例外は、データソースを参照として渡す必要があるデータバインディングを適切にサポートするためです。
デフォルト値はウィジェットのプロパティに保存されるため、jQuery UI が設定した値を上書きできます。たとえば、次の設定を行うと、今後作成されるすべてのプログレスバーインスタンスはデフォルトで値 80 になります:
$.ui.progressbar.prototype.options.value = 80;
オプションはウィジェットの状態の一部であるため、初期化後にもオプションを設定できます。option メソッドについては後ほど説明します。
メソッド
ウィジェットが初期化されたので、その状態を照会したり、ウィジェット上でアクションを実行したりできます。初期化後のすべてのアクションはメソッド呼び出しとして実行されます。ウィジェット上でメソッドを呼び出すには、jQuery プラグインにメソッド名を渡します。たとえば、プログレスバーウィジェット(Progressbar Widget)でvalue()メソッドを呼び出すには、次のようにします:
$( "#elem" ).progressbar( "value" );
メソッドが引数を受け取る場合、メソッド名の後に引数を渡すことができます。たとえば、引数を渡すには40 到 value()メソッドを使用できます:
$( "#elem" ).progressbar( "value", 40 );
jQuery の他のメソッドと同様に、ほとんどのウィジェットメソッドは jQuery オブジェクトを返します:
$( "#elem" ) .progressbar( "value", 90 ) .addClass( "almost-done" );
各ウィジェットには、ウィジェットが提供する機能に基づいた独自のメソッドセットがあります。ただし、すべてのウィジェットに存在するメソッドもいくつかあり、これらについては以下で詳しく説明します。
イベント
すべてのウィジェットには、さまざまな動作に関連するイベントがあり、状態が変化したときに通知します。ほとんどのウィジェットでは、イベントがトリガーされるとき、名前はウィジェット名の小文字形式が接頭辞として付きます。たとえば、プログレスバーのchangeイベントは、値が変更されたときにトリガーされます。
$( "#elem" ).bind( "progressbarchange", function() {
alert( "The value has changed!" );
});
各イベントには対応するコールバックがあり、これはオプションとして提供されます。必要に応じて、プログレスバーのchangeコールバックを、バインドせずにprogressbarchangeイベント。
$( "#elem" ).progressbar({
change: function() {
alert( "The value has changed!" );
}
});
すべてのウィジェットにはchangeイベントがあり、インスタンス化されたときにトリガーされます。
インスタンス化
ウィジェットのインスタンスは、ウィジェットの完全名をキーとするjQuery.data()に保存されます。したがって、次のコードを使用して、要素からプログレスバーウィジェット(Progressbar Widget)のインスタンスオブジェクトを取得できます。
$( "#elem" ).data( "ui-progressbar" );
要素が指定されたウィジェットにバインドされているかどうかは、:dataセレクターを使用して検出できます。
$( "#elem" ).is( ":data( 'ui-progressbar' )" ); // true $( "#elem" ).is( ":data( 'ui-draggable' )" ); // false
また、:dataを使用して、指定されたウィジェットのインスタンスであるすべての要素のリストを取得できます。
$( ":data( 'ui-progressbar' )" );
プロパティ
すべてのウィジェットには次のプロパティがあります:
- defaultElement:ウィジェットインスタンスの構築時に要素が提供されなかった場合に使用する要素。たとえば、プログレスバーの
defaultElementである"<div>",$.ui.progressbar({ value: 50 })で、新しく作成された<div>上にプログレスバーウィジェットのインスタンスをインスタンス化します。 - document:ウィジェット要素を含む
document。フレームワーク内でウィジェットと対話する必要がある場合に便利です。 - element:ウィジェットのインスタンス化に使用される要素を含む jQuery オブジェクト。複数の要素を選択して呼び出すと
.myWidget()、各要素に対して個別のウィジェットインスタンスが作成されます。したがって、このプロパティは常に 1 つの要素を含みます。 - namespace:ウィジェットプロトタイプが保存されているグローバル jQuery オブジェクトの場所。たとえば、
"ui"のnamespaceは、ウィジェットプロトタイプが$.ui。 - options:ウィジェットが現在使用しているオプションを含むオブジェクト。インスタンス化時に、ユーザーが指定したオプションは自動的に
$.myNamespace.myWidget.prototype.optionsで定義されたデフォルト値とマージされます。ユーザーが指定したオプションはデフォルト値を上書きします。 - uuid:コントロール識別子を表す一意の整数。
- version:ウィジェットの文字列バージョン。jQuery UI ウィジェットの場合、このプロパティはウィジェットが使用する jQuery UI のバージョンに設定されます。プラグイン開発者は、プロトタイプでこのプロパティを明示的に設定する必要があります。
- widgetEventPrefix:ウィジェットのイベント名に追加される接頭辞。たとえば、ドラッグ可能ウィジェット(Draggable Widget)の
widgetEventPrefixである"drag"であるため、draggable を作成すると、イベント名は"dragcreate"。デフォルトでは、ウィジェットのwidgetEventPrefixはその名前です。注:このプロパティは非推奨であり、将来のバージョンで削除される予定です。イベント名は widgetName:eventName に変更されます(例:"draggable:create")。 - widgetFullName:名前空間を含むウィジェットの完全名。
$.widget( "myNamespace.myWidget", {} ),widgetFullNameは"myNamespace-myWidget"。 - widgetName:ウィジェットの名前。
$.widget( "myNamespace.myWidget", {} ),widgetNameは"myWidget"。 - window:ウィジェット要素を含む
window。フレームワーク内でウィジェットと対話する必要がある場合に便利です。
jQuery.Widget ベースウィジェットの使い方
説明:ウィジェットファクトリー(Widget Factory)で使用されるベースウィジェット。
クイックナビゲーション
| オプション | メソッド | イベント |
|---|---|---|
| オプション | 型 | 説明 | デフォルト値 |
|---|---|---|---|
| disabled | Boolean | に設定されている場合true、そのウィジェットは無効になります。コード例: 指定された
$( ".selector" ).widget({ disabled: true });
初期化後に、 // getter var disabled = $( ".selector" ).widget( "option", "disabled" ); // setter $( ".selector" ).widget( "option", "disabled", true ); |
false |
| hide | Boolean または Number または String または Object | アニメーションを使用して要素を非表示にするかどうか、およびどのようにアニメーションで非表示にするか。 複数の型をサポート:
コード例: 指定された
$( ".selector" ).widget({ hide: { effect: "explode", duration: 1000 } });
初期化後に、次を取得または設定します:
// getter
var hide = $( ".selector" ).widget( "option", "hide" );
// setter
$( ".selector" ).widget( "option", "hide", { effect: "explode", duration: 1000 } );
|
null |
| show | Boolean または Number または String または Object | 要素をアニメーションで表示するかどうか、およびどのようにアニメーションで表示するか。 複数の型をサポートします:
コード例: 指定された
$( ".selector" ).widget({ show: { effect: "blind", duration: 800 } });
初期化後に、次を取得または設定します:
// getter
var show = $( ".selector" ).widget( "option", "show" );
// setter
$( ".selector" ).widget( "option", "show", { effect: "blind", duration: 800 } );
|
null |
| メソッド | 戻り値 | 説明 |
|---|---|---|
| _create() | jQuery (plugin only) | _create()メソッドはウィジェットのコンストラクターです。引数はありませんが、this.elementとthis.optionsがすでに設定されています。
コード例: オプションに基づいてウィジェット要素の背景色を設定します。
_create: function() {
this.element.css( "background-color", this.options.color );
}
|
| _delay( fn [, delay ] ) | Number | 指定された遅延の後に関数を呼び出します。thisコンテキストを正しく保ちます。基本的にはsetTimeout()。を使用します。 clearTimeout()タイムアウト ID を返します。
コード例: 100 ミリ秒後にウィジェット上で this._delay( this._foo, 100 ); |
| _destroy() | jQuery (plugin only) | パブリックなdestroy()メソッドは、すべてのパブリックデータ、イベントなどをクリアします。カスタマイズ、ウィジェットの指定、クリーンアップを表します。_destroy()。
コード例: ウィジェットが破棄されたときに、ウィジェットの要素からクラスを削除します。
_destroy: function() {
this.element.removeClass( "my-widget" );
}
|
| _focusable( element ) | jQuery (plugin only) | 要素にフォーカスしたときに適用するui-state-focusクラスのelement。
コード例: ウィジェット内の一連の要素にフォーカス可能なスタイルを適用します: this._focusable( this.element.find( ".my-items" ) ); |
| _getCreateEventData() | Object | すべてのウィジェットはcreateイベントをトリガーします。デフォルトでは、イベントにはデータは提供されませんが、このメソッドはオブジェクトを返し、それがcreateイベントのデータとして渡されます。
コード例: 向
_getCreateEventData: function() {
return this.options;
}
|
| _getCreateOptions() | Object | このメソッドにより、ウィジェットは初期化中にオプションを定義するためのカスタムメソッドを定義できます。ユーザーが提供したオプションは、このメソッドが返すオプション、つまりデフォルトのオプションを上書きします。
コード例: ウィジェット要素の id 属性をオプションとして利用できるようにします。
_getCreateOptions: function() {
return { id: this.element.attr( "id" ) };
}
|
| _hide( element, option [, callback ] ) | jQuery (plugin only) | 組み込みのアニメーションメソッドまたはカスタムエフェクトを使用して要素を非表示にします。可能なoption値については、hide。
コード例: カスタムアニメーション用に
this._hide( this.element, this.options.hide, function() {
// Remove the element from the DOM when it's fully hidden.
$( this ).remove();
});
|
| _hoverable( element ) | jQuery (plugin only) | 要素にホバーしたときに適用するui-state-hoverクラスのelement。イベントハンドラーは破棄時に自動的にクリーンアップされます。
コード例: 要素にホバーしたとき、要素内のすべての this._hoverable( this.element.find( "div" ) ); |
| _init() | jQuery (plugin only) | ウィジェットの初期化は作成とは異なる概念です。引数なしでプラグインを呼び出すか、オプションハッシュのみを指定してプラグインを呼び出すと、ウィジェットが初期化されます。ウィジェットが作成されるときにこのメソッドが含まれます。 注:引数なしでウィジェットを正常に呼び出したときに実行する論理アクションが存在する場合、初期化はこのときにのみ処理できます。
コード例: もし
_init: function() {
if ( this.options.autoOpen ) {
this.open();
}
}
|
| _off( element, eventName ) | jQuery (plugin only) | 指定された要素からイベントハンドラーのバインドを解除します。
コード例: ウィジェットの要素からすべての click イベントのバインドを解除します。 this._off( this.element, "click" ); |
| _on( [suppressDisabledCheck ] [, element ], handlers ) | jQuery (plugin only) | イベント名内のセレクターによる委任がサポートされています。例:"click .foo"。_on()メソッドは直接イベントバインドに比べていくつかの利点を提供します:
コード例: ウィジェット要素内のクリックされたすべてのリンクのデフォルトの動作を防止します。
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
}
});
|
| _setOption( key, value ) | jQuery (plugin only) | 個々のオプションごとに_setOptions()メソッドを呼び出します。ウィジェットの状態は変更に応じて更新されます。
コード例: ウィジェットの
_setOption: function( key, value ) {
if ( key === "width" ) {
this.element.width( value );
}
if ( key === "height" ) {
this.element.height( value );
}
this._super( key, value );
}
|
| _setOptions( options ) | jQuery (plugin only) | を呼び出すと、option()メソッドが呼び出されたときに呼び出されます。どのような形式でoption()が呼び出されても同様です。複数のオプションの変更に基づいて処理を変更する必要がある場合、このメソッドをオーバーライドすると便利です。
コード例: ウィジェットの
_setOptions: function( options ) {
var that = this,
resize = false;
$.each( options, function( key, value ) {
that._setOption( key, value );
if ( key === "height" || key === "width" ) {
resize = true;
}
});
if ( resize ) {
this.resize();
}
}
|
| _show( element, option [, callback ] ) | jQuery (plugin only) | 組み込みのアニメーションメソッドまたはカスタムエフェクトを使用して要素を表示します。可能なoption値については、show。
コード例: カスタムアニメーションに渡す
this._show( this.element, this.options.show, function() {
// Focus the element when it's fully visible.
this.focus();
}
|
| _super( [arg ] [, ... ] ) | jQuery (plugin only) | 親ウィジェットから同じ名前のメソッドを、任意に指定されたパラメータ付きで呼び出します。実質的には.call()。
コード例: 処理
_setOption: function( key, value ) {
if ( key === "title" ) {
this.element.find( "h3" ).text( value );
}
this._super( key, value );
}
|
| _superApply( arguments ) | jQuery (plugin only) | 親ウィジェットから同じ名前のメソッドを、パラメータの配列を指定して呼び出します。実質的には.apply()。
コード例: 処理
_setOption: function( key, value ) {
if ( key === "title" ) {
this.element.find( "h3" ).text( value );
}
this._superApply( arguments );
}
|
| _trigger( type [, event ] [, data ] ) | Boolean | イベントとそれに関連するコールバックをトリガーします。その名前を持つオプションは、コールバックとして呼び出される型と等しくなります。 イベント名は、ウィジェット名と型を小文字にした文字列です。 注:データを提供する場合、3つのパラメータすべてを提供する必要があります。イベントが渡されない場合は、null を渡します。 デフォルトの動作が阻止された場合は、false を返し
コード例: キーが押されたときに、
this._on( this.element, {
keydown: function( event ) {
// Pass the original event so that the custom search event has
// useful information, such as keyCode
this._trigger( "search", event, {
// Pass additional information unique to this event
value: this.element.val()
});
}
});
|
| destroy() | jQuery (plugin only) | ウィジェットの機能を完全に削除します。これにより、要素は初期化前の状態に戻ります。
コード例: ウィジェットの任意のアンカーをクリックしたときに、ウィジェットを破棄します。
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.destroy();
}
});
|
| disable() | jQuery (plugin only) | ウィジェットを無効にします。
コード例: ウィジェットの任意のアンカーをクリックしたときに、ウィジェットを無効にします。
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.disable();
}
});
|
| enable() | jQuery (plugin only) | ウィジェットを有効にします。
コード例: ウィジェットの任意のアンカーをクリックしたときに、ウィジェットを有効にします。
this._on( this.element, {
"click a": function( event ) {
event.preventDefault();
this.enable();
}
});
|
| option( optionName ) | Object | 指定されたoptionNameに関連付けられた現在の値を取得します。
コード例: 取得する this.option( "width" ); |
| option() | PlainObject | 現在のウィジェットオプションハッシュを表すキーと値のペアを含むオブジェクトを取得します。
コード例: デバッグ用に、各ウィジェットオプションのキーと値のペアを記録します。
var options = this.option();
for ( var key in options ) {
console.log( key, options[ key ] );
}
|
| option( optionName, value ) | jQuery (plugin only) | 指定されたoptionNameに関連付けられたウィジェットオプションの値を設定します。
コード例: 設定する this.option( "width", 500 ); |
| option( options ) | jQuery (plugin only) | ウィジェットに1つ以上のオプションを設定します。
コード例: 設定する
this.option({
width: 500,
height: 500
});
|
| widget() | jQuery | 元の要素またはその他の関連する生成要素を含むjQueryオブジェクトを返します。
コード例: ウィジェットの作成時に、ウィジェットの元の要素の周りに赤い枠線を配置します。
_create: function() {
this.widget().css( "border", "2px solid red" );
}
|
| イベント | 型 | 説明 |
|---|---|---|
| create( event, ui ) | widgetcreate | ウィジェットが作成されたときにトリガーされます。
注: コード例: 指定された create コールバックを持つウィジェットを初期化します:
$( ".selector" ).widget({
create: function( event, ui ) {}
});
widgetcreate イベントにイベントリスナーをバインドします:
$( ".selector" ).on( "widgetcreate", function( event, ui ) {} );
|