jQuery.AutoComplete是一个基于jQuery的自动补全插件。借助于jQuery优秀的跨浏览器特性,可以兼容Chrome/IE/Firefox/Opera/Safari等多种浏览器。

特性一览:

在Html文件的</head>标签之前,引入插件:
<script type="text/javascript" src="/path/to/jquery-1.7.1.min.js"></script>            
<link rel="stylesheet" type="text/css" href="/path/to/jquery.autocomplete.css"></link>
<script type="text/javascript" src="/path/to/jquery.autocomplete.js"></script>
一个简单的例子:
$('#sample').AutoComplete({
    'data': ['One', 'Two', 'Three', 'Four', 'Five', 'Six', 'Seven', 'Eight', 'Nine', 'Ten', 'Eleven', 'Twelve']
});

样式

width列表的宽度。
类型:数字,字符串默认值: 320单位: px
当列表宽度不足以容纳下列表项的内容时,列表项的文本以折行的方式显示。可以通过设定足够大的列表宽度,避免折行的发生。
[since v1.1.0]如果设定 width 为 'auto',那么补全列表的宽度与输入框的宽度一致。

示例: 宽度设为数字
			
示例: 宽度设为'auto'
            

maxHeight列表的最大高度。
类型:数字默认值: null单位: px
限制列表的高度不能大于某个值。当列表实际长度大于限制值时,显示纵向滚动轴。

示例:
            

itemHeight列表项的高度。
类型:数字默认值: null单位: px

示例:
            

listStyle列表的样式。
类型:字符串默认值: 'normal'范围: ['normal', 'iconList', 'custom']
'normal': 普通文本样式。
'iconList': 左边是图标右边是文本的样式。
'custom': 自定义样式。须配合createItemHandler参数一起使用。

示例: 'normal':
            
示例: 'iconList':
            
示例: 'custom':
            

listDirection列表的位置和方向。
类型:字符串默认值: 'down'范围: ['down', 'up']
'down': 列表会显示在输入框的下方。
'up': 列表会显示在输入框的上方。(注:在某些情况下,通过设定列表项高度[itemHeight],可帮助正确定位列表的显示位置)

示例: 'down':
            
示例: 'up':
            

数据

data数据源。
类型:数组,函数,Url字符串默认值: []
输入框中每次发生按件抬起事件(除某些被忽略的按键,如上下左右键)时,AutoComplete都会从数据源中搜寻符合匹配规则的数据作为列表的项。

示例: 数组作为数据源
            
示例: 函数作为数据源
            
示例: Url字符串作为数据源
            

ajaxDataTypeAjax返回数据的格式。
类型:字符串默认值: 'json'范围: ['json', 'xml']
指导AutoComplete如何对返回数据做解析,同时也作为jQuery.ajax函数的dataType参数,。

示例: json
            
示例: xml
            

ajaxParamsAjax发送给服务器的数据。
类型:对象,函数,字符串默认值: {'keyword': 输入框中的值}
作为jQuery.ajax函数中的data参数。

ajaxTimeoutAjax的超时。
类型:数字默认值: 3000单位: 毫秒
作为jQuery.ajax函数中的timeout参数。

ajaxTypeAjax访问服务器的HTTP(s)方法(method)。
类型:字符串默认值: 'GET'范围: ['GET', 'POST']
作为jQuery.ajax函数中的type参数。

maxItems列表的最大项数。
类型:数字默认值: 20
作用类似maxHeight参数,用来限制列表的高度。

示例:
            

事件

matchHandler发生匹配处理时的回调函数。
类型:函数
通过此回调函数,可以实现自定义的匹配规则。在匹配的过程中,数据源中的每一个数据项都会触发一次此回调函数。

function matchHandler(keyword, data)

示例:
            

emphasisHandler在渲染匹配内容时的回调函数。
类型:函数
通过此函数,可以实现自定义的匹配内容渲染。每个匹配成功的数据项都会触发一次此回调函数。

function emphasisHandler(keyword, data)

示例:
            

createItemHandler在创建列表项时的回调函数。
类型:函数
listStyle参数设置为'custom'时,AutoComplete会调用此回调函数获取列表项的内容。

示例:
            

beforeLoadDataHandler在每次输入之后装载数据之前的回调函数。[since v1.1.1]
类型:函数
在输入框中每输入一个有效字符,控件都会发起一次数据请求并装载之。beforeLoadDataHandler在输入发生之后,数据请求和装载之前被调用,输入框中的值会作为参数传递给回调函数。如果回调函数的返回值为false,则控件取消随后的数据请求和装载动作。

示例:
            

afterSelectedHandler在列表项被选择之后的回调函数。[since v1.1.2]
类型:函数
无论是使用键盘还是鼠标来选择列表项,都会触发这个回调函数。控件首先将用户选中列表项的值放置到输入框中,然后调起回调函数,将绑定在这个列表项上的数据传递给它。

示例:
            

行为

async是否异步。
类型:布尔值默认值: false
AutoComplete将“输入框按键抬起 => 从数据源获取数据 => 匹配处理 => 匹配渲染处理 => 列表生成并显示”这5步作为一次处理过程。
在同步的设置下,一个过程完成之后,才会开始第二个过程。如果数据源来自较慢的网络,亦或过程较为耗时,用户会感到一定的延时阻塞;
在异步的设置下,不用等待第一个过程完成,第二个过程就可以立即开始,因此没有阻塞发生且有助于改善用户的体验。多个过程同时执行时,AutoComplete会自动判别哪个是有效过程,忽略其他无效过程。

示例:
            

emphasis是否渲染匹配文本。
类型:布尔值默认值: true

调试

onerror遇到错误时的回调函数
类型:函数
遇到错误时,AutoComplete默认采取静默方式处理。通过设置此回调函数,可以获取到错误发生的信息。

function onerror(msg)

ChangeLog

v1.1.2

v1.1.1

v1.1.0