aralejs / autocomplete

自动补全组件

AutoComplete

• order: 1

---

自动补全组件。

---

AutoComplete 继承自 overlay，可使用其中包括 widget、base、class、events、attribute、aspect 的属性和方法。

使用说明

初始化 autocomplete

ac = new AutoComplete({
    trigger: '#test',
    dataSource: ['abc', 'abd', 'cbd']
}).render();

再稍微复杂一点可以通过数据控制显示，dataSource 可以是一个数据集，格式为

dataSource: [
  {value: 'shanghai', label: '上海', alias: ['sh']},
  {value: 'beijing', label: '北京', alias: ['bj']}
]

组件通过 value 和 alias 进行过滤，而最后显示的是 label 的数据，选中后输入框的也是 label 数据。这三个字段为保留字段，其他字段可以自己定义，还可以定义模板去修改显示，查看演示。

在看 API 之前查看更多演示

API

Attribute

trigger selector

指定输入框

template string

默认模板请查看源码

注意覆盖的时候不要缺少 data-role，查看如何自定义 template 的演示，简单的场景可以使用下面几项。

header string

自定义模板头部，默认为空。

html string

自定义每项，默认是 {{label}}。

footer string

自定义模板尾部，默认为空。

classPrefix string

样式前缀，默认为 ui-select

dataSource array | object | string | function

最终提供给 filter 的数据是一个数组，数组内的每项为一个对象，value、label 和 alias 为保留字段。

[
  {value: '', label: '', alias: []},
  ...
]

如果传入的为字符串 ['a']，会自动转化成 [{value: 'a', label: 'a'}]。

数据源支持4种形式

1. Array

   直接提供一个数组，无需转换

   ['10010', '10086', '10000']
   

2. Object

   提供一个对象，里面要包含数组，可以通过 locator: 'data' 指定这个数组

   {
       data: ['10010', '10086', '10000']
   }
   

3. URL

   提供一个 URL，通过 ajax 返回数据，返回的数据也可以通过 locator 查找。

   URL 提供模版参数 ./test.json?v={{query}}&t={{timestamp}}，query 是输入的值，timestamp 为时间戳。

   如果 URL 为 http 或 https 开头，会用 jsonp 发送请求，否则为 ajax。

4. Function

   提供一个自定义函数，根据自己的业务逻辑返回数组，这个自定义程度很高，可实现上面 3 种方式。

   可以每次输入都动态生成数据，如邮箱自动补完

   dataSource: function(query) {
     return [
       query + '@gmail.com',
       query + '@qq.com',
       query + '@163.com'
     ];
   }
   

   也可以自己发送请求获取数据，return false 阻止同步返回，使用 done 异步返回数据。

   dataSource: function(query, done) {
       var that = this;
       $.ajax('test.json?v=' + query, {
           dataType: 'jsonp'
       }).success(function(data) {
           done(data);
       })
       return false;
   }
   

locator object | function

这个参数与 dataSource 相关，一般情况 dataSource 为一个数组，filter 可以直接处理。但如果返回的是 Object，那么就需要指定那个数组。

这个参数可定位到需要的值，支持两种方式

1. 字符串，默认为 data。如果为空字符串则返回原来的值。

   {
       data: ['10010', '10086', '10000']
   }
   

   指定 locator: 'data'，最终给 filter 的为 ['10010', '10086', '10000']

   还支持多层定位，如下可用 locator: 'a.b'

   {a : {b: [1, 2]}}
   

2. 自定义函数

   locator : function(data) {
       // find data and return
   }
   

filter function

过滤器用于筛选 dataSource，最后输出给模板进行渲染，默认方法为 startsWith。

使用方式可查看过滤器章节。

submitOnEnter boolean

回车时是否提交表单，默认为 true，会提交表单，组件不做任何处理。

disabled boolean

是否禁用，默认为 false

selectFirst boolean

默认选中第一项

delay number

按键频率，每次按键的间隔，在这个时间范围内不会处理过滤流程。

方法

selectItem

选中某项

.selectItem(0)

选中第一项，如果没有参数，选中当前 selectedIndex 那项。

setInputValue

通过 api 模拟输入框输入，输入 a

.setInputValue('a')

Properties

input

输入框的实例，this.input，查看文档

dataSource

数据源的实例，this.dataSource，查看文档

items

下拉框的选项，this.items，等同于 this.$('[data-role=items]').children()。

事件

itemSelected

当选中某项时触发

• data：选中项对应的数据源对象
• item：选中项对应的 DOM

.on('itemSelected', function(data, item){
    console.log(data.label);
});

indexChanged

当选项切换时触发，可能是鼠标或键盘。

• currentIndex: 切换后的索引值

• previousIndex: 切换前的索引值

.on('indexChanged', function(current, prev){
    console.log(this.items[current])
});

autocomplete's Issues

无匹配的时候按上下键会报错

review 结果

• ✔ Autocomplete -> AutoComplete

• ✔ 按照事件命名规范：驼峰

• ✔ resultsLocator 默认值为 data，用户约定

  resultsLocator 改成任何类型都支持

• ✘ dataReturn 事件，数据返回的时候可以处理

  filter 处理完后就渲染页面了，没必要再加中间步骤了

• 参考一下 kissy 的 suggest

• ✔ 输入框的回车后会提交表单 #2

• ✔ circular 去掉，默认循环

控件未初始化前键入内容无法触发

当用户在js未运行前就键入内容就无法显示了，建议增加配置使控件初始化完即根据value展开。

textarea 事件单独处理

textarea 回车的时候是换行而不是提交，submitOnEnter 属性对这种场景意义不大，想想如何对这种场景做特殊处理。

textarea 支持光标跟随

如果是 textarea，下拉层希望出现在光标下面，而不是输入框下面。

提供 delay 属性

之前修改了刷新频率的值，但是 ajax 请求发送的还是太频繁，如果设置过长，会有明显的延时。

两者很难折中，所以就提供属性配置。

输入过滤 会引起cursor移动位置

可以看autocmplete的过滤器的例子中的输入过滤，如果把输入框中[email protected]中的a删除后在输入一个a后，光标会移动到最后的位置。

textarea 支持

从 autocomplete 独立出来，textarea-complete.js

• #12 光标跟随
• #34 输入框事件处理
• #36 selectItem 处理
• #40 上下按键的交互

example demo 完善

现在缺少文字提示，内容较少

提供 hover 接口

• itemEnter
• itemLeave

支持 disabled 属性

disabled = true 则不再进行补完的操作。

当dataSource为异步的时候，默认filter:''

简单数据的时候，filter默认为'startsWith'，而在异步获取数据的情况下，应该默认为filter:''

inputFilter之后，前后值一样，还会触发搜索

如题

数据源 abort

每次按键都会触发查询流程，现在通过 delay 控制入口，但是如果已经进入数据查询后就不能阻止了。

dataSource 提供 abort 方法可能阻止数据查询，主要是 ajax 的异步查询。

textarea 中 selectItem 处理

textarea 一般不是全文 complete，所以要根据光标的位置插入文本。

demo里面ui-autocomplete-item-hl样式缺失 看不到效果啦

demo里面ui-autocomplete-item-hl样式缺失 看不到效果啦

当trigger为textarea，且submitOnEnter设置为false，回车换行失效

如题，这个时候，文本框无法输入换行。

输入某个不匹配的时候应该隐藏

输入不匹配的时候现在仍然显示

应该将模版清空并隐藏

增加minChars和maxChars这两个配置

提供触发补全的最短/最长支付数

dataSource url 的参数没有编码

'./data.json?query={{query}}'

query 值需要被编码成 utf-8，而不是根据页面的编码。

支持contenteditable="true"的块级DOM

支持可编辑的HTML容器

补 0.9.0 的测试用例

提供除回车外，TAB按键也能支持选中当前项

由于部分业务可能会占用回车事件（比如注册keydown事件监测Enter）。需要通过TAB键也能选中项。

回车后还是会触发 keyup

keydown 在 keyup 之前，所以回车后还是会触发 keyup，这导致回车选中某项时还会触发 keyup，如果内容有变化还会再次显示。

所以在操作键后不再触发 keyup。

输入框的回车后会提交表单

回车时要选中某一项，要确定是否要提交表单

支持ESC关闭浮层

如题

focus/blur 逻辑优化

ebf95a2

之前把 blur 去掉了，还得考虑下更好的方法。

控制按键频率

如果 ajax 的数据，按键频率太快会频繁的去请求

当输入和补全结果一致时回车和右方向键都会使下拉框消失后又重现

itemSelect 事件返回的值支持原对象。

支持输入过滤

用户输入的值可能不是 filter 想要的，有时候还要进行处理，增加 inputFilter 参数。

README存在很多404链接

RT

无数据就不显示了

现在的逻辑是 data 返回空数组就不显示，但有的时候在没数据的时候要显示“无结果”等文案。

希望这种情况只要改模板就好了。

dataSource 支持 ajax

如果提供的相对路径 / ./ getData.json，用 ajax get 请求

如果为 http:// https:// 则用 jsonp

建议增加focusShow配置

场景：
http://www.aliexpress.com/ 的搜索框

问题：
输入一个字母后离开输入框，再次focus输入框时候需要立即展现之前的联想框体

目前实现：

setup :function() {
    var _self = this;
    xxxxxx.superclass.setup.call(_self);            
    this.get('trigger').focus(function(){
        if(this.value !== "" && _self.get('data').length !== 0){
            _self.show();
        }
    });
}

键盘左右光标移动处理不一致

向右移动，浮层消失；向左移动，浮层不会消失。

选择某项后按下键没有筛选结果

数据源：['abc', 'abd']

按回车选择 abc，再次点击下键还是 ['abc', 'abd']，应该只显示 abc。

重构代码

input 变化会触发获取数据、过滤、渲染的流程，选中某项后 input 也发生变化了，但不应该在走这个流程

当.set('disabled', true)的时候，应该关闭当前已经浮出的渐进提示框

如题

键盘上下的交互

input 框中上下按键会到输入框的最左和最右，如果不阻止感觉体验不好。

textarea 框上下按键是选中不同的行，如果阻止就无法上下移动。

现在 input 默认阻止，textarea 要覆盖的话有很多代码重复。

itemSelect 接口变更

现在 callback 返回两个值

.on('itemSelect', function(text, data) {

})

text 的值在 data 中也存在，text 没有存在的必要

数据支持复杂的结构

dataSource 获取的数据

[
    {title:'a', name:'b'},
    {title:'c', name:'d'},
]

在选择某项后仍然希望获取 title 和 name，显示和选择的值不同。

blur 隐藏浮层的处理

当选中某一项时，输入框的焦点会移向浮层，这时会触发 blur 事件，blur 优先于 click，浮层隐藏了就无法选中

现在是 400ms 后再触发的处理方式，想想有没有更好的

ajax下filter被重设为空的问题

看到新更新的autocomplete在ajax下把filter拿走了 这个原来作为兼容老接口方案是有用的
例如我们的数据返回需要经过重新组织才能使用。

当禁用autocomplete时，按键盘向下光标，依然会显示浮层。

使用.set('disabled', true)之后，貌似没禁用完全，键盘事件还是在监听。

鼠标选中项之后，没有focus回输入框

这个是选bug还是enhancement呢？

异步获取数据，浮层不会显示

是否显示的判断是同步执行的，如果异步获取数据，那么在之前已经执行了。

增加 filter:stringMatch

模版处理数组长度的问题

<div class="{{prefix}}">
    <ul class="{{prefix}}-ctn" data-role="items">
        {{#each items}}
            <li data-role="item" class="{{../prefix}}-item" data-value="{{value}}">{{highlightItem ../prefix}}</li>
        {{/each}}
    </ul>
        {{items.length}}
</div>

items.length 返回为 0

<div class="{{prefix}}">
    <ul class="{{prefix}}-ctn" data-role="items">
        {{items.length}}    
        {{#each items}}
            <li data-role="item" class="{{../prefix}}-item" data-value="{{value}}">{{highlightItem ../prefix}}</li>
        {{/each}}
    </ul>

</div>

items.length 返回正确

测过 handlebars，应该不是这个的问题。

提供 selectFirst 参数

默认选中第一个，按回车就可直接选择