QQ 事件实体

约 1461 字大约 5 分钟

2026-03-19

QQ 平台（OneBot v11 / NapCat）的事件实体完整参考。

导入路径： from ncatbot.event.qq import GroupMessageEvent, NoticeEvent, RequestEvent, ...

源码： ncatbot/event/qq/

枚举速查

导入： from ncatbot.types.qq import PostType, MessageType, NoticeType, RequestType, MetaEventType

枚举	值
`PostType`	`MESSAGE`, `MESSAGE_SENT`, `NOTICE`, `REQUEST`, `META_EVENT`
`MessageType`	`PRIVATE`, `GROUP`
`NoticeType`	`GROUP_UPLOAD`, `GROUP_ADMIN`, `GROUP_DECREASE`, `GROUP_INCREASE`, `GROUP_BAN`, `FRIEND_ADD`, `GROUP_RECALL`, `FRIEND_RECALL`, `GROUP_MSG_EMOJI_LIKE`, `NOTIFY`
`NoticeNotifySubType`	`POKE`, `LUCKY_KING`, `HONOR`
`GroupAdminSubType`	`SET`, `UNSET`
`GroupDecreaseSubType`	`LEAVE`, `KICK`, `KICK_ME`
`GroupIncreaseSubType`	`APPROVE`, `INVITE`
`GroupBanSubType`	`BAN`, `LIFT_BAN`
`RequestType`	`FRIEND`, `GROUP`
`MetaEventType`	`LIFECYCLE`, `HEARTBEAT`, `HEARTBEAT_TIMEOUT`

消息事件

MessageEvent

QQ 消息事件基类。Traits： Replyable, Deletable, HasSender, HasAttachments

属性	类型	说明
`message_type`	`MessageType`	消息类型（`PRIVATE` / `GROUP`）
`sub_type`	`str`	子类型
`message_id`	`str`	消息 ID
`user_id`	`str`	发送者 ID
`message`	`MessageArray`	消息内容
`raw_message`	`str`	原始消息字符串
`sender`	`BaseSender`	发送者信息
`font`	`int`	字体

方法	签名	说明
`is_group_msg()`	`() → bool`	是否群消息
`reply()`	`async (text=, *, at=, image=, video=, rtf=, at_sender=True)`	回复消息
`delete()`	`async ()`	撤回消息
`get_attachments()`	`async () → AttachmentList`	提取媒体附件

reply() 行为详情：

自动添加引用回复（Reply 段）
群消息 + at_sender=True 时自动 @发送者
群消息发到群，私聊消息发到私聊
rtf 参数接受 MessageArray，用于追加复杂消息

@bot.on_message()
async def handle(event: MessageEvent):
    await event.reply(text="收到！")
    await event.reply(image="https://example.com/img.png", at_sender=False)
    await event.reply(rtf=MessageArray().add_text("复杂").add_image("pic.jpg"))

GroupMessageEvent

群消息事件。额外 Traits： GroupScoped, Kickable, Bannable

属性	类型	说明
`group_id`	`str`	群号
`anonymous`	`Anonymous?`	匿名信息
`sender`	`GroupSender`	群发送者（含 `card`, `role`, `title` 等）

方法	签名	说明
`kick()`	`async (reject_add_request=False)`	踢出发送者
`ban()`	`async (duration=1800)`	禁言发送者（秒）

@bot.on_message()
async def handle(event: GroupMessageEvent):
    await event.ban(duration=60)   # 禁言 60 秒
    await event.kick()             # 踢出

PrivateMessageEvent

私聊消息事件。接口同 MessageEvent，无额外属性。

通知事件

NoticeEvent

QQ 通知事件基类。Traits： HasSender, GroupScoped

属性	类型	说明
`notice_type`	`NoticeType`	通知类型
`group_id`	`str?`	群号（非群事件为 None）
`user_id`	`str?`	相关用户 ID

GroupIncreaseEvent

群成员增加事件。额外 Trait： Kickable

属性	类型	说明
`sub_type`	`str`	`"approve"` (管理同意) / `"invite"` (被邀请)
`operator_id`	`str`	操作者 ID

方法	签名	说明
`kick()`	`async (reject_add_request=False)`	踢出新成员

GroupUploadEvent

群文件上传事件。

属性	类型	说明
`file`	`FileInfo`	上传的文件信息（含 `id`, `name`, `size`, `busid`）

GroupAdminEvent

群管理员变动事件。

属性	类型	说明
`sub_type`	`str`	`"set"` (设置管理) / `"unset"` (取消管理)

GroupDecreaseEvent

群成员减少事件。

属性	类型	说明
`sub_type`	`str`	`"leave"` (主动退群) / `"kick"` (被踢) / `"kick_me"` (Bot 被踢)
`operator_id`	`str`	操作者 ID

GroupBanEvent

群禁言事件。

属性	类型	说明
`sub_type`	`str`	`"ban"` (禁言) / `"lift_ban"` (解禁)
`operator_id`	`str`	操作者 ID
`duration`	`int`	禁言时长（秒），0 表示解禁

FriendAddEvent

好友添加事件。当有新好友添加成功时触发。无额外属性。

GroupRecallEvent

群消息撤回事件。

属性	类型	说明
`operator_id`	`str`	操作者 ID
`message_id`	`str`	被撤回的消息 ID

FriendRecallEvent

好友消息撤回事件。

属性	类型	说明
`message_id`	`str`	被撤回的消息 ID

GroupMsgEmojiLikeEvent

群消息表情回应事件。当群成员对某条消息添加或移除表情回应时触发。

属性	类型	说明
`message_id`	`str`	被回应的消息 ID
`likes`	`list[EmojiLike]`	表情回应列表，每项含 `emoji_id` 和 `count`
`message_seq`	`int?`	消息序列号（NapCat 扩展，可能为 None）
`is_add`	`bool?`	是否为新增回应（NapCat 扩展，可能为 None）

NotifyEvent

Notify 通知事件基类。

属性	类型	说明
`sub_type`	`str`	Notify 子类型（`"poke"` / `"lucky_king"` / `"honor"`）

PokeNotifyEvent

戳一戳事件。继承自 NotifyEvent。

属性	类型	说明
`target_id`	`str`	被戳者 ID

LuckyKingNotifyEvent

运气王事件。继承自 NotifyEvent。

属性	类型	说明
`target_id`	`str`	运气王用户 ID

HonorNotifyEvent

群荣誉变更事件。继承自 NotifyEvent。

属性	类型	说明
`honor_type`	`str`	`"talkative"` (龙王) / `"performer"` (群聊之火) / `"emotion"` (快乐源泉)

通知数据模型一览

数据模型	notice_type	实体类
`GroupUploadNoticeEventData`	`GROUP_UPLOAD`	`GroupUploadEvent`
`GroupAdminNoticeEventData`	`GROUP_ADMIN`	`GroupAdminEvent`
`GroupDecreaseNoticeEventData`	`GROUP_DECREASE`	`GroupDecreaseEvent`
`GroupIncreaseNoticeEventData`	`GROUP_INCREASE`	`GroupIncreaseEvent`
`GroupBanNoticeEventData`	`GROUP_BAN`	`GroupBanEvent`
`FriendAddNoticeEventData`	`FRIEND_ADD`	`FriendAddEvent`
`GroupRecallNoticeEventData`	`GROUP_RECALL`	`GroupRecallEvent`
`FriendRecallNoticeEventData`	`FRIEND_RECALL`	`FriendRecallEvent`
`GroupMsgEmojiLikeNoticeEventData`	`GROUP_MSG_EMOJI_LIKE`	`GroupMsgEmojiLikeEvent`
`NotifyEventData`	`NOTIFY`	`NotifyEvent`
`PokeNotifyEventData`	`NOTIFY` (poke)	`PokeNotifyEvent`
`LuckyKingNotifyEventData`	`NOTIFY` (lucky_king)	`LuckyKingNotifyEvent`
`HonorNotifyEventData`	`NOTIFY` (honor)	`HonorNotifyEvent`

请求事件

RequestEvent

请求事件基类。Traits： HasSender, Approvable

属性	类型	说明
`request_type`	`RequestType`	`FRIEND` / `GROUP`
`user_id`	`str`	请求者 ID
`comment`	`str?`	验证信息
`flag`	`str`	请求标识（用于处理请求）

NapCat comment 格式

NapCat 适配器下，comment 字段的实际格式为 问题：xxx\n答案：yyy（而非纯答案文本）。例如：

问题：请输入您的单位和姓名
答案：东南大学 计小软

如果需要提取用户实际填写的答案，必须解析 答案： 之后的部分。直接将 comment 当作答案使用会导致正则匹配失败。

测试工厂提供了 napcat_comment() 辅助函数来构造这种格式——详见工厂场景与 Mock。

方法	签名	说明
`approve()`	`async (remark="", reason="")`	同意请求
`reject()`	`async (reason="")`	拒绝请求

FriendRequestEvent

好友请求事件。接口同 RequestEvent。

GroupRequestEvent

群请求事件。额外 Trait： GroupScoped

属性	类型	说明
`sub_type`	`str`	`"add"` (主动加群) / `"invite"` (被邀请)
`group_id`	`str`	群号

@bot.on_request()
async def handle(event: RequestEvent):
    if event.request_type == RequestType.FRIEND:
        await event.approve(remark="自动通过")
    elif event.request_type == RequestType.GROUP:
        await event.reject(reason="暂不接受")

元事件

MetaEvent

元事件实体。无额外 Trait。

属性	类型	说明
`meta_event_type`	`MetaEventType`	`LIFECYCLE` / `HEARTBEAT` / `HEARTBEAT_TIMEOUT`

工厂映射

QQ 工厂 (create_qq_entity) 的映射规则：

精确映射：

数据模型	→ 实体类
`PrivateMessageEventData`	`PrivateMessageEvent`
`GroupMessageEventData`	`GroupMessageEvent`
`FriendRequestEventData`	`FriendRequestEvent`
`GroupRequestEventData`	`GroupRequestEvent`
`GroupUploadNoticeEventData`	`GroupUploadEvent`
`GroupAdminNoticeEventData`	`GroupAdminEvent`
`GroupDecreaseNoticeEventData`	`GroupDecreaseEvent`
`GroupIncreaseNoticeEventData`	`GroupIncreaseEvent`
`GroupBanNoticeEventData`	`GroupBanEvent`
`FriendAddNoticeEventData`	`FriendAddEvent`
`GroupRecallNoticeEventData`	`GroupRecallEvent`
`FriendRecallNoticeEventData`	`FriendRecallEvent`
`GroupMsgEmojiLikeNoticeEventData`	`GroupMsgEmojiLikeEvent`
`NotifyEventData`	`NotifyEvent`
`PokeNotifyEventData`	`PokeNotifyEvent`
`LuckyKingNotifyEventData`	`LuckyKingNotifyEvent`
`HonorNotifyEventData`	`HonorNotifyEvent`

降级映射：

post_type	→ 降级实体
`message` / `message_sent`	`MessageEvent`
`notice`	`NoticeEvent`
`request`	`RequestEvent`
`meta_event`	`MetaEvent`

继承关系

BaseEvent (common)
├── MessageEvent               Replyable, Deletable, HasSender, HasAttachments
│   ├── PrivateMessageEvent
│   └── GroupMessageEvent      + GroupScoped, Kickable, Bannable
├── NoticeEvent                HasSender, GroupScoped
│   ├── GroupUploadEvent
│   ├── GroupAdminEvent
│   ├── GroupDecreaseEvent
│   ├── GroupIncreaseEvent     + Kickable
│   ├── GroupBanEvent
│   ├── FriendAddEvent
│   ├── GroupRecallEvent
│   ├── FriendRecallEvent
│   ├── GroupMsgEmojiLikeEvent
│   └── NotifyEvent
│       ├── PokeNotifyEvent
│       ├── LuckyKingNotifyEvent
│       └── HonorNotifyEvent
├── RequestEvent               HasSender, Approvable
│   ├── FriendRequestEvent
│   └── GroupRequestEvent      + GroupScoped
└── MetaEvent

交叉引用

通用事件基础 — BaseEvent、Mixin Traits
Bilibili 事件实体 — Bilibili 平台事件
QQ 平台消息段 — QQ 消息段类型
QQ 响应类型 — API 返回值类型

版权所有

版权归属：MI

许可证：署名 4.0 国际 (CC-BY-4.0)

通用

QQ

Bilibili

GitHub

AI

Misc