Awesomplete是一款实用的轻量级js自动完成autocomplete插件。它的特点有:轻量级、高度可定制、简单易用、无外部依赖等。该js自动完成autocomplete插件支持HTML5<datalist>属性,该属性只有现代浏览器才支持。

使用方法

要使用该自动完成autocomplete插件,首先需要在页面中引入awesomplete.cssawesomplete.js文件:

<link rel="stylesheet" href="awesomplete.css" />
<script src="awesomplete.js" async></script>                
                

该自动完成autocomplete插件的html结构只需要一个<input>元素(也许可以工作在有contentEditable属性的元素,如<textarea>上,但未经测试)。为<input>元素添加classawesomplete,在data-list中填写你想要自动提示的字符串,逗号隔开。你也可以通过js代码来初始化它。

<input class="awesomplete" data-list="Ada, Java, JavaScript, Brainfuck, LOLCODE, Node.js, Ruby on Rails" />                   
                
使用datalist

可以有多种方式来将一组选项与<input>元素联系起来完成自动提示功能。上面的例子也可以使用下面的方法来编写,下面的写法会在js脚本没有被加载的时候提供一个完美的回退:

<input class="awesomplete" list="mylist" />
<datalist id="mylist">
    <option>Ada</option>
    <option>Java</option>
    <option>JavaScript</option>
    <option>Brainfuck</option>
    <option>LOLCODE</option>
    <option>Node.js</option>
    <option>Ruby on Rails</option>
</datalist>                   
                
使用无序列表

如果你不想使用<datalist>,可以使用下面的无序列表:

<input class="awesomplete" data-list="#mylist" />
<ul id="mylist">
    <li>Ada</li>
    <li>Java</li>
    <li>JavaScript</li>
    <li>Brainfuck</li>
    <li>LOLCODE</li>
    <li>Node.js</li>
    <li>Ruby on Rails</li>
</ul>                    
                
使用JS来初始化

可以使用下面的方法来使用js初始化该自动完成插件:

<input id="myinput" />
<ul id="mylist">
    <li>Ada</li>
    <li>Java</li>
    <li>JavaScript</li>
    <li>Brainfuck</li>
    <li>LOLCODE</li>
    <li>Node.js</li>
    <li>Ruby on Rails</li>
</ul>                    
                
var input = document.getElementById("myinput");
new Awesomplete(input, {list: "#mylist"});                    
                

或者使用一个选择器来引用列表元素:

var input = document.getElementById("myinput");
new Awesomplete(input, {list: document.querySelector("#mylist")});                    
                
直接使用字符串来初始化

可以直接使用一个字符串数组来作为列表:

<input id="myinput" />
                
var input = document.getElementById("myinput");
new Awesomplete(input, {
    list: ["Ada", "Java", "JavaScript", "Brainfuck", "LOLCODE", "Node.js", "Ruby on Rails"]
});                    
                

甚至可以在初始化之后再设置(或覆盖)这个数组:

var input = document.getElementById("myinput");
var awesomplete = new Awesomplete(input);

/* ...more code... */

awesomplete.list = ["Ada", "Java", "JavaScript", "Brainfuck", "LOLCODE", "Node.js", "Ruby on Rails"];                    
                

配置参数

下面所有的参数都可以通过在<input>元素中使用data-属性来实现。如果你在<input>元素设置了data-minchars属性,又在js代码中设置了minChars选项,将以HTML属性优先。你可以使用js选项来在自动完成插件被初始化后改变它的配置,这时,即使是HTML属性也会被改变。

js选项 HTML属性 描述 默认值
list data-list 调用自动完成的字符串列表。
  • 字符串数组
  • HTML元素
  • CSS选择器
  • 包含逗号的字符串
N/A
minChars data-minchars 用户键入多少个字符才开始自动提示 Number 2
maxItems data-maxitems 显示匹配词的数量 Number 10
autoFirst data-autofirst 第一个元素是否被自动选择? Boolean false
扩展

下面的js选项没有对应的HTML属性,因为它们的值是函数。它们允许你在Awesomplete工作时改变设置的属性:

属性 描述 默认值
filter 控制匹配的方式。默认情况下,输入的字符串可以匹配任何一处的字符串,并且区分大小写。 该函数有两个参数:第一个是用于测试的字符串,第二个是用户输入的字符串。如果匹配返回true,不匹配返回false。要想从第一个字符开始匹配,可以使用Awesomplete.FILTER_STARTSWITH Awesomplete.FILTER_CONTAINS:可以从任何地方开始匹配,大小写敏感。
sort 控制列表元素的顺序。 Sort function to sort the items after they have been filtered and before they are truncated and converted to HTML elements. Sorted by length first, order second.
item 控制如何生成列表元素。 该函数有两个参数:第一个是用于测试的字符串,第二个是用户输入的字符串。返回一个列表元素。 生成的列表元素通过用户输入的字符串被高亮(通过<mark>
replace 控制使用什么方式来用选择的列表项替换用户输入文本。 该函数有一个参数:用户选择的文本。使用该文本来替换当前输入的文本。 function (text) {this.input.value = value;}

事件

为避免冲突,所有的事件都使用awesomplete-前缀。

事件名称 事件描述 event.preventDefault()?
awesomplete-select The user has made a selection (either via pressing enter or clicking on an item), but it has not been applied yet. Yes. The selection will not be applied and the popup will not close.
awesomplete-selectcomplete The user has made a selection (either via pressing enter or clicking on an item), and it has been applied. NO
awesomplete-open The popup just appeared. NO
awesomplete-close The popup just closed. NO

API

下面是Awesomplete的一些可用方法:

方法名称 方法描述
open() 打开提示框
close() 关闭提示框
next() 在提示框中高亮下一个选项
previous() 在提示框中高亮前一个选项
goto(i) 在提示框中高亮第i个选项(设置为-1取消所有的选择),避免使用该方法,尽量使用next()和previous()方法。
select() 选择当前高亮的元素使用它来替换input中的文本,并关闭提示框。
evaluate() Evaluates the current state of the widget and regenerates the list of suggestions or closes the popup if none are available. You need to call it if you dynamically set list while the popup is open.