[jQuery套件]自動完成–AutoSuggest

本質

   本質上AutoSuggest jQuery套件是一款用於解決欄位文字輸入自動完成的Js套件。AutoSuggest jQuery較不同之處在於它較一般自動完成的jQuery套件小,縮小化後僅8.8kb。AutoSuggest jQuery有極其強大的客製化功能,可應用於各種不同的情境下。

圖1. AutoSuggest jQuery實際操作範例

基本型

   若是較一般的使用情境其實不需要太多額外的設定即可使用AutoSuggest jQuery這個套件;而在程式撰寫上,該套件的輸入參數個數僅兩個- 資料來源 和 參數物件。

   資料來源: AutoSuggest jQuery的資料來源可以是預先下載好的Js物件,亦可以採用Ajax的方式讓AutoSuggest jQuery在比對時是將資料送往後端伺服器進行資料比對。而此兩者在撰寫上的差異僅僅只是一個Js物件, 另一個是Url字串。

   1. Js物件範例:

1 var data={ items: [
2    {value: "1", name: "Hi"},
3    {value: "2", name: "Hello"}
4 ]};
5
6 $("input[type=text]").autoSuggest(data.items);

    2. Url字串

1 $("input[type=text]").autoSuggest(<a href="http://MyWebSite.com/Controller/Action">http://MyWebSite.com/Controller/Action</a>);

   採用Url字串若不做特別設定,則AutoSuggest jQuery套件預設會以HttpGet的方式,並且以q為參數名稱向開發人員所指定的Url進行資料比對,故,在伺服器端的Action在撰寫上要特別小心參數名稱不可取錯,並且要能夠允許Get方法。

1 [HttpGet]
2 public JsonResult GetData(string q) { ... }

   若需要較大量的客製化,則必須針對其參數物件進行設定。

 

參數物件

   AutoSuggest jQuery一共有27個參數可供設定。

   1. asHtmlID

       預設值: false

       類型: 字串

       AutoSuggest jQuery套件當啟動時會產生附加的Html標籤;當使用者鍵入字串並且選擇了某筆配對的資料項目,則該資料項目的值會自動放置到AutoSuggest自動產生的Hidden標籤中, 並且以逗號作為資料的區隔符號,若設定此參數為"X",則Hidden標籤的id則為"as-values-X"。

   2. startText

       預設值: "Enter Name Here"

       類型: 字串

       此一屬性所設定的值會顯示在AutoSuggest jQuery所附著的Html標籤中作為初始提示訊息顯示。

   3. emptyText

       預設值: "No Results"

       類型: 字串

       當使用者所輸入的字串經比對後發現沒有適合的配對資料,則會在AutoSuggest jQuery的下拉選單中顯示此參數所設定的值。

   4. preFill

       預設值: {}

       類型: Js物件

       某些時候要將使用者已經設定過的值重新倒回來,這個時就可以藉由設定這個參數來達成。而此一參數都是採用單個js物件或是js物件陣列;使用上要注意的是,指派給preFill的物件其內部需具有指定的屬性;例如,若已設定selectedItemProp為name,而selectedValuesProp為value,則指派給preFill的所有物件都需具有name以及value這兩個屬性。

   5. limitText

       預設值: "No More Selections Are Allowed"

       類型: 字串

       AutoSuggest jQuery套件允許開發人員設定限制值;當使用者操作達到開發人員所限制的項目時,會顯示這個屬性所設定的值。

   6. selectedItemProp

       預設值: "value"

       類型: 字串

       設定AutoSuggest jQuery在比對完使用者所輸入的字串之後,將此屬性所指定的物件屬性名稱顯示在下拉選單上。

   7. seletedValuesProp

       預設值: "value"

       類型: 字串

       當使用者選則了某項配對的資料項目後,AutoSuggest會將此資料項目依此屬性所指定的物件屬性名稱儲存到AutoSuggest所動態產生的Hidden標籤中。

   8. searchObjProps

       預設值: "value"

       類型: 字串

       AutoSuggest jQuery會依此屬性所指定的物件屬性名稱的值作為字串比對的目標。

   9. queryParam

       預設值: "q"

       類型: 字串

       當採用Ajax的方式作為資串比對的方法時,會依此屬性所指定的輸入參數名稱送至後端伺服器進行字串比對。

   10. retriveLimit

        預設值: false

        類型: 字串

        當採用Ajax的方式作為字串比對的方法時,會依此屬性所指定數字在Ajax中夾帶"&limit="這個輸入參數到後端,作為配對資料筆數上限的設定。

   11. extraParams

        預設值: ""

        類型: 字串

        當採用Ajax的方式作為字串比對的方法時,會依此屬性所指定的字串作為Ajax中夾帶;使用上要在每個參數前加上"&"符號。例: "&IsDel=false&Type=1"。

   12. matchCase

        預設值: false

        類型: 布林

        當設定為true時,比對字串時除了字元之外還會針對字元的大小寫進行比對。

   13. minChars

        預設值: 1

        類型: 整數

        規範使用者最少需鍵入幾個字元,當使用者輸入足夠的字元後AutoSuggest才會啟動字串比對。

   14. keyDelay

        預設值: 400

        類型: 整數

        AutoSuggest會依此屬性所設定的微秒來作為當使用者鍵入資料後等待的時間;待到達等待時間之後才啟動字串比對。

   15. resultsHighlight

        預設值: true

        類型: 布林

        當設定為true時,使用者在挑選配對的項目時,該筆項目在下拉選單中會以不同的顏色作為區隔。

   16. neverSubmit

        預設值: false

        類型: 布林

        當設定為true時,AutoSuggest套件不會引發表單的提交事件。

   17. selectionLimit

        預設值: false

        類型: 整數

        限制使用者可以比對資料的次數。

   18. showResultList

        預設值: true

        類型: 布林

        若設定為false,則配對資料就不會顯示在下拉選單中。

   19. start

        預設值: null

        類型: callback Function

        AutoSuggest jQuery套件被啟動時會呼叫此函數。

   20. selectionClick

        預設值: null

        類型: callback Function

        當使用者選擇了某個配對的項目後AutoSuggest套件會呼叫此函數,並且將使用者所選擇的項目作為輸入參數輸入到函數中。

        範例:

1 selectionClick: function(elem) { elem.fadeTo("slow", 0.5); }

   21. selectionAdded

        預設值: null

        類型: callback Function

        當使用者選擇了某個配對的項目或是藉由鍵盤的tab/逗號鍵新增資料都會讓AutoSuggest呼叫此函數,並將所新增的資料作為輸入參數輸入到函數中。

        範例:

1 selectionAdded: function(elem) { elem.fadeTo("slow", 0.5); }

   22. selectionRemoved

        預設值: null

        類型: callback Function

        當使用者點選已選項目的"x"或是以鍵盤的刪除鍵來刪除資料時,AutoSuggest會呼叫此函數,並把所刪除資料作為輸入參數輸入到函數中。

        範例:

1 selectionRemoved: function(elem) { elem.fadeTo("fast",0, function() { elem.remove();})};

   23. formatList

        預設值: null

        類型: callback Function

        當資料比對完畢在將配對資料顯示在下拉選單之前AutoSuggest會呼叫此函數;故可以利用此函數進行配對資料顯示的客製化。

        範例: 

1 formatList: function(data, elem) {
2
3    var img = data.img;
4
5    var newElem = elem.html("<img src='" + img + "' alt='" + data.value +"' />");
6
7    return newElem;
8
9 }

   24. beforeRetrieve

        預設值: null

        類型: callback Function

        在AutoSuggest套件將使用者所輸入的資料進行比對之前會呼叫此函數;此函數的目的在於提供一個可以調整使用者所輸入的查詢比對字串,譬如當使用者輸入"guy",則函數可將此字串加以修飾成"guy_"。

        範例:

1 beforeRetrieve: function(string) { return string+"_"; }

   25. retrieveComplete

        預設值: null

        類型: callback Function

        當採用Ajax時,資料在後端伺服器比對完畢之後送回到AutoSuggest套件會呼叫此函數,並且將比對的資料作為輸入參數輸入到函數中。

        範例: 

1 retrieveComplete: function(data) { return data; }

   26. resultClick

        預設值: null

        類型: callback Function

        當使用者點選配對資料下拉選單中某個項目時AutoSuggest會呼叫此一函數,並且將使用者所點選的項目作為輸入參數輸入到函數中。

        範例:

1 resultClick: function(data) { console.log(data); }

   27. resultComplete

        預設值: null

        類型: callback Function

        當配對資料顯示在下拉選單後AutoSuggest套件會呼叫此函數。