aiogram 富文本类型 RichTextBold 详解：加粗节点的源码实现与 sendRichMessage 实战用法

后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载本篇技术指南以 aiogram 仓库中的 RichTextBold API 文档 为核心深入解析 Telegram Bot API 新一代「富文本Rich Text」体系中加粗文本类型RichTextBold的字段定义、判别式联合解析原理并结合sendRichMessage、Message.answer_rich/Message.reply_rich给出可直接复用的发送示例。读完本文你将掌握在 aiogram 中构造任意层级嵌套的加粗富文本、理解其底层 Pydantic 判别机制并能独立排查嵌套解析性能问题。RichTextBold 是什么在 Telegram Bot API 中RichTextBold表示一段加粗文本A bold text。它是富文本体系Rich Text中的一种格式化节点与斜体RichTextItalic、下划线RichTextUnderline、删除线RichTextStrikethrough、剧透RichTextSpoiler等并列属于「Rich Text」对象在 Telegram 端能够解析的 26 种具体类型之一参见基类文档 rich_text.py 中的类型清单。在 aiogram 中RichTextBold定义于 aiogram/types/rich_text_bold.py继承自RichText而RichText继承自TelegramObject即所有 Telegram 对象的公共基类。其 API 文档由 docs/api/types/rich_text_bold.rst 中的automodule指令自动生成。字段定义只有两个字段RichTextBold的全部字段同时也是构造参数如下源码见 rich_text_bold.py字段类型说明typeLiteral[RichTextType.BOLD]默认值RichTextType.BOLD富文本类型标识恒为boldtextRichTextUnion加粗的文本内容支持嵌套其中type被建模为Literal类型并带有默认值你无需手动传typeaiogram 会自动填入bold这一点在源码中由type: Literal[RichTextType.BOLD] RichTextType.BOLD声明保证。RichTextType.BOLD来自 aiogram/enums/rich_text_type.py其底层枚举值为字符串bold且RichTextType本身是一个str, Enum双继承枚举可直接作为 JSON 序列化值发送。text 字段为何是 RichTextUniontext的类型是RichTextUnion而非简单的str这是富文本体系的核心设计加粗内容本身可以继续嵌套其他富文本节点。例如「加粗文本中再包含一段斜体」就对应bold(textitalic(text...))的树形结构。RichTextUnion的定义位于 aiogram/types/rich_text_union.py它是一个递归联合类型合法取值包括普通字符串str纯文本列表list[RichTextUnion]多段文本的数组26 种具体的RichText*模型RichTextBold、RichTextItalic、RichTextSpoiler、RichTextDateTime、RichTextTextMention、RichTextCode、RichTextUrl、RichTextMention、RichTextHashtag、RichTextButton、RichTextAnchor、RichTextReferenceLink等。由于存在递归引用列表中可以再嵌套列表、节点中可以再嵌套节点RichTextUnion可以表达任意深度的富文本树。判别式联合RichTextUnion 如何高效解析RichTextUnion的实现值得单独说明。它没有使用简单的 Pydantic 智能联合smart union而是采用带判别器的显式联合discriminated union。核心逻辑在 rich_text_union.py 中的_rich_text_union_tag函数def _rich_text_union_tag(value: Any) - Any: if isinstance(value, str): return str if isinstance(value, (list, tuple)): return list if isinstance(value, dict): return value.get(type) return getattr(value, type, None)该函数按 Python 类型或type字段为每个取值打上标签Tag再交给Discriminator进行路由字符串打str标签、列表/元组打list标签、字典按type键取值、模型实例取type字段。这样 Pydantic 在反序列化时可以直接定位到对应的具体模型类而不是逐个尝试所有联合成员。这一设计有一个重要的工程动机。RichTextUnion混入了str、list[RichTextUnion]与RichText*模型三类成员无法像普通联合那样使用Field(discriminatortype)早期实现中 Pydantic 会在每一层嵌套上逐个尝试所有成员导致「加粗里套斜体、斜体里套剧透」这类深层嵌套在验证时呈指数级复杂度严重时直接冻结事件循环。仓库的变更记录 CHANGES/1925.bugfix.rst 明确记载了该修复Fixed an exponential slowdown (a CPU hang that froze the event loop) when validating updates with nested rich text, such as bold inside italic inside spoiler.RichTextUnionis now a discriminated union keyed ontype, with plain strings and arrays tagged by their Python type.对应的回归测试位于 tests/test_issues/test_1925_rich_text_union_discriminator.py其中既有「30 层嵌套验证耗时必须小于 1 秒」的性能护栏test_nested_rich_text_validation_is_not_exponential通过 SIGALRM 在 5 秒后强制中止也有混合列表与字符串、元组输入、JSON 输入、模型实例输入等覆盖RichTextBold的用例如test_mixed_list_and_str断言value[1]被解析为RichTextBold实例。RichTextBold 在消息体系中的位置RichTextBold不是孤立存在的类型它位于「富文本消息」的完整嵌套链中。在 aiogram 中这条链路是InputRichMessageaiogram/types/input_rich_message.py待发送的富文本消息html、markdown、blocks三个字段必须且只能使用其一其中blocks是list[InputRichBlockUnion]。InputRichBlockParagraphaiogram/types/input_rich_block_paragraph.py文本段落块对应 HTML 的p标签其text字段正是RichTextUnion——加粗节点通常就放在段落块的 text 里。接收方向对应RichBlockParagraphaiogram/types/rich_block_paragraph.py同样以RichTextUnion承载文本再向上汇总为RichMessage.blocks见 aiogram/types/rich_message.py。发送富文本消息的方法发送方通过sendRichMessageAPI 发送aiogram 中的方法对象是 aiogram/methods/send_rich_message.py 的SendRichMessage其关键参数包括参数类型说明chat_idChatIdUnion目标会话的唯一标识必填rich_messageInputRichMessage待发送的富文本消息必填business_connection_idstr \| None商务连接标识代表商家账号发送时使用message_thread_idint \| None论坛主题topic标识direct_messages_topic_idint \| None私信会话 topic 标识disable_notificationbool \| None静默发送protect_contentbool \| Default \| None禁止转发与保存默认Default(protect_content)allow_paid_broadcastbool \| None允许付费广播每条 0.1 Telegram Starsmessage_effect_idstr \| None消息特效仅私聊suggested_post_parametersSuggestedPostParameters \| None私信场景下的建议帖参数reply_parametersReplyParameters \| None要回复的消息描述reply_markupReplyMarkupUnion \| None内联键盘等附加界面ephemeral_message_parametersEphemeralMessageParameters \| None临时消息参数实战构造并发送包含加粗文本的富文本消息下面结合上述类型给出一个完整的、可直接运行的示例。它演示了三件事普通加粗、加粗中嵌套斜体、以及通过bot.send_rich_message发送。import asyncio from aiogram import Bot from aiogram.types import ( InputRichBlockParagraph, InputRichMessage, RichTextBold, RichTextItalic, ) API_TOKEN YOUR_BOT_TOKEN async def main() - None: bot Bot(tokenAPI_TOKEN) # 1) 简单加粗type 字段会自动填入 bold bold_node RichTextBold(text这是加粗文字) # 2) 嵌套加粗加粗内部再套一层斜体 nested_node RichTextBold( textRichTextItalic(text加粗中的斜体), ) # 3) 混合多段文本字符串与节点共存 mixed [ 普通文本, RichTextBold(text加粗文本), RichTextBold(text[RichTextItalic(text斜体), 与更多内容]), ] rich_message InputRichMessage( blocks[ InputRichBlockParagraph(textbold_node), InputRichBlockParagraph(textnested_node), InputRichBlockParagraph(textmixed), ], ) result await bot.send_rich_message( chat_id123456789, rich_messagerich_message, ) print(f消息已发送: {result.message_id}) await bot.session.close() if __name__ __main__: asyncio.run(main())要点说明所有RichText*节点都可以直接以 Python 对象传入text字段无需手写 JSONtype字段带默认值构造时不必传序列化时自动为boldInputRichMessage的blocks里放的是InputRichBlock*块加粗节点放在块的text内。使用 Message 快捷方法在收到消息后更常用的做法是利用消息对象上的快捷方法它们会自动填充chat_id、message_thread_id、business_connection_id等字段实现见 aiogram/types/message.pyfrom aiogram.types import InputRichMessage, InputRichBlockParagraph, RichTextBold # 在处理器内 async def on_message(message): await message.answer_rich( InputRichMessage( blocks[ InputRichBlockParagraph( textRichTextBold(text回复中的加粗内容) ) ], ), )Message.answer_rich(...)作为新消息发送到当前会话Message.reply_rich(...)作为对原消息的回复发送自动填充reply_parameters与ephemeral_message_parameters。两种方法都返回SendRichMessage方法对象既可以直接await也可以在 Webhook 处理器中作为返回值使用。方法对象的更多用法直接导入SendRichMessage、绑定特定 bot、作为 Webhook 回复等见 docs/api/methods/send_rich_message.rst。与传统加粗工具函数的区别aiogram 中还有一套面向传统sendMessage实体格式HTML / Markdown的加粗工具函数容易与RichTextBold混淆需要区分aiogram/utils/markdown.py 中的bold(...)Markdown 加粗与hbold(...)HTML 加粗返回的是格式化的字符串配合parse_mode使用底层实现为markdown_decoration.bold(...)/html_decoration.bold(...)RichTextBold则是Bot API 富文本消息体系sendRichMessage中的结构化节点携带明确的type字段由 Pydantic 判别式联合解析不支持传统的parse_mode。两者的应用场景不同传统实体格式适用于sendMessage等既有方法而富文本消息sendRichMessage用于新的富文本能力段落、引用、列表、媒体混排等加粗节点在其中承担局部文字强调的职责。选择依据取决于你调用的发送方法send_rich_message系列方法内部必须使用RichText*节点send_message系列则使用bold/hbold字符串工具。相关源码与测试导航若需进一步深入可按以下路径在仓库中查阅类型实现aiogram/types/rich_text_bold.py、aiogram/types/rich_text.py判别式联合aiogram/types/rich_text_union.py类型枚举aiogram/enums/rich_text_type.py消息与发送aiogram/types/input_rich_message.py、aiogram/methods/send_rich_message.py、aiogram/types/message.py 中的answer_rich/reply_rich回归测试与变更记录tests/test_issues/test_1925_rich_text_union_discriminator.py、CHANGES/1925.bugfix.rst总结RichTextBold是 aiogram 富文本体系中最基础、最常用的格式化节点之一两个字段type恒为bold、text为可递归嵌套的RichTextUnion可以表达从简单加粗到「加粗内嵌斜体再嵌剧透」的任意深度结构。理解其底层的判别式联合机制不仅能正确构造和解析富文本消息还能避免嵌套验证时的指数级性能陷阱。配合sendRichMessage及Message.answer_rich/Message.reply_rich快捷方法即可在生产机器人中稳定输出结构化的加粗富文本内容。赞分享后端即时通讯API设计【免费下载链接】aiogramaiogram is a modern and fully asynchronous framework for Telegram Bot API written in Python using asyncio项目地址https://gitcode.com/gh_mirrors/ai/aiogram点击查看免费下载相关推荐aiogram 中 RichTextReferenceLink 类型详解富文本脚注引用链接节点的实现与用法aiogram 中 RichTextReferenceLink 类型详解富文本脚注引用链接节点的实现与用法 RichTextReferenceLink 是 a后端即时通讯API设计Sunshine游戏串流技术如何彻底改变家庭游戏体验Sunshine游戏串流技术如何彻底改变家庭游戏体验 在数字娱乐的浪潮中游戏玩家们面临着一个普遍的技术挑战如何将高性能游戏PC的计算能力扩展到家庭中的每一个后端即时通讯API设计CTF-Wiki 深度解析Windows NT 内核基础知识全览对象管理、内存管理与系统调用CTF Wiki 深度解析Windows NT 内核基础知识全览对象管理、内存管理与系统调用 本文以 CTF Wiki 中文站的 Windows 内核态基后端即时通讯API设计上一篇Apache Beam Python Katas 实战使用 ParDo 与自定义 DoFn 实现过滤Filter using ParDo下一篇AutoResearch双MCP Server实战让外部模型进入代码审查与结论评审闭环创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考