Виджет для сервиса подсказок DaData.ru.
- Установка
- Использование
- Параметры
- Коллбэки
- События
- Методы
- Гранулярные подсказки
- Вспомогательные функции
- Использование с TypeScript
- Примеры использования
npm install @dadata/suggestionsПодключение стилей:
@import "@dadata/suggestions/styles";
.suggestions-input {
/* можно кастомизировать */
}Чтобы подключить подсказки к текстовому полю на странице, его нужно передать в метод createSuggestions:
import { createSuggestions } from "@dadata/suggestions";
const suggestions = createSuggestions(input, options);В качестве второго параметра виджет принимает объект с опциями и коллбэками. Все параметры опциональные, исключая параметр type (тип подсказок).
Тип подсказок. Обязательный.
Тип: "name" | "address" | "bank" | "email" | "party" | string
API-ключ. Обязателен для пользователей «Дадаты».
Тип: string
По умолчанию: не задано.
Минимальная длина текста, после которой включаются подсказки.
Тип: number
По умолчанию: 1
Период ожидания перед отправкой запроса на сервер подсказок, в миллисекундах. Позволяет не перегружать сервер запросами, если пользователь очень быстро печатает.
Тип: number
По умолчанию: 100
Автоматически выбирать первую подсказку в списке.
Тип: boolean
По умолчанию: false
Поясняющий текст, который показывается в выпадающем списке над подсказками. При hint=false текст показываться не будет.
Тип: string | false
По умолчанию: "Выберите вариант или продолжите ввод"
Поясняющий текст, который показывается, если для введённого запроса ничего не найдено.
Текст зависит от типа подсказок. При noSuggestionsHint=false текст показываться не будет.
Тип: string | false
По умолчанию: "Неизвестное значение"
Обогащать подсказку при выборе (если обогащение возможно в зависимости от типа подсказок). Обогащение производится дополнительным запросом на сервер подсказок.
Тип: boolean
По умолчанию: true
Дополнительные параметры для передачи с запросом на сервер подсказок.
Может быть или в виде объекта с параметрами, или функцией, принимающей запрос query и возвращающей объект параметров.
Тип:
Record<string, unknown>
| (query: string) =>
Record<string, unknown>По умолчанию: не задано.
Базовый URL сервера подсказок.
Тип: string
По умолчанию: https://suggestions.dadata.ru/suggestions/api/4_1/rs
Полный url для запроса подсказок. Если не передан, то конструируется на основе serviceUrl:
{serviceUrl}/{method}/{type}
Тип: string
По умолчанию: не задано.
Дополнительные HTTP-заголовки, которые необходимо передать на сервер. Может быть или в виде объекта с заголовками, или функцией, возвращающей этот объект.
Тип: Record<string, string> | (() => Record<string, string>)
По умолчанию: не задано.
Таймаут для запросов к серверу подсказок в миллисекундах. Если запрос не успевает выполниться за указанное время, то будет отменен.
Тип: number
По умолчанию: 3000
Идентификатор в партнерской программе.
Тип: string
По умолчанию: не задано.
Предотвращает отправку запросов к серверу, если по предыдущему запросу не было найдено подсказок. Например, если по запросу "мос" не было подсказок, то запрос "моск" не будет отправлен.
Тип: boolean
По умолчанию: false
Отключает кэширование ответов сервера.
Тип: boolean
По умолчанию: false
Для подсказок по адресам (type=address), банкам (type=bank) и организациям (type=party).
Определяет местоположение по IP и устанавливает его в качестве приоритетного при поиске подсказок (locations_boost).
Если в параметрах передан собственный параметр locations_boost - перезаписывает его.
Тип: boolean
По умолчанию: true
Для подсказок по email (type=email).
Включает подсказки по локальной (до символа @) части email-адреса.
Тип: boolean
По умолчанию: true
Максимальная ширина экрана в px, при которой будет применен вид, адаптированный для мобильных устройств.
Тип: number
По умолчанию: 600
Время в миллисекундах, на которое будет отложено очищение списка подсказок при закрытии.
Позволяет реализовать анимацию закрытия списка. Открытый список с подсказками получает css-класс suggestions-wrapper--active, при закрытии активный класс удаляется, и по истечению closeDelay список очищается.
Тип: number
По умолчанию: не задано.
Прокручивать текстовое поле к верхней границе экрана при фокусе. Если настройка включена, действует только на мобильных устройствах.
Тип: boolean
По умолчанию: false
Предотвратить поведение по умолчанию при нажатии Tab в текстовом поле.
Тип: boolean
По умолчанию: false
Автоматически подставлять подходящую подсказку из списка, когда текстовое поле теряет фокус.
Тип: boolean
По умолчанию: true
Автоматически подставлять подходящую подсказку из списка при нажатии на Enter.
Тип: boolean
По умолчанию: true
Автоматически подставлять подходящую подсказку из списка при нажатии на пробел.
Тип: boolean
По умолчанию: false
В объекте options помимо параметров виджета можно передать коллбэки (функции-обработчики для событий, происходящих в работе виджета). Все коллбэки опциональные, this привязано к input-элементу.
Вызывается перед отправкой запроса к серверу подсказок. Здесь можно модифицировать параметры (модифицировать аргумент params) или вернуть false чтобы предотвратить запрос.
(params: Record<string, unknown>) => void | false;Вызывается, если сервер вернул ошибку.
(
query: string | null,
res: Response | undefined,
textStatus: string,
errorThrown: string
) => void;Вызывается, когда подсказки получены и проверен их формат. Здесь их можно отсортировать или отфильтровать перед дальнейшей обработкой.
В suggestions передается массив полученных подсказок. Можно изменять непосредственно этот массив, либо вернуть новый массив.
(suggestions: Suggestion[]) => Suggestion[] | void;Вызывается при получении ответа от сервера и содержит финальный список подсказок (вызывается после onSuggestionsFetch). В suggestions передается массив полученных подсказок.
(query: string, suggestions: Suggestion[]) => void;Вызывается при выборе подсказки (как при выборе пользователя, так и при автоматическом).
Аргумент changed показывает, было ли реально выбрано новое значение (true), или только обогащено текущее (false), т.е. когда suggestion.value осталось прежним, а только обновились поля в suggestion.data
(suggestion: Suggestion, changed: boolean) => void;Вызывается, пользователь нажал ENTER или input-элемент потерял фокус, а подходящей подсказки нет.
(query: string) => void;Вызывается при сбросе выбранной раньше подсказки после изменения значения в текстовом поле.
(suggestion: Suggestion) => void;Вызывается перед показом выпадающего списка подсказок. В аргументе container получает html-элемент контейнера, в котором будет отображен список подсказок.
(container: HTMLElement) => void;Преобразование объекта подсказки перед ее отображением в списке. Позволяет сохранить стандартное форматирование подсказки в списке, но изменить отображаемые данные. Не сохраняет изменения в оригинальной подсказке (изменения применяются только для отображения).
(suggestion: Suggestion, query: string) => Suggestion;Форматирование подсказки перед ее отображением в списке. Возвращает строку (обычный текст или html-разметка), которая будет выведена в списке подсказок как есть.
(
value: string,
currentValue: string,
suggestion: Suggestion,
options: { unformattableTokens: string[] }
) => string;Возвращает строку для вставки в поле ввода при выборе подсказки. Заменяет suggestion.value на переданное значение.
Если возвращает null - будет использовано стандартное значение подсказки.
(suggestion: Suggestion) => string | null;Виджет вызывает события (CustomEvent) на текстовом поле, к которому он подключен, подписаться на них можно с помощью метода addEventListener
Список подсказок очищен через метод clear().
Параметры в event.detail: нет.
Установлена подсказка через метод setSuggestion().
Параметры в event.detail: нет.
Восстановлен объект подсказки через метод fixData().
Параметры в event.detail:
{
suggestion: Suggestion;
}Виджет удален через метод dispose().
Параметры в event.detail: нет.
Сброшена ранее сохраненная подсказка (вызывается аналогично с коллбэком onInvalidateSelection).
Параметры в event.detail:
{
suggestion: Suggestion;
}Выбрана подсказка из списка (вызывается аналогично с коллбэком onSelect).
Параметры в event.detail:
{
suggestion: Suggestion;
suggestionChanged: boolean;
}Нет подходящей подсказки для выбора (вызывается аналогично с коллбэком onSelectNothing).
Параметры в event.detail:
{
query: string;
}При подключении подсказок к текстовому полю с помощью метода createSuggestions возвращается объект с методами управления виджетом:
Очищает кэш запросов, список подсказок и значение в текстовом поле.
() => void;Очищает только кэш запросов.
() => void;Отключает виджет.
() => void;Включает виджет.
() => void;Удаляет виджет.
() => void;Прячет список подсказок.
() => void;Показывает список подсказок.
() => void;Устанавливает параметры и коллбеки виджета.
(newOptions: Partial<Options>) => void;Возвращает текущие опции виджета.
() => void;Запрашивает подсказку по переданному значению query и выбирает ее. Объект подсказки возвращается асинхронно в событии suggestions-fixdata на текстовом поле.
(query: string) => void;Запоминает переданный объект подсказки и устанавливает его значение в поле.
(suggestion: Suggestion) => void;Возвращает объект выбранной подсказки.
() => Suggestion | null;Возвращает индекс выбранной подсказки.
() => number;Возвращает массив подсказок.
() => Suggestion[];Возвращает input-элемент, к которому подключены подсказки.
() => HTMLInputElement;Возвращает строковое значение выбранной подсказки (текущее значение input-элемента).
() => string;Возвращает адрес, определенный через геолокацию.
() => Promise<Suggestion | null>;Для подсказок по адресам (type=address) возможна работа виджета в гранулярном режиме (адрес по частям в разных полях). Для этого в качестве третьего аргумента можно передать родительский экземпляр подсказок, который будет ограничивать подсказки в текущем поле:
import { createSuggestions } from "@dadata/suggestions";
const regionInput = document.getElementById("region");
const cityInput = document.getElementById("city");
const regionOptions = {
type: "address",
params: { from_bound: { value: "region" }, to_bound: { value: "region" } },
};
const cityOptions = {
type: "address",
params: { from_bound: { value: "city" }, to_bound: { value: "city" } },
};
const regionSuggs = createSuggestions(region, regionOptions);
// подсказки по городам будут ограничены значением в поле региона
const citySuggs = createSuggestions(region, cityOptions, regionSuggs);Помимо основного метода createSuggestions виджет экспортирует вспомогательные функции getBoundedValue и getLocation.
Возвращает строковое значение подсказки в указанных границах bounds для подсказок по адресам:
interface Bounds {
from_bound: { value: string };
to_bound: { value: string };
}
interface Options {
bounds: Bounds;
suggestion: Suggestion;
type: "address";
}
type getBoundedValue = (options: Options) => string;import { getBoundedValue, createSuggestions } from "@dadata/suggestions";
const bounds = {
from_bound: { value: "region" },
to_bound: { value: "city" },
};
const suggestions = createSuggestions(input, {
type: "address",
formatSelected(suggestion) {
// вернет значение подсказки от региона до города
// в соответствии с переданными границами bounds
return getBoundedValue(bounds, suggestion, "address");
},
});Возвращает текущую геолокацию по IP:
interface API_OPTIONS {
url?: string;
headers?: Record<string, string> | (() => Record<string, string>);
token?: string;
serviceUrl?: string;
partner?: string;
timeout?: number;
}
type getLocation = (options?: API_OPTIONS) => Promise<Suggestion | null>;import { getLocation } from "@dadata/suggestions";
const token = /* */;
getLocation({ token }).then((location) => {
if (location) console.log(location.data.city);
})Виджет включает в себя декларации типов, которые должны работать из коробки
import type { Options, Suggestion, SuggestionsType } from "@dadata/suggestions";
const options: Options = {};Объект подсказки - это опциональный generic, по умолчанию типизирован без детализации объекта в поле data:
type AnyData = { [K: string]: any };
interface Suggestion<T = AnyData> {
value: string;
unrestricted_value: string;
data: T;
}Передать собственный тип для подсказок можно при инициализации виджета, и этот тип будет распространен на все объекты подсказок в коллбэках и методах этого экземпляра.
interface AddressSuggestion {
postal_code: string | null;
kladr_id: string | null;
...
history_values: string[] | null;
}
const input = document.getElementById("address") as HTMLInputElement;
const suggestions = createSuggestions<AddressSuggestion>(input, {
type: "address",
onSelect(suggestion) { // suggestion is Suggestion<AddressSuggestion>
console.log(suggestion);
}
});
suggestions.getSuggestions(); // вернет Suggestion<AddressSuggestion>[]При изменении опций виджета можно передать новый тип, если нужно на лету изменить тип подсказок:
const suggestions = createSuggestions<AddressSuggestion>(input, options);
suggestions.setOptions<NameSuggestion>({
type: "name",
onSelect(suggestion) {
// suggestion is Suggestion<NameSuggestion>
console.log(suggestion);
},
});Методы getSelection, getSuggestions и getOptions - тоже позволяют изменить тип подсказки в возвращаемом значении:
const suggestions = createSuggestions<AddressSuggestion>(input, options);
suggestions.getSelection<NameSuggestion>(); // Suggestion<NameSuggestion>
suggestions.getSuggestions<EmailSuggestion>(); // Suggestion<EmailSuggestion>[]
suggestions.getOptions<PartySuggestion>(); // Options<PartySuggestion>Все примеры собраны на странице Как сделать что угодно в Подсказках.