自動完成(Autocomplete)能大幅降低使用者的輸入成本,也是搜尋框的標準配備。以下把這個經典插件的參數、資料格式與各類用法一次講清楚。
autocomplete(url or data, [options])
url or data 可以是陣列或遠端網址;[options] 為選項,逐項說明如下。
,。(row, i, max):資料列、目前處理到第幾列(從 1 開始)、資料列總數。預設 none,此時每一行只顯示一個值。{ bar: 4 } 時,假設使用者輸入 foo,請求網址會解析成 my_autocomplete_backend.php?q=foo&bar=4。預設 {}。使用者選中某一項後觸發,回傳 jQuery 物件。三個參數分別是:
event.type 為 result。formatResult 的回傳值。$("#singleBirdRemote").result(function(event, data, formatted){
// 例如選取後為其他控制項賦值、觸發別的事件等
});
本地資料源可以是 JavaScript 陣列,也可以是 JSON 物件陣列:
var data = ["c++", "java", "php", "coldfusion", "javascript"];
var data = [{text:'Link A', url:'/page1'}, {text:'Link B', url: '/page2'}];
使用遠端網址時,插件預設會送出兩個參數:q(輸入值)與 limit(回傳結果上限),其他參數可透過 extraParams 追加。
遠端資料源必須遵守固定格式:以 \n 分隔每一行,行內再用 | 分隔各欄位。後端 C# 的輸出範例:
string data = "c++\n java \n php \n coldfusion \n javascript";
string data = "{text:'LinkA', url:'/page1'} \n {text:'Link B', url: '/page2'}";
寫法一,直接傳入陣列並搭配版面選項:
$("#tags").autocomplete(["c++", "java", "php", "coldfusion", "javascript"], {
width: 320,
max: 4,
highlight: false,
multiple: true,
multipleSeparator: "",
scroll: true,
scrollHeight: 300
});
寫法二,用物件陣列並在選取後跳轉:
var data = [{text:'Link A', url:'/page1'}, {text:'Link B', url: '/page2'}];
$("...").autocomplete(data, {
formatItem: function(item) {
return item.text;
}
}).result(function(event, item) {
location.href = item.url;
});
前台 JavaScript:
<script type="text/javascript">
$(document).ready(function() {
$("#Login").focus().autocomplete("/ajax/Account", {
formatItem: function(row, i, max) {
var obj = eval("(" + row + ")"); // 轉成 JS 物件
return obj.Text;
},
formatResult: function(row) {
var obj = eval("(" + row + ")");
return obj.Text;
}
}).result(function(event, item) {
var obj = eval("(" + item + ")");
$("#link").attr("href", obj.url);
});
});
</script>
後台 C#(MVC):
public ContentResult GetUserAccount(string q)
{
string strResult = "";
// ...查詢資料操作...
// ...格式化資料...
// 格式化後的結果形如:
strResult = "{text:'Link A', url:'/page1'}\n {text:'Link B', url: '/page2'}";
return Content(strResult);
}
另一種做法是先以 getJSON 把資料取回,再餵給 autocomplete,這樣格式處理更直觀:
<script type="text/javascript">
$(document).ready(function() {
$.getJSON("/ajax/Account", function(data) {
$("#Login").focus().autocomplete(data, {
formatItem: function(item, i, max) {
return item.Text;
},
formatResult: function(item) {
return item.Text;
}
}).result(function(event, item) {
$("#link").attr("href", item.url);
});
});
});
</script>
對應的後台只需輸出合法 JSON:
public ContentResult Account(string q)
{
string strResult = "";
// ...查詢與格式化...
strResult = "[{\"text\":\"LinkA\", \"url\":\"/page1\"}, {\"text\":\"LinkB\", \"url\": \"/page2\"} ]";
return Content(strResult);
}
範例中的 eval() 用來把字串轉物件,示範可以,正式環境請改用 JSON.parse();eval 會執行任意程式碼,若資料來源遭污染就是安全漏洞。另外,遠端模式下建議在伺服端限制 limit 的上限,避免被大量請求拖垮。