telegram-node-bot-extensions

Этот небольшой проект представляет собой расширения стандартного функционала для библиотеки telegram-node-bot.

Установка

Добавление пакета в проект через npm:

npm install --save telegram-node-bot-extensions

Инициализация модуля:

require('telegram-node-bot-extensions')(Telegram, tg)

Мульти-формы

Вы можете создавать сложные формы с высокой степенью вложенности. Используйте $.runMultiForm для запуска.

const form = {
    category: {
        question: 'Выбери категорию',
        error: 'Ты неправильно ввел категорию!',
        keyboard: [['Курьер', 'Ремонт']],
        'Курьер': {
            subcategory: {
                question: 'Выбери подкатегорию',
                error: 'Ты неправильно ввел подкатегорию!',
                keyboard: [['Пеший курьер', 'Доставка продуктов']]
            },
            size: {
                question: 'Установить размер посылки?',
                keyboard: [['Да', 'Нет']],
                values: {'Да': true, 'Нет': false},
                'Да': {
                    length: {
                        question: 'Задай длину посылки (см)',
                        validator: message => {return Number.isInteger(parseInt(message.text))}
                    },
                    width: {
                        question: 'Задай ширину посылки (см)',
                        validator: message => {return Number.isInteger(parseInt(message.text))}
                    }
                }
            },
            weight: {
                question: 'Задай вес посылки',
                validator: message => {return Number.isInteger(parseInt(message.text))}
            }
        },
        'Ремонт': {
            subcategory: {
                question: 'Выбери подкатегорию',
                keyboard: [['Ремонт мебели', 'Отделочные работы']]
            }
        }
    },
    contacts: {
        question: 'Оставить контакты?',
        keyboard: [['Да', 'Нет']]
    }
}
 
const config = {
    buttons: {
        cancel: 'Отменить',
        back: 'Назад'
    },
    messages: {
        canceled: 'Заполнение формы отменено.',
        completed: 'Форма успешно заполнена.'
    },
    disable_notification: true,
    disable_web_page_preview: true,
    parse_mode: 'HTML'
}
 
$.runMultiForm(form, result => console.log(result), config)

Структура формы

Каждая форма состоит из вопросов, на которые должен ответить пользователь. Каждый вопрос должен включать в себя текст вопроса и ответ на него. В качестве проверки ответа выступает функция-валидатор, возвращающая логическое значение, либо текст из кнопок клавиатуры. Если указано и то и другое, функция-валидатор будет иметь приоритет.

...
    validator: message => {return Number.isInteger(parseInt(message.text))}
...

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

...
    question: 'Выбери подкатегорию',
    error: 'Ты неправильно ввел подкатегорию!',
...

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

...
    question: 'Выбери категорию',
    error: 'Ты неправильно ввел категорию!',
    keyboard: [['Курьер', 'Ремонт']],
    'Курьер': {...},
    'Ремонт': {...}
...

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

...
    question: 'Установить размер посылки?',
    keyboard: [['Да', 'Нет']],
    values: {'Да': true, 'Нет': false},
...

Настройка формы

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

const config = {
    buttons: {
        cancel: 'Отменить',
        back: 'Назад'
    },
    messages: {
        canceled: 'Заполнение формы отменено.',
        completed: 'Форма успешно заполнена.'
    },
    disable_notification: true,
    disable_web_page_preview: true,
    parse_mode: 'HTML'
}

В объекте buttons задается использование кнопок. Можно включить кнопки отмены и возвращения к предыдущему вопросу. Аналогичным образом, в объекте messages можно включить сообщения при завершении и при отмене формы.

Помимо этого, доступен к изменению ряд стандартных параметров: disable_notification, disable_web_page_preview и parse_mode.

Важно отметить, что конфиг совершенно опционален. Все функции, которыми он управляет по умолчанию выключены. Поэтому, если вы не хотите, допустим, использовать кнопку "Назад", просто не указывайте ее в конфиге.

Инлайновые меню с вкладками

Для создания таких меню можно воспользоваться методом $.runInlineTabsMenu.

const tabs = [
    {
        message: 'Первая вкладка',
        menu: [
            [
                {text: 'Один', callback: callbackQuery => console.log('one')},
                {text: 'Два', callback: callbackQuery => console.log('two')}
            ],
            [
                {text: 'Три', callback: callbackQuery => console.log('three')}
            ]
        ]
    },
    {
        message: 'Вторая вкладка',
        menu: [
            [
                {text: 'Четыре', callback: callbackQuery => console.log('four')}
            ],
            [
                {text: 'Пять', callback: callbackQuery => console.log('five')}
            ]
        ]
    },
    {
        message: 'Третья вкладка'
    },
    {
        message: 'Четвертая вкладка'
    },
    {
        message: 'Пятая вкладка'
    },
    {
        message: 'Шестая вкладка'
    }
]
 
const config = {
    title: '<b>Заголовок</b>',
    max_buttons: 5,
    disable_notification: true,
    disable_web_page_preview: true,
    parse_mode: 'HTML'
}
 
$.runInlineTabsMenu(tabs, config)

Структура меню

Массив вкладок содержит объекты, которые описывают каждую отдельную вкладку. В свою очередь, вкладка должна содержать текст (поле message) и может содержать меню с инлайновыми кнопками (поле menu).

...
    message: 'Первая вкладка',
    menu: [
        [
            {text: 'Один', callback: callbackQuery => console.log('one')},
            {text: 'Два', callback: callbackQuery => console.log('two')}
        ],
        [
            {text: 'Три', callback: callbackQuery => console.log('three')}
        ]
    ]
...

Меню описывает набор строк и кнопок в них. Каждая кнопка должна содержать текст (поле text) и функцию-колбек (поле callback), который будет вызван при нажатии на эту кнопку.

...
    {text: 'Один', callback: callbackQuery => console.log('one')},
...

Настройка меню

В конфиге, который передается вторым необязательным параметром в конструктор, можно задать использование заголовка (поле title), который будет добавляться перед текстом вкладки. Поле max_buttons устанавливает максимальное количество кнопок для навигации по вкладкам (по умолчанию 5). Количество кнопок должно быть нечетным.

const config = {
    title: '<b>Заголовок</b>',
    max_buttons: 5,
    disable_notification: true,
    disable_web_page_preview: true,
    parse_mode: 'HTML'
}

Также можно установить значения для стандартных параметров: disable_notification, disable_web_page_preview и parse_mode.

Инлайновые клавиатуры

Появился простой механизм для создания инлайновых клавиатур:

let keyboard = $.genInlineKeyboard('Один', 'one', 'Два', 'two')
$.sendMessage('Выбери действие', {reply_markup: keyboard})

Метод $.genInlineKeyboard генерирует инлайновую клавиатуру из переданных пар аргументов: первый параметр устанавливает текст кнопки, второй устанавливает данные (callback_data). Оба переданных значения должны быть строкового типа.

Также параметры могут быть переданы в виде массива:

let buttons = ['Один', 'one', 'Два', 'two']
$.sendMessage('Выбери действие', {reply_markup: $.genInlineKeyboard(buttons)})

Можно использовать вложенные массивы для создания нескольких кнопок на одной строке:

let buttons = [['Один', 'one'], ['Два', 'two', 'Три', 'three'], 'Четыре', 'four', ['Пять', 'five']]
$.sendMessage('Выбери действие', {reply_markup: $.genInlineKeyboard(buttons)})