自动建议控件

Dmitry Khudorozhkov

4.90/5 (117投票s)

2007年8月24日

Zlib

12分钟阅读

958800

2648

本文介绍了一个能够为任何 INPUT 输入框增强自动建议功能的代码，该功能支持 AJAX。

下载最新版本 - 11.25 KB

前言

感谢您花时间阅读本文。如果您愿意给个评价（尤其是低分），请附带评论说明问题所在。反馈是改进的动力。

引言

由 zichun 撰写的自动完成控件文章在过去几年中获得了广泛关注。"自动完成"功能（也称为"自动建议"，取名自 Google Suggest）极大地提高了网站的可用性并丰富了用户体验。然而，原始作者已停止支持代码，并且没有回复我的电子邮件。此外，近年来对自动完成控件的需求也在不断增长。

为了解决所有脚本问题并提供持续的用户支持，自动建议控件应运而生。进行了哪些更改和修复？

脚本现在支持离线（通过客户端数组）和在线（通过 AJAX）两种方式来填充建议列表。
脚本现在 100% 兼容所有主流浏览器（Mozilla/Firefox、Opera、Safari、Chrome、Microsoft Internet Explorer）。
脚本已移至单个文件。
所有样式信息均已移至 CSS。
已发现并修复内存泄漏问题。
添加了许多有用的选项。

安装

首先，您应该将 autosuggest.js、autosuggest.css、arrow-down.gif、arrow-down-d.gif、arrow-up.gif 和 arrow-up-d.gif 上传到您的服务器。接下来，假设我们有一个简单的页面，其中只有一个 input 字段。

<html>
    <body>
        <input type="text"
            id="tb" value=""
            style="font-family:verdana;width:300px;font-size:12px" />

    </body>
</html>

您应该做的第一件事是添加对 autocomplete.js 和 autocomplete.css 文件的引用。

<html>
    <head>

        <link rel="stylesheet" type="text/css" href="autosuggest.css"></link>
        <script type="text/javascript" src="autosuggest.js"></script>

    </head>

 ...

接下来，使用要绑定的 INPUT 元素的 id 初始化自动建议控件。

<input type="text" id="tb" value=""

    style="font-family:verdana;width:300px;font-size:12px" />

   <script> new autosuggest("tb"); </script>

如果您想使用静态客户端数组，请

在页面的 head 中创建它。

<head>
    <script type="text/javascript" src="autosuggest.js"></script>

    <script>
        var customarray =
                     ["apple", "alligator", "banana", "elephant",
                      "pear", "kingbird", "kingbolt", "kingcraft",
                      "kingcup', "kingdom", "kingfisher"];
    </script>

</head>

将其作为第二个参数传递给 autosuggest 对象。

<script>
    var obj = new autosuggest("tb", customarray);

</script>

确保 autosuggest.js 开头的 autosuggest_url 变量为空（""）。
您可以在任何时候使用 bindArray 方法更改绑定的静态数组。
```
    var customarray2 = [ ... ];  

    ...

    obj.bindArray(customarray2);
```
如果您想创建链接的自动建议控件，这一点尤其有用。

注意：为了充分利用缓存的优势，请考虑将 custom_array 移至 autosuggest.js 或任何其他外部 JavaScript 文件。

如果您希望通过 AJAX 检索建议，请
1. 将服务器端脚本（用于检索建议列表）的 URL 作为第三个参数传递给 autosuggest 对象。
```
<script>
    var obj = new autosuggest("tb", "", "http://mysite.org/suggest.asp?");
</script>
```
  注意：请确保在 Web 服务 URL 的末尾加上 ? 符号。
2. 可选地，您可以设置全局 autosuggest_url 变量（在 autocomplete.js 中）为服务器端脚本的路径；这样您可以避免使用 autosuggest 的第三个参数（当您在页面上使用多个自动建议控件时，这可能很有用）。但是，如果您指定了第三个参数，它将覆盖全局 autosuggest_url。
  
  注意：脚本期望返回的数据为以下 XML 格式：
```
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
	<listdata>item1|item2|...</listdata>
```
  （即，在单个 listdata 标签内，由竖线字符分隔的一组字符串。）
  
  注意：默认分隔符是 |（竖线）；ajax_delimiter 变量控制此行为。
3. 与静态数组类似，您可以在任何时候使用 bindURL 方法重新绑定 Web 服务 URL。
```
    obj.bindURL("http://mysite.com/suggest?");
```

选项

在本地测试脚本时，由于安全限制，Mozilla/Firefox 浏览器不允许您进行 AJAX 查询。要解决此问题，请在 autosuggest.js 中取消注释以下内容：
```
// try { netscape.security.PrivilegeManager.enablePrivilege 
// 	("UniversalBrowserRead"); } catch (e) { }
```
如果您希望在此控件中使用向上/向下箭头而不是滚动条，可以将 use_scroll 变量设置为 false。
默认情况下，脚本会用所有以用户输入的字符串开头的项目填充建议列表。如果您想更改此行为，以便返回包含输入字符串的所有变体，请将 limit_start 变量设置为 false。否则，建议保持为 true。
如果您选择将 limit_start 变量设置为 false，您还有另一个选项需要考虑：match_first。它控制建议的出现顺序。设置为 true 时，它会首先显示所有以用户输入的字符串开头的项目，然后是所有包含输入字符串的其他项目；设置为 false 时，它会按它们在内部数组中出现的顺序显示所有项目，而不考虑部分匹配。
如果您在页面上有多个输入框/组合框，并且遇到建议列表显示在其他控件后面的情况，您应该将 use_IFrame 变量设置为 true。否则，建议保持为 false。
默认情况下，在特殊超时时间（response_time）过去之前，建议列表不会显示；这是为了提高可用性（并为 AJAX 用户节省一些流量）。您可以根据需要进行更改。
默认情况下，当建议列表首次打开时，没有项目被选中。这可以通过将 autosuggest 对象中的 no_default 变量更改为 false 来控制。
当前，脚本只在用户输入第一个字符时加载建议变体一次；然后进行实际的过滤。如果您希望设置更复杂的过滤技术，请考虑更改 full_refresh 选项，该选项指示脚本在每次按下键时进行 AJAX 调用。
如果您希望将 autosuggest 对象用作普通的 select 元素，可以查看 selectedIndex 属性，该属性包含所选建议的索引（从零开始）。
您可能希望将输入和选择限制在预定义的集合值内。在这种情况下，请使用 restrict_typing 选项（仅适用于客户端数组）；它不允许用户输入不在键数组中的值。请注意，此选项不能防止文本字段接受“错误”值（例如，通过从剪贴板粘贴）——因此，服务器端检查始终是个好主意。

您可以做的另一件事是将此自动建议控件变成一个 AJAX 驱动的 select，通过使用键/值对而不是普通字符串；结合 selectedIndex，这可以用于检索项目的 [值]。客户端数组的情况是

<head>
    <script type="text/javascript" src="autosuggest.js"></script>

    <script>
        var customarray =
           [['apple', 1], ['alligator', 2], ['banana', 3],
            ['elephant', 4], ['pear', 5], ['kingbird', 6],
            ['kingbolt', 7], ['kingcraft', 8],
            ['kingcup', 9], ['kingdom', 10], ['kingfisher', 11]];
    </script>

</head>

而 AJAX 字符串必须是

<listdata>key1,value1|key2,value2|...</listdata>

注意：分隔键和值的分隔符（默认为逗号）可以通过 item_delimiter 属性进行控制。

autosuggest 构造函数还可以接受第四个参数——一个函数的引用，该函数在用户选择建议时被调用。
```
new autosuggest("tb", customarray, null, function(index, control)
{
    alert("You've selected the key: " + control.keywords[index]);
});
```
该函数接收两个参数：所选项目的索引（在 keywords 数组中）以及调用此回调函数的控件对象的引用。

结束？

当然没有。如果您有任何问题，请随时在下面的论坛中发帖，或者给我发电子邮件，并且请为本文投票。:) 我会尽力回答所有请求并提供用户支持。

尽情享用！

历史

2007 年 8 月 22 日 - 版本 1.0
- 首次发布
2007 年 8 月 30 日 - 版本 1.1
- actb 对象现在彼此独立。
- 支持鼠标滚动。
- ESC 键现在可以关闭建议列表。
- 箭头图像现在更好地与浏览器缓存配合。
- 修复了 TAB 键过早切换焦点的问
- 修复了在某些情况下 INPUT 输入框失去焦点（导致自动建议控件失效）的问题。
2007 年 9 月 10 日 - 版本 1.2
- 添加了使用标准滚动条而不是向上/向下“按钮”的功能（actb_useScroll，默认开启）- 由 **LTSpeed** 贡献。
- 添加了 Microsoft Internet Explorer 错误的一个解决方法，该错误导致建议列表显示在页面控件后面（actb_useIFrame，默认关闭）- 由 **Jac Steyn** 贡献。
- 2 个图标使用更好的压缩方式保存（另外 2 个已压缩）- 由 **Jac Steyn** 贡献。
- 其他小的修正和修复。
- 修正了文章中一些误导性的陈述。
2007 年 9 月 20 日 - 版本 1.3
- 修复了错误的 actb_useIFrame 选项，现在它能正常工作了。
- 修复了 actb_useIFrame 选项的另一个问题，即用户无法通过鼠标单击选择建议。
- 增加了为每个 actb 对象指定服务器端 URL 的能力。
- 增加了避免初始选择第一个建议变体的能力（actb_noDefault，默认开启）。
- 增加了在每次按键时重新加载建议列表的功能（actb_fullRefresh，默认关闭）。
- 添加了 actb_selectedIndex 属性，包含最后选择的变体的索引（从零开始）。
- 各种小的修复和改进。
2007 年 10 月 10 日 - 版本 1.4
- 添加了 actb_response 选项。
- 添加了 actb_firstMatch 选项。
- 增加了使用键/值对的能力（接近 AJAX 驱动的 SELECT）。
- 增加了使用向下箭头键检索建议列表的能力（针对非空 INPUT 输入框）。
- 现在仅当用户实际更改 INPUT 输入框中的文本时，建议列表才会重新绘制。
- 修复了在使用键盘导航建议列表时，actb_selectedIndex 未正确赋值的错误。
- 其他小的错误修复。
2008 年 1 月 10 日 - 版本 1.5
- （希望）解决了建议框显示在 HTML 控件下方（“IFRAME 模式”）的所有问题。
- 建议框的构建速度显著提高（Internet Explorer 速度提高 2 倍，Firefox 速度提高 8 倍以上）。
- 按下“向下箭头”键现在会显示所有可用的建议（在 AJAX 模式下无效）。
- 现在可以使用 PageUp 和 PageDown 键滚动建议。
- 如果任何建议比建议框宽，建议框的宽度现在会增加。
- 带连字符的长建议不会跨越多行，而是会增加建议框的宽度。
- 修复了烦人的“'actb_display' 为 null 或不是对象”错误。
- 小的错误修复。
2008 年 12 月 16 日 - 版本 1.6
- 修复了在滚动文档中建议列表定位不正确的错误。
- 修复了 Firefox 与冗长 AJAX 响应相关的问题。
- actb_selectedIndex 现在始终具有正确的值。
- 构建包含大量（数百个）建议的建议列表现在速度快得多。
- 您现在可以使用 ajax_delimiter 和 item_delimiter 变量轻松地将自动建议控件调整为使用您 Web 服务的输出。
- 您现在可以使用 actb_htextColor 控制当前选中项文本的颜色。
2009 年 1 月 30 日 - 版本 1.7
- 修复了在 Microsoft Internet Explorer 和 Webkit 浏览器中使用 actb_useScroll 时，用户点击滚动条后建议列表消失的问题。
- 修复了使用 actb_useScroll 时，向下滚动时非标准滚动行为的一个小问题。
- 修复了建议列表比父输入框稍宽时的一个小显示问题。
- 引入了 actb_restrict 选项，该选项允许您将输入限制为客户端数组的键。
- 为代码添加了更多注释。
2009 年 2 月 2 日 - 版本 1.7
- 修复了（在上一个版本中引入的）一个问题，该问题不允许在建议框打开时聚焦其他输入字段（涉及 Internet Explorer 和 Webkit）。
2009 年 2 月 8 日 - 版本 1.8
- 修复了在滚动文档中，用户在 Microsoft Internet Explorer 和 Webkit 浏览器中点击滚动条后建议列表消失的问题。
  （这是对早期修复的附加补丁）。
- 所有全局变量（除 suggesturl 外）和函数都已移至 actb 对象（作为成员方法或内部函数），因此脚本现在不会干扰全局命名空间。
- 脚本已进行调整，以生成 XHTML 兼容的输出。
2009 年 4 月 10 日 - 版本 1.9
- 在滚动模式下，建议列表现在几乎即时显示，无论建议列表有多长（+ 许多性能优化）。
- 恢复了自采用 zichun 的代码以来丢失的功能，即检索关键字中间的其他关键字的建议。
- 修复了 item_delimiter 在代码中未正确使用的问
- 修复了在输入字段值更改后 actb_noDefault 选项未被尊重的问
- actb_selectedItem 现在包含原始建议列表中的所选项目索引，而不是过滤列表中的索引。
- actb 构造函数现在可以接受第四个参数——onSelect——一个回调函数的引用，该函数在用户每次选择建议时都会触发。
2009 年 4 月 16 日 - 版本 2.0
*** 与以前的版本不兼容 ***
- 主对象名称已更改——actb 已更改为 autosuggest——并且所有成员变量、方法和生成的 ID 都被赋予了易读的名称。
- 代码中的变量现在使用下划线表示法（除了 selectedIndex），而方法现在使用小驼峰表示法。
- 经过大量优化和代码体积缩减，脚本比以前的版本小了约 12%。
- 您现在可以在箭头模式下使用 PageUp 和 PageDown 键来导航建议。
- 脚本现在不会生成任何 CSS 警告（如 Firefox 的错误控制台所示）。
- 2 张 GIF 图片已优化（另外 2 张已经压缩）。
- 修复了箭头模式下 autosuggest 框的一些问
2009 年 4 月 20 日 - 版本 2.1（由 **Marco Vervoort** 贡献）
- 修复了仅在 Firefox 中出现的一个问题，当 restrict_typing 设置为 true 时，包含大写符号的任何建议都变得不可用。
- 修复了一个错误，当 no_default 设置为 false 时，所有建议都显示为已选中。
- 修复了 insertWord 方法中在没有定义分隔符时出现的错误。
- 修复了 getCaretEnd 方法在 Firefox 中生成警告的一个小问题。
- onSelect 回调现在接收第二个参数——调用它的 autosuggest 对象的引用。
2009 年 8 月 4 日 - 版本 2.2
- 修复了结果排序不正确的问题，该问题在某些情况下会缓存前一个搜索的结果。
- 修复了仅在 Internet Explorer 中出现的一个错误，您无法在目标输入字段上使用 onblur 属性（它被脚本重写了）。
- 修复了一个错误，当滚动到仍在加载的长列表的末尾时，可能会导致渲染问题并使建议列表失效。
- 修复了 restrict_typing 选项在输入字段中有多个分隔项时行为不正确的问（与 **Marco Vervoort** 合作）。
- 修复了一个错误，当键入一个没有匹配建议的关键字后，建议列表仍然可见，显示最新的合法建议。
- 您现在可以通过 bindArray 和 bindURL 方法动态绑定 AJAX Web 服务的数组和/或 URL。
- 在浏览器窗口大小调整后，建议列表现在会正确地重新定位到父输入框下方。
- Home/End/PageUp/PageDown 键的行为在不同浏览器之间的兼容性现在更好。
- 版本号现在写在 autosuggest.js 中。
2009 年 8 月 18 日 - 版本 2.3
- 修复了导致 AJAX 支持失效的错误。
- 修复了导致 use_iframe 选项失效的错误。
2009 年 10 月 10 日 - 版本 2.4
*** 与以前的版本不兼容 ***
- 所有样式信息已移至 CSS（autosuggest.css）。
- 修复了在冗长的 XHTML 文档中使用自动建议控件时滚动条功能不正确的错误。
- 示例页面已更正，以验证为 XHTML 1.0 Strict。