關鍵設定如下:
$('#Sale').typeahead({
ajax: {
url: '@Url.Action("../Contract/GetSale")',
// timeout: 300,
method: 'post',
triggerLength: 1,
loadingClass: null,
preProcess: function (result) {
return result;
}
},
display: "Value",
val: "ID",
items: 10,
itemSelected: function (item, val, text) {
$("#SalesID").val(val);
}
});
要留意的是,這裡用的並非 Bootstrap 內建的 typeahead,而是社群版本 bootstrap-typeahead.js(若能用 bootstrap3-typeahead.js 更佳)。兩者的差異在於:內建版只支援前端本地陣列,而社群版額外提供了 ajax 來源、loadingClass、itemSelected 回呼等擴充能力,才能做到「一邊打 asynchronously 一邊查後端」的效果。
設定中的幾個重點:triggerLength: 1 代表輸入一個字就觸發查詢;display 指定下拉清單要顯示哪個欄位;val 指定實際要存進隱藏欄位的值(此例把 ID 寫進 #SalesID);itemSelected 則在使用者選定項目後呼叫,用來同步表單欄位。
// ----------------------------------------------------------------------------
//
// bootstrap-typeahead.js
//
// Twitter Bootstrap Typeahead Plugin
// v1.2.2
// https://github.com/tcrosen/twitter-bootstrap-typeahead
//
//
// Author
// ----------
// Terry Rosen
// tcrosen@gmail.com | @rerrify | github.com/tcrosen/
//
//
// Description
// ----------
// Custom implementation of Twitter's Bootstrap Typeahead Plugin
// https://twitter.github.com/bootstrap/javascript.html#typeahead
//
//
// Requirements
// ----------
// jQuery 1.7+
// Twitter Bootstrap 2.0+
//
// ----------------------------------------------------------------------------
! function ($) {
"use strict";
//------------------------------------------------------------------
//
// Constructor
//
var Typeahead = function (element, options) {
this.$element = $(element);
this.options = $.extend(true, {}, $.fn.typeahead.defaults, options);
this.$menu = $(this.options.menu).appendTo('body');
this.shown = false;
// Method overrides
this.eventSupported = this.options.eventSupported || this.eventSupported;
this.grepper = this.options.grepper || this.grepper;
this.highlighter = this.options.highlighter || this.highlighter;
this.lookup = this.options.lookup || this.lookup;
this.matcher = this.options.matcher || this.matcher;
this.render = this.options.render || this.render;
this.select = this.options.select || this.select;
this.sorter = this.options.sorter || this.sorter;
this.source = this.options.source || this.source;
if (!this.source.length) {
var ajax = this.options.ajax;
if (typeof ajax === 'string') {
this.ajax = $.extend({}, $.fn.typeahead.defaults.ajax, { url: ajax });
} else {
this.ajax = $.extend({}, $.fn.typeahead.defaults.ajax, ajax);
}
if (!this.ajax.url) {
this.ajax = null;
}
}
this.listen();
};
Typeahead.prototype = {
constructor: Typeahead,
//=============================================================================================================
//
// Utils
//
//=============================================================================================================
//------------------------------------------------------------------
// Check if an event is supported by the browser eg. 'keypress'
// * This was included to handle the "exhaustive deprecation" of jQuery.browser in jQuery 1.8
eventSupported: function (eventName) {
var isSupported = (eventName in this.$element);
if (!isSupported) {
this.$element.setAttribute(eventName, 'return;');
isSupported = typeof this.$element[eventName] === 'function';
}
return isSupported;
},
//=============================================================================================================
//
// AJAX
//
//=============================================================================================================
//------------------------------------------------------------------
// Handle AJAX source
ajaxer: function () {
var that = this;
var query = that.$element.val();
if (query === that.query) {
return that;
}
// Query changed
that.query = query;
// Cancel last timer if set
if (that.ajax.timerId) {
clearTimeout(that.ajax.timerId);
that.ajax.timerId = null;
}
if (!query || query.length < that.ajax.triggerLength) {
// Cancel the ajax callback if in progress
if (that.ajax.xhr) {
that.ajax.xhr.abort();
that.ajax.xhr = null;
that.ajaxToggleLoadClass(false);
}
return that.shown ? that.hide() : that;
}
// Query is good to send, set a timer
that.ajax.timerId = setTimeout(function () {
$.proxy(that.ajaxExecute(query), that)
}, that.ajax.timeout);
return that;
},
//------------------------------------------------------------------
// Execute an AJAX request
ajaxExecute: function (query) {
this.ajaxToggleLoadClass(true);
// Cancel last call if already in progress
if (this.ajax.xhr) this.ajax.xhr.abort();
var params = this.ajax.preDispatch ? this.ajax.preDispatch(query) : { query: query };
var jAjax = (this.ajax.method === "post") ? $.post : $.get;
this.ajax.xhr = jAjax(this.ajax.url, params, $.proxy(this.ajaxLookup, this));
this.ajax.timerId = null;
},
//------------------------------------------------------------------
// Perform a lookup in the AJAX results
ajaxLookup: function (data) {
var items;
this.ajaxToggleLoadClass(false);
if (!this.ajax.xhr) return;
if (this.ajax.preProcess) {
data = this.ajax.preProcess(data);
}
// Save for selection retreival
this.ajax.data = data;
items = this.grepper(this.ajax.data);
if (!items || !items.length) {
return this.shown ? this.hide() : this;
}
this.ajax.xhr = null;
return this.render(items.slice(0, this.options.items)).show();
},
//------------------------------------------------------------------
// Toggle the loading class
ajaxToggleLoadClass: function (enable) {
if (!this.ajax.loadingClass) return;
this.$element.toggleClass(this.ajax.loadingClass, enable);
},
//=============================================================================================================
//
// Data manipulation
//
//=============================================================================================================
//------------------------------------------------------------------
// Search source
lookup: function (event) {
var that = this;
var items;
if (that.ajax) {
that.ajaxer();
} else {
that.query = that.$element.val();
if (!that.query) {
return that.shown ? that.hide() : that;
}
items = that.grepper(that.source);
if (!items || !items.length) {
return that.shown ? that.hide() : that;
}
return that.render(items.slice(0, that.options.items)).show();
}
},
//------------------------------------------------------------------
// Filters relevent results
grepper: function (data) {
var that = this;
var items;
if (data && data.length && !data[0].hasOwnProperty(that.options.display)) {
return null;
}
items = $.grep(data, function (item) {
return that.matcher(item[that.options.display], item);
});
return this.sorter(items);
},
//------------------------------------------------------------------
// Looks for a match in the source
matcher: function (item) {
return ~item.toLowerCase().indexOf(this.query.toLowerCase());
},
//------------------------------------------------------------------
// Sorts the results
sorter: function (items) {
var that = this;
var beginswith = [];
var caseSensitive = [];
var caseInsensitive = [];
var item;
while (item = items.shift()) {
if (!item[that.options.display].toLowerCase().indexOf(this.query.toLowerCase())) {
beginswith.push(item);
} else if (~item[that.options.display].indexOf(this.query)) {
caseSensitive.push(item);
} else {
caseInsensitive.push(item);
}
}
return beginswith.concat(caseSensitive, caseInsensitive);
},
//=============================================================================================================
//
// DOM manipulation
//
//=============================================================================================================
//------------------------------------------------------------------
// Shows the results list
show: function () {
var pos = $.extend({}, this.$element.offset(), {
height: this.$element[0].offsetHeight
});
this.$menu.css({
top: pos.top + pos.height,
left: pos.left
});
this.$menu.show();
this.shown = true;
return this;
},
//------------------------------------------------------------------
// Hides the results list
hide: function () {
this.$menu.hide();
this.shown = false;
return this;
},
//------------------------------------------------------------------
// Highlights the match(es) within the results
highlighter: function (item) {
var query = this.query.replace(/[\-\[\]{}()*+?.,\\\^$|#\s]/g, '\\$&');
return item.replace(new RegExp('(' + query + ')', 'ig'), function ($1, match) {
return '<strong>' + match + '</strong>';
});
},
//------------------------------------------------------------------
// Renders the results list
render: function (items) {
var that = this;
items = $(items).map(function (i, item) {
i = $(that.options.item).attr('data-value', item[that.options.val]);
i.find('a').html(that.highlighter(item[that.options.display], item));
return i[0];
});
items.first().addClass('active');
this.$menu.html(items);
return this;
},
//------------------------------------------------------------------
// Item is selected
select: function () {
var $selectedItem = this.$menu.find('.active');
this.$element.val($selectedItem.text()).change();
this.options.itemSelected($selectedItem, $selectedItem.attr('data-value'), $selectedItem.text());
return this.hide();
},
//------------------------------------------------------------------
// Selects the next result
next: function (event) {
var active = this.$menu.find('.active').removeClass('active');
var next = active.next();
if (!next.length) {
next = $(this.$menu.find('li')[0]);
}
next.addClass('active');
},
//------------------------------------------------------------------
// Selects the previous result
prev: function (event) {
var active = this.$menu.find('.active').removeClass('active');
var prev = active.prev();
if (!prev.length) {
prev = this.$menu.find('li').last();
}
prev.addClass('active');
},
//=============================================================================================================
//
// Events
//
//=============================================================================================================
//------------------------------------------------------------------
// Listens for user events
listen: function () {
this.$element
.on('blur', $.proxy(this.blur, this))
.on('keyup', $.proxy(this.keyup, this));
if (this.eventSupported('keydown')) {
this.$element.on('keydown', $.proxy(this.keypress, this));
} else {
this.$element.on('keypress', $.proxy(this.keypress, this));
}
this.$menu
.on('click', $.proxy(this.click, this))
.on('mouseenter', 'li', $.proxy(this.mouseenter, this));
},
//------------------------------------------------------------------
// Handles a key being raised up
keyup: function (e) {
e.stopPropagation();
e.preventDefault();
switch (e.keyCode) {
case 40: // down arrow
case 38: // up arrow
break;
case 9: // tab
case 13: // enter
if (!this.shown) {
return;
}
this.select();
break;
case 27: // escape
this.hide();
break;
default:
this.lookup();
}
},
//------------------------------------------------------------------
// Handles a key being pressed
keypress: function (e) {
e.stopPropagation();
if (!this.shown) {
return;
}
switch (e.keyCode) {
case 9: // tab
case 13: // enter
case 27: // escape
e.preventDefault();
break;
case 38: // up arrow
e.preventDefault();
this.prev();
break;
case 40: // down arrow
e.preventDefault();
this.next();
break;
}
},
//------------------------------------------------------------------
// Handles cursor exiting the textbox
blur: function (e) {
var that = this;
e.stopPropagation();
e.preventDefault();
setTimeout(function () {
if (!that.$menu.is(':focus')) {
that.hide();
}
}, 150);
},
//------------------------------------------------------------------
// Handles clicking on the results list
click: function (e) {
e.stopPropagation();
e.preventDefault();
this.select();
},
//------------------------------------------------------------------
// Handles the mouse entering the results list
mouseenter: function (e) {
this.$menu.find('.active').removeClass('active');
$(e.currentTarget).addClass('active');
}
};
//------------------------------------------------------------------
// Plugin definition
$.fn.typeahead = function (option) {
return this.each(function () {
var $this = $(this);
var data = $this.data('typeahead');
var options = typeof option === 'object' && option;
if (!data) {
$this.data('typeahead', (data = new Typeahead(this, options)));
}
if (typeof option === 'string') {
data[option]();
}
});
};
//------------------------------------------------------------------
// Defaults
$.fn.typeahead.defaults = {
source: [],
items: 8,
menu: '<ul class="typeahead dropdown-menu"></ul>',
item: '<li><a href="#"></a></li>',
display: 'name',
val: 'id',
itemSelected: function () { },
ajax: {
url: null,
timeout: 300,
method: 'post',
triggerLength: 3,
loadingClass: null,
displayField: null,
preDispatch: null,
preProcess: null
}
};
$.fn.typeahead.Constructor = Typeahead;
}(window.jQuery);
讀原始碼時有幾處值得留意。ajaxer 裡做了防抖(debounce)處理:查詢字串沒變就直接返回,有舊的計時器就先清掉,字元數不足 triggerLength 時甚至會主動 abort 進行中的請求——這能有效避免快速輸入時送出一堆無效查詢。
另外 sorter 把結果分成三層排序:以查詢字開頭的排最前、大小寫完全相符的次之、其餘墊後,這比單純的 indexOf 排序更貼近使用者期待。而 highlighter 在拼 RegExp 前先跳脫特殊字元,避免輸入 (、* 這類字元時造成語法錯誤。
實務上仍需注意安全性:render 用 .html() 插入後端回傳的文字,若資料來源未經消毒,就存在 XSS 風險。建議在伺服器端過濾,或前端改用 .text() 搭配另外處理高亮。