后端即时通讯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 的RichBlockDetails类型展开讲解如何在 Telegram Bot API 的富消息Rich Message体系中构造默认折叠、点击展开的详情块对应 HTML 的details标签。你将掌握RichBlockDetails的全部字段语义summary、blocks、is_open、它与RichBlockUnion/RichTextUnion判别联合的嵌套关系以及通过send_rich_message实际发送包含详情块的富消息的完整代码路径。富消息与块RichBlock体系概述在 Telegram Bot API 的富消息能力中一条消息由若干个块block顺序组成。aiogram 中接收到的富消息由 RichMessage 表示其核心字段blocks: list[RichBlockUnion]承载消息内容发送侧则使用 InputRichMessage它同时支持html、markdown与blocks三种描述方式且三选一Exactlyoneof the fieldshtml,markdown, orblocksmust be used。每个块的具体类型由基类 RichBlock 的 docstring 列明目前共有 24 种例如段落RichBlockParagraph对应p、小节标题、预格式化文本、引用、折叠引用、表格、地图、按钮、各类媒体块以及本文的主角——RichBlockDetails对应details。所有块类型共享一个判别字段type其取值由枚举 RichBlockType 定义其中DETAILS details。RichBlockDetails 字段全解析RichBlockDetails定义于 aiogram/types/rich_block_details.py源码 docstring 明确说明它是一个用于细节披露的可展开块语义与 HTML 标签details一一对应。类中共有 4 个字段下表汇总了每个字段的名称、类型、是否必填与含义字段类型必填语义typeLiteral[RichBlockType.DETAILS]是默认值即details块类型恒为details作为判别联合的标签summaryRichTextUnion是始终显示的摘要文本对应summary即折叠时仍可见的标题行blockslist[RichBlockUnion]是块内容展开后展示的子块列表is_openbool \| None否默认None若为True内容默认可见展开状态type判别联合的锚点type字段被声明为Literal[RichBlockType.DETAILS]且带默认值这意味着构造对象时可以省略typeaiogram 会自动补上details反序列化时该字段是 RichBlockUnion 判别的依据。从 rich_block_union.py 的源码可见RichBlockUnion使用 Pydantic 的Annotated[...]联合并显式指定Field(discriminatortype)。当传入的 payload 中type为details时Pydantic 会直接选中RichBlockDetails成员完成解析而无需逐个尝试其他 23 种块类型。summary始终可见的摘要summary的类型是RichTextUnion其定义见 aiogram/types/rich_text_union.py。它并非单一模型而是一个递归联合可以接受纯字符串普通文本list[RichTextUnion]文本数组允许不同样式混排任意RichText*样式模型如粗体RichTextBold、斜体RichTextItalic、下划线、删除线、剧透RichTextSpoiler、上下标、行内代码、自定义 emoji、URL、 提及、话题标签等近 30 种行内文本类型。正因如此summary既可以是一行普通摘要文字也可以是由粗体、emoji、链接组合而成的富文本摘要。值得强调的是摘要内容始终显示——无论详情块处于折叠还是展开状态summary都可见这与details/summary的交互行为一致。blocks可嵌套的块内容blocks的类型是list[RichBlockUnion]即内容本身由若干块组成。由于RichBlockUnion是递归可嵌套的例如blockquote内可再嵌blockquote、details内可再嵌details这允许构造任意深度的树状结构。在 tests/test_issues/test_1925_rich_text_union_discriminator.py 中就有直接使用RichBlockDetails的回归测试用例rich_message: { blocks: [ { type: details, summary: , blocks: [{type: paragraph, text: _nested_text(5)}], } ] }测试断言details块被解析为RichBlockDetails实例其内部又解析出RichBlockParagraph段落文本再递归解析出 5 层RichText*嵌套spoiler/bold/subscript/italic/underline最终落到字符串叶子节点——完整验证了详情块 → 子块 → 行内文本的三级嵌套链路。is_open默认展开控制is_open是可选的布尔字段默认None。语义如下省略或传None由 Telegram 客户端决定默认状态通常为折叠传True详情块内容默认可见传False详情块内容默认折叠。这与 HTMLdetails上open属性的行为一致。在 aiogram 的输入侧镜像类中该字段的注释是PassTrueif the content of the block is visible by default与输出侧语义完全对齐。输入侧镜像InputRichBlockDetails 与发送链路发送富消息时Telegram API 使用的是独立的输入侧类型。aiogram 在 aiogram/types/input_rich_block_details.py 中定义了 InputRichBlockDetailstype恒为InputRichBlockType.DETAILS同样是detailssummary: RichTextUnion、is_open: bool | None与输出侧一致唯一区别是blocks: list[InputRichBlockUnion]使用的是输入侧联合 InputRichBlockUnion。由于输入侧与输出侧的块共享相同的type标签和字段名同一份{type: details, ...}payload 可以同时通过RichBlockDetails与InputRichBlockDetails的验证——这一点在 tests/test_issues/test_1842_rich_block_union_discriminator.py 的注释中明确说明。发送方法是 SendRichMessage对应 Bot 上的快捷方法bot.send_rich_message(chat_id..., rich_message...)见 aiogram/types/message.py 的Message.send_rich_message快捷封装。一个最小可用的发送示例from aiogram import Bot from aiogram.types import InputRichMessage, InputRichBlockDetails, InputRichBlockParagraph bot Bot(tokenYOUR_TOKEN) rich_message InputRichMessage( blocks[ InputRichBlockDetails( summary点击查看说明, blocks[ InputRichBlockParagraph(text这里是展开后可见的详细内容。), ], is_openFalse, ) ] ) await bot.send_rich_message(chat_idCHAT_ID, rich_messagerich_message)判别联合的工程意义深层嵌套的块结构在非判别联合下会产生指数级验证开销每个嵌套层级都要回溯尝试所有成员。aiogram 通过两个层面的工程手段解决了该问题RichBlockUnion使用Field(discriminatortype)的判别联合验证复杂度为线性对应回归测试 tests/test_issues/test_1842_rich_block_union_discriminator.pyRichTextUnion无法直接使用type判别因为还混入了str与list因此改用自定义判别函数_rich_text_union_tag字符串与数组按 Python 类型打标签模型按type字段打标签见 aiogram/types/rich_text_union.py。CHANGES 中的 1925.bugfix.rst 记录了这次修复此前嵌套富文本验证会指数级变慢并冻结事件循环。因此在RichBlockDetails内部嵌套多层details或深层的富文本样式时验证性能依然有保障这正是该类可放心用于生产环境的结构性前提。接收侧验证与类型收敛当 Bot 收到包含details块的更新时aiogram 会把原始 JSON 解析为具体的强类型对象。以 tests/test_issues/test_1925_rich_text_union_discriminator.py 的用例为例update Update.model_validate({... rich_message: {blocks: [{type: details, ...}]}}) details update.message.rich_message.blocks[0] assert isinstance(details, RichBlockDetails) paragraph details.blocks[0] assert isinstance(paragraph, RichBlockParagraph)解析结果中rich_message.blocks[0]是RichBlockDetails实例可直接访问.summary、.blocks、.is_open内部子块解析为对应具体类型无需手动判断或转型。如果type值非法例如{type: definitely_not_a_block}判别联合会抛出单个union_tag_invalid错误并定位到出错的块下标而不是返回一长串模糊的成员匹配错误见 tests/test_issues/test_1842_rich_block_union_discriminator.py。小结与最佳实践RichBlockDetails是 aiogram 富消息体系中实现可折叠内容的标准构件核心要点可归纳为字段职责明确summary负责始终可见的标题行blocks负责展开后展示的内容可任意嵌套其他块is_open控制默认展开状态类型安全type恒为details配合判别联合实现线性复杂度的嵌套解析输入侧与输出侧类型一一对应发送路径通过InputRichBlockDetails构造块放入InputRichMessage(blocks[...])再经bot.send_rich_message发送接收侧则直接从message.rich_message.blocks中取得已收敛为具体类型的RichBlockDetails实例。在具体场景中建议把冗长的条款、FAQ 答案、操作说明放入details块用简洁的summary保持消息正文紧凑同时利用blocks的递归嵌套能力组织复杂的层次化内容。赞分享后端即时通讯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点击查看免费下载相关推荐MMagic 数据流全解析从 Dataset 到 Model 再到 Visualizer 的完整链路MMagic 数据流全解析从 Dataset 到 Model 再到 Visualizer 的完整链路 导读 本文基于 MMagic 官方进阶指南 data_f后端即时通讯API设计aiogram RichBlockListItem 详解在 Python 中构建 Telegram 富文本消息的列表块aiogram RichBlockListItem 详解在 Python 中构建 Telegram 富文本消息的列表块 RichBlockListItem 是后端即时通讯API设计aiogram RichBlockSectionHeading 详解在富消息中用 h1-h6 标题块组织 Telegram 内容aiogram RichBlockSectionHeading 详解在富消息中用 h1 h6 标题块组织 Telegram 内容 RichBlockSecti后端即时通讯API设计上一篇TeslaMate把特斯拉的能耗和电池衰减记录成曲线3 张图看懂车况下一篇CoTracker安装部署全攻略从环境配置到模型验证创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考