jQuery 输入框下拉提示 仿百度(jquery autocomplete)

自动填充利用搜索和过滤，让用户快速找到并选择所需要的值。

当一个启动了自动填充功能的输入框得到焦点或者被输入值的时候，插件搜索匹配的选项并显示出来供用户选择。当输入更多的值的时候，可以得到更好的匹配结果。

这项功能可以用来输入刚刚选择的值，例如标签；或者输入一个地址、邮编，抑或从地址本里面输入邮件地址。

本地或者远程的数据都可作为自动填充的数据：当数据集较小的时候用本地数据比较好，例如具有 50 条数据左右的地址本；当数据量比较大的时候就需要远程数据了，比如要要从具有成千上万条的数据库中选择的时候。

下面就根据官方的文档一步一步地说明 jquery autocomplete 插件的用法：

官方文档的下载地址为： http://bassistance.de/jquery-plugins/jquery-plugin-autocomplete/

jQuery 官方 api 地址： http://docs.jquery.com/Plugins/Autocomplete

(一)        本地数据

解压之后在 jquery-autocomplete /demo/localdata.js 定义了 3 个数组， months, emails 和 cities ，用来演示本地数据的自动填充。

 

函数签名：

autocomplete( url or data, [options] )

利用这个函数可以让一个输入框或者文本域是可以自动填充的。

第一个参数可以是一个远程数据的 URL ，也可以是本地数组。对于远程数据：当用户输入数据的时候，一个请求被发送到指定的后台程序 ( 比如 "my_autocomplete_backend.php") ，此请求包含两个 get 参数，一个名为“ q ”值为输入框的内容，一个为名为“ limit ”，值为配置选项中 max 的值。

如果输入的内容是 foo ，将会得到这样一个 URL ：

my_autocomplete_backend.php?q=foo&limit=10

结果必须一行返回一个值，结果的顺序将和后台返回的数据的顺序保持一致。

第二个参数是配置 autocomplete 的选项，参数形式为键值对，所有的选项都是可选的。

1.      自动填充本地数据，没有配置选项

首先来看最简单的 autocomplete ，来看文档例子的第一段：

<form autocomplete="off">

<p>

<label>Single City (local):</label>

         <input type="text" id="suggest1" />

         </p>

</form>

我们来看对应的 js ：

$().ready(function(){

         $("#suggest1").focus().autocomplete(cities);

});

其中 cities 被定义为 ["Aberdeen", "Ada", "Adamsville",…] 类型的数组。如此当往 id 为 suggest1 的输入框输入内容的时候， cities 中的内容就会被过滤，匹配的内容显示在下方供选择。这里 autocomplete 只有一个参数，就是本地的数组。

2.      自动填充本地数据，有配置选项

带配置项的 autocomplete ，看文档例子的第二段（这里省去的外面的 form ）：

<p>

                   <label>Month (local):</label>

                            <input type="text" id="month" />

                   </p>

         看对应的 js ：

$().ready(function(){

         $("#month").autocomplete(months, {

                   minChars: 0,

                   max: 12,

                   autoFill: true,

                   mustMatch: true,

                   matchContains: false,

                   scrollHeight: 220,

                   formatItem: function(data, i, total) {

                            // don't show the current month in the list of values (for whatever reason)

                            if ( data[0] == months[new Date().getMonth()] )

                                     return false;

                            return data[0];

                   }

         });});

         首先来看 months 的定义：

var months = ['January', 'February', 'March', 'April', 'May', 'June', 'July', 'August', 'September', 'October', 'November', 'December'];

然后看配置选项：

1)   minChars (Number): 在触发autoComplete 前用户至少需要输入的字符数.Default: 1 ，如果设为0 ，在输入框内双击或者删除输入框内内容时显示列表

2)   max (Number):autoComplete 下拉显示项目的个数.Default: 10 ，由于月份只有12 个，这里定义为12 。

3)   autoFill (Boolean): 要不要在用户选择时自动将用户当前鼠标所在的值填入到输框.Default: false

4)   mustMatch (Booolean): 如果设置为true,autoComplete 只会允许匹配的结果出现在输入框, 所有当用户输入的是非法字符时将会得不到下拉框.Default: false

5)   matchContains (Boolean): 决定比较时是否要在字符串内部查看匹配, 如ba 是否与foo bar 中的ba 匹配. 使用缓存时比较重要. 不要和autofill 混用.Default: false

6)   scrollHeight (Number): 自动完成提示的卷轴高度用像素大小表示 Default: 180

7)   formatItem (Function): 为每个要显示的项目使用高级标签. 即对结果中的每一行都会调用这个函数, 返回值将用LI 元素包含显示在下拉列表中. Autocompleter 会提供4 个参数(row, i, max,value): 返回的结果数组, 当前处理的行数( 即第几个项目, 是从1 开始的自然数), 当前结果数组元素的个数即项目的个数, 最后一个是查询到的项. Default: none, 表示不指定自定义的处理函数, 这样下拉列表中的每一行只包含一个值.

这样就很容易可以看懂第二段了。

3.      自动填充本地数据，格式化显示和结果

配置项复杂的 autocomplete ，看文档例子的第三段：

<p>

         <label>E-Mail (local):</label>

         <input type="text" id="email" />

         <input type="button" value="Get Value" />

         </p>

对应的 js ：

         $("#email").autocomplete(emails, {

                   minChars: 0,

                   width: 310,

 

                   matchContains: "word",

                   autoFill: false,

                   formatItem: function(row, i, max) {

                            return i + "/" + max + ": \"" + row.name + "\" [" + row.to + "]";

                   },

                   formatMatch: function(row, i, max) {

                            return row.name + " " + row.to;

                   },

                   formatResult: function(row) {

                            return row.to;

                   }

         });

首先来看 emails 的定义：

var emails = [

         { name: "Peter Pan", to: "[e-mail]" },

         { name: "Molly", to: "[e-mail]" },

         { name: "Forneria Marconi", to: "[e-mail]" },

         { name: "Master <em>Sync</em>", to: "[e-mail]" },

         { name: "Dr. <strong>Tech</strong> de Log", to: "[e-mail]" },

         { name: "Don Corleone", to: "[e-mail]" },

         { name: "Mc Chick", to: "[e-mail]" },

         { name: "Donnie Darko", to: "[e-mail]" },

         { name: "Quake The Net", to: "[e-mail]" },

         { name: "Dr. Write", to: "[e-mail]" }

];

emails 的定义稍微复杂一些，可以看做数组的数组。

然后看配置选项：

1)         前 2 个选项和前面基本相同， matchContains 的配置和前面不同，这里的配置为“ word ”，即为 true ，表示可以是包含关系。 autoFill 为 false 表示不自动把鼠标所在的行填充到输入框。

2)         formatItem 对返回结果的每一行做了处理。每一行都被处理成了这样的一种形式： i/max:”name”[to], 例如第一个被表示成： 1/10: "Peter Pan"[ [e-mail] ]

3)         formatMatch 对每一行数据使用此函数格式化需要查询的数据格式 . 返回值是给内部搜索算法使用的 . 参数值和 formatItem 的参数一样。

4)         formatResult 和 formatItem 类似 , 但可以将将要输入到 input 文本框内的值进行格式化 . 同样有三个参数 , 和 formatItem 一样 .Default: none, 表示要么是只有数据 , 要么是使用 formatItem 提供的值 .

4.      自动填充本地数据，多项选择，用分隔符分隔

<p>

         <label>Tags (local):</label>

         <input type="text" id='tags' />

</p>

对应 js ：

$("#tags").autocomplete(["c++", "java", "php", "coldfusion", "javascript", "asp", "ruby", "python", "c", "scala", "groovy", "haskell", "pearl"], {

         width: 320,

         max: 4,

         highlight: false,

         multiple: true,

         multipleSeparator: " ",

         scroll: true,

         scrollHeight: 300

});

配置选项很简单，就是多了一个多项选择和分隔符。

5.      自动填充本地数据，弹出层（ thickbox ）

<p>

         <a href="http://xianfengmc.blog.163.com/blog/#TB_inline?height=155&width=400&inlineId=modalWindow" class="thickbox">Click here for an autocomplete inside a thickbox window.</a> (this should work even if it is beyond the fold)

</p>         

<div id="modalWindow" style="display: none;">

         <p>

                   <label>E-Mail (local):</label>

                   <input type="text" id="thickboxEmail" />

                   <input type="button" value="Get Value" />

         </p>

</div>

对应 js ：

$("#thickboxEmail").autocomplete(emails, {

         minChars: 0,

         width: 310,

         matchContains: true,

         highlightItem: false,

         formatItem: function(row, i, max, term) {

                   return row.name.replace(new RegExp("(" + term + ")", "gi"), "<strong>$1</strong>") + "<br><span style='font-size: 80%;'>Email: &lt;" + row.to + "&gt;</span>";

         },

         formatResult: function(row) {

                   return row.to;

         }

});

当点击链接的时候弹出层，可以在弹出层中调用 autocomplete 。

(二)        远程数据 6.      自动填充远程数据，配置简单

从第四段开始就是取远程数据了，看第四段的 html ：

<p>

         <label>Single Bird (remote):</label>

         <input type="text" id="singleBirdRemote" />

</p>

对应的 js ：

$("#singleBirdRemote").autocomplete("search.php", {

         width: 260,

         selectFirst: false

});

由于远程取的是 php 文件，所以我首先搭建了一个 php 环境，用的是 Apache 的 http 服务器，不会搭建的话随便百度一下。我是用的百度文库里的一片文章，如果你懒的话就用这个地址吧 http://wenku.baidu.com/view/ddc083c24028915f804dc2ff.html 。

首先让我们来看看 search.php ，里面都做了什么。

search.php 文件的一开始：

  <?php

$q = strtolower($_GET["q"]);

if (!$q) return;

用 $_GET() 方法获取 get 参数 q ，如果 q 为空则直接返回。然后定义了一个键值对的数据：

$items = array(

"Great <em>Bittern</em>"=>"Botaurus stellaris",

"Little <em>Grebe</em>"=>"Tachybaptus ruficollis",

"Black-necked Grebe"=>"Podiceps nigricollis",...);

文件的最后：

foreach ($items as $key=>$value) {

         if (strpos(strtolower($key), $q) !== false) {

                   echo "$key|$value\n";

         }

}

?>

foreach 循环数组里所有的元素，如果“键”里边包含所输入的值（查询的时候都把字母转化为了小写），则输出到页面。

其次，让我们分析一下 js ：

autocomplete 函数第一个参数是一个 url ： search.php ，刚才已经分析过 search.php 文件， search.php 把删选出来的数据返回给 autocomplete 用作自动填充的选项。第二个参数是配置选项，这里只给出了两个选项：第一个 width 不必多说，第二个 selectFirst: selectFirst (Boolean): 如果设置成 true, 在用户键入 tab 或 return 键时 autoComplete 下拉列表的第一个值将被自动选择 , 尽管它没被手工选中 ( 用键盘或鼠标 ). 当然如果用户选中某个项目 , 那么就用用户选中的值 . Default: true

7.      自动填充远程数据，关键字包含，多项选择

之所以放在一块儿看，是因为这两段比较象，只是看不同的配置：

<p>

<label>Single City (contains):</label>

<input type="text" id="suggest14" />

</p>

<p>

         <label>Multiple Cities (local):</label>

         <textarea id='suggest3' cols='40' rows='3'></textarea>

</p>

对应的 js ：

$("#suggest14").autocomplete(cities, {

         matchContains: true,

         minChars: 0

});

$("#suggest3").autocomplete(cities, {

         multiple: true,

         mustMatch: true,

         autoFill: true

});

第六段的配置其实上边已经讲述，第七段多了一个配置选项 multiple: multiple (Boolean): 是否允许输入多个值即多次使用 autoComplete 以输入多个值 . Default: false.

8.      自动填充远程数据，用函数格式化显示和结果

<p>

         <label>Multiple Birds (remote):</label>

         <textarea id='suggest4'></textarea>

</p>

对应的 js ：

$("#suggest4").autocomplete('search.php', {

         width: 300,

         multiple: true,

         matchContains: true,

         formatItem: formatItem,

         formatResult: formatResult

});

取远程数据 search.php ，不过把 formatItem 和 formatResult 分别指定了一个函数，这次我们需要看的只是这两个函数：

function formatItem(row) {

         return row[0] + " (<strong>id: " + row[1] + "</strong>)";

}

function formatResult(row) {

         return row[0].replace(/(<.+?>)/gi, '');

}

formatItem 函数对每一行进行了格式化， formatResult 函数去掉了其中的一些字符，如此而已。

9.      自动填充远程数据，列表中显示图片

<p>

         <label>Image search (remote):</label>

         <input type="text" id='imageSearch' />

</p>

对应的 js ：

$("#imageSearch").autocomplete("images.php", {

         width: 320,

         max: 4,

         highlight: false,

         scroll: true,

         scrollHeight: 300,

         formatItem: function(data, i, n, value) {

                  return "<img src='http://xianfengmc.blog.163.com/blog/images/" + value + "'/> " + value.split(".")[0];

         },

         formatResult: function(data, value) {

                  return value.split(".")[0];

         }

});

这次 autocomplete 函数请求的时候一个远程数据 images.php ，来看看 images.php 做了什么：

<?php

$term = $_REQUEST['q'];

$images = array_slice(scandir("images"), 2);

foreach($images as $value) {

         if( strpos(strtolower($value), $term) === 0 ) {

                   echo $value . "\n";

         }

}

?>

首先利用 $_REQUEST 得到参数 q ，赋值给 $item ，然后扫描 images 目录，返回文件名数组，并分隔数组，然后去搜索文件名，如果包含输入的值则返回文件名。

formatItem 函数首先根据查询到的文件名显示图片，然后输入文件名。

formatResult 只是显示文件名。