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
