CodePlayer

本文参考jQuery UI Autocomplete 官方文档编写，当前最新版本为 1.11。

概述

任何可以接收输入的元素均可以使用jQuery UI Autocomplete插件，例如：<input>、<textarea>文本域，以及带有contenteditable属性的元素。

键盘交互

当Autocomplete的自动完成菜单处于打开状态时，你可以使用以下键盘命令：

• 上(↑)： 移动焦点到菜单上一项。如果当前已经是第一项，则移动焦点到输入元素。如果当前已经是输入元素，则移动焦点到菜单最后一项。
• 下(↓): 移动焦点到菜单下一项。如果当前已经是最后一项，则移动焦点到输入元素。如果当前已经是输入元素，则移动焦点到菜单第一项。
• ESC: 关闭菜单。
• ENTER: 选择当前获得焦点的菜单项，并关闭菜单。
• TAB: 选择当前获得焦点的菜单项，关闭菜单，并将焦点移动到下一个可获得焦点的元素。

• PAGE UP/PAGE DOWN: 滚动一页菜单项(基于菜单高度)。通常来说，并不建议一次性显示需要用户翻页那么多的菜单项。

Autocomplete的配置选项

重要说明：Autocomplete 的所有配置选项，都支持在初始化时进行设置，例如：

// 给id为title的元素添加autocomplete功能，并以对象形式设置一或多个配置选项
$("#title").autocomplete( {
	optionName1: "选项1",
	optionName2: "选项2",
	optionName3: "选项3"	
} );

初始化之后，我们还可以通过以下方式来设置或获取配置选项，例如：

// 获取配置选项optionName的值
$("#title").autocomplete("option", "optionName");

// 设置配置选项optionName的值
$("#title").autocomplete("option", "optionName", "选项值");

appendTo

可选/String类型默认值为null。指定用于显示菜单的div应该追加到哪个元素内。当该值为null时，Autocomplete将会检查输入元素的祖辈中是否存在一个包含CSS类名ui-front的元素。如果存在，则追加到该元素内；如果不存在，则默认追加到body元素内。

$( "#title" ).autocomplete( { appendTo: "#menuWrapper" } );

autoFocus

可选/Boolean类型默认值为false。如果设为true，在菜单显示时，将默认选中第一项。

$( "#title" ).autocomplete( { autoFocus: true } );

delay

可选/Integer类型默认值为300。指定在按键发生后多少毫秒后才触发执行自动完成。

$( "#title" ).autocomplete( { delay: 500 } );

disabled

可选/Boolean类型默认值为false。是否禁用自动完成功能。

minLength

可选/Integer类型默认值为 1。指定触发自动完成的最小输入字符数，如果输入的字符小于该长度，将不会触发自动完成功能。将该值设为0，可以在不输入字符的情况下显示菜单(根据实测显示，可能需要通过上下方向键来触发)。

$( "#title" ).autocomplete({ minLength: 0 });

position

可选/Object类型默认值为{ my: "left top", at: "left bottom", collision: "none" }。指示在关联的输入元素的什么位置显示菜单。其默认值表示，菜单相对于关联目标元素的左下角，作为自己的左上角。该参数用法很多，详情请参考jQuery UI position。

// 相对于输入元素的右下角，作为菜单的右上角
$( "#title" ).autocomplete({ position: { my : "right top", at: "right bottom" } });

source

Array/String/Function类型指定显示菜单的数据来源，必须指定该参数。

如果该参数为数组，则它可以是以下两种形式：

// 形式一
[ "选项1", "选项2", "选项3" ]

// 形式二(必须是label和value属性，label用于显示，value用于实际输入)
[ 
    { label: "选项1", value: "值1" },
    { label: "选项2", value: "值2" },
    { label: "选项3", value: "值3" }
]

/* 形式一相当于是形式二中对象的label和value属性都相同的情况 */

Autocomplete将根据用户的输入，自动模糊匹配数组的字符串或对象的label属性，并显示符合条件的菜单。

如果该参数是字符串，则将其视作一个远程请求的URL。Autocomplete将向目标URL发送Ajax请求，并将用户的输入以参数term追加到URL上，该URL应该返回JSON格式的字符串，并且可以转换为如上两种形式的数组。Autocomplete认为远程请求已经完成了数据过滤，它将不再进行模糊匹配，而是直接将返回的所有数据项显示出来。

如果该参数是函数，Autocomplete会为其提供两个参数：前者是一个仅有term属性的对象，该属性表示用户的输入；后者是一个响应函数。你可以根据用户的输入，自行获取数据，并进行任何处理，最后调用响应函数(第二个参数)，将数组数据交给Autocomplete去显示菜单。

$("#title").autocomplete( {
	source: function(request, response){
		// request.term 是用户输入的字符串
		// 你可以在这里自行获取数据、自行处理
		
		var dataArray = [,,,]; // 表示处理后的数组数据

		// 将数组数据交给Autocomplete显示为菜单
		// 如果情况特殊，你也可以不调用，从而不显示菜单
		response( dataArray );
	}
} );