typeahead.js 是 Twitter 官方推出的自動完成外掛,功能相當完整。本文示範如何在 Bootstrap 3 專案中把它跑起來,並說明 Bloodhound 這個資料引擎的用法與可用事件。
官方網站:https://twitter.github.io/typeahead.js
jQuery 版文件:https://github.com/twitter/typeahead.js/blob/master/doc/jquery_typeahead.md
· local:直接給一個陣列,資料就在前端。
· prefetch:先抓一份 JSON 回來快取,之後比對都在本地進行。
· remote:每次輸入都向伺服器查詢,適合資料量龐大或需要即時性的場景。

<input id="orderNo" class="typeahead" placeholder="Countries" type="text" class="form-control" name="ordersn">
順帶一提,這行 HTML 重複寫了兩次 class 屬性。HTML 規格中同一元素的重複屬性只有第一個會生效,所以 form-control 實際上不會被套用。正確寫法應該合併:class="typeahead form-control"。
// 純本機資料的 Bloodhound 實例
var states = new Bloodhound({
datumTokenizer: Bloodhound.tokenizers.whitespace,
queryTokenizer: Bloodhound.tokenizers.whitespace,
local: states // states 是一個字串陣列
});
// 混合 prefetch 與 remote 的 Bloodhound 實例
var findOrderByIdVague = new Bloodhound({
datumTokenizer: Bloodhound.tokenizers.obj.whitespace('value'),
queryTokenizer: Bloodhound.tokenizers.whitespace,
// 先快取一份常用資料
prefetch: '${ctx}/admin/order/preOrderByIdVague.json',
// 本地找不到時,再向伺服器查詢;%QUERY 為佔位符
remote: {
url: '${ctx}/admin/order/findOrderByIdVague/%QUERY.json',
wildcard: '%QUERY'
},
afterSelect: function (item) {
// 選中之後的事件,item 即為當前選取的項目
alert(item);
}
});
$(function () {
/** 單純使用本地陣列的寫法
$('#addCombo .typeahead').typeahead({
hint: true,
highlight: true,
minLength: 1
}, {
name: 'states',
source: states
});
**/
$('#addCombo .typeahead').typeahead(null, {
name: 'best-pictures',
display: 'value',
source: findOrderByIdVague
});
// 監聽選取事件
$('#addCombo .typeahead').bind('typeahead:select', function (ev, suggestion) {
console.log('Selection: ' + suggestion.value);
});
});
這裡有幾個關鍵概念。datumTokenizer 與 queryTokenizer 分別決定「資料怎麼被拆解成比對用的 token」與「使用者輸入怎麼被拆解」。obj.whitespace('value') 表示要把物件中的 value 欄位取出來做空白切分。display: 'value' 則指定輸入框要顯示哪個欄位。
另外注意 .typeahead(null, {...}) 的第一個參數是通用設定,第二個才是各資料集的設定。傳 null 代表不特別設定通用選項,而 name 用來標識資料集,多資料集時必須唯一。
範例中的 afterSelect 拼字有誤(alert(iterm)),且未見於官方選項清單;若要處理選取後的行為,建議改用下面說明的 typeahead:select 事件。
findOrderByIdVague/D20150502.json:
[
{ "value": "D20150502173435141299" },
{ "value": "D20150502172928109304" }
]
preOrderByIdVague.json:
[{"value":"D201"}]
因為 prefetch 與 remote 同時存在,Bloodhound 會先用 prefetch 的快取回應,若結果數量少於 sufficient 所設定的門檻(預設 5),才接著發出 remote 請求補足。這正是這個範例選 prefetch 只放一筆資料的原因——目的是示範「快取不夠就補打 API」的行為。
下列事件會在 typeahead 的生命週期中觸發於 input 元素上:
· typeahead:active — typeahead 進入啟用狀態時觸發。
· typeahead:idle — typeahead 進入閒置狀態時觸發。
· typeahead:open — 結果容器被打開時觸發。
· typeahead:close — 結果容器被關閉時觸發。
· typeahead:change — 正規化後的 change 事件。輸入框失焦且值已變動時觸發。
· typeahead:render — 某資料集的建議被渲染時觸發。回呼會收到四個參數:jQuery 事件物件、被渲染的建議、是否為非同步取得,以及資料集名稱。
· typeahead:select — 某個建議被選中時觸發。回呼收到 jQuery 事件物件與該建議物件。
· typeahead:autocomplete — 發生自動補完時觸發。回呼收到 jQuery 事件物件與用於補完的建議物件。
· typeahead:cursorchange — 游標在結果間移動時觸發。回呼收到 jQuery 事件物件與移動到的建議物件。
· typeahead:asyncrequest — 送出非同步查詢請求時觸發。回呼收到 jQuery 事件物件、當前查詢字串與資料集名稱。
· typeahead:asynccancel — 非同步請求被取消時觸發,參數同上。
· typeahead:asyncreceive — 非同步請求完成時觸發,參數同上。
使用範例:
$('.typeahead').bind('typeahead:select', function(ev, suggestion) {
console.log('Selection: ' + suggestion);
});
.typeahead, .tt-query, .tt-hint {
width: 396px;
height: 30px;
padding: 8px 12px;
font-size: 24px;
line-height: 30px;
border: 2px solid #ccc;
-webkit-border-radius: 8px;
-moz-border-radius: 8px;
border-radius: 8px;
outline: none;
}
.typeahead { background-color: #fff; }
.typeahead:focus { border: 2px solid #0097cf; }
.tt-query {
-webkit-box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.075);
-moz-box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.075);
box-shadow: inset 0 1px 1px rgba(0, 0, 0, 0.075);
}
.tt-hint { color: #999; }
.tt-menu {
width: 422px;
margin: 12px 0;
padding: 8px 0;
background-color: #fff;
border: 1px solid #ccc;
border: 1px solid rgba(0, 0, 0, 0.2);
-webkit-border-radius: 8px;
-moz-border-radius: 8px;
border-radius: 8px;
-webkit-box-shadow: 0 5px 10px rgba(0,0,0,.2);
-moz-box-shadow: 0 5px 10px rgba(0,0,0,.2);
box-shadow: 0 5px 10px rgba(0,0,0,.2);
}
.tt-suggestion {
padding: 3px 20px;
font-size: 18px;
line-height: 24px;
}
.tt-suggestion:hover,
.tt-suggestion.tt-cursor {
color: #fff;
background-color: #0097cf;
}
.tt-suggestion p { margin: 0; }
.gist { font-size: 14px; }
/* 範例專用樣式 */
#custom-templates .empty-message {
padding: 5px 10px;
text-align: center;
}
#multiple-datasets .league-name {
margin: 0 20px 5px 20px;
padding: 3px 0;
border-bottom: 1px solid #ccc;
}
#scrollable-dropdown-menu .tt-menu {
max-height: 150px;
overflow-y: auto;
}
#rtl-support .tt-menu { text-align: right; }
這裡的三個 class 命名規則值得記住:tt-input 是輸入框、tt-hint 是灰色提示文字、tt-menu 是下拉容器、tt-suggestion 是每一筆候選、tt-cursor 則是目前用鍵盤選到的那一筆。要客製外觀時,改這幾個就夠了。
官方發佈的 typeahead.bundle.js(0.11.1 版)已內含 Bloodhound、Transport、PersistentStorage、SearchIndex、Menu、Dataset 與 Typeahead 等全部模組,同時也打包了 _(UnderScore 的精簡版)與 highlight 工具,因此不需要另外載入 underscore-min.js。這個檔案本身是三千餘行的第三方函式庫原始碼,請直接從專案下載頁面取得,本文不再轉貼。
從原始碼架構可以看出它的設計相當嚴謹:Transport 負責請求排隊與去重(同時最多 6 個 pending 請求,相同的 fingerprint 會共用同一個 xhr)、LruCache 提供 LRU 快取、PersistentStorage 在 localStorage 不可用時會自動降級為 noop、SearchIndex 則用 trie 樹做前綴比對。這些細節解釋了為什麼它在大量資料下仍能保持流暢。
以上就是 Bootstrap 3 搭配 typeahead.js 實作自動完成的完整分享,希望對你的搜尋體驗有所幫助。