[jQuery套件]AutoComplete自動完成
本質
提供使用者能夠快速找到自己所想要輸入的資料。
圖1. jQuery UI AutoComplete示範
jQuery UI AutoComplete是jQuery官方所提供的一個即為簡便的UI小工具;當使用者輸入關鍵字之後,jQuery UI AutoComplete套件會自動搜尋來源資料中是否有符合的資料,若有,則顯示在下拉選單中供使用者選擇自己所需要的資料。當使用者輸入更多字元,jQuery UI AutoComplete會依當前的資料進行再過濾的動作,進而縮小資料範圍讓使用者更快找到所需要的資料。
jQuery UI AutoComplete所需要的資料來源可以是Js的字串陣列或是Js的物件陣列。
範例:
var arTags = ["apple", "orange"];
$("input#tag").autocomplete({source: arTags});
jQuery UI AutoComplete套件允許套用在: input/textarea標籤以及任何內容可供使用者修改的標籤。jQuery UI AutoComplete擁有極強的彈性,可供開發人員有著更豐富的資料控制模式;譬如說,當使用者輸入城市名稱並從下拉選單中選擇比對的資料後,資料輸入框呈現郵遞區號。
jQuery UI AutoComplete的資料來源可以是靜態的資料亦可以採用Ajax的方式來比對資料。採用靜態資料作為jQuery UI AutoComplete的比對用資料來源通常適用在靜態資料不多的情境,反之,採用Ajax通常就是應用在大型資料上。
使用者操作方式
當使用者輸入資料後jQuery UI AutoComplete套件會進行資料比對,並且將比對後的配對資料顯示在下拉選單中,當下拉選單顯示之後使用者可以使用下列的按鍵進行相對應的操作:
1. Up: 在下拉選單中向上移動欲選擇的配對項目,若目前位置是配對項目中的第一筆,則會移到動資料輸入框;若當前位置是在資料輸入框,則會移動到下拉選單的最後一筆。
(i.e. 當下拉選單是處於關閉狀態下,並且使用者在資料框輸入的字元數符合minLength限制時,使用者按下Up鍵會叫出下拉選單)
2. Down: 在下拉選中向下移動欲選擇的配對項目,若目前位置是配對項目中的最後一筆,則會移動到資料輸入框;若當前位置是在資料輸入框,則會移動到下拉選單中第一筆。
(i.e. 當下拉選單是處於關閉狀態下,並且使用者在資料框輸入的字元數符合minLength限制時,使用者按下Up鍵會叫出下拉選單)
3. Escape: 關閉下拉選單。
4. Tab: 選定下拉選單中當前取得焦點的配對項目並且關閉下拉選單,將資料呈現在資料輸入方框爾後再將焦點移至資料輸入方框。
5. Page Up/Down: 捲動下拉選單中的配對項目到上/下一頁(i.e. 這通常是應用在有特別設定下拉選單高度的情境下,否則預設下拉選單的高度會配合配對資料數)。
外觀
jQuery UI AutoComplete的外觀基本上是依照jQuery UI CSS framework來設定的,但是額外會使用到兩個CSS類別:
1. ui-autocomplete: 下拉選單會使用這個CSS類別;若有客製下拉選單的需求可以修改此項目。
2. ui-autocomplete-input: 當jQuery UI AutoComplete啟動後會將此類別添加到與之結合的資料輸入框上。
與其它jQuery UI的相依
1. UI Core
2. Widget Factory
3. Position
4. Menu
警告事項
jQuery UI AutoComplete套件會使用到jQuery UI CSS,若需要客製化版型時,請盡可能不要與jQuery UI CSS發生衝突。
jQuery UI AutoComplete套件會強制控制Html標籤,因此,像是change事件就幾乎不會觸發。
參數物件
jQuery UI AutoComplete提供了7個參數供開發人員客製:
1. appendTo
類型: 字串
資料格式: jQuery CSS3選擇器
描述: 用於指定下拉選單該附著在那一個Html標籤。
範例: $(".selector").autocomplete({appendTo: "#ele"})
取得: var appendTo = $(".selector").autocomplete("option", "appendTo");
設定: $(".selector").autocomplete("option", "appendTo", "#Elem");
2. autoFocus
類型: 布林
資料格式: true/false
描述: 若設定為true,則當比對完畢並且呈現在下拉選單時,會將第一筆配對項目設定為焦點。
範例: $(".selector").autocomplete({autoFocus: true});
取得: var IsFocus = $(".selector").autocomplete("option", "autoFocus");
設定: $(".selector").autocomplete("option", "autoFocus", true);
3. delay
類型: 整數
資料格式: 0~int.MaxValue
描述: 設定從使用者輸入完畢到開始比對中間的延遲時間,單位為微秒;若採用Ajax而此值設定的過低會造成後端伺服器很大的負擔。
範例: $(".selector").autocomplete({delay: 500});
取得: var delay = $(".selector").autocomplete("option", "delay");
設定: $(".selector").autocomplete("option", "delay", 500);
4. disabled
類型: 布林
資料格式: true/false
描述: 若設定為true則jQuery UI AutoComplete不啟用。
範例: $(".selector").autocomplete({disabled: true});
取得: var disabled = $(".selector").autocomplete("option", "disabled");
設定: $(".selector").autocomplete("option", "disabled", true);
5. minLength
類型: 整數
資料格式: 0~int.MaxValue
描述: 限制使用者最少需要輸入多少字元才啟動比對機制;當設定為0時通常是應用在比對資料量極少的情況下,若比對資料量極為龐大則盡量將此值設定得高一點。
範例: $(".selector").autocomplete({minLength: 0});
取得: var minLength = $(".selector").autocomplete("option", "minLength");
設定: $(".selector").autocomplete("option", "minLength", 0);
6. position
類型: jQuery Position物件
預設值: {my: "left top", at: "left bottom", collision: "none"}
描述: 用來指定下拉選單放置在資料輸入框的位置。
jQuery Position物件參數:
1. my: 指定下拉選單內容項目的對齊方式,共有: left/right/top/bottom項目可供設定之外,亦可加上偏移量,例如: right+10。
2. at: 指定下拉選單要依附在資料輸入框的那一個位置;共有: left/right/top/bottom項目可供設定,亦可加上偏移量。
3. of: 指定要依附在那一個Html標籤。(i.e. 通常是設定為資料輸入框)
4. collision: 當下拉選單超出螢幕時的處理模式,共有: flip/fit/flipfit/none可供設定。
範例: $(".selector").autocomplete({position: {my: "right top", at: "right bottom"}});
取得: var position = $(".selector").autocomplete("option", "position");
設定: $(".selector").autocomplete("option", "position", {my: "right top", at: "right bottom"});
7. source(必填)
類型: 字串陣列/物件陣列/Url字串/函數
預設值: null
描述: 當字串比對機制啟動時,會以此參數作為比對的來源。當設定值為:
1. 字串陣列:
資料範例: ["choise1", "choise2"]
描述: jQuery UI AutoComplete套件為以此字串陣列內容作為比對資料庫。
2. 物件陣列:
資料範例: [{label: "choise1", value: "value1"}, {label: "choise1", value: "value2"}]
描述: 若採用物件陣列,則陣列中的物件需強制具有value屬性。倘若還有提供label屬性,則會以label屬性作為下拉選單配對項目的顯示字串。
3. Url字串:
資料範例: http://www.mySite.com/Controller/Action
描述: jQuery UI AutoComplete比對資料時會採以Get並且參數為"term"向指定的Url查詢比對資料,並且解讀其所回傳的Json;該Url可以跨網域,但該Url所指定的網站需提供JSONP。
4. 函數:
資料範例: function(request,response) { .... }
描述: jQuery UI AutoComplete會將使用者在輸入方框的資料放置到輸入參數request的屬性term中,並且會將response的資料設定為比對後的配對資料庫,故在撰寫非Ajax時,務必要將處理比對完後的資料賦予response,否則jQuery UI AutoComplete會有靈異現象。
範例:
(非Ajax)
$(".selector").autocomplete(
{ source:
function(request, response) {
var matcher =
new RegExp( $.ui.autocomplete.escapeReges(request.term),"i");
response( $.grep(fruits, function(value) { return matcher.test(value); }) );
});
(Ajax)
$.(".selector").autocomplete(
{ source:
function(request, response) {
$("/Controller/Action", { data: request.term}, response); } });
參數方法
1. close
描述: 用於關閉下拉選單,通常和search方法一起合併使用。
範例: $(".selector").autocomplete("close");
2. destroy
描述: 用於將資料輸入框上所有關於jQuery UI AutoComplete所附加的項目全部清除掉。
範例: $(".selector").autocomplete("destory");
3. disable
描述: 除能AutoComplete
範例: $(".selector").autocomplete("disable");
4. enable
描述: 致能AutoComplete
範例: $(".selector").autocomplete("enable");
5. search
描述: 強制啟動字串比對機制,並將配對資料顯示在下拉選單中。若參數為空白字串,則顯示所有比對資料庫中的所有資料,若無設定參數,則會以資料輸入框中的資料作為比對字串進行比對。
範例: $(".selector").autocomplete("search", "");
參數事件
1. change
描述: 當資料輸入框失去焦點且資料輸入框的值有異動時會觸發change事件。
輸入參數:
1. event: 型態為Event
2. ui: 型態為Js物件, 內含屬性item且其型態為jQuery物件,預設為null;若使用者選擇過配對資料,則其值為該配對資料並包裹成jQuery物件。
範例: $(".selector").autocomplete({
change: function(event, ui) { ... }
});
或
$(".selector").on("autocompletechange", function(event, ui) { ... });
2. close
描述: 當下拉選單隱藏時觸發。
輸入參數:
1. event: 型態為Event。
2. ui: 型態為Js物件。
範例: $(".selector").autocomplete({
close: function(event, ui) { ... }
});
或
$(".selector").on("autocompleteclose", function(event, ui) { ... });
3. create
描述: 當jQuery UI AutoComplete相關物件建立時觸發。
輸入參數:
1. event: 型態為Event。
2. ui: 型態為Js物件。
範例: $(".selector").autocomplete({
create: function(event, ui) { ... }
});
或
$(".selector").on("autocompletecreate", function(event, ui) { ... });
4. focus
描述: 當下拉選單的匹配項目得到焦點時會觸發此事件。(i.e. 不是使用者點選)
輸入參數:
1. event: 型態為Event。
2. ui: 型態為Js物件。內含屬性item且型態為目前具有焦點的匹配項目jQuery物件。
範例: $(".selector").autocomplete({
focus: function(event, ui) { ... }
});
或
$(".selector").on("autocompletefocus", function(event, ui) { ... });
5. open
描述: 當下拉選單顯示或是匹配資料有變動時觸發。
輸入參數:
1. event: 型態為Event。
2. ui: 型態為Js物件。
範例: $(".selector").autocomplete({
open: function(event, ui) { ... }
});
或
$(".selector").on("autocompleteopen", function(event, ui) { ... });
6. response
描述: 當比對完畢且在顯示下拉選單之前觸發;縱使沒有任何匹配的資料亦會觸發。
輸入參數:
1. event: 型態為Event。
2. ui: 型態為Js物件,內部包含屬性content且其型態為Js物件陣列;該屬性內部裝的是匹配的資料,可將這些資料進行進一步客製化,但是切記物件一定要包含label和value屬性。
範例: $(".selector").autocomplete({
response: function(event, ui) { ... }
});
或
$(".selector").on("autocompleteresponse", function(event, ui) { ... });
7. search
描述: 在進行比對之前且符合限制條件(i.e. minLength/delay)觸發。
輸入參數:
1. event: 型態為Event。
2. ui: 型態為Js物件。
範例: $(".selector").autocomplete({
search: function(event, ui) { ... }
});
或
$(".selector").on("autocompletesearch", function(event, ui) { ... });
8. select
描述: 當使用者點選下拉選單中的項目時觸發。
輸入參數:
1. event: 型態為Event。
2. ui: 型態為Js物件。內含屬性:item且型態為使用者選擇的項目jQuery物件。
範例: $(".selector").autocomplete({
select: function(event, ui) { ... }
});
或
$(".selector").on("autocompleteselect", function(event, ui) { ... });
實務
在實務上可以搭配linq.js所提供的在Js中使用類linq語法操作集合物件的方式來處理匹配資料。
var arData =
Enumerable.From(data)
.Select(function(o) { return {
label: o.Number+"("+o.Name+")",
value: o.Number,
code: o.Code,
seq: parseInt(o.Number)};)
.OrderBy(function(o) { return o.seq;})
.ToArray();
$("#elem").autocomplete({
source: arData,
select: function(event, ui) {
alert(ui.item.code);
}
});