易栈网-膘叔

我就不翻译了……

这些东西也不复杂。

Copy网站开始……黑黑

Dependencies

• jQuery
• bgiframe plugin
• dimensions plugin, only offset method is used

Known issues:

• When completing multiple values, only the last value can be edited with the autocomplete help
• mustMatch option is broken (mostly fixed in latest revision)
• default browser autocomplete displays a long list of values scrollable, that isn’t supported yet

Recent changes

• Heavily improved Dylan Verheul’s initial plugin, integrating modifications by Dan G. Switzer and Anjesh Tuladhar

Documentation

Autocompletition of input elements is a very helpful tool to guide users in entering the right value. That value can come from a (big) list of possible values or it may consist of values the user has entered before. This plugin makes it easy for a developer to setup autocomplete for text inputs and textareas.

Setup
First step in setting up autocomplete is to decide what kind of data is provided. To autocomplete a few dozen possible values, it is a good idea to provide local data. The data is loaded only once and then cached, providing a very responsive interface.
If the data can consist of hundreds, thousands or even millions of rows, the searching and filtering must be done where performance won’t suffer, in most cases a relational database (eg. MySQL). The plugin will request the rows for the entered value, displaying only a subset of all possible values.
For local autocomplete, just pass the data as an array to the autocomplete plugin. For remote autocomplete, specify an URL pointing to the resource providing the data. The plugin then requests data with a “q” parameter containing the current search value.

API

• autocomplete( String|Array urlOrData, Map options ) returns jQuery
  
  Provide autocomplete for text-inputs or textareas.
  
  Depends on dimensions plugin’s offset method for correct positioning of the select box and bgiframe plugin
  to fix IE’s problem with selects.

  Options

  • inputClass (String): This class will be added to the input box. Default: “ac_input”
  • resultsClass (String): The class for the UL that will contain the result items (result items are LI elements). Default: “ac_results”
  • loadingClass (String): The class for the input box while results are being fetched from the server. Default: “ac_loading”
  • minChars (Number): The minimum number of characters a user has to type before the autocompleter activates. Default: 1
  • delay (Number): The delay in milliseconds the autocompleter waits after a keystroke to activate itself. Default: 400 for remote, 10 for local
  • cacheLength (Number): The number of backend query results to store in cache. If set to 1 (the current result), no caching will happen. Do not set below 1. Default: 10
  • matchSubset (Boolean): Whether or not the autocompleter can use a cache for more specific queries. This means that all matches of “foot” are a subset of all matches for “foo”. Usually this is true, and using this options decreases server load and increases performance. Only useful with cacheLength settings bigger then one, like 10. Default: true
  • matchCase (Boolean): Whether or not the comparison is case sensitive. Only important only if you use caching. Default: false
  • matchContains (Boolean): Whether or not the comparison looks inside (i.e. does “ba” match “foo bar”) the search results. Only important if you use caching. Don’t mix with autofill. Default: false
  • mustMatch (Booolean): If set to true, the autocompleter will only allow results that are presented by the backend. Note that illegal values result in an empty input box. Default: false
  • extraParams (Object): Extra parameters for the backend. If you were to specify { bar:4 }, the autocompleter would call my_autocomplete_backend.php?q=foo&bar=4 (assuming the input box contains “foo”). Default: {}
  • selectFirst (Boolean): If this is set to true, the first autocomplete value will be automatically selected on tab/return, even if it has not been handpicked by keyboard or mouse action. If there is a handpicked (highlighted) result, that result will take precedence. Default: true
  • formatItem (Function): Provides advanced markup for an item. For each row of results, this function will be called. The returned value will be displayed inside an LI element in the results list. Autocompleter will provide 3 parameters: the results row, the position of the row in the list of results (starting at 1), and the number of items in the list of results. Default: none, assumes that a single row contains a single value.
  • formatResult (Function): Similar to formatResult, but provides the formatting for the value to be put into the input field. Again three arguments: Data, position (starting with one) and total number of data. Default: none, assumes either plain data to use as result or uses the same value as provided by formatItem.
  • multiple (Boolean): Whether to allow more then one autocomplted-value to enter. Default: false
  • multipleSeparator (String): Seperator to put between values when using multiple option. Default: “, “
  • width (Number): Specify a custom width for the select box. Default: width of the input element
  • autoFill (Boolean): Fill the textinput while still selecting a value, replacing the value if more is type or something else is selected. Default: false
  • max (Number): Limit the number of items in the select box. Is also send as a “limit” parameter with a remote request. Default: 10

  Example:

  Autocomplete a text-input with remote data. For small to giant datasets.

  When the user starts typing, a request is send to the specified backend (”my_autocomplete_backend.php”),
  with a GET parameter named q that contains the current value of the input box and a paremeter “limit” with
  the value specified for the max option.

  A value of “foo” would result in this request url: my_autocomplete_backend.php?q=foo&limit=10

  The result must return with one value on each line. The result is presented in the order
  the backend sends it.

  $("#input_box").autocomplete("my_autocomplete_backend.php");

  HTML:

  <input id="input_box" />

  Example:

  Autcomplete a text-input with local data. For small datasets.

  $("#input_box").autocomplete(["Cologne", "Berlin", "Munich"]);

  HTML:

  <input id="input_box" />

  Example:

  Autcomplete a text-input with data received via AJAX. For small to medium sized datasets.

  $.getJSON("my_backend.php", function(data) {
    $("#input_box").autocomplete(data);
  });

  HTML:

  <input id="input_box" />

  Example:

  Autcomplete a textarea with local data (for small datasets). Once the user chooses one
  value, a separator is appended (by default a comma, see multipleSeparator option) and more values
  are autocompleted.

  $("#mytextarea").autocomplete(["Cologne", "Berlin", "Munich"], {
   multiple: true
  });

  HTML:

  <textarea id="mytextarea" />

• result( Function handler ) returns jQuery
  
  Handle the result of a search event. Is executed when the user selects a value or a
  programmatic search event is triggered (see search()).
  
  You can add and remove (using unbind(”result”)) this event at any time.

  Example:

  Bind a handler to the result event to display the selected value in a #result element.
  The first argument is a generic event object, in this case with type “result”.
  The second argument refers to the selected data, which can be a plain string value or an array or object.
  The third argument is the formatted value that is inserted into the input field.

  jQuery('input#suggest').result(function(event, data, formatted) {
    jQuery("#result").html( !data ? "No match!" : "Selected: " + formatted);
  });

• search( ) returns jQuery
  
  Trigger a search event. See result(Function) for binding to that event.
  
  A search event mimics the same behaviour as when the user selects a value from
  the list of autocomplete items. You can use it to execute anything that does something
  with the selected value, beyond simply putting the value into the input and submitting it.

  Example:

  Triggers a search event.

  jQuery('input#suggest').search();