SimpleAutocomplete — различия между версиями
Материал из YourcmcWiki
м (→Использование) |
м (→Использование) |
||
| Строка 19: | Строка 19: | ||
; input: Поле ввода, в которое будем подсказывать, либо DOM-объект, либо его ID. ID, кстати, всегда необходимо. | ; input: Поле ввода, в которое будем подсказывать, либо DOM-объект, либо его ID. ID, кстати, всегда необходимо. | ||
| − | ; dataLoader(hint, value): Функция, которая должна загрузить опции для подсказки и вызвать <tt>hint.replaceItems([ [ name, value ], [ name, value ], ... ])</tt>. | + | ; dataLoader(hint, value, more): Функция, которая должна загрузить опции для подсказки и вызвать <tt>hint.replaceItems([ [ name, value ], [ name, value ], ... ], more)</tt>. |
| + | ;* hint — объект автокомплита, на котором и надо вызывать replaceItems. | ||
| + | ;* value — введённая пользователем строка, на основе которой надо предоставлять подсказки. | ||
| + | ;* more — при использовании moreMarker «страница» подсказок, которую нужно загрузить (0 = первая страница). | ||
Необязательные параметры конструктора передаются в объекте <tt>params</tt>: | Необязательные параметры конструктора передаются в объекте <tt>params</tt>: | ||
; multipleDelimiter: Чтобы включить мультивыбор, передайте сюда разделитель (например ',' или ';'), который не может входить в выбираемые значения. Также они не могут включать пробелы в начале и конце. Значение поля ввода будет установлено равным значениям всех выбранных элементов, соединённым через данный разделитель и один пробел (например «a, b»). | ; multipleDelimiter: Чтобы включить мультивыбор, передайте сюда разделитель (например ',' или ';'), который не может входить в выбираемые значения. Также они не могут включать пробелы в начале и конце. Значение поля ввода будет установлено равным значениям всех выбранных элементов, соединённым через данный разделитель и один пробел (например «a, b»). | ||
| + | ; multipleListener(hint, index, item): | ||
; onChangeListener(hint, index): Функция, которая будет вызвана при изменении значения через данный автокомплит. <tt>index</tt> — номер элемента, выделение которого изменилось. Её нужно использовать вместо обычного события «onchange» на поле ввода. | ; onChangeListener(hint, index): Функция, которая будет вызвана при изменении значения через данный автокомплит. <tt>index</tt> — номер элемента, выделение которого изменилось. Её нужно использовать вместо обычного события «onchange» на поле ввода. | ||
; maxHeight: Максимальная высота выпадающего списка в пикселах. | ; maxHeight: Максимальная высота выпадающего списка в пикселах. | ||
; emptyText: Текст (HTML-код), который нужно показать, если dataLoader вернёт пустой массив. Если пуст или false (по умолчанию), то при отсутствии элементов подсказка будет скрыта. | ; emptyText: Текст (HTML-код), который нужно показать, если dataLoader вернёт пустой массив. Если пуст или false (по умолчанию), то при отсутствии элементов подсказка будет скрыта. | ||
| − | ; | + | ; prompt: HTML-код «пояснения», показываемого перед ''непустым'' списком опций. По умолчанию — не задан. |
; delay: Если установить в ненулевое целочисленное значение, то подсказки будут подгружаться с сервера не чаще, чем раз в delay миллисекунд. По умолчанию 300. | ; delay: Если установить в ненулевое целочисленное значение, то подсказки будут подгружаться с сервера не чаще, чем раз в delay миллисекунд. По умолчанию 300. | ||
| + | ; moreMarker: Если выведенный список подсказок ограничен, но пользователю хочется всё-таки иметь возможность просмотреть их все без ввода дополнительных символов, вы можете добавить в список элемент со специальным значением, равным moreMarker (по умолчанию <tt><nowiki>"#MORE"</nowiki></tt>) в конце списка, обработать параметр more в dataLoader’е (см. выше) и подгрузить дополнительные значения в список. | ||
Если в какой-то момент объект ''SimpleAutocomplete'' вам станет более не нужен, его можно уничтожить: | Если в какой-то момент объект ''SimpleAutocomplete'' вам станет более не нужен, его можно уничтожить: | ||
| Строка 36: | Строка 41: | ||
hint = null; | hint = null; | ||
</code-javascript> | </code-javascript> | ||
| + | |||
| + | При заданном multipleListener также можно включать/выключать (в смысле disable) элементы списка и руками указывать, выбраны ли они, | ||
| + | * При загрузке списка: <tt>hint.replaceItems([ [ name, value, disabled, checked ], ... ], more)</tt>. | ||
| + | * Отдельные элементы, после загрузки: <tt>hint.changeMultiItem(index, name, disabled, checked);</tt> | ||
== Демонстрация == | == Демонстрация == | ||
Версия 21:04, 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)
- 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;
При заданном multipleListener также можно включать/выключать (в смысле disable) элементы списка и руками указывать, выбраны ли они,
- При загрузке списка: hint.replaceItems([ [ name, value, disabled, checked ], ... ], more).
- Отдельные элементы, после загрузки: hint.changeMultiItem(index, name, disabled, checked);
Демонстрация
Обычная подсказка:
Мультивыбор с пояснением:
Мультивыбор с побочным эффектом:
FIXME
- В Firefox слой подсказки не уменьшается меньше минимальной высоты скроллбара из установленного стиля. То есть, скроллбар виден всегда, даже если там только 1 элемент, и бывает так, что элемент один, а под ним пустое место.
