本文整理了一套以 Bootstrap 外掛實作 Autocomplete 自動補全的完整流程,包含前端腳本、資料格式約定與 PHP 端回應範例,並補上原文交代不清的一些細節,希望能幫上大家的忙。
使用之前,當然要先引入 jQuery 與 Bootstrap。這裡有兩個關鍵點特別容易踩坑:
第一,後端回傳的二維陣列結構,必須與 formatItem 中取用的欄位名稱完全一致,否則提示清單會一片空白。
第二,回傳的字串一定要先用 $.parseJSON() 解析成物件,再交給 process(),切勿直接把原始文字丟進去。
source:簽名為 function(query, process){}。query 是輸入框當前文字,你可以在這裡發出 Ajax 請求向後端要資料(JSON 陣列),再把結果當成參數傳給 process。
formatItem:簽名為 function(item){}。負責把單筆資料轉成字串,用來顯示在提示清單中,回傳值必須是字串。
setValue:簽名為 function(item){}。決定選中某項後,輸入框顯示什麼、實際要帶走的值又是什麼。回傳格式為 {'data-value': 顯示值欄位, 'real-value': 實際值欄位},之後可透過輸入框的 real-value 屬性把真實值取出來。
items:提示清單最多顯示幾筆,預設 8。
minLength:輸入字元數達到多少才觸發比對,預設 1。
delay:停止輸入後延遲幾毫秒才真正送出請求,避免打字太快造成後端被狂刷,預設 500。
<script>
$('#sim_iccid').autocomplete({
source: function(query, process){
var matchCount = this.options.items; // 允許回傳的結果集上限
$.get("https://www.soyiyuan.com/update/", {"iccid": query, "matchCount": matchCount}, function(respData){
respData = $.parseJSON(respData); // 記得先解析
return process(respData);
});
},
formatItem: function(item){
return item["iccid"] + "(" + item["mobile"] + ")";
},
setValue: function(item){
return {'data-value': item["iccid"], 'real-value': item["mobile"]};
}
});
</script>
假設 $data 是一個二維陣列,直接 echo json_encode($data); 即可。
[{"iccid":"12345678901234567890","mobile":"1850000"},{"iccid":"12345785","mobile":"1850001"}]
Bootstrap 的 Autocomplete 其實是基於內建的 typeahead 改寫而來。差別在於 typeahead 只吃字串陣列,無法處理需要同時帶多個欄位的複雜物件;改造後的版本則可以輕鬆應付「顯示一段文字、實際帶走另一段值」這類常見需求。
// 另一個應用場景:區域選擇
$('#autocompleteInput').autocomplete({
source: function(query, process){
var matchCount = this.options.items;
$.post("/bootstrap/region", {"matchInfo": query, "matchCount": matchCount}, function(respData){
return process(respData);
});
},
formatItem: function(item){
return item["regionName"] + "(" + item["regionNameEn"] + "," + item["regionShortnameEn"] + ") - " + item["regionCode"];
},
setValue: function(item){
return {'data-value': item["regionName"], 'real-value': item["regionCode"]};
}
});
$("#goBtn").click(function(){
// 真正要送給後端的是區域代碼,不是顯示文字
var regionCode = $("#autocompleteInput").attr("real-value") || "";
alert(regionCode);
});
以上就是完整的實作思路。想 further 深入 Bootstrap 的讀者,可以搭配《Bootstrap 學習教程》《Bootstrap 實戰教程》《Bootstrap 外掛使用教程》一起看,效果會更好。