自动完成.js
这个 JavaScript 库在您的搜索框中添加了快速而全功能的自动补全菜单,显示“ 按您输入” 的结果 。 它很容易与阿尔戈利亚的实时搜索引擎结合. 该库作为jQuery插件,Angular.js指令或独立库提供.
目录
特征
- 向终端用户输入时显示建议
- 显示顶端建议作为提示(即背景文本)
- 支持允许用户界面灵活性的自定义模板
- 与RTL语言和输入法编辑器合作良好
- 触发自定义事件
安装
这个 autocomplete.js 必须包含库 之后 jQuery, Zepto 或 Angular.js (带有 jQuery). 否则,它会使用嵌入的Zepto.
日记
<script src="https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.min.js"></script>
<!-- OR -->
<script src="https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.jquery.min.js"></script>
<!-- OR -->
<script src="https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.angular.min.js"></script>
(简体中文)
<script src="https://cdnjs.cloudflare.com/ajax/libs/autocomplete.js/<VERSION>/autocomplete.min.js"></script>
<!-- OR -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/autocomplete.js/<VERSION>/autocomplete.jquery.min.js"></script>
<!-- OR -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/autocomplete.js/<VERSION>/autocomplete.angular.min.js"></script>
无
npm install --save autocomplete.js
鲍尔
bower install algolia-autocomplete.js -S
来源值/
您可以在 点/。 。 。 .
浏览器
你可以需要它和使用它 浏览器数字 :
var autocomplete = require('autocomplete.js');
使用量
独立
- 包含
autocomplete.min.js - 初始化自动补全菜单
autocomplete函数
3⁄4 ̄ ̧漯B数字 : autocomplete.js 与框外的最新版本 algoliasearch v4 兼容, 但是您可以自己像这样创建兼容源 :
<input type="text" id="search-input" placeholder="Search unicorns..." />
<!-- [ ... ] -->
<script src="https://cdn.jsdelivr.net/npm/algoliasearch@4/dist/algoliasearch.umd.min.js"></script>
<script src="https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.min.js"></script>
<script>
var client = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey');
var index = client.initIndex('YourIndex');
function newHitsSource(index, params) {
return function doSearch(query, cb) {
index
.search(query, params)
.then(function(res) {
cb(res.hits, res);
})
.catch(function(err) {
console.error(err);
cb([]);
});
};
}
autocomplete('#search-input', { hint: false }, [
{
source: newHitsSource(index, { hitsPerPage: 5 }),
displayKey: 'my_attribute',
templates: {
suggestion: function(suggestion) {
return suggestion._highlightResult.my_attribute.value;
}
}
}
]).on('autocomplete:selected', function(event, suggestion, dataset, context) {
console.log(event, suggestion, dataset, context);
});
</script>
查询
- 包含
autocomplete.jquery.min.js包含之后jQuery - 初始化自动补全菜单
autocompletej 查询插件
3⁄4 ̄ ̧漯B数字 : autocomplete.js 不符合最新版本的 algoliasearch v4, 因此我们强烈建议您使用以下代码片断中指定的 algoliasearch v3 .
<input type="text" id="search-input" />
<!-- [ ... ] -->
<script src="https://cdn.jsdelivr.net/algoliasearch/3/algoliasearch.min.js"></script>
<script src="https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.jquery.min.js"></script>
<script>
var client = algoliasearch('YourApplicationID', 'YourSearchOnlyAPIKey')
var index = client.initIndex('YourIndex');
$('#search-input').autocomplete({ hint: false }, [
{
source: $.fn.autocomplete.sources.hits(index, { hitsPerPage: 5 }),
displayKey: 'my_attribute',
templates: {
suggestion: function(suggestion) {
return suggestion._highlightResult.my_attribute.value;
}
}
}
]).on('autocomplete:selected', function(event, suggestion, dataset, context) {
console.log(event, suggestion, dataset, context);
});
</script>
Angular.JS (英语)
- 包含
autocomplete.angular.min.js包含之后jQuery打开Angular.js - 输入
algolia.autocomplete模块 - 添加数据
autocomplete, (中文(简体) ),aa-datasets选项aa-options属性到搜索栏
3⁄4 ̄ ̧漯B数字 : autocomplete.js 不符合最新版本的 algoliasearch v4, 因此我们强烈建议您使用以下代码片断中指定的 algoliasearch v3 .
<div ng-controller="yourController">
<input type="text" id="search-input" autocomplete aa-datasets="getDatasets()" />
</div>
<!-- [ include jQuery + Angular.js ] -->
<script src="https://cdn.jsdelivr.net/algoliasearch/3/algoliasearch.angular.min.js"></script>
<script src="https://cdn.jsdelivr.net/autocomplete.js/0/autocomplete.angular.min.js"></script>
<script>
angular.module('myApp', ['algoliasearch', 'algolia.autocomplete'])
.controller('yourController', ['$scope', 'algolia', function($scope, algolia) {
var client = algolia.Client('YourApplicationID', 'YourSearchOnlyAPIKey');
var index = client.initIndex('YourIndex');
$scope.getDatasets = function() {
return {
source: algolia.sources.hits(index, { hitsPerPage: 5 }),
displayKey: 'my_attribute',
templates: {
suggestion: function(suggestion) {
return suggestion._highlightResult.my_attribute.value;
}
}
};
};
$scope.$on('autocomplete:selected', function(event, suggestion, dataset) {
console.log(event, suggestion, dataset, context);
});
}]);
</script>
说明: 你需要依赖 jQuery,嵌入于Angular.js的lite版本不会成功.
看和感觉
下面是描述自动完成的 DOM 结构的 faux 胡子模板
下放菜单。 记住 header, (中文(简体) ), footer, (中文(简体) ), suggestion,以及 empty
来源于提供的详细模板 这里。 。 。 .
<span class="aa-dropdown-menu{{#datasets}} aa-{{'with' or 'without'}}-{{name}}{{/datasets}}">
{{#datasets}}
<div class="aa-dataset-{{name}}">
{{{header}}}
<span class="aa-suggestions">
{{#suggestions}}
<div class="aa-suggestion">{{{suggestion}}}</div>
{{/suggestions}}
{{^suggestions}}
{{{empty}}}
{{/suggestions}}
</span>
{{{footer}}}
</div>
{{/datasets}}
{{empty}}
</span>
当最终用户鼠标或按键超过一个时 .aa-suggestion,阶级 aa-cursor 将加入其中。 您可以使用此类作为钩子来设计“ 光标下” 建议状态 .
添加以下 CSS 规则添加默认样式 :
.algolia-autocomplete {
width: 100%;
}
.algolia-autocomplete .aa-input, .algolia-autocomplete .aa-hint {
width: 100%;
}
.algolia-autocomplete .aa-hint {
color: #999;
}
.algolia-autocomplete .aa-dropdown-menu {
width: 100%;
background-color: #fff;
border: 1px solid #999;
border-top: none;
}
.algolia-autocomplete .aa-dropdown-menu .aa-suggestion {
cursor: pointer;
padding: 5px 4px;
}
.algolia-autocomplete .aa-dropdown-menu .aa-suggestion.aa-cursor {
background-color: #B2D7FF;
}
.algolia-autocomplete .aa-dropdown-menu .aa-suggestion em {
font-weight: bold;
font-style: normal;
}
这就是 基本实例 看起来像:

全球选项
初始化自动完成时,您可以配置一些全局选项 .
-
autoselect- 如果true中的第一个建议将自动拥有cursor类,和按<ENTER>将选择它. -
autoselectOnBlur- 如果true,当输入模糊时,在下拉时第一个给出的建议将自动拥有cursor类,和按<ENTER>将选择它。 此选项应在移动时使用, 参见 113号 -
tabAutocomplete- 如果true,按下选项卡将选择下拉中的第一个建议。 默认为true。 。 。 . -
hint- 如果false,自动完成不会显示提示。 默认为true。 。 。 . -
debug- 如果true,自动完成不会关闭blur默认为false。 。 。 . -
clearOnSelected- 如果true,当选择建议时,自动完成将清空搜索框。 如果您想要使用此选项作为输入标记的方式, 则此选项很有用selected活动. -
openOnFocus- 如果true,当输入被聚焦时,下拉菜单会打开。 默认为false。 。 。 . -
appendTo– 如果设置了 DOM 选择器,则不包入输入并附加与选择器相匹配的第一个 DOM 元素的包和下放菜单. 它会自动地将包装放入输入下,并设置到与输入相同的宽度. 无法使用hint: true,因为hint需要包围输入的包装. -
dropdownMenuContainer– 如果设置了 DOM 选择器, 它会覆盖下放菜单的容器 . -
templates——可选散列凌驾于默认模板之上.dropdownMenu– 下放菜单模板. 模板应包括所有 数据集 占位符 .header— 预留到下拉菜单的页眉footer— 将页脚附加到下拉菜单empty– 当没有数据集返回结果时显示的模板 。 诱导功能 其上下文包含query。 。 。 .
-
cssClasses——可选散列凌驾于默认的cs类.root——根类. 默认为algolia-autocomplete。 。 。 .prefix– 所有嵌入元素的 CSS 类前缀 。 默认为aa。 。 。 .noPrefix- 如果您不想使用任何前缀, 请将此设定为真实 。 如果没有这个选项,所有嵌入式元素类都会有一个前缀. 默认为false。 。 。 .dropdownMenu– 降级菜单CSS类. 默认为dropdown-menu。 。 。 .input– 输入 CSS 类. 默认为input。 。 。 .hint- 提示CSS课。 默认为hint。 。 。 .suggestions– 建议列出CSS类. 默认为suggestions。 。 。 .suggestion– 建议包装 CSS 类. 默认为suggestion。 。 。 .cursor- 光标 CSS 类。 默认为cursor。 。 。 .dataset– 数据集CSS类. 默认为dataset。 。 。 .empty- 空CSS课。 默认为empty。 。 。 .
-
keyboardShortcuts- 用于集中输入的快捷键。 例如,如果想要绑定s财务报告和审定财务报表/您可以指定 :keyboardShortcuts: ['s', '/'] -
ariaLabel- 一个可选的字符串,将包含aria-label属性.
<script type="text/template" id="my-custom-menu-template">
<div class="my-custom-menu">
<div class="row">
<div class="col-sm-6">
<div class="aa-dataset-d1"></div>
</div>
<div class="col-sm-6">
<div class="aa-dataset-d2"></div>
<div class="aa-dataset-d3"></div>
</div>
</div>
</div>
</script>
<style>
body {
font-family: -apple-system, sans-serif;
}
.algolia-autocomplete {
width: 100%;
}
.algolia-autocomplete .aa-input, .algolia-autocomplete .aa-hint {
width: 100%;
}
.algolia-autocomplete .aa-hint {
color: #999;
}
.algolia-autocomplete .aa-dropdown-menu {
width: 100%;
background-color: #fff;
border: 1px solid #999;
border-top: none;
}
.algolia-autocomplete .aa-dropdown-menu .aa-suggestion {
cursor: pointer;
padding: 5px 4px;
}
.algolia-autocomplete .aa-dropdown-menu .aa-suggestion.aa-cursor {
background-color: #B2D7FF;
}
.algolia-autocomplete .aa-dropdown-menu .aa-suggestion em {
font-weight: bold;
font-style: normal;
}
.branding {
font-size: 1.3em;
margin: 0.5em 0.2em;
}
.branding img {
height: 1.3em;
margin-bottom: - 0.3em;
}
</style>
<script>
$('#search-input').autocomplete(
{
templates: {
dropdownMenu: '#my-custom-menu-template',
footer: '<div class="branding">Powered by <img src="https://www.algolia.com/static_assets/images/press/downloads/algolia-logo-light.svg" /></div>'
}
},
[
{
source: $.fn.autocomplete.sources.hits(index1, { hitsPerPage: 5 }),
name: 'd1',
templates: {
header: '<h4>List 1</h4>',
suggestion: function(suggestion) {
// FIXME
}
}
},
{
source: $.fn.autocomplete.sources.hits(index2, { hitsPerPage: 2 }),
name: 'd2',
templates: {
header: '<h4>List 2</h4>',
suggestion: function(suggestion) {
// FIXME
}
}
},
{
source: $.fn.autocomplete.sources.hits(index3, { hitsPerPage: 2 }),
name: 'd3',
templates: {
header: '<h4>List 3</h4>',
suggestion: function(suggestion, answer) {
// FIXME
}
}
}
]
);
</script>
-
minLength- 建议开始前所需的最小字符长度 {\fn黑体\fs22\bord1\shad0\3aHBE\4aH00\fscx67\fscy66\2cHFFFFFF\3cH808080}被逼迫起来 默认为1。 。 。 . -
autoWidth– 此选项允许您控制自动完整包装的宽度 。 何时false自动完成的包装将没有宽度样式属性,您可以将您的特定宽度属性放入您的 cs 来控制包装。 默认值是true。 。 。 .
一种方案是使用这一选项。 譬如说. 你有一个 max-width css 属性在您的 autocomplete-dropdown-menu 您需要扩展宽度直到填充 max-width。在这种情况下,你放了一个 width: auto 在自动完成的 css 类包装和 max-width 在你的自动完成降级课 和所有完成.
数据集
自动完成由一个或多个数据集组成。 当最终用户修改 每个数据集将试图对基本输入值提出建议 新价值.
数据集可以使用下列选项进行配置.
-
source- 建议的辅助数据来源。 预期是一项职能 签名(query, cb)预计该职能将 计算用于query然后引用cb说定了.cb能够同步引用或 同步进行. -
name- 数据集的名称。 本文后附tt-dataset-改为 构成包含 DOM 元素的类名称。 只须包括 下划线、破折号、字母(a-z)和数字。 默认为随机 编号. -
displayKey- 对于给定的建议对象,确定字符串 代表大会。 用于设定输入值 选择建议后控制。 可以是密钥字符串,也可以是 函数将建议对象转换为字符串。 默认为value。 。 。 . 函数使用示例:displayKey: function(suggestion) { return suggestion.nickname || suggestion.firstName } -
templates– 在渲染数据集时使用一散列模板. 说明 预编译模板是一个将 JavaScript 对象作为其对象的函数 第一个参数并返回 HTML 字符串.-
empty- 当0可以为给定查询提供建议. 可以是HTML字符串,也可以是预编译模板. 诱导功能 的上下文中包含query, (中文(简体) ),isEmpty,任意选项 来文方可能提出的论据:function emptyTemplate({ query, isEmpty }, [forwarded args])。 。 。 . -
footer– 在数据集下方渲染. 可以是 HTML 字符串或预编译模板. 诱导功能 的上下文中包含query, (中文(简体) ),isEmpty,任意选项 来文方可能提出的论据:function footerTemplate({ query, isEmpty }, [forwarded args])。 。 。 . -
header– 在数据集上方被渲染. 可以是 HTML 字符串 或预编译模板. 诱导功能 的上下文中包含query, (中文(简体) ),isEmpty,任意选项 来文方可能提出的论据:function headerTemplate({ query, isEmpty }, [forwarded args])。 。 。 . -
suggestion- 曾经提出过一个建议 诱导功能 与suggestion,以及任何可能具有 来文方转交:function suggestionTemplate(suggestion, [forwarded args])。 。 。 . 默认值为displayKey包裹在一个p标记 :.<p>{{value}}</p>。 。 。 .
-
-
debounce- 如果设定, 将会将源执行推迟到之后debounce毫秒 自上次援引以来已经过去. -
cache- 如果设置为false,之后的相同查询将始终执行源函数以获取建议。 默认为true。 。 。 .
来源
少数帮助者默认提供,以方便基于Algolia的源的创建.
点击数
建立基于Algolia的源 hits 数组,只需使用 :
{
source: autocomplete.sources.hits(indexObj, { hitsPerPage: 2 }),
templates: {
suggestion: function(suggestion, answer) {
// FIXME
}
}
}
("xxxxx in yyyyy") (中文(简体) )
要构建一个类似亚马逊的自动完整菜单,建议流行查询,对于最受欢迎的显示关联类别者,您可以使用 popularIn 资料来源:
{
source: autocomplete.sources.popularIn(popularQueriesIndexObj, { hitsPerPage: 3 }, {
source: 'sourceAttribute', // attribute of the `popularQueries` index use to query the `index` index
index: productsIndexObj, // targeted index
facets: 'facetedCategoryAttribute', // facet used to enrich the most popular query
maxValuesPerFacet: 3 // maximum number of facets returned
}, {
includeAll: true, // should it include an extra "All department" suggestion
allTitle: 'All departments' // the included category label
}),
templates: {
suggestion: function(suggestion, answer) {
var value = suggestion.sourceAttribute;
if (suggestion.facet) {
// this is the first suggestion
// and it has been enriched with the matching facet
value += ' in ' + suggestion.facet.value + ' (' + suggestion.facet.count + ')';
}
return value;
}
}
}
自定义源
这个 source 选项也可以取一个函数。 它能让你更能控制 Algolia 搜索的结果 职能 function(query, callback) 需要2个参数
query: String: 自动完成中键入的文字callback: Function: 处理结束时用一系列建议调用
source: function(query, callback) {
var index = client.initIndex('myindex');
index.search(query, { hitsPerPage: 1, facetFilters: 'category:mycat' }).then(function(answer) {
callback(answer.hits);
}, function() {
callback([]);
});
}
或通过重用现有来源:
var hitsSource = autocomplete.sources.hits(index, { hitsPerPage: 5 });
source: function(query, callback) {
hitsSource(query, function(suggestions) {
// FIXME: Do stuff with the array of returned suggestions
callback(suggestions);
});
}
警卫
用户生成的数据: 防范 XSS
恶意用户可能试图通过在数据中存储HTML/JS来设计XSS攻击. 重要的是,在使用用户生成的数据之前,必须适当逃出 自动完成.js 模板.
为了方便地做到这一点, 自动完成.js 向您提供摆脱所有 HTML 代码但突出标记的帮助函数 :
templates: {
suggestion: function(suggestion) {
var val = suggestion._highlightResult.name.value;
return autocomplete.escapeHighlightedString(val);
}
}
如果您确实指定了自定义加亮前/后标签, 您可以将其指定为第二和第三个参数 :
templates: {
suggestion: function(suggestion) {
var val = suggestion._highlightResult.name.value;
return autocomplete.escapeHighlightedString(val, '<span class="highlighted">', '</span>');
}
}
财务问题
我怎么会 Control- 点击结果,然后在新的标签中打开?
你需要更新你的建议模板,以使其成为 <a href> 链接
而不是简单的潜水. Control- 点击它们会触发默认浏览器
行为和打开新标签中的建议 .
为了支持键盘导航, 你需要听
autocomplete:selected 事件和更改 window.location 前往目的地
URL (中文(简体) ).
请注意,您可能需要检查 context.selectionMethod 内
autocomplete:selected 先说 如是等数 click你应该 return
提前, 否则您的主窗口会 (单位:千美元) 跟着链接.
这里举出一个例子,说明它的样子:
autocomplete(…).on('autocomplete:selected', function(event, suggestion, dataset, context) {
// Do nothing on click, as the browser will already do it
if (context.selectionMethod === 'click') {
return;
}
// Change the page, for example, on other events
window.location.assign(suggestion.url);
});
活动
自动完成组件触发以下自定义事件 .
-
autocomplete:opened- 当自动完成的下拉菜单是时触发 打开. -
autocomplete:shown- 当自动完成的下拉菜单是时触发 显示( 打开和不空) . -
autocomplete:empty– 当所有数据集为空时触发. -
autocomplete:closed- 当自动完成的下拉菜单是时触发 关闭. -
autocomplete:updated– 当数据集被渲染时触发. -
autocomplete:cursorchanged- 移动下拉菜单光标时触发 对另一个建议。 3 将引用事件处理器 参数: j 查询事件对象、建议对象和名称 该数据集属于建议. -
autocomplete:selected— 当下放菜单中的建议是时触发 选中 。 事件处理器将引用以下参数: jQuery 事件对象、建议对象、数据集名称 建议属于和属于context对象。 这个context包含 (单位:千美元).selectionMethod键可以是click, (中文(简体) ),enterKey, (中文(简体) ),tabKey或者说blur,取决于建议是如何选定的. -
autocomplete:cursorremoved- 当光标离开选择区时触发 或它的当前指数低于 0 -
autocomplete:autocompleted– 当查询自动完成时触发. 自动完成表示查询被更改为提示. 事件处理者会 以3个论点援引:j查询事件反对,建议反对, 以及建议所属数据集的名称. -
autocomplete:redrawn- 触发当appendTo并调整了包装的大小/位置.
所有自定义事件都会在自定义完成时初始化的元素上被触发.
API 密码
查询
任何转动 input[type="text"] 元素输入自动补全菜单. globalOptions 是一个
用于配置您喜欢的自动补全的散列选项。 参见
全球选项 需要更多关于现有配置的信息。 后续
参数( e)*datasets),是数据集的单个选项散列。 为了更多
有关数据集的详情,参见: 数据集。 。 。 .
$(selector).autocomplete(globalOptions, datasets)
示例
$('.search-input').autocomplete({
minLength: 3
},
{
name: 'my-dataset',
source: mySource
});
j 查询# 自动完成(' destroy' )
删除自动完整功能并返回 input 元素返回到它的
原状.
$('.search-input').autocomplete('destroy');
j 查询# 自动完成( “ 打开 ”)
打开自动完成的下拉菜单。 注意开放并不意味着 菜单可见。 菜单只有在打开并有内容时才可见.
$('.search-input').autocomplete('open');
j 查询# 自动完成( “ 关闭 ”)
关闭自动完成的下拉菜单.
$('.search-input').autocomplete('close');
j 查询# 自动完成( “ val” )
返回自动完成的当前值。 值是用户拥有的文本
输入 input 键.
var myVal = $('.search-input').autocomplete('val');
j 查询# 自动完成( “ val, val )
设置自动完成的值。 这应当用来取代 jQuery#val。 。 。 .
$('.search-input').autocomplete('val', myVal);
jQuery.fn.autocomplete.no 冲突()
返回自动完整插件的引用并返回 jQuery.fn.autocomplete
至上一个数值。 可用于避免命名相撞.
var autocomplete = jQuery.fn.autocomplete.noConflict();
jQuery.fn._autocomplete = autocomplete;
独立
独立版本 API 是similier to jQuery 的:
var search = autocomplete(containerSelector, globalOptions, datasets);
示例
var search = autocomplete('#search', { hint: false }, [{
source: autocomplete.sources.hits(index, { hitsPerPage: 5 })
}]);
search.autocomplete.open();
search.autocomplete.close();
search.autocomplete.getVal();
search.autocomplete.setVal('Hey Jude');
search.autocomplete.destroy();
search.autocomplete.getWrapper(); // since autocomplete.js wraps your input into another div, you can access that div
也可以通过自定义的 Autocomplete.js 构造器中的 Typeahead 实例 :
var search = autocomplete('#search', { hint: false }, [{ ... }], new Typeahead({ ... }));
自动完成。 no country ()
返回自动完整插件的引用并返回 window.autocomplete
至上一个数值。 可用于避免命名相撞.
var algoliaAutocomplete = autocomplete.noConflict();
贡献和释放
见 捐款额
贷项
这个图书馆原来是从 推特的typeahead.js (简体中文) 图书馆.