Russian | English
React компонент для использования API сервиса DaData, реализованный в виде поля ввода с выпадающим списком загруженных с сервиса "подсказок", запрашиваемых и уточняющихся по мере пользовательского ввода. Компонент предоставлет удобные средства навигации и управления с клавиатуры в дополнение к возможности выбора мышью.
в верхней части скринкаста отображаются клавиатурные нажатия выведенные при помощи keycastr приложения для MacOS
DatData сервис является shareware (т.е. условно-бесплатный), для его использования необходим токен (персональный или для организации). Для персонального использования необходимо зарегестрировать Account, ваш персональный токен позволяет осуществлять не более 10000 запросов к API в сутки.
npm install react-dadata-boximport ReactDadataBox from 'react-dadata-box';
// ...
<ReactDadataBox token="API_KEY" query="Москва" />
allowClear?: boolean;определяет отображение элемента UI для очищения выбранного значения (при 'очистке' вызываются соотв. события изменения значения)
autocomplete?: 'on' | 'off';значение свойства 'autocomplete' передаваемого в поле ввода
Функция принимающая в качестве аргумента список подсказок, которая возвращающает компонент (или массив компонентов) для определения 'произвольных действий' (custom actions) которые размещаются обособленной отдельной группой в конце выпадающего списка подсказок.
в версии v1.3.4 вариант определения как 'React.ReactNode' упразднен в определении типов
насиная с версии v1.3.5 вариант определения как 'React.ReactNode' будет упразднен технически
// {ResponseType<T>} где 'T' это один из FetchType (значение передаваемое в пропс 'type'):
// {AddressQueryMode} 'address' | {PartyQueryMode} 'party' | {BankQueryMode} |
// {EmailQueryMode} 'email' | {FioQueryMode} 'fio' | {FmsUnitQueryMode} 'fms_unit';
// это определяет типизацию структуры соотв. ответа от DaData по специфическому type
customActions?: ((suggestions: SpecificQueryModeResponse<T>[]) => React.ReactNode);at versions < v1.3.4
// {DadataSuggestion} всегда типизируется как объект возвращаемый при запросе 'address'
customActions?: ((suggestions: DadataSuggestion[]) => React.ReactNode) | React.ReactNode;пользовательская стилизация для встроенных компонентов: выпадающий список, отдельно взятая подсказка, помощь по управлению, произвольное действие Объект ключами которого выступают встроенные css классы для соответствующих встроенных компонентов, а в качестве занчения может быть установлена строка которая будет использована как дополнительное имя класса css, или объект с описанием стилей который будет передан в style свойство соответвующего react примитива.
customStyles?: {
'react-dadata__custom-action'?: string | React.CSSProperties;
'react-dadata__suggestion'?: string | React.CSSProperties;
'react-dadata__suggestion-note'?: string | React.CSSProperties;
'react-dadata__suggestions'?: string | React.CSSProperties;
}пользовательский URI для запроса сервиса DaData (если он расположен за прокси сервером или развернут локально в собственной инфраструктуре). Может быть строкой, в таком случае воспринимается как путь до расположения корня сервиса DaData (путь к конкретному вызову API будет добавляться автоматически), так же может быть установлен в качестве объекта с полями 'host' и/или 'api', воспринимаемых как путь к корню расположения сервиса и подмена пути вызова API, соответственно.
customEndpoint?: string | { host?: string; api?: string };
{
host: 'https://suggestions.dadata.ru',
api: 'suggestions/api/4_1/rs/suggest'
}функция принимающая аргументом объект (свойства передаваемые во встроенный input), возвращающая пользовательскую реализацию input компонента или другой компонент реализующий схожий интерфейс.
interface BaseInputProps<T = HTMLInputElement> {
autoComplete: boolean | 'off';
className: string;
onBlur: React.FocusEventHandler<T>;
onChange: React.ChangeEventHandler<T>;
onFocus: React.FocusEventHandler<T>;
onKeyDown: React.KeyboardEventHandler<T>;
placeholder: string;
value: string;
}
...
customInput?: (props: BaseInputProps) => React.ReactNode;
задержка перед запросом данных с сервиса во время непрерывного пользовательского ввода (debounce) в милисекундах
debounce?: number;обработчик события выбора подсказки пользователем (клик по элементу в списке или Enter для элемента который в данный момент выделен), принимает объект отражающий выбранную 'подсказку' в качестве аргумента
onChange?: (suggestion: DadataSuggestion) => void;обработчик события вызываемого в случаях когда по текущему запросу пользователя сервис не возвращает подсказок, принимает в качестве аргумента текущую строку запроса.
onIdleOut?: (query: string) => void;патч-объект или функция возвращающая патч-объект, объединяемый с сформированным автоматически объектом нагрузки (payload) для сервиса DaData. Таким образом можно формировать запросы со сложной фильтрацией и использовать прочие возможности предоставляемые API сервиса (не реализованные в интерфейсе компонента)
interface BasePayload {
query: string;
count?: number;
}
...
object | ((payload: BasePayload) => BasePayload & object);значение свойства 'placeholder' передаваемого в поле ввода
placeholder?: string;непосредственно строка запроса для сервиса DaData (query свойство в payload)
query?: string;
определяет отображение "подсказки" по управлению с клавиатуры (отображаемую вверху выпадающего списка)
showNote?: boolean;специальная строка запроса (не отображаемая в поле ввода) определяющая набор запрашиваемых значений, если основная строка поиска не установлена или пуста (если основная строка поиска установлена - значение этого свойства игнорируется)
silentQuery?: string;
функция которрая может быть использована для автоматического выбора предварительно запрошенной подсказки (если были установлены query или silentQuery) она принимает список полученных подсказок, и если она возвращает индекс выбранной подсказки - она будет выбрана (все обработчики выбора будут вызваны, так же как и для выбора пользователя)
silentInit?: (suggestions: DadataSuggestion[]) => number | undefined;
авторизационный токен сервиса DaData
token: string;тип запрашиваемых "подсказок" (в терминологии сервиса DaData): 'address' (адреса), 'bank' (банки), 'email' (электронная почта), 'fio' (ФИО + определение пола), 'fms_unit' (отделение выдавшее паспорт РФ)
type?: 'address' | 'party' | 'bank' | 'email' | 'fio' | 'fms_unit';
'address' является значение по умолчанию - и не требует явной установки
// н/п если мы используем сервис 'party'
import { PartyResponseType } from 'react-dadata-box';
...
// после установки 'party' как дженерик параметра компонента - обработчики такие как 'onChange' начинают типизироваться соотв.
// выводится тип (suggestion: PartyResponseType) => void в данном примере
<ReactDadataBox<'party'>
token={testToken}
type='party'
onChange={(suggestion: PartyResponseType) => setSample2(suggestion)}
customActions={(suggestions) =>
!suggestions.length && (
<a href=" " onClick={idleAction}>
произвольное действие
</a>
)
}
/>экспортируемые встроенные типы описывающие структуры ответа соответственно строке типа:
| type param | built-in type |
|---|---|
| 'address' | AddressResponseType (default) |
| 'party' | PartyResponseType |
| 'bank' | BankResponseType |
| 'email' | EmailResponseType |
| 'fio' | FioResponseType |
| 'fms_unit' | FmsUnitResponseType |
свойство определяющее принудительное раскрытие списка подсказок (преимущественно необходимо для удобства отладки/разработки н/п customActions)
forceOpenList?: boolean;