Привет! Продолжаем разбор темы разработки Telegram ботов с помощью Aiogram 3. В прошлой статье мы рассмотрели:
Магические фильтры (кратко)
Фильтры Command и CommandStart
Роутеры и диспетчер
Создание токена бота через BotFather
Выполнили первый запуск бота
Работали в рамках структуры, разработанной мной
Если вы новичок, предлагаю следовать моей структуре бота, но дальше – на ваше усмотрение.
О чём сегодня пойдёт речь:
Текстовые клавиатуры (markup)
ReplyKeyboardBuilder (генератор текстовых клавиатур)
Командное меню
Магические фильтры (в контексте клавиатур)
Бонус: Command object
Давайте обо всём по порядку.
Текстовая клавиатура
Текстовая клавиатура отображается под полем набора сообщения. Основная её особенность в том, что она не содержит никакой информации, кроме текста на кнопках (исключение – специальные кнопки, такие как геолокация о которых мы поговорим далее).
Другими словами, текст на кнопке отправляется боту, который реагирует на это сообщение, например, через F.text ==.
Начнем с кода. Реализуем его в файле all_kb.py, который находится в пакете keyboards (см. предыдущую статью для деталей).
Создадим простую клавиатуру главного меню. Для разнообразия сделаем так, чтоб у администраторов была дополнительная кнопка "Админ Панель" после выполнения простого фильтра.
Импорты в all_kb.py:
from aiogram.types import KeyboardButton, ReplyKeyboardMarkup from create_bot import admins
Создание клавиатуры "Главное меню":
def main_kb(user_telegram_id: int): kb_list = [ [KeyboardButton(text="📖 О нас"), KeyboardButton(text="👤 Профиль")], [KeyboardButton(text="📝 Заполнить анкету"), KeyboardButton(text="📚 Каталог")] ] if user_telegram_id in admins: kb_list.append([KeyboardButton(text="⚙️ Админ панель")]) keyboard = ReplyKeyboardMarkup(keyboard=kb_list, resize_keyboard=True, one_time_keyboard=True) return keyboard
Описание функции main_kb
Функция main_kb принимает один аргумент user_telegram_id типа int, который представляет собой ID пользователя в Telegram.
Создание списка кнопок:
kb_list = [ [KeyboardButton(text="📖 О нас"), KeyboardButton(text="👤 Профиль")], [KeyboardButton(text="📝 Заполнить анкету"), KeyboardButton(text="📚 Каталог")] ]
kb_list: список списков с объектамиKeyboardButton.Первая строка кнопок: "📖 О нас" и "👤 Профиль".
Вторая строка кнопок: "📝 Заполнить анкету" и "📚 Каталог".
Добавление кнопки для админов:
if user_telegram_id in admins: kb_list.append([KeyboardButton(text="⚙️ Админ панель")])
Если user_telegram_id присутствует в списке admins, добавляется строка с кнопкой "⚙️ Админ панель".
Создание и возврат объекта клавиатуры:
keyboard = ReplyKeyboardMarkup(keyboard=kb_list, resize_keyboard=True, one_time_keyboard=True) return keyboard
Функция возвращает созданную клавиатуру, которую мы затем привязываем к сообщению.
Привязка клавиатуры к сообщению (handlers/start.py):
from aiogram import Router, F from aiogram.filters import CommandStart from aiogram.types import Message from keyboards.all_kb import main_kb start_router = Router() @start_router.message(CommandStart()) async def cmd_start(message: Message): await message.answer('Запуск сообщения по команде /start используя фильтр CommandStart()', reply_markup=main_kb(message.from_user.id))
Для нашего фильтра мы вытянули телеграм айди пользователя из объекта message (message.from_user.id).
Импортируем клавиатуру из пакета keyboards и при помощи reply_markup привязываем её к сообщению. Давайте посмотрим что у нас получилось:
Так как у нас кнопок было достаточно много — они у нас получились более-менее обычного размера, но, если бы это была всего 1 кнопка, то тут бы вышло такое:
Улучшение клавиатуры
def main_kb(user_telegram_id: int): kb_list = [ [KeyboardButton(text="📖 О нас"), KeyboardButton(text="👤 Профиль")], [KeyboardButton(text="📝 Заполнить анкету"), KeyboardButton(text="📚 Каталог")] ] if user_telegram_id in admins: kb_list.append([KeyboardButton(text="⚙️ Админ панель")]) keyboard = ReplyKeyboardMarkup( keyboard=kb_list, resize_keyboard=True, one_time_keyboard=True, input_field_placeholder="Воспользуйтесь меню:" ) return keyboard
resize_keyboard=True: клавиатура будет автоматически изменять размер.one_time_keyboard=True: клавиатура скрывается после одного использования.input_field_placeholder: заменяет стандартную подпись «Написать сообщение...» на пользовательскую.
Смотрим что получилось:
Особые текстовые кнопки
Теперь создадим клавиатуру с "особыми кнопками". На примере будут кнопки:
Поделиться контактами
Поделиться локацией
Создать викторину/опрос
Создание специальной клавиатуры:
def create_spec_kb(): kb_list = [ [KeyboardButton(text="Отправить гео", request_location=True)], [KeyboardButton(text="Поделиться номером", request_contact=True)], [KeyboardButton(text="Отправить викторину/опрос", request_poll=KeyboardButtonPollType())] ] keyboard = ReplyKeyboardMarkup(keyboard=kb_list, resize_keyboard=True, one_time_keyboard=True, input_field_placeholder="Воспользуйтесь специальной клавиатурой:") return keyboard
request_location=True: позволяет пользователю отправить геолокацию.request_contact=True: позволяет отправить контактный номер.request_poll=KeyboardButtonPollType(): позволяет создать викторину или опрос. Может принимать один из параметров type = «quiz» (викторина) или «regular» (опрос). В нашем случае и то и то будет обработано.
Привязка специальной клавиатуры под обработчик /start_2:
@start_router.message(Command('start_2')) async def cmd_start(message: Message): await message.answer('Запуск сообщения по команде /start_2 используя фильтр Command()', reply_markup=create_spec_kb())
Смотрим что получилось:
Геолокацию можно отправить только со смартфона. При вызове этой опции через пк - получим такое сообщение:
Со смартфона данные передаются корректно, и теперь остается только обработать гео-данные. Как это сделать мы подробно обговорим в теме про FSM.
При клике на "Поделиться номером" (текст может быть любой). Пользователь увидит всплывающее окно:
После клика на "Поделиться" произойдет отправка номера телефона, который привязан к профилю телеграмм. Далее останется захватить ответ. Как это сделать мы тоже подробно обговорим в теме про FSM.
Штуку с викториной и опросником удобно использовать в группах и телеграмм каналах, которые будет администрировать ваш бот.
Использование ReplyKeyboardBuilder
Теперь давайте воспользуемся нововведением в aiogram 3, а именно строителем текстовых клавиатур. Для начала сделаем импорт:
from aiogram.utils.keyboard import ReplyKeyboardBuilder
Давайте сгенирируем некую шкалу голосования в котором результаты у нас записаны в виде баллов от 1 до 10. Пример кода:
def create_rat(): builder = ReplyKeyboardBuilder() for item in [str(i) for i in range(1, 11)]: builder.button(text=item) builder.button(text='Назад') builder.adjust(4, 4, 2, 1) return builder.as_markup(resize_keyboard=True)
Описание функции create_rat
def create_rat(): builder = ReplyKeyboardBuilder()
Создаем объект ReplyKeyboardBuilder, который будет использоваться для построения клавиатуры.
Добавление кнопок с оценками
for item in [str(i) for i in range(1, 11)]: builder.button(text=item)
Создаем список строк от '1' до '10' с помощью генератора списка.
Для каждого элемента в этом списке добавляем кнопку с текстом, равным этому элементу.
Добавление кнопки "Назад"
builder.button(text='Назад')
Настройка расположения кнопок
builder.adjust(4, 4, 2, 1)
Устанавливаем расположение кнопок на клавиатуре.
adjust(4, 4, 2, 1) указывает, что кнопки должны быть размещены в строках по 4, 4, 2 и 1 кнопке соответственно.
Первая строка будет содержать 4 кнопки.
Вторая строка будет содержать 4 кнопки.
Третья строка будет содержать 2 кнопки.
Четвертая строка будет содержать 1 кнопку ("Назад").
Возврат разметки клавиатуры
return builder.as_markup(resize_keyboard=True)
Преобразуем построенную клавиатуру в объект ReplyKeyboardMarkup с помощью метода as_markup.
Указываем параметр resize_keyboard=True, чтобы клавиатура автоматически изменяла размер в зависимости от количества и размера кнопок.
Привяжем клавиатуру к команде /start_3
@start_router.message(F.text == '/start_3') async def cmd_start(message: Message): await message.answer('Запуск сообщения по команде /start_3 используя магический фильтр F.text!', reply_markup=create_rat())
Смотрим что получилось:
Видим что все получилось как задумывали.
Мне кажется, что я раскрыл максимум из того что могло иметь отношение к текстовым кнопкам. Теперь поговорим про командное меню.
Работа с командным меню
Похожее меню мы можем создать двумя способами:
Через BotFather
Напрямую через код
Оба способа мы рассмотрим далее.
Настройка командного меню через BotFather
start - Главная страница start_3 - Вызов спец. клавиатуры
После этих действий в боте появится кнопка «Меню» с этими командами. Как вы понимаете, для того чтоб все работало необходимо в боте привязать к каждой команде нужное действие.
Настройка командного меню через код:
from aiogram.types import BotCommand, BotCommandScopeDefault async def set_commands(): commands = [BotCommand(command='start', description='Старт'), BotCommand(command='start_2', description='Старт 2'), BotCommand(command='start_3', description='Старт 3')] await bot.set_my_commands(commands, BotCommandScopeDefault())
Давайте разберем код функции set_commands построчно, чтобы понять, что он делает.
Импортируемые модули и объекты
from aiogram.types import BotCommand, BotCommandScopeDefault
BotCommand: объект, используемый для создания команд бота. Каждая команда имеет два атрибута: command (имя команды) и description (описание команды).BotCommandScopeDefault: объект, определяющий область действия команд. В данном случае используется область по умолчанию, что означает, что команды будут действовать для всех пользователей.
Описание функции set_commands
async def set_commands():
Объявляем асинхронную функцию set_commands, которая будет использоваться для установки команд бота. Асинхронная функция используется, потому что взаимодействие с API Telegram требует выполнения асинхронных запросов.
Создание списка команд
commands = [ BotCommand(command='start', description='Старт'), BotCommand(command='start_2', description='Старт 2'), BotCommand(command='start_3', description='Старт 3') ]
Создаем список commands, содержащий три команды:
BotCommand(command='start', description='Старт'):команда /start с описанием "Старт".BotCommand(command='start_2', description='Старт 2'):команда /start_2 с описанием "Старт 2".BotCommand(command='start_3', description='Старт 3'): команда /start_3 с описанием "Старт 3".
Установка команд бота
await bot.set_my_commands(commands, BotCommandScopeDefault())
Вызываем метод set_my_commands объекта bot для установки команд бота.
Передаем в метод два аргумента:
commands: список команд, который мы создали ранее.BotCommandScopeDefault(): область действия команд по умолчанию, которая устанавливает команды для всех пользователей.
и вызовем функцию в конце главной функции (то есть наш бот сначала будет запускаться, а после отправлять командное меню):
async def main(): # scheduler.add_job(send_time_msg, 'interval', seconds=10) # scheduler.start() dp.include_router(start_router) await bot.delete_webhook(drop_pending_updates=True) await dp.start_polling(bot) await set_commands()
Проверяем:
Использование Command Object для обработки аргументов команды
Вы, возможно, знали (если нет, то сейчас узнаете), что ссылки вида https://t.me/your_bot?start=12345 имеют особое значение для Telegram ботов. Бот может захватывать и обрабатывать информацию, следующую за start=. Это особенно полезно для реализации реферальных программ или отслеживания источника, откуда пришел пользователь.
Рассмотрим пример использования этой возможности на практическом примере. Писал бота клиники, который периодически рекламируется в различных Telegram-каналах и группах. Вместо простой ссылки на бота, такой как https://t.me/your_bot, менеджеры используют ссылки с метками, например, https://t.me/your_bot?start=habr, где habr - это метка источника.
Когда бот обнаруживает нового пользователя, он проверяет, была ли передана специальная информация в стартовой ссылке (метка). Если метка присутствует, бот фиксирует приход пользователя с конкретного источника. Эта информация затем отправляется на админ-панель для анализа маркетологами.
То же самое можно сделать для реферальной программы. Например, реферальная ссылка может содержать Telegram ID пользователя. Бот проверяет, является ли пользователь новым, и если это так, то пользователю, который поделился своей реферальной ссылкой, начисляются бонусы.
Для начала нам нужно выполнить новый импорт (CommandObject):
from aiogram.filters import CommandStart, Command, CommandObject
Изменение функции cmd_start:
@start_router.message(CommandStart()) async def cmd_start(message: Message, command: CommandObject): command_args: str = command.args if command_args: await message.answer( f'Запуск сообщения по команде /start используя фильтр CommandStart() с меткой <b>{command_args}</b>', reply_markup=main_kb(message.from_user.id)) else: await message.answer( f'Запуск сообщения по команде /start используя фильтр CommandStart() без метки', reply_markup=main_kb(message.from_user.id))
Обратите внимание, что в тройке больше не работает: message.get_args()!
Тут нас может заинтересовать только извлечение аргументов из команды:
command_args: str = cmd.args
Далее уже работаем с переменной command_args, как с обычным значением. Если метки не будет, то command_args будет равно None (этот случай я так же обработал в своем коде).
Тестируем:
Тот же результат мы получим если передадим свою метку в конструкцию такого вида:
/start метка
Мы видим, что бот успешно обработал метку. Ничто не мешает добавить такой же обработчик к любой другой команде. Это будет работать аналогично команде “/start”, за исключением того, что другие команды нельзя использовать в стартовой ссылке.
Заключение
Сегодня мы подробно разобрали темы командного меню и текстовых кнопок. Если у вас возникли вопросы по этой теме, пишите их в комментариях — я всегда стараюсь ответить каждому.
Если эта статья была для вас полезной, оставьте комментарий, подпишитесь и поставьте лайк. На создание таких туториалов уходит много времени и сил, и ваша поддержка очень важна для меня. Обратная связь от аудитории вдохновляет продолжать делиться знаниями и опытом.
Спасибо за внимание, и до новых встреч!
