Автозаполнение

Autocomplete


Описание
Свойства
Методы
События
Оформление

Плагин Autocomplete помогает пользователю заполнять текстовые поля, предлагая подходящие варианты по первым набранным им символам. Чтобы выбрать вариант из предоставленных подсказок можно воспользоваться клавиатурой (клавиши стрелок и enter) или мышью (кликнув по нужному варианту).

Данные для автозаполнения могут быть заданы тремя способами:

  • Массивом (это будет хорошим решением, если количество вариантов не превышает 50-100 элементов).
  • URL страницы, на которую будет автоматически отправляться ajax-запрос при каждом изменении вводимого текста.
  • Функцией. В этом случае поиск подходящих элементов нужно будет осуществить самостоятельно (наиболее гибкий вариант).

Во всех случаях, источник данных указывается в свойстве source. Разберем все три возможных варианта задания этого свойства более подробно:

Массив

В этом случае, задается либо массив строк, либо массив объектов, которые должны содержать поля label, value или оба. Если заданы оба поля, то в списке автозаполнения будут показываться поля из label, а при выборе любого из них, в текстовое поле будет помещен соответствующее значение value. Если задать массив объектов только с label или только с value, то эти значения будут отображаться и в предложенном списке и вставляться при выборе:

// массив строк
var availableTags = [
  "Испанский",
  "Итальянский",
  "Английский",
  "Китайский",
  "Русский"
];
 
// или массив объектов
availableTags = [
  {label:"Испанский", value:"es"},
  {label:"Итальянский", value:"it"},
  {label:"Английский", value:"en"},
  {label:"Китайский", value:"zh"},
  {label:"Русский", value:"ru"}
];
 
// задаем массив в качестве источника слов для автозаполнения.
$( "#tags" ).autocomplete({source: availableTags});

URL страницы

Если в свойстве source задать строку с url-адресом, то при изменении содержимого текстового поля, по этому адресу будет автоматически производиться ajax-запрос на сервер. Серверу будет передаваться содержимое текстового поля в параметре term. Естественно, обработку данных на сервере вы должны будете организовать самостоятельно (скорее всего, это будет заключаться в поиске подходящих слов по подстроке, в вашей базе данных). Ответ от сервера должен соответствовать тому же формату, что и в предыдущем случае:

Функция

Это наиболее гибкое из возможных решений. Заданная функция будет получать два параметра:

  • Первый — объект запроса, который будет содержать одно поле: term. Оно будет содержать текущее содержимое текстового поля, для которого нужно подобрать элементы автозаполнения.
  • Вторым параметром будет задана функция, которую будет необходимо вызвать и передать ей список подходящих элементов автозаполнения. Он должен соответствовать тому же формату, что и в предыдущих случаях (массив строк или массив объектов). Необходимо отметить, что эта функция должна быть вызвана при любых обстоятельствах, даже если при подборе элементов автозаполнения произошла ошибка.

Рассмотрим пример, в котором в качестве свойства source задается функция, запрашивающая данные для автозаполнения на стороннем сервере (кроссдоменный запрос). Этот пример реализован выше под заголовком "Подгрузка удаленных данных".


↓ Имя свойства :типы значений (значение по умолчанию)
disabled:boolean(false)
Останавливает\возобновляет работу плагина Autocomplete.
// ------- Работа со свойством disabled ---------
// в момент установки autocomplete на элемент
$("selector").autocomplete({ disabled: true });
 
//получение значения disabled 
var disabled = $("selector").autocomplete( "option", "disabled" );
//изменение значения disabled
$("selector").autocomplete( "option", "disabled", true );
appendTo:селектор("body")
Определяет, в какой элемент будет вставлен список автозаполнения.
// ------- Работа со свойством appendTo ---------
// в момент установки autocomplete на элемент
$("selector").autocomplete({ appendTo:"#someElem" });
 
//получение значения appendTo
var appendTo = $(".selector").autocomplete( "option", "appendTo" );
//изменение значения appendTo
$("selector").autocomplete( "option", "appendTo", "#someElem" );
autoFocus:boolean(false)
Когда этот параметр равен true, первое значение в списке автозаполнения будет автоматически оказываться в фокусе. (Не увидел разницы в работе плагина при разных значениях этого параметра (замечание переводчика)).
// ------- Работа со свойством autoFocus ---------
// в момент установки autocomplete на элемент
$("selector").autocomplete({ autoFocus:true });
 
//получение значения autoFocus
var autoFocus = $("selector").autocomplete( "option", "autoFocus" );
//изменение значения autoFocus
$("selector").autocomplete( "option", "autoFocus", true );
delay:integer(300)
Определяет сколько миллисекунд должно пройти после последнего нажатия клавиши, чтобы сработало автозаполнение. Эта задержка важна при получении данных из удаленного источника (если она будет равна 0, то запрос будет производиться при каждом введенном символе, что приведет к большому количеству лишних запросов на сервер). Если вы используете локальные списки автозаполнения (задаете его с помощью массива), то можете смело присвоить этому свойству 0.
// ------- Работа со свойством delay ---------
// в момент установки autocomplete на элемент
$("selector").autocomplete({ delay: 0 });
 
//получение значения delay
var delay = $("selector").autocomplete( "option", "delay" );
//изменение значения delay
$("selector").autocomplete( "option", "delay", 0 );
minLength:integer(1)
Определяет минимальное количество символов, при котором будет осуществлен поиск подходящих элементов автозаполнения. Если вы берете данные для автозаполнения у сервера, увеличение этого параметра (обычно до 2 или 3) снизит количество запросов на сервер, почти не повлияв на удобство использования (вряд-ли можно подобрать удачные варианты по одной букве).
// ------- Работа со свойством minLength ---------
// в момент установки autocomplete на элемент
$("selector").autocomplete({ minLength: 2 });
 
//получение значения minLength
var minLength = $("selector").autocomplete( "option", "minLength" );
//изменение значения minLength
$("selector").autocomplete( "option", "minLength", 2 );
position:object({my:"left top", at:"left bottom", collision:"none"})
Определяет позиционирование списка автозаполнения.
// ------- Работа со свойством position ---------
// в момент установки autocomplete на элемент
$("selector").autocomplete({ position:{my:"right top", at:"right bottom"} });
 
//получение значения position
var position = $("selector").autocomplete( "option", "position" );
//изменение значения position
$("selector").autocomplete( "option", "position", {my:"right top", at:"right bottom"} );
source:string,array,функция(нет. Необходимо задать)
Определяет источник элементов автозаполнения. Подробности в разделе Описание.
// ------- Работа со свойством source ---------
// в момент установки autocomplete на элемент
$("selector").autocomplete({ source:["c++", "java", "php"] });
 
//получение значения source
var source = $("selector").autocomplete( "option", "source" );
//изменение значения source
$("selector").autocomplete( "option", "source", ["c++", "java", "php"] );

↓ Способ вызова
.autocomplete("destroy") 
Удаляет всю функциональность плагина autocomplete с выбранных элементов.
.autocomplete("disable") 
Останавливает работу плагина autocomplete на выбранных элементах. Для возобновления, необходимо воспользоваться методом .autocomplete("enable").
.autocomplete("enable") 
Возобновляет работу плагина autocomplete на выбранных элементах (например, после того, как она была остановлена с помощью .autocomplete("disable")).
.autocomplete("option", optionName, [value]) 
Этот метод позволяет изменять/получать свойства плагина autocomplete. Если необходимо изменить сразу несколько свойств, воспользуйтесь следующей формой этой функции — .autocomplete("option", options), где options это объект в формате {optionName1:value1, optionName2:value2, ...}.
.autocomplete("widget") 
Возвращает те из выбранных элементов, к которым был применен плагин autocomplete (поиск осуществляется по классу ui-autocomplete, который автоматически присваивается этим элементам).
.autocomplete("search" , [value]) 
Этот метод вызывает событие типа search на выбранных элементах, что запустит процедуру поиска подходящих элементов автозаполнения (если конечно содержимое текстового поля будет соответствовать значению minLength). Если задать необязательный параметр value, то поиск элементов будет произведен по этому значению, независимо от содержимого текстового поля. Например, если задать minLength = 0 и вызвать .autocomplete("search" , "") (с пустым value), то список автозаполнения будет открыт со всеми возможными вариантами.
.autocomplete("close") 
Закрывает список автозаполнения.

↓ Внутреннее имя события :внешнее имя
create:autocompletecreate
Событие create происходит в момент инициализации autocomplete на элементе.
// обработка события create
$("selector").autocomplete({
   create: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "autocompletecreate", function(event, ui){ ... });
search:autocompletesearch
Событие search происходит до того, как начинается поиск подходящих элементов, но после того, как закончится задержка (см. свойство delay). Если обработчик этого события вернет false, то поиск элементов для автозаполнения будет отменен.
// обработка события search
$("selector").autocomplete({
   search: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "autocompletesearch", function(event, ui){ ... });
open:autocompleteopen
Событие open происходит в момент открытия списка с элементами автозаполнения.
// обработка события open
$("selector").autocomplete({
   open: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "autocompleteopen", function(event, ui){ ... });
focus:autocompletefocus
Происходит при выделении одного из элементов автозаполнения. Когда это событие происходит из-за нажатия на клавиши клавиатуры ↓ или ↑ (кроме этого, событие focus может происходить при наведении курсора на элементы), текст выделенного элемента оказывается в текстовом поле. Если обработчик события focus возвратит false, то замены текста в текстовом поле не произойдет, однако выделения элемента это не отменит.
// обработка события focus
$("selector").autocomplete({
   focus: function(event, ui) {  /*ui.item будет содержать выделенный элемент*/ }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "autocompletefocus", function(event, ui){ ... });
select:autocompleteselect
Происходит при выборе элемента автозаполнения. Стандартное действие на это событие — перенос текста выбранного элемента в текстовое поле, а затем закрытие списка автозаполнения. Если обработчик события select вернет false, то переноса текста не произойдет, однако список все равно будет закрыт. Очередность событий при выборе одного из элементов: select, close, а затем change.
// обработка события select
$("selector").autocomplete({
   select: function(event, ui) { /*ui.item будет содержать выбранный элемент*/ }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "autocompleteselect", function(event, ui){ ... });
close:autocompleteclose
Происходит при закрытии списка автозаполнения. Очередность событий при выборе одного из элементов: select, close, а затем change.
// обработка события close
$("selector").autocomplete({
   close: function(event, ui) { ... }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "autocompleteclose", function(event, ui){ ... });
change:autocompletechange
Событие change происходит при выборе элемента автозаполнения, уже после закрытия всего списка. То есть, очередность событий при выборе одного из элементов: select, close, а затем change.
// обработка события change
$("selector").autocomplete({
   change: function(event, ui) { /*ui.item будет содержать выбранный элемент*/ }
});
 
// еще один способ (используя метод bind)
$("selector").bind( "autocompletechange", function(event, ui){ ... });

Плагин Autocomplete использует стандартные стили jQueryUI-css для оформления выпадающего списка с элементами автозаполнения. Для редактирования оформления рекомендуется использовать специальную ручную настройку на сайте jQuery UI. Для специфичных манипуляций с элементами списка автозаполнения, можно воспользоваться информацией о его структуре:

Т.е. элементу текстового поля будет добавлен класс ui-autocomplete-input. Выпадающей список представляет из себя html-список, каждый элемент которого будет иметь класс ui-menu-item.