Фабрика міток зворотнього виклику та фільтрування

class aiogram.filters.callback_data.CallbackData

Базовий клас для обгортки мітки зворотного виклику

Цей клас слід використовувати як супер-клас зворотних викликів, визначених користувачем.

Ключове слово класу prefix потрібне для визначення префікса, а також аргумент sep можна передати для визначення роздільника (за замовчуванням це :).

pack() → str

Генерування рядок мітки зворотного виклику

Повертає:

дійсна мітка зворотного виклику для Telegram Bot API

classmethod unpack(value: str) → Self

Аналіз рядка мітки зворотного виклику

Параметри:

value – значення з Telegram

Повертає:

екземпляр мітки зворотного виклику

classmethod filter(rule: MagicFilter | None = None) → CallbackQueryFilter

Створює фільтр для запиту зворотного виклику з правилом

Параметри:

rule – магічне правило

Повертає:

екземпляр фільтру

Використання

Створення підкласу CallbackData:

class MyCallback(CallbackData, prefix="my"):
    foo: str
    bar: int

Після цього ви можете створити будь-який зворотній виклик на основі цього класу, наприклад:

cb1 = MyCallback(foo="demo", bar=42)
cb1.pack()  # returns 'my:demo:42'
cb1.unpack('my:demo:42')  # returns <MyCallback(foo="demo", bar=42)>

Отже… Тепер ви можете використовувати цей клас для створення будь-яких зворотних викликів із визначеною структурою

...
# Pass it into the markup
InlineKeyboardButton(
    text="demo",
    callback_data=MyCallback(foo="demo", bar="42").pack()  # value should be packed to string
)
...

… і обробляти за певними правилами

# Filter callback by type and value of field :code:`foo`
@router.callback_query(MyCallback.filter(F.foo == "demo"))
async def my_callback_foo(query: CallbackQuery, callback_data: MyCallback):
    await query.answer(...)
    ...
    print("bar =", callback_data.bar)

Also can be used in Keyboard builder:

builder = InlineKeyboardBuilder()
builder.button(
    text="demo",
    callback_data=MyCallback(foo="demo", bar="42")  # Value can be not packed to string inplace, because builder knows what to do with callback instance
)

Ще один абстрактний приклад:

class Action(str, Enum):
    ban = "ban"
    kick = "kick"
    warn = "warn"

class AdminAction(CallbackData, prefix="adm"):
    action: Action
    chat_id: int
    user_id: int

...
# Inside handler
builder = InlineKeyboardBuilder()
for action in Action:
    builder.button(
        text=action.value.title(),
        callback_data=AdminAction(action=action, chat_id=chat_id, user_id=user_id),
    )
await bot.send_message(
    chat_id=admins_chat,
    text=f"What do you want to do with {html.quote(name)}",
    reply_markup=builder.as_markup(),
)
...

@router.callback_query(AdminAction.filter(F.action == Action.ban))
async def ban_user(query: CallbackQuery, callback_data: AdminAction, bot: Bot):
    await bot.ban_chat_member(
        chat_id=callback_data.chat_id,
        user_id=callback_data.user_id,
        ...
    )

Відомі обмеження

Дозволені типи та їх підкласи:

• str

• int

• bool

• float

• Decimal (from decimal import Decimal)

• Fraction (from fractions import Fraction)

• UUID (from uuid import UUID)

• Enum (from enum import Enum, лише для переліків рядків)

• IntEnum (from enum import IntEnum, тільки для переліків int)

Примітка

Зауважте, що ціле число Enum завжди має бути підкласом IntEnum через проблеми з синтаксичним аналізом.