@dadata/suggestions

Виджет для сервиса подсказок DaData.ru.

- Установка
- Использование
- Параметры
- Коллбэки
- События
- Методы
- Гранулярные подсказки
- Вспомогательные функции
- Использование с TypeScript
- Примеры использования

Установка

``bash
npm install @dadata/suggestions
`

Подключение стилей:

`css
@import "@dadata/suggestions/styles";

.suggestions-input {
/ можно кастомизировать /
}
`

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

Чтобы подключить подсказки к текстовому полю на странице, его нужно передать в метод createSuggestions:

`js
import { createSuggestions } from "@dadata/suggestions";

const suggestions = createSuggestions(input, options);
`

В качестве второго параметра виджет принимает объект с опциями и коллбэками. Все параметры опциональные, исключая параметр type (тип подсказок).

Параметры

$3

#### type

Тип подсказок. Обязательный.

Тип: "name" | "address" | "bank" | "email" | "party" | string

#### token

API-ключ. Обязателен для пользователей «Дадаты».

Тип: string

По умолчанию: не задано.

$3

#### minChars

Минимальная длина текста, после которой включаются подсказки.

Тип: number

По умолчанию: 1

#### deferRequestBy


Период ожидания перед отправкой запроса на сервер подсказок, в миллисекундах.
Позволяет не перегружать сервер запросами, если пользователь очень быстро печатает.

Тип: number

По умолчанию: 100

#### autoSelectFirst

Автоматически выбирать первую подсказку в списке.

Тип: boolean

По умолчанию: false

#### hint

Поясняющий текст, который показывается в выпадающем списке над подсказками. При hint=false текст показываться не будет.

Тип: string | false

По умолчанию: "Выберите вариант или продолжите ввод"

#### noSuggestionsHint

Поясняющий текст, который показывается, если для введённого запроса ничего не найдено.
Текст зависит от типа подсказок. При noSuggestionsHint=false текст показываться не будет.

Тип: string | false

По умолчанию: "Неизвестное значение"

#### enrichmentEnabled

Обогащать подсказку при выборе (если обогащение возможно в зависимости от типа подсказок).
Обогащение производится дополнительным запросом на сервер подсказок.

Тип: boolean

По умолчанию: true

#### params

Дополнительные параметры для передачи с запросом на сервер подсказок.
Может быть или в виде объекта с параметрами, или функцией, принимающей запрос query и возвращающей объект параметров.

Тип:

`ts
Record

| (query: string) =>
Record
`

По умолчанию: не задано.

$3

#### serviceUrl

Базовый URL сервера подсказок.

Тип: string

По умолчанию: https://suggestions.dadata.ru/suggestions/api/4_1/rs

#### url

Полный url для запроса подсказок. Если не передан, то конструируется на основе serviceUrl:

`text
{serviceUrl}/{method}/{type}
`

Тип: string

По умолчанию: не задано.

#### headers

Дополнительные HTTP-заголовки, которые необходимо передать на сервер.
Может быть или в виде объекта с заголовками, или функцией, возвращающей этот объект.

Тип: Record | (() => Record)

По умолчанию: не задано.

#### timeout

Таймаут для запросов к серверу подсказок в миллисекундах.
Если запрос не успевает выполниться за указанное время, то будет отменен.

Тип: number

По умолчанию: 3000

#### partner

Идентификатор в партнерской программе.

Тип: string

По умолчанию: не задано.

#### preventBadQueries

Предотвращает отправку запросов к серверу, если по предыдущему запросу не было найдено подсказок. Например, если по запросу "мос" не было подсказок, то запрос "моск" не будет отправлен.

Тип: boolean

По умолчанию: false

#### noCache

Отключает кэширование ответов сервера.

Тип: boolean

По умолчанию: false

$3

#### geolocation

Для подсказок по адресам (type=address), банкам (type=bank) и организациям (type=party).
Определяет местоположение по IP и устанавливает его в качестве приоритетного при поиске подсказок (locations_boost).

Если в параметрах передан собственный параметр locations_boost - перезаписывает его.

Тип: boolean

По умолчанию: true

#### suggest_local

Для подсказок по email (type=email).
Включает подсказки по локальной (до символа @) части email-адреса.

Тип: boolean

По умолчанию: true

$3

#### mobileWidth

Максимальная ширина экрана в px, при которой будет применен вид, адаптированный для мобильных устройств.

Тип: number

По умолчанию: 600

#### closeDelay

Время в миллисекундах, на которое будет отложено очищение списка подсказок при закрытии.

Позволяет реализовать анимацию закрытия списка. Открытый список с подсказками получает css-класс suggestions-wrapper--active, при закрытии активный класс удаляется, и по истечению closeDelay список очищается.

Тип: number

По умолчанию: не задано.

#### scrollOnFocus

Прокручивать текстовое поле к верхней границе экрана при фокусе. Если настройка включена, действует только на мобильных устройствах.

Тип: boolean

По умолчанию: false

#### tabDisabled

Предотвратить поведение по умолчанию при нажатии Tab в текстовом поле.

Тип: boolean

По умолчанию: false

#### triggerSelectOnBlur

Автоматически подставлять подходящую подсказку из списка, когда текстовое поле теряет фокус.

Тип: boolean

По умолчанию: true

#### triggerSelectOnEnter

Автоматически подставлять подходящую подсказку из списка при нажатии на Enter.

Тип: boolean

По умолчанию: true

#### triggerSelectOnSpace

Автоматически подставлять подходящую подсказку из списка при нажатии на пробел.

Тип: boolean

По умолчанию: false

Коллбэки

В объекте options помимо параметров виджета можно передать коллбэки (функции-обработчики для событий, происходящих в работе виджета). Все коллбэки опциональные, this привязано к input-элементу.

$3

Вызывается перед отправкой запроса к серверу подсказок. Здесь можно модифицировать параметры (модифицировать аргумент params) или вернуть false чтобы предотвратить запрос.

`ts
(params: Record) => void | false;
`

$3

Вызывается, если сервер вернул ошибку.

`ts
(
query: string | null,
res: Response | undefined,
textStatus: string,
errorThrown: string
) => void;
`

$3

Вызывается, когда подсказки получены и проверен их формат. Здесь их можно отсортировать или отфильтровать перед дальнейшей обработкой.

В suggestions передается массив полученных подсказок. Можно изменять непосредственно этот массив, либо вернуть новый массив.

`ts
(suggestions: Suggestion[]) => Suggestion[] | void;
`

$3

Вызывается при получении ответа от сервера и содержит финальный список подсказок (вызывается после onSuggestionsFetch). В suggestions передается массив полученных подсказок.

`ts
(query: string, suggestions: Suggestion[]) => void;
`

$3

Вызывается при выборе подсказки (как при выборе пользователя, так и при автоматическом).

Аргумент changed показывает, было ли реально выбрано новое значение (true), или только обогащено текущее (false), т.е. когда suggestion.value осталось прежним, а только обновились поля в suggestion.data

`ts
(suggestion: Suggestion, changed: boolean) => void;
`

$3

Вызывается, пользователь нажал ENTER или input-элемент потерял фокус, а подходящей подсказки нет.

`ts
(query: string) => void;
`

$3

Вызывается при сбросе выбранной раньше подсказки после изменения значения в текстовом поле.

`ts
(suggestion: Suggestion) => void;
`

$3

Вызывается перед показом выпадающего списка подсказок. В аргументе container получает html-элемент контейнера, в котором будет отображен список подсказок.

`ts
(container: HTMLElement) => void;
`

$3

Преобразование объекта подсказки перед ее отображением в списке. Позволяет сохранить стандартное форматирование подсказки в списке, но изменить отображаемые данные. Не сохраняет изменения в оригинальной подсказке (изменения применяются только для отображения).

`ts
(suggestion: Suggestion, query: string) => Suggestion;
`

$3

Форматирование подсказки перед ее отображением в списке. Возвращает строку (обычный текст или html-разметка), которая будет выведена в списке подсказок как есть.

`ts
(
value: string,
currentValue: string,
suggestion: Suggestion,
options: { unformattableTokens: string[] }
) => string;
`

$3

Возвращает строку для вставки в поле ввода при выборе подсказки. Заменяет suggestion.value на переданное значение.

Если возвращает null - будет использовано стандартное значение подсказки.

`ts
(suggestion: Suggestion) => string | null;
`

События

Виджет вызывает события (CustomEvent) на текстовом поле, к которому он подключен, подписаться на них можно с помощью метода addEventListener

$3

Список подсказок очищен через метод clear().

Параметры в event.detail: нет.

$3

Установлена подсказка через метод setSuggestion().

Параметры в event.detail: нет.

$3

Восстановлен объект подсказки через метод fixData().

Параметры в event.detail:

`ts
{
suggestion: Suggestion;
}
`

$3

Виджет удален через метод dispose().

Параметры в event.detail: нет.

$3

Сброшена ранее сохраненная подсказка (вызывается аналогично с коллбэком onInvalidateSelection).

Параметры в event.detail:

`ts
{
suggestion: Suggestion;
}
`

$3

Выбрана подсказка из списка (вызывается аналогично с коллбэком onSelect).

Параметры в event.detail:

`ts
{
suggestion: Suggestion;
suggestionChanged: boolean;
}
`

$3

Нет подходящей подсказки для выбора (вызывается аналогично с коллбэком onSelectNothing).

Параметры в event.detail:

`ts
{
query: string;
}
`

Методы

При подключении подсказок к текстовому полю с помощью метода createSuggestions возвращается объект с методами управления виджетом:

$3

Очищает кэш запросов, список подсказок и значение в текстовом поле.

`ts
() => void;
`

$3

Очищает только кэш запросов.

`ts
() => void;
`

$3

Отключает виджет.

`ts
() => void;
`

$3

Включает виджет.

`ts
() => void;
`

$3

Удаляет виджет.

`ts
() => void;
`

$3

Прячет список подсказок.

`ts
() => void;
`

$3

Показывает список подсказок.

`ts
() => void;
`

$3

Устанавливает параметры и коллбеки виджета.

`ts
(newOptions: Partial) => void;
`

$3

Возвращает текущие опции виджета.

`ts
() => void;
`

$3

Запрашивает подсказку по переданному значению query и выбирает ее. Объект подсказки возвращается асинхронно в событии suggestions-fixdata на текстовом поле.

`ts
(query: string) => void;
`

$3

Запоминает переданный объект подсказки и устанавливает его значение в поле.

`ts
(suggestion: Suggestion) => void;
`

$3

Возвращает объект выбранной подсказки.

`ts
() => Suggestion | null;
`

$3

Возвращает индекс выбранной подсказки.

`ts
() => number;
`

$3

Возвращает массив подсказок.

`ts
() => Suggestion[];
`

$3

Возвращает input-элемент, к которому подключены подсказки.

`ts
() => HTMLInputElement;
`

$3

Возвращает строковое значение выбранной подсказки (текущее значение input-элемента).

`ts
() => string;
`

$3

Возвращает адрес, определенный через геолокацию.

`ts
() => Promise;
`

Гранулярные подсказки

Для подсказок по адресам (type=address) возможна работа виджета в гранулярном режиме (адрес по частям в разных полях). Для этого в качестве третьего аргумента можно передать родительский экземпляр подсказок, который будет ограничивать подсказки в текущем поле:

`js
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.

$3

Возвращает строковое значение подсказки в указанных границах bounds для подсказок по адресам:

`ts
interface Bounds {
from_bound: { value: string };
to_bound: { value: string };
}

interface Options {
bounds: Bounds;
suggestion: Suggestion;
type: "address";
}

type getBoundedValue = (options: Options) => string;
`

`js
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");
},
});
`

$3

Возвращает текущую геолокацию по IP:

`ts
interface API_OPTIONS {
url?: string;
headers?: Record | (() => Record);
token?: string;
serviceUrl?: string;
partner?: string;
timeout?: number;
}

type getLocation = (options?: API_OPTIONS) => Promise;
`

`js
import { getLocation } from "@dadata/suggestions";

const token = / /;

getLocation({ token }).then((location) => {
if (location) console.log(location.data.city);
})
`

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

Виджет включает в себя декларации типов, которые должны работать из коробки

`ts
import type { Options, Suggestion, SuggestionsType } from "@dadata/suggestions";

const options: Options = {};
`

Объект подсказки - это опциональный generic, по умолчанию типизирован без детализации объекта в поле data:

`ts
type AnyData = { [K: string]: any };

interface Suggestion {
value: string;
unrestricted_value: string;
data: T;
}
`

Передать собственный тип для подсказок можно при инициализации виджета, и этот тип будет распространен на все объекты подсказок в коллбэках и методах этого экземпляра.

`ts
interface AddressSuggestion {
postal_code: string | null;
kladr_id: string | null;
...
history_values: string[] | null;
}

const input = document.getElementById("address") as HTMLInputElement;

const suggestions = createSuggestions(input, {
type: "address",
onSelect(suggestion) { // suggestion is Suggestion
console.log(suggestion);
}
});

suggestions.getSuggestions(); // вернет Suggestion[]
`

При изменении опций виджета можно передать новый тип, если нужно на лету изменить тип подсказок:

`ts
const suggestions = createSuggestions(input, options);

suggestions.setOptions({
type: "name",
onSelect(suggestion) {
// suggestion is Suggestion
console.log(suggestion);
},
});
`

Методы getSelection, getSuggestions и getOptions - тоже позволяют изменить тип подсказки в возвращаемом значении:

`ts
const suggestions = createSuggestions(input, options);

suggestions.getSelection(); // Suggestion
suggestions.getSuggestions(); // Suggestion[]
suggestions.getOptions(); // Options
``

Примеры использования

Исходники и демки доступны на платфоме Codepen по ссылкам ниже.

$3

Подсказки по адресу

Разложить адрес по полям

Муниципальное деление

Ограничение области поиска:

- Ограничить сектор поиска по адресу
- Адреса внутри окружности на карте
- Только города
- Иностранные города
- Без земельных участков
- Без станций метро

Подсказки по отдельным полям адреса (гранулярные подсказки):

- Регион, город, улица, дом
- Адрес до н/п одной строкой + улица и дом отдельно
- Страна + остальной адрес отдельно
- Все поля адреса

Форматирование:

- Город и н/п без типов
- Адрес в формате Почты России
- Полные типы вместо сокращенных
- Точки после сокращений

Почтовый индекс:

- Подставить индекс после выбора адреса
- Определить город по индексу
- Подсказки по индексу

Геолокация по IP:

- Включить и отключить геолокацию
- Сохранить информацию о геолокации

Карты и доставка:

- Выбрать адрес на карте
- Показать адрес на карте (Яндекс)
- Показать адрес на карте (Google)
- Идентификатор города в службах доставки

Международные подсказки:

- Подсказки на английском языке
- Подсказки по всем странам
- Подсказки по всем странам (гранулярные)
- Подсказки по выбранным странам
- Города мира

Другие возможности:

- Адрес по коду ФИАС или КЛАДР
- Получить код регистрирующей налоговой по адресу
- Предзаполнение сохраненного адреса (гранулярный)
- Предзаполнение сохраненного адреса (одной строкой)
- Запретить автоисправление
- Запретить вводить адрес без дома
- Проверить заполненность адреса
- Установка адреса через setSuggestion

$3

Подсказки по организациям

Подсказки по ИНН

Заполнить реквизиты компании по ИНН

Ограничить сектор поиска по организациям

Подсказки по организациям без филиалов

Фильтр по ОКВЭД

Запретить автоисправление

Запретить вводить компанию, если ее нет в ЕГРЮЛ

Включить и отключить геолокацию

Собственное сообщение, если компания не найдена

$3

Подсказки по банкам

Ограничить сектор поиска по банкам

Отфильтровать банки по городу

Заполнить реквизиты банка по БИК

$3

Подсказки по ФИО

Разложить ФИО по полям

Гранулярные подсказки ФИО

$3

Кем выдан паспорт (только наименование)

Кем выдан паспорт (код + наименование)

$3

Подсказки по email

Подсказывать только домен

$3

Включить или отключить подсказки

Изменить количество подсказок

Подсказки с 3-го символа

Обработчик onSelectNothing

Сообщение пользователю, если подсказки не работают

Мобильная версия подсказок