DIV CSS 佈局教程網

jQuery Autocomplete 自動完成功能完整詳解
編輯:JQuery特效代碼     

自動完成(Autocomplete)能大幅降低使用者的輸入成本,也是搜尋框的標準配備。以下把這個經典插件的參數、資料格式與各類用法一次講清楚。

參考資源

  • https://bassistance.de/jquery-plugins/jquery-plugin-autocomplete/
  • https://docs.jquery.com/Plugins/Autocomplete

語法與參數

autocomplete(url or data, [options])

url or data 可以是陣列或遠端網址;[options] 為選項,逐項說明如下。

行為與外觀

  • minChars(Number):觸發自動完成前,使用者至少要輸入的字元數。預設 1;設為 0 時,在輸入框內雙擊或清空內容也會顯示列表。
  • width(Number):下拉框寬度,預設等於 input 元素寬度。
  • max(Number):下拉顯示的項目數上限,預設 10。
  • delay(Number):按鍵後啟動自動完成的延遲毫秒數,預設遠端 400、本地 10。
  • autoFill(Boolean):選擇時是否自動把滑鼠所在的值填入輸入框,預設 false。
  • mustMatch(Boolean):設為 true 時只允許比對成功的結果留在輸入框,輸入非法內容將不會出現下拉,預設 false。
  • selectFirst(Boolean):設為 true 時,使用者按 Tab 或 Enter 會自動選取下拉的第一項(即使未經手動選取);若使用者已選中某項則以其選擇為準。預設 true。

比對與快取

  • matchContains(Boolean):是否在字串內部進行比對,例如輸入 ba 是否要匹配 foo bar。使用快取時影響明顯,且不要與 autoFill 混用。預設 false。
  • cacheLength(Number):快取長度,也就是從資料庫取回的結果要保留幾筆,設為 1 代表不快取。預設 10。
  • matchSubset(Boolean):是否允許使用伺服器查詢的快取。若已快取 foo 的結果,使用者再輸入 foo 就不必重新查詢,直接取用快取。通常在快取長度大於 1 時才有效,開啟可減輕伺服器負擔。預設 true。
  • matchCase(Boolean):比對時是否區分大小寫,使用快取時同樣重要——例如 foot 要不要去 FOO 的快取裡找。預設 false。

多值輸入與捲軸

  • multiple(Boolean):是否允許一次輸入多個值,也就是重複使用自動完成,預設 false。
  • multipleSeparator(String):多選時用來分隔各選擇的字元,預設 ,。
  • scroll(Boolean):結果集超出預設高度時是否改用捲軸顯示,預設 true。
  • scrollHeight(Number):捲軸高度(px),預設 180。

格式化函數

  • formatItem(Function):為每個顯示項目套用進階標記,結果的每一行都會呼叫此函數,回傳值會被包在 LI 元素中呈現於下拉。函數收到三個參數 (row, i, max):資料列、目前處理到第幾列(從 1 開始)、資料列總數。預設 none,此時每一行只顯示一個值。
  • formatResult(Function):與 formatItem 類似,但作用對象是「即將填入輸入框的值」,同樣有三個參數。預設 none,表示要嘛只有資料,要嘛使用 formatItem 提供的值。
  • formatMatch(Function):格式化每一行「需要拿去比對」的資料,回傳值供內部搜尋演算法使用,參數為 row。
  • extraParams(Object):為後端腳本額外提供參數,以鍵值對物件表示。傳入 { bar: 4 } 時,假設使用者輸入 foo,請求網址會解析成 my_autocomplete_backend.php?q=foo&bar=4。預設 {}。

result 事件

使用者選中某一項後觸發,回傳 jQuery 物件。三個參數分別是:

  • event:事件物件,event.type 為 result。
  • data:被選中的資料列。
  • formatted:formatResult 的回傳值。
$("#singleBirdRemote").result(function(event, data, formatted){
  // 例如選取後為其他控制項賦值、觸發別的事件等
});

資料來源:本地與遠端

本地資料源可以是 JavaScript 陣列,也可以是 JSON 物件陣列:

var data = ["c++", "java", "php", "coldfusion", "javascript"];
var data = [{text:'Link A', url:'/page1'}, {text:'Link B', url: '/page2'}];

使用遠端網址時,插件預設會送出兩個參數:q(輸入值)與 limit(回傳結果上限),其他參數可透過 extraParams 追加。

遠端資料源必須遵守固定格式:以 \n 分隔每一行,行內再用 | 分隔各欄位。後端 C# 的輸出範例:

string data = "c++\n java \n php \n coldfusion \n javascript";
string data = "{text:'LinkA', url:'/page1'} \n {text:'Link B', url: '/page2'}";

實例演練

一、本地資料源

寫法一,直接傳入陣列並搭配版面選項:

$("#tags").autocomplete(["c++", "java", "php", "coldfusion", "javascript"], {
  width: 320,
  max: 4,
  highlight: false,
  multiple: true,
  multipleSeparator: "",
  scroll: true,
  scrollHeight: 300
});

寫法二,用物件陣列並在選取後跳轉:

var data = [{text:'Link A', url:'/page1'}, {text:'Link B', url: '/page2'}];
$("...").autocomplete(data, {
  formatItem: function(item) {
    return item.text;
  }
}).result(function(event, item) {
  location.href = item.url;
});

二、遠端資料源

前台 JavaScript:

<script type="text/javascript">
$(document).ready(function() {
  $("#Login").focus().autocomplete("/ajax/Account", {
    formatItem: function(row, i, max) {
      var obj = eval("(" + row + ")"); // 轉成 JS 物件
      return obj.Text;
    },
    formatResult: function(row) {
      var obj = eval("(" + row + ")");
      return obj.Text;
    }
  }).result(function(event, item) {
    var obj = eval("(" + item + ")");
    $("#link").attr("href", obj.url);
  });
});
</script>

後台 C#(MVC):

public ContentResult GetUserAccount(string q)
{
  string strResult = "";
  // ...查詢資料操作...
  // ...格式化資料...
  // 格式化後的結果形如:
  strResult = "{text:'Link A', url:'/page1'}\n {text:'Link B', url: '/page2'}";
  return Content(strResult);
}

另一種做法是先以 getJSON 把資料取回,再餵給 autocomplete,這樣格式處理更直觀:

<script type="text/javascript">
$(document).ready(function() {
  $.getJSON("/ajax/Account", function(data) {
    $("#Login").focus().autocomplete(data, {
      formatItem: function(item, i, max) {
        return item.Text;
      },
      formatResult: function(item) {
        return item.Text;
      }
    }).result(function(event, item) {
      $("#link").attr("href", item.url);
    });
  });
});
</script>

對應的後台只需輸出合法 JSON:

public ContentResult Account(string q)
{
  string strResult = "";
  // ...查詢與格式化...
  strResult = "[{\"text\":\"LinkA\", \"url\":\"/page1\"}, {\"text\":\"LinkB\", \"url\": \"/page2\"} ]";
  return Content(strResult);
}

實務提醒

範例中的 eval() 用來把字串轉物件,示範可以,正式環境請改用 JSON.parse();eval 會執行任意程式碼,若資料來源遭污染就是安全漏洞。另外,遠端模式下建議在伺服端限制 limit 的上限,避免被大量請求拖垮。

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