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 независимо от значения.

Примечание: когда меню подсказок открыто,appendToэту опцию не следует изменять.

Примеры кода:

Инициализировать автодополнение с указаннымappendTooption:

$( ".selector" ).autocomplete({ appendTo: "#someElem" });
    

После инициализации получите или задайтеappendTooption:

// getter
var appendTo = $( ".selector" ).autocomplete( "option", "appendTo" );
 
// setter
$( ".selector" ).autocomplete( "option", "appendTo", "#someElem" );
    
null
autoComplete Boolean Если установлено значениеtrue, когда меню отображается, первый элемент автоматически получит фокус.

Примеры кода:

Инициализировать автодополнение с указаннымautoFocusoption:

$( ".selector" ).autocomplete({ autoFocus: true });
    

После инициализации получите или задайтеautoFocusoption:

// getter
var autoFocus = $( ".selector" ).autocomplete( "option", "autoFocus" );
 
// setter
$( ".selector" ).autocomplete( "option", "autoFocus", true );
    
false
delay Integer Задержка между нажатием клавиши и выполнением поиска, в миллисекундах. Для локальных данных нулевая задержка имеет смысл (более отзывчиво), но для удалённых данных она создаёт высокую нагрузку и снижает отзывчивость.

Примеры кода:

Инициализировать автодополнение с указаннымdelayoption:

$( ".selector" ).autocomplete({ delay: 500 });
    

После инициализации получите или задайтеdelayoption:

// getter
var delay = $( ".selector" ).autocomplete( "option", "delay" );
 
// setter
$( ".selector" ).autocomplete( "option", "delay", 500 );
    
300
disabled Boolean Если установлено значениеtrue, автозаполнение отключено.

Примеры кода:

Инициализировать автодополнение с указаннымdisabledoption:

$( ".selector" ).autocomplete({ disabled: true });
    

После инициализации получите или задайтеdisabledoption:

// getter
var disabled = $( ".selector" ).autocomplete( "option", "disabled" );
 
// setter
$( ".selector" ).autocomplete( "option", "disabled", true );
    
false
minLength Integer Минимальное количество символов, которое пользователь должен ввести до выполнения поиска. Для локальных данных с небольшим количеством записей обычно устанавливается равным нулю, но если поиск по одному символу будет соответствовать тысячам записей, необходимо установить большее значение.

Примеры кода:

Инициализировать автодополнение с указаннымminLengthoption:

$( ".selector" ).autocomplete({ minLength: 0 });
    

После инициализации получите или задайтеminLengthoption:

// getter
var minLength = $( ".selector" ).autocomplete( "option", "minLength" );
 
// setter
$( ".selector" ).autocomplete( "option", "minLength", 0 );
    
1
position Object Определяет положение меню подсказок относительно связанного элемента ввода.ofПо умолчанию эта опция использует элемент ввода, но можно указать другой элемент для позиционирования. Для получения дополнительных сведений о различных опциях см.jQuery UI Position。

Примеры кода:

Инициализировать автодополнение с указаннымpositionoption:

$( ".selector" ).autocomplete({ position: { my : "right top", at: "right bottom" } });
    

После инициализации получите или задайтеpositionoption:

// 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. В демонстрации основное внимание уделяетсяsourceразличным вариантам этой опции — вы можете найти тот, который соответствует вашему варианту использования, и просмотреть соответствующий код.

Поддерживается несколько типов:

  • Array: массив, который можно использовать для локальных данных. Поддерживаются два формата:
    • Массив строк:[ "Choice1", "Choice2" ]
    • Массив объектов сlabelиvalueатрибутами:[ { label: "Choice1", value: "value1" }, ... ]
    Атрибут label отображается в меню подсказок. Когда пользователь выбирает элемент, значение вставляется в элемент input. Если указан только один атрибут, этот атрибут рассматривается и как label, и как value. Например, если вы указываете толькоvalueатрибут, value также рассматривается как label.
  • String: При использовании строки плагин Autocomplete ожидает, что строка указывает на URL-ресурс, который может возвращать данные JSON. Он может находиться на том же хосте или на другом хосте (необходимо предоставить JSONP). Плагин Autocomplete не фильтрует результаты, а вместо этого черезtermполе добавляет строку запроса, чтобы серверный скрипт мог фильтровать результаты. Например, еслиsourceпараметр установлен в"http://example.com", а пользователь вводитfoo, GET-запрос будетhttp://example.com?term=foo. Сам формат данных может быть таким же, как формат локальных данных, описанных ранее.
  • Function: Третий вариант — функция обратного вызова — обеспечивает наибольшую гибкость и может использоваться для подключения любого источника данных к Autocomplete. Функция обратного вызова принимает два параметра:
    • некийrequestобъект сtermатрибут, представляющий значение в текущем поле ввода текста. Например, если пользователь вводит в поле города"new yo", тогда term виджета Autocomplete эквивалентен"new yo"。
    • aresponseфункция обратного вызова, предоставляющая один параметр: данные, предлагаемые пользователю. Данные должны быть отфильтрованы на основе предоставленного term и могут быть в любом из локальных форматов данных, описанных выше. Используется для предоставления пользовательской функции обратного вызова источника для обработки ошибок во время запроса. Даже если возникает ошибка, вы должны вызватьresponseфункцию обратного вызова. Это гарантирует, что виджет всегда находится в правильном состоянии.

    При фильтрации локальных данных можно использовать встроенную$.ui.autocomplete.escapeRegexфункцию. Она принимает строковый аргумент, экранирует все символы регулярных выражений и делает результат безопасным для передачи вnew RegExp()。

Пример кода:

Инициализируйте autocomplete с указаннымиsourceпараметрами:

$( ".selector" ).autocomplete({ source: [ "c++", "java", "php", "coldfusion", "javascript", "asp", "ruby" ] });
    

После инициализации получите или задайтеsourceoption:

// 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параметр.
  • optionName
    Тип: String
    Описание: Имя опции, которую нужно получить.

Пример кода:

Вызовите метод:

var isDisabled = $( ".selector" ).autocomplete( "option", "disabled" );
    
option() PlainObject Получает объект, содержащий пары ключ/значение, которые представляют текущий хэш параметров автозаполнения.
  • Этот метод не принимает аргументов.

Пример кода:

Вызовите метод:

var options = $( ".selector" ).autocomplete( "option" );
    
option( optionName, value ) jQuery (только плагин) Устанавливает значение параметра автозаполнения, связанного с указаннымoptionNameпараметр.
  • optionName
    Тип: String
    Описание: Имя опции, которую нужно установить.
  • value
    Тип: Object
    Описание: Значение, задаваемое для параметра.

Пример кода:

Вызовите метод:

$( ".selector" ).autocomplete( "option", "disabled", true );
    
option( options ) jQuery (только плагин) Устанавливает один или несколько параметров для автозаполнения.
  • options
    Тип: Object
    Описание: Пары «параметр — значение» для установки.

Пример кода:

Вызовите метод:

$( ".selector" ).autocomplete( "option", { disabled: true } );
    
widget() jQuery ВозвращаетjQueryобъект, содержащий элемент меню.
  • Этот метод не принимает аргументов.

Пример кода:

Вызовите метод widget:

$( ".selector" ).autocomplete( "widget" );
    

Точки расширения Возвращает Описание
Виджет Autocomplete создается с помощьюWidget Factoryи может быть расширен. При расширении виджета можно переопределять или добавлять поведение в виджет-расширение. Приведенные ниже методы служат точками расширения и имеют такую же стабильность API, как иметоды плагина, перечисленные выше. Дополнительные сведения о расширениях виджетов см. в разделеРасширение виджетов с помощью Widget Factory.
_renderItem( ul, item ) jQuery Метод, управляющий созданием каждого пункта в меню виджета. Метод должен создать новый <li> элемент, добавить его в меню и вернуть его.

Примечание: на данный момент<ul> созданный элемент должен содержать <a> элемент для совместимости с виджетом меню. См. пример ниже.

  • ul
    Тип: jQuery
    Описание: Только что созданный<li>элемент должен быть добавлен к<ul>элементу.
  • item
    Тип: Object
    • label
      Тип: String
      Описание: Строка, отображаемая для записи.
    • item
      Тип: String
      Описание: Значение, вставляемое в поле ввода при выборе записи.

Пример кода:

Добавьте значение записи как<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использования.
  • ul
    Тип: jQuery
    Описание: Пустой<ul>элемент, используемый в качестве меню виджета.
  • items
    Тип: Array
    Описание: Массив элементов, соответствующих вводу пользователя. Каждый элемент — объект сlabelиvalueсвойством.

Пример кода:

Добавляет имя 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 Срабатывает при изменении значения поля ввода.
  • event
    Тип: Event
  • ui
    Тип: Object
    • item
      Тип: Object
      Описание: Элемент, выбранный из меню, в противном случае свойство равноnull。

Пример кода:

Инициализировать autocomplete с указанной функцией обратного вызова change:

$( ".selector" ).autocomplete({
  change: function( event, ui ) {}
});
    

Привяжите обработчик события к событию autocompletechange:

$( ".selector" ).on( "autocompletechange", function( event, ui ) {} );
    
close( event, ui ) autocompleteclose Срабатывает, когда меню скрыто. Не каждоеcloseсобытие сопровождаетсяchangeсобытие.
  • event
    Тип: Event
  • ui
    Тип: Object

Примечание:uiОбъект пуст; он включён для согласованности с другими событиями.

Пример кода:

Инициализируйте autocomplete с указанной функцией обратного вызова close:

$( ".selector" ).autocomplete({
  close: function( event, ui ) {}
});
    

Привяжите обработчик события к событию autocompleteclose:

$( ".selector" ).on( "autocompleteclose", function( event, ui ) {} );
    
create( event, ui ) autocompletecreate Срабатывает при создании autocomplete.
  • event
    Тип: Event
  • ui
    Тип: Object

Примечание:uiОбъект пуст; он включён для согласованности с другими событиями.

Пример кода:

Инициализируйте autocomplete с указанной функцией обратного вызова create:

$( ".selector" ).autocomplete({
  create: function( event, ui ) {}
});
    

Привяжите обработчик события к событию autocompletecreate:

$( ".selector" ).on( "autocompletecreate", function( event, ui ) {} );
    
focus( event, ui ) autocompletefocus Срабатывает, когда фокус перемещается на элемент (не выбранный). Действие по умолчанию — заменить значение в текстовом поле на значение элемента в фокусе, даже если событие вызвано взаимодействием с клавиатурой. Отмена этого события предотвращает обновление значения, но не препятствует получению фокуса пунктом меню.
  • event
    Тип: Event
  • ui
    Тип: Object
    • item
      Тип: Object
      Описание: элемент, получивший фокус.

Пример кода:

Инициализируйте автозаполнение с указанной функцией обратного вызова focus:

$( ".selector" ).autocomplete({
  focus: function( event, ui ) {}
});
    

Привяжите обработчик события к событию autocompletefocus:

$( ".selector" ).on( "autocompletefocus", function( event, ui ) {} );
    
open( event, ui ) autocompleteopen Срабатывает при открытии или обновлении меню подсказок.
  • event
    Тип: Event
  • ui
    Тип: Object

Примечание:uiОбъект пуст; он включён для согласованности с другими событиями.

Пример кода:

Инициализируйте автозаполнение с указанной функцией обратного вызова open:

$( ".selector" ).autocomplete({
  open: function( event, ui ) {}
});
    

Привяжите обработчик события к событию autocompleteopen:

$( ".selector" ).on( "autocompleteopen", function( event, ui ) {} );
    
response( event, ui ) autocompleteresponse Срабатывает после завершения поиска и до показа меню. Полезно для локальной обработки данных предложений, где пользовательскийsourceобратный вызов параметра не требуется. Это событие всегда срабатывает при завершении поиска, и оно срабатывает даже если меню не отображается, потому что поиск не вернул результатов или Autocomplete отключён.
  • event
    Тип: Event
  • ui
    Тип: Object
    • content
      Тип: Array
      Описание: Содержит данные ответа, и их можно изменить, чтобы изменить отображаемые результаты. Эти данные уже нормализованы, поэтому если вы изменяете данные, убедитесь, что каждый элемент содержитvalueиlabelсвойством.

Примеры кода:

Инициализируйте autocomplete с указанным обратным вызовом response:

$( ".selector" ).autocomplete({
  response: function( event, ui ) {}
});
    

Привяжите обработчик события к событию autocompleteresponse:

$( ".selector" ).on( "autocompleteresponse", function( event, ui ) {} );
    
select( event, ui ) autocompleteselect Срабатывает при выборе элемента из меню. Действие по умолчанию — заменить значение в текстовом поле значением выбранного элемента. Отмена этого события предотвращает обновление значения, но не предотвращает закрытие меню.
  • event
    Тип: Event
  • ui
    Тип: Object
    • item
      Тип: Object
      Описание: объект со свойствами выбранного элементаlabelиvalueсвойства.

Примеры кода:

Инициализируйте 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>

Другие расширения