Форматирование текста¶

В этой странице описаны способы форматирования текста сообщений в MAX.

Поддерживаемые форматы¶

Подробная документация по форматированию: dev.max.ru/docs.

В таблице перечислены все поддерживаемые элементы форматирования:

Элемент	HTML	Markdown	Примечание
Жирный	`<b>текст</b>`	`текст`
Курсив	`<i>текст</i>`	`_текст_`
Подчёркнутый	`<u>текст</u>`	`++текст++`
Зачёркнутый	`<s>текст</s>`	`~~текст~~`
Заголовок	`<h1>текст</h1>`	`# текст`	только `h1`; не задокументирован, работает
Выделение	`<mark>текст</mark>`	`^^текст^^`	не отображается в web-версии; не задокументирован, работает
Моноширинный	`<code>текст</code>`	`текст`	не отображается в web-версии
Цитата	`<blockquote>текст</blockquote>`	`> текст`	не задокументирован, работает
Ссылка	`<a href="url">текст</a>`	`[текст](url)`
Упоминание	`<a href="max://user/ID">Полное имя</a>`	`[Полное имя](max://user/ID)`	текст ссылки должен быть полным именем

Примечание

<blockquote> не упомянут в официальной документации MAX, однако работает.

<code> и <pre> (моноширинный) не отображаются в web-версии клиента.

Примечание

Упоминание работает только если текст ссылки является полным именем пользователя.

<a href="max://user/1234567890">Иван Иванов</a> - сработает
<a href="max://user/1234567890">Любой другой текст</a> - нет

TextFormat¶

TextFormat определяет режим форматирования при отправке текста.

from maxo.enums import TextFormat
from maxo.routing.updates import MessageCreated

@router.message_created()
async def handler(message: MessageCreated):
    await message.answer_text("<b>Привет!</b>", format=TextFormat.HTML)
    await message.answer_text("**Привет!**", format=TextFormat.MARKDOWN)

Text API (`maxo.utils.formatting`)¶

Модуль maxo.utils.formatting позволяет составлять форматированные сообщения программно, без написания HTML или Markdown строк вручную.

Классы разметки¶

Text - базовый контейнер, принимает произвольные узлы
Bold, Italic, Underline, Strikethrough, Monospaced, BlockQuote, Heading, Highlighted - обёртки форматирования
Link(*body, url="https://...") - ссылка
Mention("Полное имя", user_id=123) - упоминание (текст должен быть полным именем)

from maxo.utils.formatting import Bold, Italic, Link, Mention

text = Bold("Важное ", Italic("сообщение"), "!")
link = Link("Библиотека maxo", url="https://github.com/K1rL3s/maxo")
mention = Mention("Иван Иванов", user_id=1234567890)

Рендеринг и отправка¶

Для отправки нужно сконвертировать Text объект в строку через .as_html() или .as_markdown():

from maxo.enums import TextFormat
from maxo.routing.updates import MessageCreated
from maxo.utils.formatting import Bold, Italic

@router.message_created()
async def handler(message: MessageCreated):
    text = Bold("Привет, ", Italic("мир"), "!")

    # HTML
    await message.answer_text(text.as_html(), format=TextFormat.HTML)

    # Markdown
    await message.answer_text(text.as_markdown(), format=TextFormat.MARKDOWN)

Метод .as_kwargs() возвращает {"text": "...", "format": None} - только текст без разметки (entities не передаются). Подходит для отправки содержимого Text объекта как plain text.

Вспомогательные функции¶

as_line(*items, end="\n", sep="") - строка с разделителем и \n в конце
as_list(*items, sep="\n") - элементы через \n
as_marked_list(*items, marker="- ") - список с маркером
as_numbered_list(*items, start=1, fmt="{}. ") - нумерованный список
as_section(title, *body) - секция с заголовком
as_marked_section(title, *body, marker="- ") - секция с маркированным списком
as_numbered_section(title, *body, start=1, fmt="{}. ") - секция с нумерованным списком
as_key_value(key, value) - строка вида <b>key:</b> value

from maxo.enums import TextFormat
from maxo.routing.updates import MessageCreated
from maxo.utils.formatting import Bold, as_key_value, as_marked_list, as_section

@router.message_created()
async def handler(message: MessageCreated):
    report = as_section(
        Bold("Отчёт"),
        as_key_value("Статус", "активен"),
        as_marked_list("Пункт 1", "Пункт 2", "Пункт 3"),
    )
    await message.answer_text(report.as_html(), format=TextFormat.HTML)