概览

NcatBot 将 OneBot/NapCat 的原始事件（称为官方事件）结构封装为更易用的事件对象。本文介绍全部事件对象及其附属数据结构：

• GroupMessageEvent（群消息）
• PrivateMessageEvent（私聊消息）
• MessageSendEvent（自身消息）
• RequestEvent（请求：加好友/加群）
• NoticeEvent（通知：群上传/变更/撤回等）

这些事件对象都会出现在 BotClient 的回调或插件的 EventBus 订阅中。它们不仅承载数据，也内置了常用的便捷操作方法（如 reply/approve 等），直接走 BotAPI 完成上行操作。

---

事件类继承关系

BaseEventData（基础事件）

关键字段：

• self_id: str，当前 Bot QQ 号
• time: int，事件时间戳（秒）
• post_type: str，事件类型，如 message、notice、request、meta_event

BaseMessageEvent（消息事件基类）

关键字段：

• BaseEventData 的所有字段。
• message_type: str，消息类型，如 private、group
• sub_type: str，消息子类型，这里太多，下级再介绍。
• message_id: str，消息 ID
• user_id: str，消息发送者 QQ 号
• message: MessageArray，结构化消息片段集合，参见MessageArray 使用指南
• raw_message: str，原始文本消息
• sender: BaseSender，发送者信息，参见下文。

GroupMessageEvent（群消息）

关键字段：

• 包括 BaseMessageEvent 的所有字段。
• group_id: str，群号
• sub_type: str，消息子类型，normal | anonymous | notice。
• sender: GroupSender，发送者信息，参见下文。

便捷方法：

• await reply(text=None, image=None, at=True, space=True, rtf=None) -> str：在群内回复，默认 at 发送者并引用原消息，返回消息 ID；
• await delete()：撤回该消息；
• await kick()：踢出发送者；
• await ban(ban_duration=30)：禁言发送者（秒）。
• 方法名后缀加 _sync 即同步调用。

典型使用（BotClient 装饰器）：

@bot.on_group_message()
async def on_group(e: GroupMessageEvent):
    if "ping" in e.raw_message:
        e.reply_sync("pong 1")
        await e.reply("pong 2")

---

PrivateMessageEvent（私聊消息）

关键字段（只列核心）：

• 包括 BaseMessageEvent 的所有字段。
• sub_type: str，消息子类型，friend | group | other。
• sender: PrivateSender，发送者信息，参见下文。

便捷方法：

• await reply(text=None, image=None, rtf=None) -> str：私聊回复，会自动引用原消息，返回消息 ID；

---

MessageSendEvent（自身消息）

关键字段（只列核心）：

• 包括BaseEventData 的所有字段。
• message_sent_type: str，消息发送者类型，上报为自身消息时为self。

便携方法：

• await reply(text=None, image=None, rtf=None) -> str:便携回复自身消息，可自动判断回复群消息还是私聊消息；
• is_group_msg(): 判断是否为群消息；
• is_private_msg(): 判断是否为私聊消息；
• delete(): 撤回本条消息。

Sender（消息发送者信息）

BaseSender（基础发送者信息）

关键字段：

• user_id: str，发送者 QQ 号
• nickname: str，发送者昵称

GroupSender（群消息发送者）

关键字段：

• 包括 BaseSender 的所有字段。
• card: str，群名片/备注
• level: int，成员等级
• role: str，成员角色，owner | admin | member
• title: str，成员专属头衔，如果无，则为 None。

PrivateSender（私聊消息发送者）

关键字段：

• 包括 BaseSender 的所有字段。

RequestEvent（请求）

实战案例

用于处理「加好友」或「加群」请求。

关键字段：

• 包括 BaseEventData 的所有字段。
• request_type：friend | group
• flag：请求标识（用于执行通过/拒绝操作）
• comment：验证信息。

便捷方法：

• is_group_request()：判断是否为加群请求
• is_friend_request()：判断是否为加好友请求
• await approve(approve=True, remark=None, reason=None)：
  • request_type 为 friend：可传 remark 作为通过后的好友备注；
  • request_type 为 group：可传 reason 作为拒绝理由；
  • 内部会调用 set_friend_add_request 或 set_group_add_request。

示例：

@bot.on_request(filter="group")
async def on_group_request(e: RequestEvent):
    await e.approve(approve=True)  # 通过加群

---

NoticeEvent（通知）

承载群文件上传、成员变更、撤回、禁言、戳一戳等通知。

关键字段：

• 包括 BaseEventData 的所有字段。
• notice_type：通知类型

notice_type 字段选项：

• group_upload
• group_admin
• group_decrease
• group_increase
• friend_add
• group_recall
• group_ban
• notify
• group_msg_emoji_like ...

更多详细信息参考OneBot 事件文档。

group_increase（群成员增加）

关键字段：

• group_id：群号
• user_id：新成员 QQ 号
• operator_id：操作者 QQ 号（邀请者）
• sub_type：事件子类型，approve | invite，分别表示管理员已同意入群、管理员邀请入群。

group_decrease（群成员减少）

关键字段：

• group_id：群号
• user_id：离开者 QQ 号
• operator_id：操作者 QQ 号（如果是主动退群，则和 user_id 相同）
• sub_type：事件子类型，leave | kick | kick_me，分别表示主动退群、成员被踢、登录号被踢。

group_recall（群消息撤回）

关键字段：

• group_id：群号
• user_id：消息发送者 QQ 号
• operator_id：操作者 QQ 号（如果是自己撤回，则和 user_id 相同）
• message_id：被撤回的消息 ID

group_msg_emoji_like（群消息表情回应）

关键字段：

• group_id：群号
• user_id：点赞者 QQ 号
• message_id：被点赞的消息 ID
• emoji_like_id：表情 ID
• is_add：是否为新增回应 (bool)

---

与 BotAPI 的协作

这些事件对象的方法（如 reply/approve/delete/ban）本质上都是对 `` 的便捷封装：

• GroupMessageEvent → 调用 post_group_msg/set_group_ban/delete_msg/...
• PrivateMessageEvent → 调用 post_private_msg 等
• RequestEvent → 调用 set_friend_add_request/set_group_add_request

因此你既可以用事件自带的方法快速完成处理，也可以直接使用 BotAPI 获得更细粒度的控制（如发送转发消息、贴表情、OCR 等）。

版权所有

版权归属：huan-yp

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