UIComponent

UIComponent — базовый класс для создания экранов бота с автоматической маршрутизацией callback_data.

Класс UIComponent

from edgebot import UIComponent

Классовые атрибуты

Атрибут	Тип	По умолчанию	Описание
__prefix__	str	""	Уникальный префикс для callback_data (обязательно)
prompt	str | None	None	Ключ промпта в PromptRegistry
markup	str | None	None	Ключ клавиатуры в KeyboardRegistry
text	str	""	Inline-шаблон текста (альтернатива prompt)

Осторожно

__prefix__ обязателен и должен быть непустым. Отсутствие вызовет UIError при объявлении класса.

async open(ctx, **kwargs)

Точка входа в экран. Обязательно переопределяется в наследнике.

async def open(self, ctx: Context, **kwargs) -> None:
    ...

Обычно внутри:

1. Загружает данные из KV / реестров
2. Вызывает self.send(ctx, prompt_kwargs=..., markup_kwargs=...)

async send(ctx, …)

Отправляет новое сообщение экрана.

async def send(
    self,
    ctx: Context,
    *,
    prompt: str | Prompt | None = None,
    markup: str | InlineKeyboard | None = None,
    prompt_kwargs: dict | None = None,
    markup_kwargs: dict | None = None,
    parse_mode: str | None = None,
) -> dict

Параметр	Описание
prompt	Явный источник промпта (ключ или Prompt). Если None — self.prompt или self.text
markup	Явный источник клавиатуры (ключ или InlineKeyboard). Если None — self.markup
prompt_kwargs	Данные для фабрики промпта и Prompt.render()
markup_kwargs	Данные для фабрики клавиатуры
parse_mode	Режим парсинга; по умолчанию — bot.parse_mode

async update(ctx, …)

Редактирует текущее сообщение. Сигнатура идентична send().

async def update(self, ctx, ...) -> dict | None

Заметка

Если Telegram возвращает "message is not modified", update() тихо возвращает None вместо выброса исключения.

matches(callback_data)

Быстрая проверка принадлежности callback к этому компоненту.

def matches(self, callback_data: str) -> bool

Возвращает True, если callback_data начинается с "{__prefix__}:".

async handle_callback(ctx)

Внутренний метод маршрутизации. Вызывается из Bot.process_update().

async def handle_callback(self, ctx: Context) -> bool

Последовательность:

1. Проверка startswith("{prefix}:")
2. Сопоставление с зарегистрированными паттернами (first-match)
3. Fallback "*" (если задан)

Возвращает True, если callback был обработан.

Декоратор @UIComponent.callback(pattern)

Привязывает метод к паттерну callback_data.

@UIComponent.callback(pattern: str)

Паттерны

Паттерн	Пример callback_data	kwargs
"toggle"	"prof:toggle"	—
"del:{user_id}"	"prof:del:123"	user_id="123"
"page:{num}"	"prof:page:5"	num="5"
"*"	"prof:anything"	—

• Паттерн пишется без префикса компонента
• {name} — именованная переменная, значение передаётся в метод как kwarg
• "*" — fallback, ловит всё не подошедшее под другие паттерны

Пример

class OrderScreen(UIComponent):
    __prefix__ = "order"

    @UIComponent.callback("confirm:{order_id}")
    async def on_confirm(self, ctx: Context, order_id: str) -> None:
        await ctx.answer_callback(f"Заказ {order_id} подтверждён")

    @UIComponent.callback("cancel:{order_id}")
    async def on_cancel(self, ctx: Context, order_id: str) -> None:
        await ctx.answer_callback(f"Заказ {order_id} отменён")

    @UIComponent.callback("*")
    async def on_fallback(self, ctx: Context) -> None:
        await ctx.answer_callback("Неизвестное действие")

Резолвинг промпта

Приоритет определения текста сообщения:

1. Аргумент prompt в send() / update() (str → ключ в реестре; Prompt → как есть)
2. Атрибут self.prompt (ключ в PromptRegistry)
3. Атрибут self.text (inline-шаблон, оборачивается в Prompt)

Если ни один источник не найден — UIError.

Резолвинг клавиатуры

Приоритет определения клавиатуры:

1. Аргумент markup в send() / update() (str → ключ в реестре; InlineKeyboard → как есть)
2. Атрибут self.markup (ключ в KeyboardRegistry)
3. None — экран без клавиатуры (допустимо)