📖 Пагинация¶

Нужно пролистать длинный список элементов?

В Raito есть встроенная пагинация для inline, текста, фото, списков и rich-сообщений: простая и полностью настраиваемая.

Возможности¶

готовые типы пагинаторов (inline, text, photo, list, rich)
автоматическая навигация
зацикленная навигация (переход с последней страницы на первую и обратно)
декларативный хендлер через @rt.on_pagination(...)
гибкий API и подключаемые типы пагинаторов

Быстрый старт¶

1. Запуск пагинации¶

@router.message(filters.CommandStart())
async def start(message: Message, raito: Raito, bot: Bot) -> None:
    if not message.from_user:
        return

    await raito.paginate(
        "my_pagination_name",
        chat_id=message.chat.id,
        bot=bot,
        from_user=message.from_user,
        total_pages=10,
        limit=5,
    )

2. Обработка событий пагинации¶

Чтобы реагировать на смену страниц, используйте декоратор @rt.on_pagination(...):

@rt.on_pagination(router, "my_pagination_name")
async def on_pagination(
    query: CallbackQuery,
    paginator: InlinePaginator,
    offset: int,
    limit: int,
):
    buttons = [InlineKeyboardButton(text=str(i), callback_data=f"button_{i}") for i in range(offset, offset + limit)]
    await paginator.answer("Button list:", buttons=buttons)

Типы пагинаторов¶

Выберите пагинатор через mode= (по умолчанию PaginationMode.INLINE):

PaginationMode.INLINE: InlinePaginator, текст плюс ряд кнопок с контентом над навигацией.
PaginationMode.TEXT: TextPaginator, простой текст.
PaginationMode.PHOTO: PhotoPaginator, фото с подписью.
PaginationMode.LIST: ListPaginator, список строк, соединённых разделителем.
PaginationMode.RICH: RichPaginator, структурированные rich-сообщения: заголовки, списки, таблицы, блоки кода и не только. Требует aiogram>=3.30.0.

await raito.paginate(
    "rich_docs",
    chat_id=message.chat.id,
    bot=bot,
    from_user=message.from_user,
    mode=PaginationMode.RICH,
    total_pages=3,
)


@rt.on_pagination(router, "rich_docs")
async def on_rich_pagination(query: CallbackQuery, paginator: RichPaginator, page: int) -> None:
    await paginator.answer(rich_message=InputRichMessage(blocks=PAGES[page]))

Навигация¶

Каждый пагинатор генерирует ряд навигации по умолчанию.

Raito автоматически объединяет его с вашими кнопками:

если переданы только buttons, добавляется навигация по умолчанию
если buttons и reply_markup, объединяются оба
если только reply_markup, используется он напрямую

Чтобы прикрепить навигацию вручную:

builder = InlineKeyboardBuilder()
navigation = paginator.build_navigation()

builder.attach(builder.from_markup(navigation))
builder.button(text="Back", callback_data="menu")

Как это устроено¶

Все колбэки используют формат rt_p:mode:name:page:total:limit
PaginatorMiddleware разбирает данные и передаёт:
- paginator, offset, limit, page
Всё типобезопасно и построено на протоколе IPaginator
Можно написать свои пагинаторы и подключить их