SimpleAutocomplete — различия между версиями

Материал из YourcmcWiki
Перейти к: навигация, поиск
м
м (Использование)
Строка 20: Строка 20:
 
; input: Поле ввода, в которое будем подсказывать, либо DOM-объект, либо его ID. ID, кстати, всегда необходимо.
 
; input: Поле ввода, в которое будем подсказывать, либо DOM-объект, либо его ID. ID, кстати, всегда необходимо.
 
; dataLoader(hint, value, more): Функция, которая должна загрузить опции для подсказки и вызвать <tt>hint.replaceItems([ [ name, value ], [ name, value ], ... ], more)</tt>.
 
; dataLoader(hint, value, more): Функция, которая должна загрузить опции для подсказки и вызвать <tt>hint.replaceItems([ [ name, value ], [ name, value ], ... ], more)</tt>.
;* hint — объект автокомплита, на котором и надо вызывать replaceItems.
+
:* hint — объект автокомплита, на котором и надо вызывать replaceItems.
;* value — введённая пользователем строка, на основе которой надо предоставлять подсказки.
+
:* value — введённая пользователем строка, на основе которой надо предоставлять подсказки.
;* more — при использовании moreMarker «страница» подсказок, которую нужно загрузить (0 = первая страница).
+
:* more — при использовании moreMarker «страница» подсказок, которую нужно загрузить (0 = первая страница).
  
 
Необязательные параметры конструктора передаются в объекте <tt>params</tt>:
 
Необязательные параметры конструктора передаются в объекте <tt>params</tt>:
  
 
; multipleDelimiter: Чтобы включить мультивыбор, передайте сюда разделитель (например ',' или ';'), который не может входить в выбираемые значения. Также они не могут включать пробелы в начале и конце. Значение поля ввода будет установлено равным значениям всех выбранных элементов, соединённым через данный разделитель и один пробел (например «a, b»).
 
; multipleDelimiter: Чтобы включить мультивыбор, передайте сюда разделитель (например ',' или ';'), который не может входить в выбираемые значения. Также они не могут включать пробелы в начале и конце. Значение поля ввода будет установлено равным значениям всех выбранных элементов, соединённым через данный разделитель и один пробел (например «a, b»).
; multipleListener(hint, index, item): Для «мультивыбора с побочным эффектом» — когда не хочется трогать значение поля ввода — можно передать в этот параметр callback, который будет реагировать на клики по элементам и где-то сохранять их статус. index — номер элемента, <tt>item = [ name, value, disabled, checked ]</tt>. <br />Также в этом режиме обретает смысл включение/выключение (enable/disable) элементов списка и указание их статуса. <br /> При загрузке списка: <tt>hint.replaceItems([ [ name, value, disabled, checked ], ... ], more)</tt>. <br /> Отдельные элементы, после загрузки: <tt>hint.changeMultiItem(index, name, disabled, checked);</tt>
+
; multipleListener(hint, index, item): Для «мультивыбора с побочным эффектом» — когда не хочется трогать значение поля ввода — можно передать в этот параметр callback, который будет реагировать на клики по элементам и где-то сохранять их статус. index — номер элемента, <tt>item = [ name, value, disabled, checked ]</tt>.
 +
: Также в этом режиме обретает смысл включение/выключение (enable/disable) элементов списка и указание их статуса при загрузке списка: <tt>hint.replaceItems([ [ name, value, disabled, checked ], ... ], more)</tt>.
 
; onChangeListener(hint, index): Функция, которая будет вызвана при изменении значения через данный автокомплит. <tt>index</tt> — номер элемента, выделение которого изменилось. Её нужно использовать вместо обычного события «onchange» на поле ввода.
 
; onChangeListener(hint, index): Функция, которая будет вызвана при изменении значения через данный автокомплит. <tt>index</tt> — номер элемента, выделение которого изменилось. Её нужно использовать вместо обычного события «onchange» на поле ввода.
 
; maxHeight: Максимальная высота выпадающего списка в пикселах.
 
; maxHeight: Максимальная высота выпадающего списка в пикселах.

Версия 21:15, 5 марта 2013

Простое автодополнение (autocomplete) в текстовых полях ввода. Поддерживает мультивыбор и управление с клавиатуры (вниз, вверх, enter = выбор).

Исходники: hinter.js, hinter.css.

Последнее обновление: 2014-09-04.

Использование

Сначала включите на страницу hinter.js и hinter.css.

Для создания экземпляра SimpleAutocomplete используйте следующий JS-код:

var hint = new SimpleAutocomplete(input, dataLoader, params);

Обязательные параметры конструктора:

input
Поле ввода, в которое будем подсказывать, либо DOM-объект, либо его ID. ID, кстати, всегда необходимо.
dataLoader(hint, value, more)
Функция, которая должна загрузить опции для подсказки и вызвать hint.replaceItems([ [ name, value ], [ name, value ], ... ], more).
  • hint — объект автокомплита, на котором и надо вызывать replaceItems.
  • value — введённая пользователем строка, на основе которой надо предоставлять подсказки.
  • more — при использовании moreMarker «страница» подсказок, которую нужно загрузить (0 = первая страница).

Необязательные параметры конструктора передаются в объекте params:

multipleDelimiter
Чтобы включить мультивыбор, передайте сюда разделитель (например ',' или ';'), который не может входить в выбираемые значения. Также они не могут включать пробелы в начале и конце. Значение поля ввода будет установлено равным значениям всех выбранных элементов, соединённым через данный разделитель и один пробел (например «a, b»).
multipleListener(hint, index, item)
Для «мультивыбора с побочным эффектом» — когда не хочется трогать значение поля ввода — можно передать в этот параметр callback, который будет реагировать на клики по элементам и где-то сохранять их статус. index — номер элемента, item = [ name, value, disabled, checked ].
Также в этом режиме обретает смысл включение/выключение (enable/disable) элементов списка и указание их статуса при загрузке списка: hint.replaceItems([ [ name, value, disabled, checked ], ... ], more).
onChangeListener(hint, index)
Функция, которая будет вызвана при изменении значения через данный автокомплит. index — номер элемента, выделение которого изменилось. Её нужно использовать вместо обычного события «onchange» на поле ввода.
maxHeight
Максимальная высота выпадающего списка в пикселах.
emptyText
Текст (HTML-код), который нужно показать, если dataLoader вернёт пустой массив. Если пуст или false (по умолчанию), то при отсутствии элементов подсказка будет скрыта.
prompt
HTML-код «пояснения», показываемого перед непустым списком опций. По умолчанию — не задан.
delay
Если установить в ненулевое целочисленное значение, то подсказки будут подгружаться с сервера не чаще, чем раз в delay миллисекунд. По умолчанию 300.
moreMarker
Если выведенный список подсказок ограничен, но пользователю хочется всё-таки иметь возможность просмотреть их все без ввода дополнительных символов, вы можете добавить в список элемент со специальным значением, равным moreMarker (по умолчанию "#MORE") в конце списка, обработать параметр more в dataLoader’е (см. выше) и подгрузить дополнительные значения в список.

Если в какой-то момент объект SimpleAutocomplete вам станет более не нужен, его можно уничтожить:

hint.remove();
hint = null;

Демонстрация

Обычная подсказка:

Мультивыбор с пояснением:

Мультивыбор с побочным эффектом:

FIXME

  • В Firefox слой подсказки не уменьшается меньше минимальной высоты скроллбара из установленного стиля. То есть, скроллбар виден всегда, даже если там только 1 элемент, и бывает так, что элемент один, а под ним пустое место.