typeahead standalone
v5.4.0
Быстрая полнофункциональная автономная библиотека автозаполнения.
? Основные моменты ?
Здесь вы найдете подробную документацию с живыми демонстрациями для typeahead-standalone.js .
Предварительный просмотр базового примера:
# you can install typeahead with npm
$ npm install --save typeahead-standalone
# Alternatively you can use Yarn
$ yarn add typeahead-standaloneЗатем включите библиотеку в свое приложение/страницу.
В качестве модуля,
// using ES6 modules
import typeahead from 'typeahead-standalone' ; // imports library (js)
import 'typeahead-standalone/dist/basic.css' ; // imports basic styles (css)
// using CommonJS modules
const typeahead = require ( 'typeahead-standalone' ) ;
require ( 'typeahead-standalone/dist/basic.css' ) ;В контексте браузера
<!-- Include the basic styles & the library -->
< link rel =" stylesheet " href =" ./node_modules/typeahead-standalone/dist/basic.css " />
< script src =" ./node_modules/typeahead-standalone/dist/typeahead-standalone.umd.js " > </ script >
<!-- Alternatively, you can use a CDN. For example, use jsdelivr to get the latest version -->
< link rel =" stylesheet " href =" https://cdn.jsdelivr.net/npm/typeahead-standalone/dist/basic.css " />
< script src =" https://cdn.jsdelivr.net/npm/typeahead-standalone " > </ script >
<!-- or use unpkg.com to get a specific version -->
< link rel =" stylesheet " href =" https://unpkg.com/[email protected]/dist/basic.css " />
< script src =" https://unpkg.com/[email protected]/dist/typeahead-standalone.umd.js " > </ script > Библиотека будет доступна как глобальный объект по адресу window.typeahead
Typeahead требует input элемент, к которому можно прикрепиться, и Data source (локальный/удаленный) для отображения предложений.
Вот очень простой пример (более сложные примеры см. в демо)
<!-- include the library -->
< script src =" ... " async > </ script >
<!-- Html markup -->
< input type =" search " id =" searchInput " autocomplete =" off " placeholder =" Search... " > // local Data
const colors = [ 'Grey' , 'Brown' , 'Black' , 'Blue' ] ;
// input element to attach to
const inputElement = document . getElementById ( "searchInput" ) ;
typeahead ( {
input : inputElement ,
source : {
local : colors ,
// prefetch: {...}
// remote: {...}
}
} ) ; Вы можете передать следующие параметры конфигурации typeahead-standalone :
| Параметр | Описание | По умолчанию |
|---|---|---|
input | Элемент ввода DOM должен быть передан с этим параметром, и typeahead прикрепится к этому полю. | - (Необходимый) |
source | Это источник данных, на основе которых будут рассчитываться предложения. Источник может быть локальным, предварительно выбранным или полученным из удаленной конечной точки. Подробности | - (Необходимый) |
minLength | Укажите минимальную продолжительность, при которой предложения должны появляться на экране. | 1 |
limit | Укажите максимальное количество предложений, которые должны отображаться. | 5 |
highlight | Соответствующие буквы из запроса выделяются в списке предложений. Для облегчения стилизации добавлен класс tt-highlight | true |
autoSelect | Если установлено значение true, предварительно выбирает первое отображаемое предложение. | false |
hint | Обновляет заполнитель ввода, чтобы он соответствовал первому совпавшему предложению. Для облегчения стилизации добавлен класс tt-hint | true |
diacritics | Флаг, позволяющий включить/отключить поиск с поддержкой языковых диакритических знаков (т. е. поиск путем преобразования символов с диакритическими знаками в их эквиваленты без акцента). | undefined |
classNames: Object | Объект classNames можно использовать для установки пользовательских классов для каждого элемента HTML, который внедряется в DOM. Подробности | undefined |
templates | Объект, содержащий шаблоны для верхнего и нижнего колонтитула, предложения, группы и состояния notFound. См. раздел шаблонов для разъяснений. | undefined |
preventSubmit | Если ваш элемент ввода используется внутри элемента формы, этот флаг позволяет предотвратить действие отправки по умолчанию при нажатии клавиши ENTER. | false |
onSubmit(event, selectedItem?) | Если вы хотите использовать ввод вне элемента формы, этот обработчик можно использовать для обработки/отправки входного значения. Запускается при нажатии клавиши ENTER. Первый параметр — это событие клавиатуры, а второй параметр — выбранный элемент или неопределенный, если ни один элемент не был выбран. | undefined |
display(selectedItem, event?) => string | Этот обратный вызов выполняется, когда пользователь выбирает элемент из предложенных. Текущее предложение/элемент передается как параметр и должно возвращать строку , которая устанавливается в качестве входного значения. Второе необязательное event параметра — это событие мыши/клавиатуры, которое можно использовать для отслеживания взаимодействия с пользователем или для аналитики. По умолчанию оно равно null . | Возвращает строковое представление выбранного элемента |
tokenizer?: (words: string) => string[] | Функция токенизатора используется для разделения поискового запроса и данных поиска по заданному символу(ам). Эта функция полезна, когда вы хотите найти слова с переносом или слова с определенным префиксом/суффиксом. | слова разделяются пробелами (новая строка, табуляция, пробелы) |
listScrollOptions?: ScrollIntoViewOptions | Позволяет точно контролировать поведение прокрутки большого списка предложений, требующих прокрутки. Эти параметры передаются в функцию scrollIntoView() . МДН Ссылка | { block: "nearest", inline: "nearest", behaviour: "auto"} |
retainFocus | Этот параметр полезен для управления фокусом при нажатии клавиши «Tab», когда список предложений открыт. Если этот параметр включен, он выбирает выделенный вариант и затем возвращает фокус на ввод поиска. Если этот параметр отключен, нажатие «Tab» выберет выделенный параметр и переместит фокус на следующий элемент в вашей форме, который можно фокусировать. | true |
hooks | Опция конфигурации перехватчиков полезна для выполнения произвольного кода в определенные моменты жизненного цикла typeahead. Подробности | неопределенный |
Это источник данных, из которого будут предоставляться предложения. Это ожидаемый формат исходного объекта.
source: {
local: [],
remote: {
url: 'https://remoteapi.com/%QUERY', // OR "url: (inputQuery: string) => `https://remoteapi.com/${inputQuery}`"
wildcard: '%QUERY',
debounce: 300 // optional, default => 200ms
requestOptions: {} // optional, default => undefined
},
prefetch: {
url: 'https://remoteapi.com/load-suggestions', // OR `url: () => string`
when: 'onFocus', // optional, default => 'onInit'
done: false, // optional, default => false
process: (items) => void, // optional, default => undefined
requestOptions: {} // optional, default => undefined
},
keys: ['...'], // optional (required when source => Object[])
groupKey: '...', // optional, default => undefined
identity: (item) => string, // optional (determines uniqueness of each suggestion)
transform: function (data) {
// modify source data if needed & return it
return data;
}
}
local источник данных используется, когда вы хотите предоставить предложения из локального источника, например переменной.prefetch используется, когда вы хотите заранее загрузить предложения из удаленной конечной точки. Вы должны указать параметр url , указывающий на конечную точку, которая будет возвращать предложения. Вы можете указать необязательный параметр when , который определяет, когда должен выполняться запрос предварительной выборки. По умолчанию он имеет значение onInit , что означает, что предложения будут предварительно загружены, как только будет инициализирован ввод текста. Вы можете установить для него значение onFocus , что приведет к предварительной загрузке предложений только тогда, когда пользователь фокусирует поле ввода поиска. Флаг done является необязательным и может использоваться для программного отключения запроса предварительной выборки. Его значение по умолчанию — false . Ему автоматически присваивается значение true при первой предварительной выборке данных (чтобы предотвратить множественные сетевые запросы). Если установить done: true , запрос предварительной выборки не будет выполняться. Примером использования этого является ситуация, когда вы используете localStorage для хранения предложений, но в localStorage уже были сохранены предложения ранее, что устраняет необходимость повторной предварительной выборки данных. Обратный вызов process(suggestions) не является обязательным. Он выполняется после выполнения запроса на предварительную выборку. Он получает преобразованные предложения в качестве параметра и в качестве примера может использоваться для хранения полученных предложений в localStorage для последующего использования.remote источник данных используется, когда вы хотите запросить удаленную конечную точку для получения данных.remote источника данных необходимо указать url и параметры wildcard . wildcard будет заменен строкой поиска при выполнении запроса.debounce используется для задержки выполнения http-запросов (в миллисекундах). Это необязательно и по умолчанию составляет 200 мс.GET .transform() , которая вызывается сразу после того, как конечная точка предварительной выборки/удаленная конечная точка возвращает ответ. Вы можете изменить ответ до того, как он будет обработан опережающим вводом.keys необходим, если источником данных является массив объектов. Первый ключ используется для определения того, какое свойство объекта следует использовать в качестве текста для отображения предложений. Например, предположим, что источник данных выглядит примерно так: /* Example Data source */
[
{ id : 1 , color : "Yellow" , meta : { colorCode : "YW" } } ,
{ id : 2 , color : "Green" , meta : { colorCode : "GN" } , shade : "Greenish" } ,
{ id : 3 , color : "Olive" , meta : { colorCode : "OV" } , shade : "Greenish" } ,
...
] Теперь, если мы хотим использовать текст, определенный в свойстве color , для отображения в качестве подсказок, тогда ключи должны включать цвет в качестве первого ключа. (т.е. keys: ["color"] ).
Если вы хотите добавить дополнительные свойства в индекс поиска, вы также можете указать эти свойства в массиве keys . Лучше всего это можно понять на примере. Давайте возьмем тот же пример источника данных, который показан выше. Что, если вы хотите искать цвета по другому свойству ( colorCode ), а не только по его цвету ? Для этого просто установите keys: ["color", "meta.colorCode"] . Если вы теперь ищете « YW », как и ожидалось, появится предложение «Желтый».
groupKey: "shade" , предложения будут сгруппированы по свойству " shade ". В этом примере цвета Зеленый и Оливковый появятся в группе « Зеленый » ( shade ), тогда как Желтый цвет не будет иметь группы. groupKey также поддерживает доступ к вложенным свойствам с использованием точечной записи. (пример — groupKey: "category.title" )identity() используется для определения уникальности каждого предложения. Он получает предложение в качестве параметра и должен вернуть строку, уникальную для данного предложения. Это необязательное свойство, и по умолчанию оно возвращает значение, связанное с первым ключом, keys[0] . Однако значение по умолчанию может работать не всегда. Например, рассмотрим следующий код: /* Example Data source of Songs */
[
{ title : "God is Good" , artist : "Don Moen" } ,
{ title : "God is Good" , artist : "Paul Wilbur" } ,
{ title : "God is Good" , artist : "Micheal Smith" } ,
{ title : "El Shaddai" , artist : "Amy Grant" } ,
...
] Предположим, что ключам присвоены keys: ["title"] . По умолчанию identity() использует первый ключ (т.е. заголовок ) для определения уникальности. Таким образом, если вы ищете God , вы найдете только 1 предложение, поскольку есть 3 песни с одинаковым title . Чтобы отобразить все три предложения с разными исполнителями, вам необходимо установить свойство identity так, чтобы оно возвращало уникальную строку:
identity ( item ) = > ` ${ item . title } ${ item . artist } ` ; Настоятельно рекомендуется установить параметр конфигурацииident identity() для возврата уникальной строки, если ваш источник данных представляет собой массив объектов.
Ознакомьтесь с живыми примерами для дальнейших разъяснений.
На данный момент доступен только 1 хук:
updateHits: async (resultSet, loader) => Promise<resultSet> , который выполняется непосредственно перед отображением результатов поиска пользователю и может использоваться для переопределения предложений, возвращаемых индексом поиска. (полезно для пользовательской сортировки, фильтрации, добавления или удаления результатов. Этот крючок представляет собой асинхронную функцию, позволяющую при необходимости выполнять запросы AJAX для получения новых результатов) // Example usage of "updateHits" hook
typeahead ( {
input : document . querySelector ( ".myInput" ) ,
source : {
local : [ ] ,
// ...
} ,
hooks : {
updateHits : async ( resultSet , loader ) => {
resultSet . hits . push ( { name : "new suggestion" } ) ; // add new suggestion
// resultSet.hits.filter( ... ); // filter the suggestions
// resultSet.hits.sort( ... ); // custom sort the suggestions
// resultSet.count = 5000; // to set the total results found
/*** You can also make an AJAX request to fetch results ***/
// loader(); // display the loader template
// const response = await fetch('https://example.com');
// const text = await response.text();
// resultSet.hits = text && JSON.parse(text);
// loader(false); // hide the loader template
// resultSet.updateSearchIndex = true; // updates search index if necessary. Default `false`
return resultSet ; // you must return the resultSet
} ,
} ,
templates : {
loader : ( ) => { ... } ,
}
} ) ; Некоторые базовые стили предоставляются с помощью опережающего ввода. Пользовательский интерфейс полностью зависит от вас и настраивается до пикселя. Вы можете использовать следующие классы для добавления/переопределения стилей.
typeahead-standalone .tt-input .tt-hint .tt-list . (Класс tt-hide добавляется, когда нет доступных предложений)tt-suggestion , и если предложение выбрано, то оно дополнительно имеет класс tt-selected .tt-highlight . Вы можете добавить свои собственные стили, указав родительский селектор .typeahead-standalone . Например, мы можем обновить цвет фона каждого предложения, как показано ниже:
/* set background color for each suggestion */
. typeahead-standalone . tt-list . tt-suggestion {
background-color : green;
} Чтобы переопределить стиль по умолчанию, установите параметр конфигурации className и используйте его в качестве селектора. Допустим, вы установили className: "my-typeahead" , а затем, чтобы переопределить стиль при наведении/выборе предложения, вы можете использовать:
/* override styles */
. typeahead-standalone . my-typeahead . tt-list . tt-suggestion : hover ,
. typeahead-standalone . my-typeahead . tt-list . tt-suggestion . tt-selected {
color : black;
background-color : white;
} Начиная с v4.0 , JS и CSS были разделены, что позволяет лучше контролировать стиль. Весь CSS можно получить либо из CDN, либо снизу и скопировать непосредственно в ваш проект, что позволит вам при необходимости отменить/переопределить любые стили.
/***** basic styles *****/
. typeahead-standalone {
position : relative;
text-align : left;
color : # 000 ;
}
. typeahead-standalone . tt-input {
z-index : 1 ;
background : transparent;
position : relative;
}
. typeahead-standalone . tt-hint {
position : absolute;
left : 0 ;
cursor : default;
user-select : none;
background : # fff ;
color : silver;
z-index : 0 ;
}
. typeahead-standalone . tt-list {
background : # fff ;
z-index : 1000 ;
box-sizing : border-box;
overflow : auto;
border : 1 px solid rgba ( 50 , 50 , 50 , 0.6 );
border-radius : 4 px ;
box-shadow : 0 px 10 px 30 px 0 px rgba ( 0 , 0 , 0 , 0.1 );
position : absolute;
max-height : 70 vh ;
}
. typeahead-standalone . tt-list . tt-hide {
display : none;
}
. typeahead-standalone . tt-list div [ class ^= "tt-" ] {
padding : 0 4 px ;
}
. typeahead-standalone . tt-list . tt-suggestion : hover ,
. typeahead-standalone . tt-list . tt-suggestion . tt-selected {
background : # 55acee ;
cursor : pointer;
}
. typeahead-standalone . tt-list . tt-suggestion . tt-highlight {
font-weight : 900 ;
}
. typeahead-standalone . tt-list . tt-group {
background : # eee ;
}Вы также можете использовать шаблоны, чтобы добавить верхний и нижний колонтитулы и дополнительно стилизовать каждое предложение.
Шаблоны можно использовать для настройки отображения списка. Их использование совершенно необязательно. На данный момент доступно 7 шаблонов:
templates: {
header : ( resultSet ) => '<h1>List of Countries</h1>' , /* Rendered at the top of the dataset */
footer : ( resultSet ) => '<div>See more</div>' , /* Rendered at the bottom of the dataset */
suggestion : ( item , resultSet ) => { /* Used to render a single suggestion */
return `<div class="custom-suggestion"> ${ item . label } </div>` ;
} ,
group : ( groupName , resultSet ) => { /* Used to render a group */
return `<div class="custom-group"> ${ groupName } </div>` ;
} ,
empty : ( resultSet ) => { /* Rendered when the input query is empty */
return `<div>Search for Colors...</div>` ;
// OR (to display some suggestions by default)
return [ { title : "France" } , { title : "Spain" } ] ;
}
loader : ( ) = > 'Loading...' , /* Rendered while awaiting data from a remote source */
notFound : ( resultSet ) => '<span>Nothing Found</span>' , /* Rendered if no suggestions are available */
} Как видно выше, каждый шаблон принимает обратный вызов, который должен вернуть string , которая позже интерпретируется как HTML. Шаблоны также получают параметр resultSet , имеющий структуру, показанную ниже.
resultSet = {
query : '...' , // the input query
hits : [ ... ] , // found suggestions
count : 0 , // the total suggestions found in the search index
limit : 5 , // the number of suggestions to show
wrapper : DOMElement , // the container DOM element
} Для облегчения стилизации каждый шаблон заключен в элемент div с соответствующим классом. т.е.
header => класс tt-headerfooter => класс tt-footersuggestion => класс tt-suggestiongroup => класс tt-grouploader => класс tt-loaderempty => класс tt-emptynotFound => класс tt-notFound Параметр конфигурации classNames просто позволяет вам заменить имена классов по умолчанию по вашему выбору.
Имена классов по умолчанию, используемые в опережающем вводе, следующие:
const classNames = {
wrapper : 'typeahead-standalone' , /* main container element */
input : 'tt-input' ,
hint : 'tt-hint' ,
highlight : 'tt-highlight' ,
list : 'tt-list' , /* container element for suggestions */
hide : 'tt-hide' ,
show : 'tt-show' ,
selected : 'tt-selected' ,
/* classes used within templates */
header : 'tt-header' ,
footer : 'tt-footer' ,
loader : 'tt-loader' ,
suggestion : 'tt-suggestion' ,
group : 'tt-group' ,
empty : 'tt-empty' ,
notFound : 'tt-notFound' ,
} ;Например, если вы хотите использовать другое имя класса для элемента ввода , вы можете инициализировать ввод текста следующим образом:
typeahead ( {
input : '...' ,
source : '...' ,
classNames : {
input : 'my-custom-input-class' // this class is used instead of tt-input
}
} ) ;typeahead.reset()typeahead.addToIndex()typeahead.destroy()reset(clearLocalSrc?: boolean) Сбрасывает экземпляр опережающего ввода в состояние, в котором он находился до любого взаимодействия с пользователем. Он удаляет все элементы из индекса поиска, кроме тех, которые были добавлены через локальный источник. Чтобы удалить абсолютно все элементы, функция принимает необязательный параметр, для которого должно быть установлено значение true . Reset() также очищает кэшированные удаленные запросы.
const instance = typeahead ( { /* options */ } ) ;
// clear search index except items added via Local source
instance . reset ( ) ;
// clears entire search index
instance . reset ( true ) ;Этот API полезен в ситуациях, когда вам необходимо сделать данные недействительными по истечении определенного времени.
addToIndex()Добавляет элементы в индекс поиска. Полезно, если вы хотите получить данные самостоятельно, а затем добавить их в индекс поиска. Это похоже на добавление элементов через локальный источник.
const instance = typeahead ( { /* options */ } ) ;
instance . reset ( true ) ; // or instance.reset();
instance . addToIndex ( [ 'Blue, Baige , Black' ] ) ; destroy()Уничтожает экземпляр опережающего ввода, очищает индекс поиска, удаляет все обработчики событий и очищает DOM. Может использоваться, если вы хотите отключить упреждающий ввод.
const instance = typeahead ( { /* options */ } ) ;
instance . destroy ( ) ;Вот небольшой глоссарий возможных кодов ошибок, с которыми можно столкнуться.
| Код | Описание |
|---|---|
| е01 | Отсутствует входной элемент DOM. |
| е02 | Отсутствует/неправильный источник предложений. Вы должны предоставить хотя бы один из трех возможных источников — локальный, упреждающую выборку или удаленный в ожидаемом исходном формате (Ссылка). |
| е03 | Отсутствующие ключи |
| е04 | Запрос предварительной загрузки не выполнен |
| е05 | Удаленный запрос не выполнен |
Хотите внести свой вклад в добавление новых функций и исправлений?
Узнайте больше о вкладе.
Посмотреть список изменений
Массачусетский технологический институт © DigitalFortress
