JqueryUI - 自动完成功能小部件
自动完成是现代网站中经常使用的一种机制，可为用户提供他/她在文本框中键入的单词开头的建议列表。 然后用户可以从列表中选择一个项目，该项目将显示在输入字段中。 此功能使用户不必输入整个单词或一组单词。
JQueryUI 提供了一个自动完成小部件 — 一个非常类似于 <select> 下拉列表的控件，但会过滤选项以仅显示与用户在控件中输入的内容相匹配的选项。 jQueryUI 提供了 autocomplete() 方法来在输入字段下方创建建议列表，并向相关元素添加新的 CSS 类以赋予它们适当的样式。
语法
autocomplete() 方法有两种形式 −
$ (selector, context).autocomplete (options) 方法
autocomplete (options) 方法声明 HTML <input> 元素必须作为将显示在建议列表上方的输入字段进行管理。 options 参数是一个对象，用于指定用户在输入字段中键入时建议列表的行为。
语法
$(selector, context).autocomplete (options);
您可以使用 Javascript 对象一次提供一个或多个选项。 如果要提供多个选项，那么您将使用逗号分隔它们，如下所示 −
$(selector, context).autocomplete({option1: value1, option2: value2..... });
下表列出了可与此方法一起使用的不同选项 −
| 序号 | 选项 & 说明 |
|---|---|
| 1 | appendTo
此选项用于将元素附加到菜单。 默认情况下，它的值为 null。 |
| 2 | autoFocus
此选项设置为 true 时，菜单的第一项将在显示菜单时自动获得焦点。 默认情况下，它的值为 false。 |
| 3 | delay
此选项是一个整数，表示在尝试获取匹配值（由 source 选项指定）之前要等待的毫秒数。 通过让用户有时间在搜索开始之前输入更多字符，这有助于减少获取非本地数据时的抖动。 默认情况下，它的值为 300。 |
| 4 | disabled
如果指定此选项且 true，则自动完成小部件最初被禁用。 默认情况下，它的值为 false。 |
| 5 | minLength
在尝试获取匹配值（由 source 选项指定）之前必须输入的字符数。 当几个字符不足以将值集削减到合理水平时，这可以防止出现太大的值集。 默认情况下，它的值为 1。 |
| 6 | position
此选项标识建议菜单相对于关联输入元素的位置。 of 选项默认为输入元素，但您可以指定另一个元素来定位。 默认情况下，它的值为 { my: "left top", at: "left bottom", collision: "none" }。 |
| 7 | source
此选项指定获取与输入数据匹配的数据的方式。 必须提供一个值，否则将不会创建自动完成小部件。 默认情况下，它的值为 none; must be specified。 |
以下部分将向您展示一些自动完成小部件功能的工作示例。
默认功能
以下示例演示了自动完成小部件功能的一个简单示例，不向 autocomplete() 方法传递任何参数。
<!doctype html>
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Autocomplete functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- Javascript -->
<script>
$(function() {
var availableTutorials = [
"ActionScript",
"Bootstrap",
"C",
"C++",
];
$( "#automplete-1" ).autocomplete({
source: availableTutorials
});
});
</script>
</head>
<body>
<!-- HTML -->
<div class = "ui-widget">
<p>Type "a" or "s"</p>
<label for = "automplete-1">Tags: </label>
<input id = "automplete-1">
</div>
</body>
</html>
让我们将上面的代码保存在一个 HTML 文件 autocompleteexample.htm 中，并在支持 javascript 的标准浏览器中打开它，您应该会看到以下输出。 现在，您可以查看结果 −
autoFocus 的使用
以下示例演示了选项 autoFocus 在 JqueryUI 的自动完成小部件中的用法。
<!doctype html>
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Autocomplete functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- Javascript -->
<script>
$(function() {
var availableTutorials = [
"ActionScript",
"Bootstrap",
"C",
"C++",
];
$( "#automplete-2" ).autocomplete({
source: availableTutorials,
autoFocus:true
});
});
</script>
</head>
<body>
<!-- HTML -->
<div class = "ui-widget">
<p>Type "a" or "s"</p>
<label for = "automplete-2">Tags: </label>
<input id = "automplete-2">
</div>
</body>
</html>
让我们将上面的代码保存在一个 HTML 文件 autocompleteexample.htm 中，并在支持 javascript 的标准浏览器中打开它，您应该会看到以下输出。 现在，您可以查看结果 −
minLength 和 delay 的使用
以下示例演示了 JqueryUI 的自动完成小部件中两个选项 minLength 和 delay 的用法。
<!doctype html>
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Autocomplete functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- Javascript -->
<script>
$(function() {
var availableTutorials = [
"ActionScript",
"Bootstrap",
"C",
"C++",
"Ecommerce",
"Jquery",
"Groovy",
"Java",
"JavaScript",
"Lua",
"Perl",
"Ruby",
"Scala",
"Swing",
"XHTML"
];
$( "#automplete-3" ).autocomplete({
minLength:2,
delay:500,
source: availableTutorials
});
});
</script>
</head>
<body>
<!-- HTML -->
<div class = "ui-widget">
<p>Type two letter for e.g:ja,sc etc</p>
<label for = "automplete-3">Tags: </label>
<input id = "automplete-3">
</div>
</body>
</html>
让我们将上面的代码保存在一个 HTML 文件 autocompleteexample.htm 中，并在支持 javascript 的标准浏览器中打开它，您应该会看到以下输出。 现在，您可以查看结果 −
label 标签的使用
以下示例演示了选项 label 在 JqueryUI 的自动完成小部件中的用法。
<!doctype html>
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Autocomplete functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- Javascript -->
<script>
$(function() {
$( "#autocomplete-4" ).autocomplete({
source: [
{ label: "India", value: "IND" },
{ label: "Australia", value: "AUS" }
]
});
});
</script>
</head>
<body>
<!-- HTML -->
<div class = "ui-widget">
<p>Type I OR A</p>
<input id = "autocomplete-4">
</div>
</body>
</html>
让我们将上面的代码保存在一个 HTML 文件 autocompleteexample.htm 中，并在支持 javascript 的标准浏览器中打开它，您应该会看到以下输出。 现在，您可以查看结果 −
使用外部资源
以下示例演示了在 JqueryUI 的自动完成小部件中使用外部文件作为 source 选项。
<!doctype html>
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Autocomplete functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- Javascript -->
<script>
$(function() {
$( "#autocomplete-5" ).autocomplete({
source: "/jqueryui/search.php",
minLength: 2
});
});
</script>
</head>
<body>
<input id = "autocomplete-5">
</body>
</html>
文件 search.php 与上述文件 (autocompleteexample.html) 位于同一位置。 search.php 的内容如下 −
<?
$term = $_GET[ "term" ];
$companies = array(
array( "label" => "JAVA", "value" => "1" ),
array( "label" => "DATA IMAGE PROCESSING", "value" => "2" ),
array( "label" => "JAVASCRIPT", "value" => "3" ),
array( "label" => "DATA MANAGEMENT SYSTEM", "value" => "4" ),
array( "label" => "COMPUTER PROGRAMMING", "value" => "5" ),
array( "label" => "SOFTWARE DEVELOPMENT LIFE CYCLE", "value" => "6" ),
array( "label" => "LEARN COMPUTER FUNDAMENTALS", "value" => "7" ),
array( "label" => "IMAGE PROCESSING USING JAVA", "value" => "8" ),
array( "label" => "CLOUD COMPUTING", "value" => "9" ),
array( "label" => "DATA MINING", "value" => "10" ),
array( "label" => "DATA WAREHOUSE", "value" => "11" ),
array( "label" => "E-COMMERCE", "value" => "12" ),
array( "label" => "DBMS", "value" => "13" ),
array( "label" => "HTTP", "value" => "14" )
);
$result = array();
foreach ($companies as $company) {
$companyLabel = $company[ "label" ];
if ( strpos( strtoupper($companyLabel), strtoupper($term) )!== false ) {
array_push( $result, $company );
}
}
echo json_encode( $result );
?>
让我们将上面的代码保存在一个 HTML 文件 autocompleteexample.htm 中，并在支持 javascript 的标准浏览器中打开它，您应该会看到以下输出。 现在，您可以查看结果 −
输入两个字母的单词，例如：ja、sc 等
$ (selector, context).autocomplete ("action", params) 方法
autocomplete ("action", params) 方法可以对建议列表执行操作，例如显示或隐藏。 该操作在第一个参数中指定为字符串（例如，"关闭"以隐藏列表）。 在下表中查看可以传递的操作。
语法
$(selector, context).autocomplete ("action", params);;
下表列出了可与此方法一起使用的不同actions操作 −
| 序号 | 操作 & 说明 |
|---|---|
| 1 | close
此操作隐藏自动完成菜单中的建议列表。 此方法不接受任何参数。 |
| 2 | destroy
此操作删除自动完成功能。 建议列表已删除。 此方法不接受任何参数。 |
| 3 | disable
此操作禁用自动完成机制。 建议列表不再出现。 此方法不接受任何参数。 |
| 4 | enable
此操作重新激活自动完成机制。 建议列表将再次显示。 此方法不接受任何参数。 |
| 5 | option( optionName )
此操作检索指定参数 optionName 的值。 此选项对应于与自动完成（选项）一起使用的选项之一。 |
| 6 | option
此操作获取一个包含表示当前自动完成选项哈希的键/值对的对象。 |
| 7 | option( optionName, value )
此操作设置与指定的 optionName 关联的自动完成选项的值。 参数 optionName 是要设置的选项的名称，value 是要为选项设置的值。 |
| 8 | option( options )
此操作为自动完成设置一个或多个选项。 参数 options 是要设置的选项值对的映射。 |
| 9 | search( [value ] )
此操作搜索字符串值与数据源（在 options.source 中指定）之间的对应关系。 必须达到最小字符数（在 options.minLength 中指示）值，否则不执行搜索。 |
| 10 | widget
检索与建议列表对应的 <ul> DOM 元素。 这是一个 jQuery 类的对象，它允许在不使用 jQuery 选择器的情况下轻松访问列表。 |
示例
现在让我们看一个使用上表中的操作的示例。 以下示例演示了 option( optionName, value ) 方法的使用。
<!doctype html>
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Autocomplete functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<!-- Javascript -->
<script>
$(function() {
var availableTutorials = [
"ActionScript",
"Bootstrap",
"C",
"C++",
"Ecommerce",
"Jquery",
"Groovy",
"Java",
"JavaScript",
"Lua",
"Perl",
"Ruby",
"Scala",
"Swing",
"XHTML"
];
$( "#automplete-6" ).autocomplete({
source: availableTutorials
});
$( "#automplete-6" ).autocomplete("option", "position",
{ my : "right-10 top+10", at: "right top" })
});
</script>
</head>
<body>
<!-- HTML -->
<div class = "ui-widget">
<p>Type "a" or "s"</p>
<label for = "automplete-6">Tags: </label>
<input id = "automplete-6">
</div>
</body>
</html>
让我们将上面的代码保存在一个 HTML 文件 autocompleteexample.htm 中，并在支持 javascript 的标准浏览器中打开它，您应该会看到以下输出 −
扩展点
自动完成小部件可以通过小部件工厂进行扩展。 扩展小部件时，您可以覆盖或添加现有方法的行为。下表列出了充当扩展点的方法，它们具有与上面 列出的插件方法相同的 API 稳定性。
| 序号 | 方法 & 说明 |
|---|---|
| 1 | _renderItem( ul, item )
此方法控制小部件菜单中每个选项的创建。 此方法创建一个新的 <li> 元素，将其附加到菜单并返回它。 |
| 2 | _renderMenu( ul, items )
此方法控制构建小部件的菜单。 |
| 3 | _resizeMenu()
此方法在显示菜单之前控制菜单的大小。菜单元素在 this.menu.element 中可用。 此方法不接受任何参数。 |
自动完成元素的事件管理
除了我们在前面部分看到的自动完成（选项）方法之外，JqueryUI 还提供了针对特定事件触发的事件方法。 下面列出了这些事件方法 −
| 序号 | 事件方法 & 说明 |
|---|---|
| 1 | change(event, ui)
当 <input> 元素的值根据选择发生更改时，将触发此事件。 触发时，此事件将始终在触发 close 事件之后发生。 |
| 2 | close(event, ui)
每当自动完成菜单关闭时都会触发此事件。 |
| 3 | create(event, ui)
创建自动完成时会触发此事件。 |
| 4 | focus(event, ui)
只要其中一个菜单选项获得焦点，就会触发此事件。 除非取消（例如，通过返回 false），否则焦点值将设置到 <input> 元素中。 |
| 5 | open(event, ui)
该事件在数据准备好且菜单即将打开时触发。 |
| 6 | response(event, ui)
此事件在搜索完成后、菜单显示前触发。 搜索完成时始终会触发此事件，即使由于没有结果或禁用自动完成功能而不会显示菜单也是如此。 |
| 7 | search(event, ui)
此事件在满足任何 delay 和 minLength 条件后触发，就在源指定的机制被激活之前。 如果取消，搜索操作将中止。 |
| 8 | select(event, ui)
当从自动完成菜单中选择一个值时会触发此事件。 取消此事件会阻止将值设置到 <input> 元素中（但不会阻止菜单关闭）。 |
示例
以下示例演示了自动完成小部件中的事件方法用法。 此示例演示事件 focus 和 select 的使用。
<!doctype html>
<html lang = "en">
<head>
<meta charset = "utf-8">
<title>jQuery UI Autocomplete functionality</title>
<link href = "https://code.jquery.com/ui/1.10.4/themes/ui-lightness/jquery-ui.css"
rel = "stylesheet">
<script src = "https://code.jquery.com/jquery-1.10.2.js"></script>
<script src = "https://code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
<style>
#project-label {
display: block;
font-weight: bold;
margin-bottom: 1em;
}
#project-icon {
float: left;
height: 32px;
width: 32px;
}
#project-description {
margin: 0;
padding: 0;
}
</style>
<!-- Javascript -->
<script>
$(function() {
var projects = [
{
value: "java",
label: "Java",
desc: "write once run anywhere",
},
{
value: "jquery-ui",
label: "jQuery UI",
desc: "the official user interface library for jQuery",
},
{
value: "Bootstrap",
label: "Twitter Bootstrap",
desc: "popular front end frameworks ",
}
];
$( "#project" ).autocomplete({
minLength: 0,
source: projects,
focus: function( event, ui ) {
$( "#project" ).val( ui.item.label );
return false;
},
select: function( event, ui ) {
$( "#project" ).val( ui.item.label );
$( "#project-id" ).val( ui.item.value );
$( "#project-description" ).html( ui.item.desc );
return false;
}
})
.data( "ui-autocomplete" )._renderItem = function( ul, item ) {
return $( "<li>" )
.append( "<a>" + item.label + "<br>" + item.desc + "</a>" )
.appendTo( ul );
};
});
</script>
</head>
<body>
<div id = "project-label">Select a project (type "a" for a start):</div>
<input id = "project">
<input type = "hidden" id = "project-id">
<p id = "project-description"></p>
</body>
</html>
让我们将上述代码保存在一个 HTML 文件 autocompleteexample.htm 中，并在支持 javascript 的标准浏览器中打开它。 你应该看到以下输出 −
