jQuery Autocomplete Mod ドキュメント日本語訳

jQuery Autocomplete Mod Document Japanese Translation by Keisuke Oyama

オートコンプリート – jQuery プラグイン

メモ: これはディラン・ヴァーヘル氏 (Dylan Verheul) によって書かれた、jQuery オートコンプリートプラグインを変更したものです。このドキュメントもディランの文書を基にしています。私の変更を含めるために必要に応じて、追加変更しています。

使用方法

$(“selector”).autocomplete(url [, options]);
$(“selector”).autocompleteArray(array [, options]);

デモページ (アメリカオハイオ州内の市の名前を検索します)

http://www.pengoworks.com/workshop/jquery/autocomplete.htm

アドバイス

あなたが何をやっているか十分わかっていない限りは、セレクターがひとつだけ選択可能であることを確認してください。

例 1:

$(“#input_box”).autocomplete(“autocomplete_ajax.cfm”);

上記の例では、オートコンプリートは “input_box” という ID を持つ input 要素が存在していることを期待しています。ユーザーが input ボックスにタイプし始めたとき、オートコンプリーターは、autocomplete_ajax.cfm へのGET リクエストを、パラメータ名 q に現在の input ボックスの値をセットして要求します。ユーザが “sp” という文字 (引用符は抜かして) を入力していたとしたら、オートコンプリートは、autocomplete_ajax.cfm?q=sp という要求を行います。

その要求に対する出力の例は次のようになります:

http://www.pengoworks.com/workshop/jquery/autocomplete_ajax.cfm?q=sp

バックエンドはオートコンプリーターがとりうる値を、一行ごとに出力します。出力はパイプシンボル ‘|’ を含むことは出来ません。なぜなら、それはセパレータとして認識されるからです (詳細は後ほど)。

良い出力例は次のようになります:

Sparta
Spencer
Spencerville
Spring Valley
Springboro
Springfield

メモ: オートコンプリータはバックエンドが送信してきた順にそれを表示します。

例 2:

$(“#input_box”).autocompleteArray([“Allen”,”Albert”,”Alberto”,”Alladin”]);

上記の例では、オートコンプリートボックスはリストされた項目を含む配列から作られています。ユーザーの選択肢が小さい場合などは、AJAX はしばしばやりすぎです。この場合は配列を用いてリストを作り、全てローカルで処理することが出来ます。

プラグイン Mod の拡張

• AJAX を用いないローカルデータ配列のサポート
• ドロップダウンの項目数の制限を可能とした
• タイプするときに事前に文字を補完するようにした
• 新しい findValue() メソッドによって、プログラムから入力値が妥当な値であるか確認できるようになった (既存の選択内に入力値が存在するか確認する場合に便利)
• ドロップダウンオプションはそれぞれの表示時に再配置可能
• ドロップダウンのサイズのデフォルト幅をインプットフィールドと同じにした (より広い幅を選択可能)
• Windows のオートコンプリートボックスをよりよくエミュレートした (例: 削除を押したり、再度タイプしたときにドロップダウンメニューを元に戻す)
• いくつかの不具合の修正

詳細オプション

JavaScript オブジェクトとして詳細オプションを渡すことができます。表記は { 名前:値, …, 名前:値 } です。

例: $(“#input_box”).autocomplete(“my_autocomplete_backend.php”, { minChars:3 });

以下のオプションが利用可能です:

autoFill (既定値: false)

最初にマッチした input 要素のオートフィルに利用するかどうか決めます。タイプしているときに、最初にマッチした項目があなたが探しているものとして input 要素にセットされます。あなたが手動でタイプしていないテキストは、選択された状態となり次の文字によって、その推測が消え、次の一番の予測がセットされます。

inputClass (既定値: “ac_input”)

このクラスが input ボックスに追加されます。

resultsClass (既定値: “ac_results”)

結果の項目を含む UL のクラス (結果の項目は LI 要素です)

loadingClass = (既定値: “ac_loading”)

サーバーから値を取得している間の input ボックスのクラス

lineSeparator = (既定値: “\n”)

バックエンドからの結果行の区切り文字

cellSeparator (既定値: “|”)

バックエンドからの結果において、セルを区切る文字

minChars (既定値: 1)

オートコンプリーターをアクティベートする前にユーザーがタイプしなければならない最小限の文字数

delay (既定値: 400)

キーストロークからオートコンプリートをアクティベートするまでの遅延 ms。ローカル配列のデータを利用している場合は、この遅延をより小さい値にすると良いでしょう (例えば 40ms)。

cacheLength (既定値: 1)

キャッシュに格納されるクエリー結果の数。1 (現在の結果) をセットするとキャッシュされません。1 より小さい値をセットしてはいけません。

matchSubset (既定値: 1)

オートコンプリーターがより特定のクエリーに対してキャッシュを使うかどうか。”foot” にたいしてマッチした項目は、”foo” に対してマッチしたもののサブセットです。通常はこれは真であり、このオプションを使うことはサーバーへの負荷を減らしパフォーマンスを向上させます。cacheLength をより大きい数字 (例えば 10) にセットすることも忘れないようにしてください。

matchCase (既定値: 0)

比較が大文字小文字を区別するかどうか。キャッシュを利用しているときにのみ重要となります。

matchContains = options.matchContains || 0;

比較が検索結果の中身まで見るかどうか (例えば “ba” が “foo bar” にマッチするか).キャッシュを利用しているときにのみ重要となります。

maxItemsToShow (既定値: -1)

ドロップダウンに現れる結果の数を制限します。これが便利なのは、データセットが大きく、あまりに多い結果セットを見せたくない場合です。この機能を無効にするには、-1 をセットしてください。

mustMatch (既定値: 0)

これを 1 (true) にセットすると、オートコンプリーターはバックエンドによって示された結果のみを許します。不正な値の場合はインプットボックスは空になります。この資料のはじめの例では、”footer” とタイプするとインプットボックスは空になります。

extraParams (既定値: {})

バックエンドへの追加のパラメータ。もし {bar:4} とすると、オートコンプリータは my_autocomplete_backend.php?q=foo&bar=4 を要求します (インプットボックスの値が “foo” である場合)

width (既定値: 0)

ドロップダウンレイヤの幅。非正の整数を指定すると、インプット要素の幅によって決められます。一般的に、この値は何も指定しないでおくのが良いでしょう。しかしながら、ある状況ではインプット要素が小さいところに多数のオプションを表示しなければならない場合もあるでしょう。この場合は大きな値を指定します。

selectFirst (既定値: false)

これが true に設定されると、キーボードやマウスで選択されていなくてもリターンかタブのときにオートコンプリート値の最初の値が自動的に選択されます。もし手動で選択した結果があれば、それが使われます。

selectOnly (既定値: false)

これが true に設定され、オートコンプリート候補が１つしかなく、ユーザーがタブまたはリターンを押すと、手動でどの値も選択されていなくても、自動的にその値が選択されます。この値は selectFirst を上書きします。

formatItem (既定値: none)

項目に対してより進んだマークアップを提供する JavaScript 関数。それぞれの結果行に対して、この関数が呼び出されます。返された値が結果リストの LI 要素に表示されます。オートコンプリーターは３個のパラメータを渡します。結果行、結果リスト内におけるその行の位置、結果リスト内の項目数です。
例として、http://www.dyve.net/jquery?autocomplete のコースコードを見てください。

onItemSelect (既定値: none)

項目が選択されたときに呼び出される JavaScript 関数。LI 要素が選択されたときにオートコンプリータは単一の引数を指定して呼び出します。
この LI 要素は、バックエンドが指定した全てのセルの配列を含む “extra” という属性を持つ場合があります。
例として、http://www.dyve.net/jquery?autocomplete のコースコードを見てください。

onFindValue (既定値: none)

findValue() メソッドが呼び出されたときに呼び出される、JavaScript 関数。その関数には、onItemSelect 関数と同様に選択された LI 要素が渡されます。

より詳細なオプション

もしあなたがオートコンプリータでより多くのことをしようと思うのなら、実行時にいくつかのオプションを変更することも可能です。オートコンプリータは、インプットボックスの属性としてアクセス可能です。

例:
// オートコンプリータをセット
var ac = $(“#input_box”).autocomplete(“my_autocomplete_backend.php”);

// インプット要素内のテキストを元に、オートコンプリートボックスの値を探します
ac[0].autocompleter.findValue();

実行時にオートコンプリータの動作に影響を与えるために呼び出せる関数

findValue()

この関数でインプット要素の現在の値を検証し、その値がマッチした値の中にあるか調べます。この関数は潜在的に AJAX 操作を実行します。そのため fundValue() 関数は値を返しません。その代わりに、onFindValue コールバック関数を指定する必要があります。このメソッドは、オートコンプリートインプット要素に JavaScript で値を設定したり、LI 要素の “extra” 属性の中に格納された拡張プロパティに、テキストフィールドの “value” をマップするときに、特に有益です。

flushCache()

キャッシュをフラッシュします。

setExtraParams(obj)

これによって、オートコンプリータに追加のパラメータ obj をセットします。(obj は JavaScript オブジェクトとしてください。上記を見てください)

setExtraParameters を呼んだ後はキャッシュをフラッシュしたほうが良い場合が多いです。

当翻訳文書は小山圭介が翻訳しました。間違い、ご意見、ご感想等がありましたらコメントでお知らせください。

関連記事

• jQuery AutoComplete 実行サンプル
  
• jQuery 入門