jQuery UI API - 自動補完ウィジェット（Autocomplete Widget）

注：候補メニューが開いているとき、appendToオプションは変更しないでください。

コード例：

指定されたappendToオプションを持つ autocomplete を初期化します：

$( ".selector" ).autocomplete({ appendTo: "#someElem" });
    

初期化後、appendToオプションを取得または設定します：

// getter
var appendTo = $( ".selector" ).autocomplete( "option", "appendTo" );
 
// setter
$( ".selector" ).autocomplete( "option", "appendTo", "#someElem" );
    

コード例：

指定されたautoFocusオプションを持つ autocomplete を初期化します：

$( ".selector" ).autocomplete({ autoFocus: true });
    

初期化後、autoFocusオプションを取得または設定します：

// getter
var autoFocus = $( ".selector" ).autocomplete( "option", "autoFocus" );
 
// setter
$( ".selector" ).autocomplete( "option", "autoFocus", true );
    

コード例：

指定されたdelayオプションを持つ autocomplete を初期化します：

$( ".selector" ).autocomplete({ delay: 500 });
    

初期化後、delayオプションを取得または設定します：

// getter
var delay = $( ".selector" ).autocomplete( "option", "delay" );
 
// setter
$( ".selector" ).autocomplete( "option", "delay", 500 );
    

コード例：

指定されたdisabledオプションを持つ autocomplete を初期化します：

$( ".selector" ).autocomplete({ disabled: true });
    

初期化後、disabledオプションを取得または設定します：

// getter
var disabled = $( ".selector" ).autocomplete( "option", "disabled" );
 
// setter
$( ".selector" ).autocomplete( "option", "disabled", true );
    

コード例：

指定されたminLengthオプションを持つ autocomplete を初期化します：

$( ".selector" ).autocomplete({ minLength: 0 });
    

初期化後、minLengthオプションを取得または設定します：

// getter
var minLength = $( ".selector" ).autocomplete( "option", "minLength" );
 
// setter
$( ".selector" ).autocomplete( "option", "minLength", 0 );
    

コード例：

指定されたpositionオプションを持つ autocomplete を初期化します：

$( ".selector" ).autocomplete({ position: { my : "right top", at: "right bottom" } });
    

初期化後、positionオプションを取得または設定します：

// getter
var position = $( ".selector" ).autocomplete( "option", "position" );
 
// setter
$( ".selector" ).autocomplete( "option", "position", { my : "right top", at: "right bottom" } );
    

使用する変数に関係なく、ラベルは常にテキストとして扱われます。ラベルを html として扱いたい場合は、Scott González の html 拡張を使用できます。デモはsourceオプションのさまざまなバリエーションに焦点を当てています。自分の使用状況に一致するものを見つけて、関連するコードを確認できます。

複数の型をサポートしています：

• Array：ローカルデータに使用できる配列。次の 2 つの形式をサポートします：
  • 文字列の配列：[ "Choice1", "Choice2" ]
  • 次のプロパティを持つlabelとvalueオブジェクトの配列：[ { label: "Choice1", value: "value1" }, ... ]
  label プロパティは候補メニューに表示されます。ユーザーが項目を選択すると、value が input 要素に挿入されます。1 つのプロパティのみが指定された場合、そのプロパティは label と value の両方として扱われます。たとえば、valuevalue プロパティを提供した場合、value もラベルとして扱われます。
• String：文字列を使用する場合、Autocomplete プラグインはその文字列が JSON データを返す URL リソースを指していることを期待します。同じホスト上でも、異なるホスト上でもかまいません（JSONP を提供する必要があります）。Autocomplete プラグインは結果をフィルタリングせず、termフィールドを介してクエリ文字列を追加し、サーバー側スクリプトが結果をフィルタリングできるようにします。たとえば、sourceオプションが"http://example.com"に設定され、ユーザーがfooと入力した場合、GET リクエストはhttp://example.com?term=fooになります。データ自体の形式は、前述のローカルデータの形式と同じにすることができます。
• Function：3番目のバリアントであるコールバック関数は、最大の柔軟性を提供し、任意のデータソースを Autocomplete に接続するために使用できます。コールバック関数は 2 つの引数を受け取ります：
  • 1 つのrequestオブジェクト。このオブジェクトには 1 つのtermプロパティがあり、現在のテキスト入力の値を表します。たとえば、ユーザーが city フィールドに"new yo"、その場合、Autocomplete term は次と同等です。"new yo"。
  • 1 つのresponseコールバック関数で、単一の引数（ユーザーに提案するデータ）を受け取ります。このデータは指定された term に基づいてフィルタリングされ、上記で説明したローカルデータの任意の形式にすることができます。リクエスト中にエラーを処理するためのカスタム source コールバックを提供するために使用します。エラーが発生した場合でも、必ずresponseコールバック関数を呼び出さなければなりません。これにより、ウィジェットが常に正しい状態になることが保証されます。

  ローカルデータをフィルタリングするときは、組み込みの$.ui.autocomplete.escapeRegex関数を使用できます。この関数は文字列引数を受け取り、すべての正規表現文字をエスケープして、結果を安全に渡せるようにします。new RegExp()。

コード例：

指定されたsourceオプションを指定して autocomplete を初期化します：

$( ".selector" ).autocomplete({ source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] });
    

初期化後、sourceオプションを取得または設定します：

// getter
var source = $( ".selector" ).autocomplete( "option", "source" );
 
// setter
$( ".selector" ).autocomplete( "option", "source", [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] );
    

• このメソッドは引数を受け付けません。

コード例：

close メソッドを呼び出します：

$( ".selector" ).autocomplete( "close" );
    

• このメソッドは引数を受け付けません。

コード例：

destroy メソッドを呼び出します：

$( ".selector" ).autocomplete( "destroy" );
    

• このメソッドは引数を受け付けません。

コード例：

disable メソッドを呼び出します：

$( ".selector" ).autocomplete( "disable" );
    

• このメソッドは引数を受け付けません。

コード例：

enable メソッドを呼び出します：

$( ".selector" ).autocomplete( "enable" );
    

• optionName
  型：String
  説明：取得するオプションの名前。

コード例：

このメソッドを呼び出します：

var isDisabled = $( ".selector" ).autocomplete( "option", "disabled" );
    

• このメソッドは引数を受け付けません。

コード例：

このメソッドを呼び出します：

var options = $( ".selector" ).autocomplete( "option" );
    

• optionName
  型：String
  説明：設定するオプションの名前。
• value
  型：Object
  説明：オプションに設定する値。

コード例：

このメソッドを呼び出します：

$( ".selector" ).autocomplete( "option", "disabled", true );
    

• options
  型：Object
  説明：設定するオプションと値のペア。

コード例：

このメソッドを呼び出します：

$( ".selector" ).autocomplete( "option", { disabled: true } );
    

• value
  型：String

コード例：

search メソッドを呼び出します：

$( ".selector" ).autocomplete( "search", "" );
    

• このメソッドは引数を受け付けません。

コード例：

widget メソッドを呼び出します：

$( ".selector" ).autocomplete( "widget" );
    

Note: At this time the<ul> element created must contain an <a> element for compatibility with the menu widget. See the example below.

• ul
  型：jQuery
  説明：新しく作成された<li>要素が追加される必要がある<ul>要素。
• item
  型：Object
  
  • label
    型：String
    説明：項目に表示される文字列。
  • item
    型：String
    説明：項目が選択されたときに入力フィールドに挿入される値。

コード例：

項目の値を<li>の data 属性として追加します。

_renderItem: function( ul, item ) {
  return $( "<li>" )
    .attr( "data-value", item.value )
    .append( $( "<a>" ).text( item.label ) )
    .appendTo( ul );
}
    

• ul
  型：jQuery
  説明：ウィジェットのメニューとして使用される空の<ul>要素。
• items
  型：Array
  説明：ユーザーの入力に一致する項目を含む配列。各項目はlabelとvalueプロパティを持つオブジェクトです。

コード例：

古いメニュー項目に CSS クラス名を追加します。

_renderMenu: function( ul, items ) {
  var that = this;
  $.each( items, function( index, item ) {
    that._renderItemData( ul, item );
  });
  $( ul ).find( "li:odd" ).addClass( "odd" );
}
    

• このメソッドは引数を受け付けません。

コード例：

メニューは常に幅 500 ピクセルで表示されます。

_resizeMenu: function() {
  this.menu.element.outerWidth( 500 );
}
    

• event
  型：Event
• ui
  型：Object
  • item
    型：Object
    説明：メニューから選択された項目。それ以外の場合はプロパティはnull。

コード例：

指定された change コールバックで autocomplete を初期化します：

$( ".selector" ).autocomplete({
  change: function( event, ui ) {}
});
    

autocompletechange イベントにイベントリスナーをバインドします：

$( ".selector" ).on( "autocompletechange", function( event, ui ) {} );
    

• event
  型：Event
• ui
  型：Object

注：uiオブジェクトは空です。他のイベントとの一貫性のために含まれています。

コード例：

指定された close コールバックで autocomplete を初期化します：

$( ".selector" ).autocomplete({
  close: function( event, ui ) {}
});
    

autocompleteclose イベントにイベントリスナーをバインドします：

$( ".selector" ).on( "autocompleteclose", function( event, ui ) {} );
    

• event
  型：Event
• ui
  型：Object

注：uiオブジェクトは空です。他のイベントとの一貫性のために含まれています。

コード例：

指定された create コールバックで autocomplete を初期化します：

$( ".selector" ).autocomplete({
  create: function( event, ui ) {}
});
    

autocompletecreate イベントにイベントリスナーをバインドします：

$( ".selector" ).on( "autocompletecreate", function( event, ui ) {} );
    

• event
  型：Event
• ui
  型：Object
  • item
    型：Object
    説明：フォーカスされた項目。

コード例：

指定された focus コールバックで autocomplete を初期化します：

$( ".selector" ).autocomplete({
  focus: function( event, ui ) {}
});
    

autocompletefocus イベントにイベントリスナーをバインドします：

$( ".selector" ).on( "autocompletefocus", function( event, ui ) {} );
    

• event
  型：Event
• ui
  型：Object

注：uiオブジェクトは空です。他のイベントとの一貫性のために含まれています。

コード例：

指定された open コールバックで autocomplete を初期化します：

$( ".selector" ).autocomplete({
  open: function( event, ui ) {}
});
    

autocompleteopen イベントにイベントリスナーをバインドします：

$( ".selector" ).on( "autocompleteopen", function( event, ui ) {} );
    

• event
  型：Event
• ui
  型：Object
  • content
    型：Array
    説明：レスポンスデータを含み、表示結果を変更するために修正できます。このデータはすでに標準化されているため、データを変更する場合は、各項目にvalueとlabelプロパティが含まれていることを確認してください。

コード例：

指定された response コールバックを持つ autocomplete を初期化します：

$( ".selector" ).autocomplete({
  response: function( event, ui ) {}
});
    

autocompleteresponse イベントにイベントリスナーをバインドします：

$( ".selector" ).on( "autocompleteresponse", function( event, ui ) {} );
    

• event
  タイプ：Event
• ui
  タイプ：Object

注意：uiオブジェクトは空です。他のイベントとの一貫性を保つためにここに含まれています。

コード例：

指定された search コールバックを持つ autocomplete を初期化します：

$( ".selector" ).autocomplete({
  search: function( event, ui ) {}
});
    

autocompletesearch イベントにイベントリスナーをバインドします：

$( ".selector" ).on( "autocompletesearch", function( event, ui ) {} );
    

• event
  タイプ：Event
• ui
  タイプ：Object
  • item
    タイプ：Object
    説明：選択された項目のlabelとvalueプロパティを持つオブジェクト。

コード例：

指定された select コールバックを持つ autocomplete を初期化します：

$( ".selector" ).autocomplete({
  select: function( event, ui ) {}
});
    

autocompleteselect イベントにイベントリスナーをバインドします：

$( ".selector" ).on( "autocompleteselect", function( event, ui ) {} );