umbot
Version:
Мультиплатформенный фреймворк для создания голосовых навыков и чат-ботов с единой бизнес-логикой. Встроенная поддержка ВКонтакте, Telegram, Viber, MAX, Яндекс Алисы, Маруси и Сбера SmartApp. Архитектура на адаптерах позволяет подключать любые другие платф
297 lines (296 loc) • 13.2 kB
TypeScript
/**
* Тип элементов, по которым будет происходить навигация.
* Может быть объектом, числом, строкой или любым другим типом.
* @example
* ```ts
* // Строковые элементы
* const elements: TElementType[] = ['Элемент 1', 'Элемент 2', 'Элемент 3'];
*
* // Объекты
* const elements: TElementType[] = [
* { id: 1, name: 'Элемент 1' },
* { id: 2, name: 'Элемент 2' }
* ];
* ```
*/
export type TElementType = Record<string, string> | number | string | unknown;
/**
* Тип ключей для поиска по объектам.
* Может быть строкой или массивом строк.
* @example
* ```ts
* // Одиночный ключ
* const key: TKeys = 'name';
*
* // Массив ключей
* const keys: TKeys = ['name', 'description'];
* ```
*/
export type TKeys = string | string[];
/**
* Класс для навигации по элементам меню или списка.
* Предоставляет функциональность для:
* - Постраничной навигации по элементам
* - Поиска элементов по тексту или номеру
* - Управления отображением элементов
* - Обработки команд навигации
*
* @typeParam ElementType тип элементов, по которым будет происходить навигация
* @class Navigation
*
* @example
* ```ts
* // Создание экземпляра с максимальным количеством видимых элементов
* const navigation = new Navigation<{id: number, name: string}>(3);
*
* // Инициализация элементов
* const elements = [
* { id: 1, name: 'Элемент 1' },
* { id: 2, name: 'Элемент 2' },
* { id: 3, name: 'Элемент 3' },
* { id: 4, name: 'Элемент 4' }
* ];
*
* // Получение элементов текущей страницы
* const pageElements = navigation.getPageElements(elements, 'вперед');
*
* // Выбор элемента по тексту
* const selected = navigation.selectedElement(elements, 'Элемент 2', ['name']);
* ```
*/
export declare class Navigation<ElementType = TElementType> {
/**
* Список стандартных команд навигации вперед.
* Используется при isUsedStandardText = true
* @defaultValue ['дальше', 'вперед']
*/
STANDARD_NEXT_TEXT: string[];
/**
* Список стандартных команд навигации назад.
* Используется при isUsedStandardText = true
* @defaultValue ['назад']
*/
STANDARD_OLD_TEXT: string[];
/**
* Флаг использования стандартных команд навигации.
* Если true, используются стандартные команды из STANDARD_NEXT_TEXT и STANDARD_OLD_TEXT
* @defaultValue true
*/
isUsedStandardText: boolean;
/**
* Массив с возможными командами для навигации вперед.
* Дополняет или заменяет стандартные команды в зависимости от isUsedStandardText
* @defaultValue []
* @example
* ```ts
* navigation.nextText = ['следующая', 'продолжить'];
* ```
*/
nextText: string[];
/**
* Массив с возможными командами для навигации назад.
* Дополняет или заменяет стандартные команды в зависимости от isUsedStandardText
* @defaultValue []
* @example
* ```ts
* navigation.oldText = ['предыдущая', 'вернуться'];
* ```
*/
oldText: string[];
/**
* Массив элементов для обработки.
* @defaultValue []
*/
elements: ElementType[];
/**
* Максимальное количество отображаемых элементов на странице.
* @defaultValue 5
*/
maxVisibleElements: number;
/**
* Текущая страница.
* Рекомендуется получать это значение после завершения всех операций
* @defaultValue 0
*/
thisPage: number;
/**
* Создает экземпляр класса Navigation.
* @param {number} maxVisibleElements Максимальное количество отображаемых элементов на странице
* @example
* ```ts
* // Создание с 3 элементами на странице
* const navigation = new Navigation(3);
*
* // Создание с 10 элементами на странице
* const navigation = new Navigation(10);
* ```
*/
constructor(maxVisibleElements?: number);
/**
* Определяет желание пользователя двигаться вперед.
* Проверяет наличие команд навигации вперед в тексте
*
* @param {string} text Пользовательский запрос
* @return {boolean} true если обнаружена команда навигации вперед
* @example
* ```ts
* const isNext = navigation.isNext('покажи дальше'); // true
* const isNext = navigation.isNext('вернись назад'); // false
* ```
*/
isNext(text: string): boolean;
/**
* Определяет желание пользователя двигаться назад.
* Проверяет наличие команд навигации назад в тексте
*
* @param {string} text Пользовательский запрос
* @return {boolean} true если обнаружена команда навигации назад
* @example
* ```ts
* const isOld = navigation.isOld('вернись назад'); // true
* const isOld = navigation.isOld('покажи дальше'); // false
* ```
*/
isOld(text: string): boolean;
/**
* Валидация текущей страницы.
* Проверяет и корректирует значение thisPage в пределах допустимого диапазона
*
* @param {number} maxPage Максимальное количество страниц
*/
protected _validatePage(maxPage?: number): void;
/**
* Определяет желание пользователя перейти на определенную страницу.
* Ищет в тексте указание конкретной страницы в формате "N страница"
*
* @param {string} text Пользовательский запрос
* @return {boolean} true если обнаружено указание страницы
* @example
* ```ts
* const isNumberPage = navigation.numberPage('покажи 2 страницу'); // true
* const isNumberPage = navigation.numberPage('следующая страница'); // false
* ```
*/
numberPage(text: string): boolean;
/**
* Осуществляет переход на следующую страницу.
* Проверяет команду навигации вперед и обновляет thisPage
*
* @param {string} text Пользовательский запрос
* @return {boolean} true если переход выполнен
*/
protected _nextPage(text: string): boolean;
/**
* Осуществляет переход на предыдущую страницу.
* Проверяет команду навигации назад и обновляет thisPage
*
* @param {string} text Пользовательский запрос
* @return {boolean} true если переход выполнен
*/
protected _oldPage(text: string): boolean;
/**
* Возвращает массив элементов текущей страницы.
* Обрабатывает команды навигации и возвращает элементы в пределах maxVisibleElements
*
* ⚠️ Внимание: При передаче `text` с командой навигации ("Дальше"/"Назад")
* автоматически изменяет `this.thisPage` (текущую страницу).
*
*
* @param elements Массив элементов для обработки
* @param {string} text Пользовательский запрос
* @return Массив элементов текущей страницы
* @example
* ```ts
* const elements = [
* { id: 1, name: 'Элемент 1' },
* { id: 2, name: 'Элемент 2' },
* { id: 3, name: 'Элемент 3' },
* { id: 4, name: 'Элемент 4' }
* ];
*
* // Получение элементов первой страницы
* const pageElements = navigation.getPageElements(elements);
* // [{ id: 1, name: 'Элемент 1' }, { id: 2, name: 'Элемент 2' }]
*
* // Переход на следующую страницу
* const nextPageElements = navigation.getPageElements(null, 'вперед');
* // [{ id: 3, name: 'Элемент 3' }, { id: 4, name: 'Элемент 4' }]
* ```
*/
getPageElements(elements?: ElementType[] | null, text?: string): ElementType[];
/**
* Выбор элемента из списка по тексту или номеру.
* Поддерживает поиск по тексту с учетом схожести и выбор по номеру
*
* @param elements Массив элементов для обработки
* @param {string} text Пользовательский запрос
* @param {TKeys} keys Ключи для поиска по объектам
* @param {number} thisPage Текущая страница
* @return Выбранный элемент или null
* @example
* ```ts
* const elements = [
* { id: 1, name: 'Элемент 1' },
* { id: 2, name: 'Элемент 2' }
* ];
*
* // Выбор по номеру
* const selected = navigation.selectedElement(elements, 'выбери 1');
* // { id: 1, name: 'Элемент 1' }
*
* // Выбор по тексту
* const selected = navigation.selectedElement(elements, 'Элемент 2', ['name']);
* // { id: 2, name: 'Элемент 2' }
* ```
*/
selectedElement(elements?: ElementType[] | null, text?: string, keys?: TKeys | null, thisPage?: number | null): ElementType | null;
/**
* Возвращает массив команд навигации.
* Формирует список доступных команд для навигации по страницам
*
* @param {boolean} isNumber Включить команды с номерами страниц
* @return {string[]} Массив команд навигации
* @example
* ```ts
* // Получение базовых команд
* const commands = navigation.getPageNav();
* // ['👈 Назад', 'Дальше 👉']
*
* // Получение команд с номерами страниц
* const commands = navigation.getPageNav(true);
* // ['1', '2', '3']
* ```
*/
getPageNav(isNumber?: boolean): string[];
/**
* Возвращает информацию о текущей странице.
* Формирует строку с информацией о текущей позиции
*
* @return {string} Информация о текущей странице
* @example
* ```ts
* const info = navigation.getPageInfo();
* // "Страница 1 из 3"
* ```
*/
getPageInfo(): string;
/**
* Возвращает максимальное количество страниц.
* Вычисляет количество страниц на основе количества элементов
*
* @param elements Массив элементов
* @return Максимальное количество страниц
* @example
* ```ts
* const elements = [
* { id: 1, name: 'Элемент 1' },
* { id: 2, name: 'Элемент 2' },
* { id: 3, name: 'Элемент 3' }
* ];
*
* const maxPage = navigation.getMaxPage(elements);
* // 2 (при maxVisibleElements = 2)
* ```
*/
getMaxPage(elements?: ElementType[] | null): number;
}