NcatBot 文档

外观

事件上报

约 1022 字大约 3 分钟

2025-02-07

事件

NcatBot 的事件分两类, 一类是由 NapCat 上报的官方事件, 一类是由插件上报的自定义事件

每种事件有一个唯一的事件类型, 事件类型是一个用 . 分割的多级字符串.

官方事件类型

官方事件类型的字面量如下:

OFFICIAL_GROUP_MESSAGE_EVENT = "ncatbot.group_message_event"
OFFICIAL_PRIVATE_MESSAGE_EVENT = "ncatbot.private_message_event"
OFFICIAL_REQUEST_EVENT = "ncatbot.request_event"
OFFICIAL_NOTICE_EVENT = "ncatbot.notice_event"

自定义事件类型

参阅事件的发布和订阅.

官方事件上报

为不同事件注册回调函数

参考以下代码:

python
from ncatbot.core import BotClient
from ncatbot.core.message import GroupMessage, PrivateMessage

bot = BotClient()

@bot.group_event()
async def on_group_message(msg:GroupMessage): # 绑定群聊消息回调函数
    _log.info(msg)

@bot.private_event()
async def on_private_message(msg:PrivateMessage): # 绑定私聊消息回调函数
    _log.info(msg)

@bot.notice_event() 
async def on_notice_message(msg): # 绑定通知消息回调函数
    _log.info(msg)

@bot.request_event()
async def on_request_message(msg): # 绑定请求消息回调函数
    _log.info(msg)

BotClient.group_event(), BotClient.private_event(), BotClient.notice_event() 和 BotClient.request_event() 分别是四种消息类型的回调函数注册修饰器.

回调函数注册修饰器参数(实验性功能)

注意

该功能处于实验阶段, 不建议无基础知识的开发者使用.

回调函数注册修饰器接受一个 types 参数, 用于指定回调函数监听的细化事件类型.

types 是一个列表, 其中每个元素都是一个字符串, 一个元素指代一种消息类型. 如果收到的消息包含 types 中的任意一个类型, 回调函数就会被调用.

目前支持的类型有:

消息格式介绍
text纯文本
faceqq 表情
image图片
record语音
video视频
at@某人
rps猜拳魔法表情
dice骰子
shake私聊窗口抖动
poke群聊戳一戳
share<JSON>链接分享
contact<JSON>推荐好友/群
location<JSON>位置
music<JSON>音乐分享
reply回复消息
forward转发消息
node转发消息节点
jsonjson 信息
mfaceqq 表情包
file文件
markdownmarkdown
lightapp<JSON>小程序卡片

举个例子, 如果你想要监听群聊的文本消息, 你可以这样注册:

python
from ncatbot.core.client import BotClient
from ncatbot.core.message import GroupMessage

bot = BotClient()

@bot.group_event(["text"])
async def on_group_message(msg:GroupMessage):

需要注意的是: 只要消息内存在文本, 这个消息就会被监听, 而不是纯文本才会被监听.

事件上报代码

参阅事件的发布和订阅 以及下面的源代码.

python
async def handle_group_event(self, msg: dict):
    msg: GroupMessage = GroupMessage(msg)
    for handler, types in self._group_event_handlers:
        if types is None or any(i["type"] in types for i in msg.message):
            await handler(msg)
    await self.plugin_sys.event_bus.publish_async(
        Event(OFFICIAL_GROUP_MESSAGE_EVENT, msg, EventSource(msg.user_id, msg.group_id),)
    )
async def handle_notice_event(self, msg: dict):
    _log.debug(msg)
    for handler in self._notice_event_handlers:
        await handler(msg)
    await self.plugin_sys.event_bus.publish_async(Event(OFFICIAL_NOTICE_EVENT, msg))

官方事件发生的条件

  • group_event: 收到群聊消息时发生, 效果是触发所有绑定的回调函数并上报到事件总线.
    • 传入回调函数的参数是 GroupMessage 实例.
    • 传入事件总线的参数是 Event 实例, 所带的数据(Event.data)为 GroupMessage 实例.
  • private_event: 收到私聊消息时发生, 其余同上, 区别是 GroupMessage 换为 PrivateMessage.
  • notice_event: 收到通知信息时发生, 效果是触发所有绑定的回调函数并上报到事件总线.
    • 传入回调函数的参数是一个 dict.
    • 传入事件总线的参数 Event 实例, 所带的数据(Event.data)为 dict.
  • request_event: 收到请求信息时发生, 其余同上.

具体参数参阅回调函数

四种消息的定义

  • 群聊消息: 略
  • 私聊消息: 略
  • 通知消息: 咕咕咕
  • 请求消息: 咕咕咕

自定义事件上报

参阅事件的发布和订阅

版权归属：huan-yp

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

© 2025 NcatBot