Форматування¶

Зробіть форматування ваших повідомлень гнучким і простим

Цей інструмент працює на основі сутностей повідомлень, а не використовуючи HTML чи розмітку Markdown, ви можете легко створити своє повідомлення та надіслати його у Telegram без необхідності пам’ятати про парність тегів (відкриття та закриття) або про екранування користувацького вводу.

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

Основний сценарій¶

Складіть своє повідомлення та надішліть його у Telegram.

content = Text("Hello, ", Bold(message.from_user.full_name), "!")
await message.answer(**content.as_kwargs())

Такий самий, як наступний приклад, але без використання розмітки

await message.answer(
    text=f"Hello, <b>{html.quote(message.from_user.full_name)}</b>!",
    parse_mode=ParseMode.HTML
)

Дослівно, коли ви виконуєте метод as_kwargs, об’єкт Text перетворюється у текст Hello, Alex! із списком сутностей [MessageEntity(type='bold', offset=7, length=4)] і передається у словник, який може бути використаний як **kwargs в API-виклику.

Повний список елементів наведено на сторінці нижче.

Розширений сценарій¶

На додаток до базових елементів можуть бути реалізовані структури рендерингу контенту, тому з коробки aiogram надає декілька вже реалізованих функцій, які допомагають форматувати ваші повідомлення:

aiogram.utils.formatting.as_line(*items: Any, end: str = '\n', sep: str = '') → Text[source]¶

Об’єднайте кілька вузлів у рядок із \n в кінці рядка.

Параметри:

items – Текст або Інше
end – завершення рядка, за замовчуванням \n
sep – роздільник між елементами, за замовчуванням порожній рядок

Повертає:

Текст

aiogram.utils.formatting.as_list(*items: Any, sep: str = '\n') → Text[source]¶

Обгорніть кожен елемент у окремий рядок

Параметри:

items
sep

Повертає:

aiogram.utils.formatting.as_marked_list(*items: Any, marker: str = '- ') → Text[source]¶

Обгорніть елементи у маркований список

Параметри:

items
marker – маркер рядка, за замовчуванням „- „

Повертає:

Текст

aiogram.utils.formatting.as_numbered_list(*items: Any, start: int = 1, fmt: str = '{}. ') → Text[source]¶

Обгорніть елементи у нумерований список

Параметри:

items
start – початковий номер, за замовчуванням 1
fmt – формат номера, за замовчуванням „{}. „

Повертає:

Текст

aiogram.utils.formatting.as_section(title: Any, *body: Any) → Text[source]¶

Обгорніть елементи у простий розділ, розділ має заголовок та тіло

Параметри:

title
body

Повертає:

Текст

aiogram.utils.formatting.as_marked_section(title: Any, *body: Any, marker: str = '- ') → Text[source]¶

Обгорніть елементи у розділ із маркованим списком

Параметри:

title
body
marker

Повертає:

aiogram.utils.formatting.as_numbered_section(title: Any, *body: Any, start: int = 1, fmt: str = '{}. ') → Text[source]¶

Обгорніть елементи у розділ із нумерованим списком

Параметри:

title
body
start
fmt

Повертає:

aiogram.utils.formatting.as_key_value(key: Any, value: Any) → Text[source]¶

Обгорніть пари елементів у рядок ключ-значення. (<b>{key}:</b> {value})

Параметри:

key
value

Повертає:

Текст

і давайте завершимо їх всіх:

content = as_list(
    as_marked_section(
        Bold("Success:"),
        "Test 1",
        "Test 3",
        "Test 4",
        marker="✅ ",
    ),
    as_marked_section(
        Bold("Failed:"),
        "Test 2",
        marker="❌ ",
    ),
    as_marked_section(
        Bold("Summary:"),
        as_key_value("Total", 4),
        as_key_value("Success", 3),
        as_key_value("Failed", 1),
        marker="  ",
    ),
    HashTag("#test"),
    sep="\n\n",
)

Буде відрендерено у:

Успішно:

✅ Тест 1

✅ Тест 3

✅ Тест 4

Помилки:

❌ Тест 2

Підсумки:

Загалом: 4

Успішно: 3

Помилки: 1

#тест

Або як HTML:

<b>Success:</b>
✅ Test 1
✅ Test 3
✅ Test 4

<b>Failed:</b>
❌ Test 2

<b>Summary:</b>
  <b>Total:</b> 4
  <b>Success:</b> 3
  <b>Failed:</b> 1

#test

Available methods¶

class aiogram.utils.formatting.Text(*body: Any, **params: Any)[source]¶

Bases: Iterable[Any]

Simple text element

__init__(*body: Any, **params: Any) → None[source]¶

render(*, _offset: int = 0, _sort: bool = True, _collect_entities: bool = True) → Tuple[str, List[MessageEntity]][source]¶

Render elements tree as text with entities list

Повертає:

as_kwargs(*, text_key: str = 'text', entities_key: str = 'entities', replace_parse_mode: bool = True, parse_mode_key: str = 'parse_mode') → Dict[str, Any][source]¶

Render elements tree as keyword arguments for usage in the API call, for example:

entities = Text(...)
await message.answer(**entities.as_kwargs())

Параметри:

text_key
entities_key
replace_parse_mode
parse_mode_key

Повертає:

as_html() → str[source]¶: Render elements tree as HTML markup

as_markdown() → str[source]¶: Render elements tree as MarkdownV2 markup

Available elements¶

class aiogram.utils.formatting.Text(*body: Any, **params: Any)[source]

Bases: Iterable[Any]

Simple text element

class aiogram.utils.formatting.HashTag(*body: Any, **params: Any)[source]¶

Bases: Text

Hashtag element.

Попередження

The value should always start with „#“ symbol

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.HASHTAG

class aiogram.utils.formatting.CashTag(*body: Any, **params: Any)[source]¶

Bases: Text

Cashtag element.

Попередження

The value should always start with „$“ symbol

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.CASHTAG

class aiogram.utils.formatting.BotCommand(*body: Any, **params: Any)[source]¶

Bases: Text

Bot command element.

Попередження

The value should always start with „/“ symbol

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.BOT_COMMAND

class aiogram.utils.formatting.Url(*body: Any, **params: Any)[source]¶

Bases: Text

Url element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.URL

class aiogram.utils.formatting.Email(*body: Any, **params: Any)[source]¶

Bases: Text

Email element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.EMAIL

class aiogram.utils.formatting.PhoneNumber(*body: Any, **params: Any)[source]¶

Bases: Text

Phone number element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.PHONE_NUMBER

class aiogram.utils.formatting.Bold(*body: Any, **params: Any)[source]¶

Bases: Text

Bold element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.BOLD

class aiogram.utils.formatting.Italic(*body: Any, **params: Any)[source]¶

Bases: Text

Italic element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.ITALIC

class aiogram.utils.formatting.Underline(*body: Any, **params: Any)[source]¶

Bases: Text

Underline element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.UNDERLINE

class aiogram.utils.formatting.Strikethrough(*body: Any, **params: Any)[source]¶

Bases: Text

Strikethrough element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.STRIKETHROUGH

class aiogram.utils.formatting.Spoiler(*body: Any, **params: Any)[source]¶

Bases: Text

Spoiler element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.SPOILER

class aiogram.utils.formatting.Code(*body: Any, **params: Any)[source]¶

Bases: Text

Code element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.CODE

class aiogram.utils.formatting.Pre(*body: Any, language: str | None = None, **params: Any)[source]¶

Bases: Text

Pre element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.PRE

class aiogram.utils.formatting.TextLink(*body: Any, url: str, **params: Any)[source]¶

Bases: Text

Text link element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.TEXT_LINK

class aiogram.utils.formatting.TextMention(*body: Any, user: User, **params: Any)[source]¶

Bases: Text

Text mention element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.TEXT_MENTION

class aiogram.utils.formatting.CustomEmoji(*body: Any, custom_emoji_id: str, **params: Any)[source]¶

Bases: Text

Custom emoji element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.CUSTOM_EMOJI

class aiogram.utils.formatting.BlockQuote(*body: Any, **params: Any)[source]¶

Bases: Text

Block quote element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.BLOCKQUOTE

class aiogram.utils.formatting.ExpandableBlockQuote(*body: Any, **params: Any)[source]¶

Bases: Text

Expandable block quote element.

Will be wrapped into aiogram.types.message_entity.MessageEntity with type aiogram.enums.message_entity_type.MessageEntityType.EXPANDABLE_BLOCKQUOTE