通用消息段
约 497 字大约 2 分钟
2026-03-19
跨平台通用的消息段类型，所有平台共享。
导入路径： from ncatbot.types import MessageSegment, PlainText, At, Reply, Image, Record, Video, File
源码： ncatbot/types/common/segment/
MessageSegment 基类
所有消息段的抽象基类。子类通过 _type ClassVar 自动注册到 SEGMENT_MAP。
| 属性/方法 | 类型 | 说明 |
|---|---|---|
_type | ClassVar[str] | 协议 type 标识（如 "text", "image"） |
to_dict() | Dict[str, Any] | 序列化为 OB11 格式 {"type": ..., "data": {...}} |
from_dict(data) | MessageSegment (classmethod) | 从协议原始 dict 解析为具体子类 |
class MessageSegment(BaseModel):
_type: ClassVar[str]解析函数
from ncatbot.types import parse_segment, SEGMENT_MAP
seg = parse_segment({"type": "text", "data": {"text": "hello"}})
# → PlainText(text="hello")| 名称 | 说明 |
|---|---|
parse_segment(raw) | 从 {"type": ..., "data": {...}} 解析为具体 MessageSegment |
SEGMENT_MAP | Dict[str, Type[MessageSegment]] — type 字符串 → 段类的全局注册表 |
文本类
PlainText
纯文本消息段。
| 字段 | 类型 | 说明 |
|---|---|---|
text | str | 文本内容 |
PlainText(text="你好")At
@某人。
| 字段 | 类型 | 说明 |
|---|---|---|
user_id | str | 目标用户 ID，"all" 表示 @全体 |
- 接受
user_id或qq作为输入（AliasChoices） - 序列化时使用 OB11 的
"qq"key
At(user_id="123456") # @指定用户
At(user_id="all") # @全体成员Reply
引用回复。
| 字段 | 类型 | 说明 |
|---|---|---|
id | str | 被引用的消息 ID（自动转 str） |
Reply(id="12345")媒体类
所有媒体段继承自 DownloadableSegment，共享以下字段：
| 字段 | 类型 | 说明 |
|---|---|---|
file | str | 文件路径或 URL |
url | str? | 下载 URL |
file_id | str? | 文件 ID |
file_size | int? | 文件大小 (bytes) |
file_name | str? | 文件名 |
| 方法 | 签名 | 说明 |
|---|---|---|
to_attachment() | to_attachment() -> Attachment | 转为跨平台附件对象 |
Image→ImageAttachment，Video→VideoAttachment，Record→AudioAttachment，File→FileAttachment。
Image
图片消息段。_type = "image"
Image(file="https://example.com/img.png")
Image(file="/path/to/local.jpg")Record
语音消息段。_type = "record"
Record(file="https://example.com/voice.mp3")Video
视频消息段。_type = "video"
Video(file="https://example.com/video.mp4")File
文件消息段。_type = "file"
File(file="/path/to/document.pdf")继承关系
MessageSegment (base)
├── PlainText _type="text"
├── At _type="at"
├── Reply _type="reply"
└── DownloadableSegment (base)
├── Image _type="image"
├── Record _type="record"
├── Video _type="video"
└── File _type="file"交叉引用
- MessageArray 容器 — 消息段的有序容器
- QQ 平台消息段 — QQ 专属消息段（Face, Forward, Music 等）
版权所有
版权归属：huan-yp