DIV CSS 佈局教程網

Bootstrap 3 搭配 typeahead.js 與 Bloodhound 實作自動完成
編輯:關於JavaScript     

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:每次輸入都向伺服器查詢,適合資料量龐大或需要即時性的場景。

HTML

 <input id="orderNo" class="typeahead" placeholder="Countries" type="text" class="form-control" name="ordersn">

順帶一提,這行 HTML 重複寫了兩次 class 屬性。HTML 規格中同一元素的重複屬性只有第一個會生效,所以 form-control 實際上不會被套用。正確寫法應該合併:class="typeahead form-control"。

JavaScript

 // 純本機資料的 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

官方發佈的 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 實作自動完成的完整分享,希望對你的搜尋體驗有所幫助。

XML學習教程| jQuery入門知識| AJAX入門| Dreamweaver教程| Fireworks入門知識| SEO技巧| SEO優化集錦|
Copyright © DIV+CSS佈局教程網 All Rights Reserved