jQuery UI API - виджет Autocomplete
Категории
Использование
Описание:Функция автозаполнения выполняет поиск и фильтрацию на основе пользовательского ввода, позволяя пользователям быстро находить и выбирать значения из предустановленного списка.
Добавлено в версии:1.8
Любое поле, которое может принимать ввод, можно преобразовать в Autocomplete, то есть,<input>элементы input,<textarea>элементы textarea, иcontenteditableэлементы с атрибутом contenteditable.
При установке фокуса на поле Autocomplete или вводе в него символов плагин начинает поиск совпадающих записей и отображает список значений для выбора. Вводя больше символов, пользователь может фильтровать список, чтобы получить более точные совпадения.
Этот виджет можно использовать для выбора ранее выбранных значений, например при вводе тегов статьи или вводе адресов электронной почты из адресной книги. Автодополнение также можно использовать для заполнения связанной информации, например при вводе названия города для получения почтового индекса этого города.
Вы можете получать данные из локального или удалённого источника: локальный источник подходит для небольших наборов данных, например адресной книги с 50 записями; удалённый источник подходит для больших наборов данных, например базы данных с сотнями или тысячами записей. Дополнительные сведения о пользовательских источниках данных см. вsourceдокументации по этой опции.
Взаимодействие с клавиатурой
Когда меню открыто, доступны следующие команды клавиатуры:
- UP - Переместить фокус на предыдущий элемент. Если фокус на первом элементе, переместить фокус на поле ввода. Если фокус на поле ввода, переместить фокус на последний элемент.
- DOWN - Переместить фокус на следующий элемент. Если фокус на последнем элементе, переместить фокус на поле ввода. Если фокус на поле ввода, переместить фокус на первый элемент.
- ESCAPE - Закрыть меню.
- ENTER - Выбрать элемент, находящийся в фокусе, и закрыть меню.
- TAB - Выбрать элемент, находящийся в фокусе, закрыть меню и переместить фокус на следующий элемент, доступный для фокусировки.
- PAGE UP/DOWN - Прокрутить список на один экран (в зависимости от высоты меню).
Когда меню закрыто, доступны следующие команды клавиатуры:
- UP/DOWN - Если выполнено,
minLengthто откройте меню.
Темы оформления
Виджет Autocomplete используетjQuery UI CSS Frameworkдля определения стилей его внешнего вида и поведения. Если вам нужно использовать стили, специфичные для виджета Autocomplete, вы можете использовать следующие имена CSS-классов:
ui-autocomplete: Используется для отображения соответствующегоменю.ui-autocomplete-input: Элемент ввода, созданный виджетом Autocomplete.
Зависимости
Дополнительные примечания
- Для этого виджета требуется некоторый функциональный CSS, иначе он не будет работать. Если вы создаёте собственную тему, используйте CSS-файл, специфичный для виджета, в качестве отправной точки.
- Этот виджет программно работает со значением элемента, поэтому при изменении значения элемента он не будет нативно
changeсобытие.
Быстрая навигация
| Параметры | Методы | Точки расширения | Events |
|---|---|---|---|
| Параметры | Type | Описание | Значение по умолчанию |
|---|---|---|---|
| appendTo | Селектор | Элемент, к которому должно быть добавлено меню. Когда это значение равноnull, родительский элемент поля ввода будет проверять наличиеui-frontкласс. Если элемент сui-frontкласс найден, меню будет добавлено к этому элементу. Если ни один элемент сui-frontкласс не найден, меню будет добавлено к body независимо от значения.Примечание: когда меню подсказок открыто, Примеры кода: Инициализировать автодополнение с указанным
$( ".selector" ).autocomplete({ appendTo: "#someElem" });
После инициализации получите или задайте // getter var appendTo = $( ".selector" ).autocomplete( "option", "appendTo" ); // setter $( ".selector" ).autocomplete( "option", "appendTo", "#someElem" ); |
null |
| autoComplete | Boolean | Если установлено значениеtrue, когда меню отображается, первый элемент автоматически получит фокус.Примеры кода: Инициализировать автодополнение с указанным
$( ".selector" ).autocomplete({ autoFocus: true });
После инициализации получите или задайте // getter var autoFocus = $( ".selector" ).autocomplete( "option", "autoFocus" ); // setter $( ".selector" ).autocomplete( "option", "autoFocus", true ); |
false |
| delay | Integer | Задержка между нажатием клавиши и выполнением поиска, в миллисекундах. Для локальных данных нулевая задержка имеет смысл (более отзывчиво), но для удалённых данных она создаёт высокую нагрузку и снижает отзывчивость. Примеры кода: Инициализировать автодополнение с указанным
$( ".selector" ).autocomplete({ delay: 500 });
После инициализации получите или задайте // getter var delay = $( ".selector" ).autocomplete( "option", "delay" ); // setter $( ".selector" ).autocomplete( "option", "delay", 500 ); |
300 |
| disabled | Boolean | Если установлено значениеtrue, автозаполнение отключено.Примеры кода: Инициализировать автодополнение с указанным
$( ".selector" ).autocomplete({ disabled: true });
После инициализации получите или задайте // getter var disabled = $( ".selector" ).autocomplete( "option", "disabled" ); // setter $( ".selector" ).autocomplete( "option", "disabled", true ); |
false |
| minLength | Integer | Минимальное количество символов, которое пользователь должен ввести до выполнения поиска. Для локальных данных с небольшим количеством записей обычно устанавливается равным нулю, но если поиск по одному символу будет соответствовать тысячам записей, необходимо установить большее значение. Примеры кода: Инициализировать автодополнение с указанным
$( ".selector" ).autocomplete({ minLength: 0 });
После инициализации получите или задайте // getter var minLength = $( ".selector" ).autocomplete( "option", "minLength" ); // setter $( ".selector" ).autocomplete( "option", "minLength", 0 ); |
1 |
| position | Object | Определяет положение меню подсказок относительно связанного элемента ввода.ofПо умолчанию эта опция использует элемент ввода, но можно указать другой элемент для позиционирования. Для получения дополнительных сведений о различных опциях см.jQuery UI Position。Примеры кода: Инициализировать автодополнение с указанным
$( ".selector" ).autocomplete({ position: { my : "right top", at: "right bottom" } });
После инициализации получите или задайте
// getter
var position = $( ".selector" ).autocomplete( "option", "position" );
// setter
$( ".selector" ).autocomplete( "option", "position", { my : "right top", at: "right bottom" } );
|
{ my: "left top", at: "left bottom", collision: "none" } |
| source | Array, String или Function( Object request, Function response( Object data ) ) | Определяет используемые данные и должен быть указан. Независимо от используемой переменной, label всегда обрабатывается как текст. Если вы хотите, чтобы label обрабатывался как html, можно использоватьScott González' html extension. В демонстрации основное внимание уделяется Поддерживается несколько типов:
Пример кода: Инициализируйте autocomplete с указанными
$( ".selector" ).autocomplete({ source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] });
После инициализации получите или задайте // getter var source = $( ".selector" ).autocomplete( "option", "source" ); // setter $( ".selector" ).autocomplete( "option", "source", [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] ); |
нет; необходимо указать |
| Методы | Возвращает | Описание |
|---|---|---|
| close() | jQuery (только плагин) | Закрывает меню автозаполнения. При использовании сsearchметодом его можно использовать, чтобы закрыть открытое меню.
Пример кода: Вызовите метод close: $( ".selector" ).autocomplete( "close" ); |
| destroy() | jQuery (только плагин) | Полностью удаляет функциональность автозаполнения. Это вернёт элемент в состояние до инициализации.
Пример кода: Вызовите метод destroy: $( ".selector" ).autocomplete( "destroy" ); |
| disable() | jQuery (только плагин) | Отключает автозаполнение.
Пример кода: Вызовите метод disable: $( ".selector" ).autocomplete( "disable" ); |
| enable() | jQuery (только плагин) | Включает автозаполнение.
Пример кода: Вызовите метод enable: $( ".selector" ).autocomplete( "enable" ); |
| option( optionName ) | Object | Получает значение, связанное в данный момент с указаннымoptionNameпараметр.
Пример кода: Вызовите метод: var isDisabled = $( ".selector" ).autocomplete( "option", "disabled" ); |
| option() | PlainObject | Получает объект, содержащий пары ключ/значение, которые представляют текущий хэш параметров автозаполнения.
Пример кода: Вызовите метод: var options = $( ".selector" ).autocomplete( "option" ); |
| option( optionName, value ) | jQuery (только плагин) | Устанавливает значение параметра автозаполнения, связанного с указаннымoptionNameпараметр.
Пример кода: Вызовите метод: $( ".selector" ).autocomplete( "option", "disabled", true ); |
| option( options ) | jQuery (только плагин) | Устанавливает один или несколько параметров для автозаполнения.
Пример кода: Вызовите метод:
$( ".selector" ).autocomplete( "option", { disabled: true } );
|
| search( [value ] ) | jQuery (только плагин) | Запускаетsearchсобытие search, и если событие не отменено, вызывает источник данных. При щелчке может использоваться кнопкой в стиле selectbox для открытия подсказок. При вызове без аргументов используется текущее значение поля ввода. Может быть вызван с пустой строкой иminLength: 0для отображения всех элементов.
Пример кода: Вызовите метод search: $( ".selector" ).autocomplete( "search", "" ); |
| widget() | jQuery | ВозвращаетjQueryобъект, содержащий элемент меню.
Пример кода: Вызовите метод widget: $( ".selector" ).autocomplete( "widget" ); |
| Точки расширения | Возвращает | Описание |
|---|---|---|
| Виджет Autocomplete создается с помощьюWidget Factoryи может быть расширен. При расширении виджета можно переопределять или добавлять поведение в виджет-расширение. Приведенные ниже методы служат точками расширения и имеют такую же стабильность API, как иметоды плагина, перечисленные выше. Дополнительные сведения о расширениях виджетов см. в разделеРасширение виджетов с помощью Widget Factory. | ||
| _renderItem( ul, item ) | jQuery | Метод, управляющий созданием каждого пункта в меню виджета. Метод должен создать новый <li> элемент, добавить его в меню и вернуть его.Примечание: на данный момент
Пример кода: Добавьте значение записи как
_renderItem: function( ul, item ) {
return $( "<li>" )
.attr( "data-value", item.value )
.append( $( "<a>" ).text( item.label ) )
.appendTo( ul );
}
|
| _renderMenu( ul, items ) | jQuery (только плагин) | Этот метод отвечает за настройку размера меню перед отображением меню. Элемент меню можно получить путемthis.menu.elementиспользования.
Пример кода: Добавляет имя CSS-класса к старым пунктам меню.
_renderMenu: function( ul, items ) {
var that = this;
$.each( items, function( index, item ) {
that._renderItemData( ul, item );
});
$( ul ).find( "li:odd" ).addClass( "odd" );
}
|
| _resizeMenu() | jQuery (только плагин) | Этот метод отвечает за настройку размера меню перед отображением меню. Элемент меню можно получить путемthis.menu.elementиспользования.
Пример кода: Меню всегда отображается шириной 500 пикселей.
_resizeMenu: function() {
this.menu.element.outerWidth( 500 );
}
|
| Events | Type | Описание |
|---|---|---|
| change( event, ui ) | autocompletechange | Срабатывает при изменении значения поля ввода.
Пример кода: Инициализировать autocomplete с указанной функцией обратного вызова change:
$( ".selector" ).autocomplete({
change: function( event, ui ) {}
});
Привяжите обработчик события к событию autocompletechange:
$( ".selector" ).on( "autocompletechange", function( event, ui ) {} );
|
| close( event, ui ) | autocompleteclose | Срабатывает, когда меню скрыто. Не каждоеcloseсобытие сопровождаетсяchangeсобытие.
Примечание: Пример кода: Инициализируйте autocomplete с указанной функцией обратного вызова close:
$( ".selector" ).autocomplete({
close: function( event, ui ) {}
});
Привяжите обработчик события к событию autocompleteclose:
$( ".selector" ).on( "autocompleteclose", function( event, ui ) {} );
|
| create( event, ui ) | autocompletecreate | Срабатывает при создании autocomplete.
Примечание: Пример кода: Инициализируйте autocomplete с указанной функцией обратного вызова create:
$( ".selector" ).autocomplete({
create: function( event, ui ) {}
});
Привяжите обработчик события к событию autocompletecreate:
$( ".selector" ).on( "autocompletecreate", function( event, ui ) {} );
|
| focus( event, ui ) | autocompletefocus | Срабатывает, когда фокус перемещается на элемент (не выбранный). Действие по умолчанию — заменить значение в текстовом поле на значение элемента в фокусе, даже если событие вызвано взаимодействием с клавиатурой. Отмена этого события предотвращает обновление значения, но не препятствует получению фокуса пунктом меню.
Пример кода: Инициализируйте автозаполнение с указанной функцией обратного вызова focus:
$( ".selector" ).autocomplete({
focus: function( event, ui ) {}
});
Привяжите обработчик события к событию autocompletefocus:
$( ".selector" ).on( "autocompletefocus", function( event, ui ) {} );
|
| open( event, ui ) | autocompleteopen | Срабатывает при открытии или обновлении меню подсказок.
Примечание: Пример кода: Инициализируйте автозаполнение с указанной функцией обратного вызова open:
$( ".selector" ).autocomplete({
open: function( event, ui ) {}
});
Привяжите обработчик события к событию autocompleteopen:
$( ".selector" ).on( "autocompleteopen", function( event, ui ) {} );
|
| response( event, ui ) | autocompleteresponse | Срабатывает после завершения поиска и до показа меню. Полезно для локальной обработки данных предложений, где пользовательскийsourceобратный вызов параметра не требуется. Это событие всегда срабатывает при завершении поиска, и оно срабатывает даже если меню не отображается, потому что поиск не вернул результатов или Autocomplete отключён.
Примеры кода: Инициализируйте autocomplete с указанным обратным вызовом response:
$( ".selector" ).autocomplete({
response: function( event, ui ) {}
});
Привяжите обработчик события к событию autocompleteresponse:
$( ".selector" ).on( "autocompleteresponse", function( event, ui ) {} );
|
| search( event, ui ) | autocompletesearch | Срабатывает перед выполнением поискаminLengthиdelayа затем срабатывает. Если это событие отменено, запрос не будет отправлен, и никакие записи предложений не будут предоставлены.
Примечание: Примеры кода: Инициализируйте autocomplete с указанным обратным вызовом search:
$( ".selector" ).autocomplete({
search: function( event, ui ) {}
});
Привяжите обработчик события к событию autocompletesearch:
$( ".selector" ).on( "autocompletesearch", function( event, ui ) {} );
|
| select( event, ui ) | autocompleteselect | Срабатывает при выборе элемента из меню. Действие по умолчанию — заменить значение в текстовом поле значением выбранного элемента. Отмена этого события предотвращает обновление значения, но не предотвращает закрытие меню.
Примеры кода: Инициализируйте autocomplete с указанной callback-функцией select:
$( ".selector" ).autocomplete({
select: function( event, ui ) {}
});
Привяжите обработчик события к событию autocompleteselect:
$( ".selector" ).on( "autocompleteselect", function( event, ui ) {} );
|
Примеры
Пример 1:Простой Autocomplete из jQuery UI.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>自动完成部件(Autocomplete Widget)演示</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<label for="autocomplete">选择一个编程语言:</label>
<input id="autocomplete">
<script>
$( "#autocomplete" ).autocomplete({
source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ]
});
</script>
</body>
</html>
Пример 2:
Используйте пользовательскую callback-функцию source, чтобы сопоставлять начало поискового запроса.
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>自动完成部件(Autocomplete Widget)演示</title>
<link rel="stylesheet" href="//code.jquery.com/ui/1.10.4/themes/smoothness/jquery-ui.css">
<script src="//code.jquery.com/jquery-1.10.2.js"></script>
<script src="//code.jquery.com/ui/1.10.4/jquery-ui.js"></script>
</head>
<body>
<label for="autocomplete">选择一个编程语言:</label>
<input id="autocomplete">
<script>
var tags = [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ];
$( "#autocomplete" ).autocomplete({
source: function( request, response ) {
var matcher = new RegExp( "^" + $.ui.autocomplete.escapeRegex( request.term ), "i" );
response( $.grep( tags, function( item ){
return matcher.test( item );
}) );
}
});
</script>
</body>
</html>
Другие расширения