Превью диалогов и переходов

maxo.dialogs.tools предоставляет два инструмента для визуальной отладки диалогов без запуска бота: HTML-превью окон и PNG-диаграмму переходов между состояниями.

HTML-превью диалога

HTML-превью отображает все окна диалога в браузере: текст, кнопки и медиа. Удобно для ревью UI и проверки текстов без запуска бота.

Подготовка: preview_data

Окна с геттерами требуют данных для рендеринга. Добавьте параметр preview_data в Window - словарь с теми же ключами, которые возвращает геттер:

from maxo.dialogs import Window
from maxo.dialogs.widgets.text import Format
from maxo.dialogs.widgets.kbd import Button
from maxo.dialogs.widgets.text import Const

Window(
    Format("Привет, {name}!"),
    Button(Const("Продолжить"), id="next"),
    state=MySG.greeting,
    preview_data={"name": "Разработчик"},
)

Генерация HTML-файла

import asyncio
from maxo.dialogs.tools.preview import render_preview

asyncio.run(render_preview(router, "preview.html"))

Откройте preview.html в браузере - каждый диалог отображается как секция с превью всех своих окон. Кнопки кликабельны и переключают окна:

HTML-превью диалога

Для получения HTML-строки без записи в файл:

from maxo.dialogs.tools.preview import render_preview_content

html = asyncio.run(render_preview_content(router, simulate_events=True))

Диаграмма переходов (PNG)

Диаграмма визуализирует состояния и переходы между ними как граф. Каждый диалог - отдельная группа. Рёбра показывают тип перехода по цвету:

  • Зелёный - Start (запуск нового диалога)

  • Синий - SwitchTo / Next (переход в другое окно)

  • Серый - Back / Cancel (возврат)

Требования

pip install "maxo[preview]"     # или: uv add "maxo[preview]"
brew install graphviz           # macOS
# apt-get install graphviz      # Linux

Генерация диаграммы

from maxo.dialogs.tools.transitions import render_transitions

render_transitions(router, title="Мой бот", filename="transitions")
# Сохраняет transitions.png в текущую директорию
Диаграмма переходов

Параметры:

  • router - Dispatcher, Router или Dialog

  • title - заголовок диаграммы

  • filename - имя файла без расширения

  • format - формат вывода ("png", "svg" и др.)

Хинты для динамических переходов

Переходы, реализованные в коде (не через виджеты Start/SwitchTo), невидимы для статического анализа. Подскажите их с помощью preview_add_transitions:

from maxo.dialogs.widgets.kbd import Start

Window(
    Const("Выберите действие"),
    state=MySG.menu,
    # Переход в EditSG.main происходит в коде - указываем явно для диаграммы
    preview_add_transitions=[Start(Const(""), id="_hint", state=EditSG.main)],
)

Web-превью

Команда maxo-dialog-preview запускает локальный веб-сервер с обоими инструментами сразу - HTML-превью и диаграмма переходов доступны в браузере без генерации файлов.

maxo-dialog-preview path/to/module.py:router_variable

Откройте в браузере:

  • http://127.0.0.1:9876/ - HTML-превью всех окон

  • http://127.0.0.1:9876/transitions - PNG-диаграмма переходов

Примечание

Для работы /transitions требуется установленный graphviz и пакет maxo[preview].

Полный пример

Рабочий пример с диалогом из двух групп состояний: демонстрирует генерацию HTML-превью и PNG-диаграммы переходов, а также настройку роутера для команды maxo-dialog-preview: examples/dialogs_preview.py