NcatBot 文档

外观

回调函数

约 1236 字大约 4 分钟

2025-02-07

回调函数机制

NcatBot 采用回调函数机制来完成事件上报. 回调函数是用户自定义的异步函数. 当对应事件发生时, NcatBot 会调用这些函数, 并将事件相关信息作为参数传递.

注册回调函数

NcatBot 要求所有回调函数都是异步函数, 也就是必须用 async def 而不是 def 来定义.

并且, 在定义的上一行, 需要加上回调函数注册修饰器(@bot.xxxx_event())来明确回调函数所绑定的 BotClient 实例以及事件类型.

python
@bot.private_event() # 为 bot 的私聊事件注册回调函数
async def on_private_message(msg: PrivateMessage):
    _log.info(msg)
    if msg.raw_message == '测试':
        await bot.api.post_private_msg(msg.user_id, text="NcatBot 测试成功喵~")

Ncatbot 对回调函数的名字没有要求, 但按照习惯一般命名为 on_[事件类型].

线程安全提醒猫: 异步千万条, 安全第一条, 线程不安全, 数据两行泪.

回调函数注册修饰器

回调函数需要通过回调函数注册修饰器来绑定到 BotClient 实例对应的事件类型上.

回调函数注册修饰器是 BotClient 类的成员函数, 用回调函数注册修饰器进行绑定后, 对应 BotClient 实例发生对应事件时, 会调用绑定的的回调函数.

python
@bot.private_event()
async def on_private_message(msg: PrivateMessage):
    _log.info(msg)
    if msg.raw_message == '测试':
        await bot.api.post_private_msg(msg.user_id, text="NcatBot 测试成功喵~")

bot 是一个 BotClient 实例, 使用 bot.private_event() 作为修饰器来注册回调函数.

回调函数注册修饰器列表请查阅 事件上报.

对初学者的提醒

装饰器是一种非常强大的功能, 它允许你在不修改原有函数代码的情况下, 动态地增加函数的功能. 装饰器本质上是一个返回函数的函数. 为了更好地理解装饰器的原理, 我们结合前面提到的示例来详细解释:

  1. 装饰器的实现

    1. 定义装饰器函数: 装饰器函数接收一个函数作为参数. 在装饰器内部, 定义一个嵌套函数 (通常称为 wrapper), 这个嵌套函数会增强或修改原函数的行为.
    2. 返回嵌套函数: 装饰器函数返回嵌套函数, 这样原函数就被替换为嵌套函数.
    3. 使用装饰器: 使用 @装饰器名称 语法, 将装饰器应用到目标函数上.

  2. 装饰器的本质

相应的代码如下:

class BotClient:
    def __init__(self, use_ws=True):
        # 喵~

    def group_event(self, types=None):
        def decorator(func):
            self._group_event_handlers.append((func, types))
            return func

        return decorator

于是:

@bot.group_event()
async def on_group_message(msg: GroupMessage):
    _log.info(msg)

的本质是: on_group_message = bot.group_event()(on_group_message), 等价于执行 bot._group_event_handlers.append((on_group_message, None)).

可选参数 types 的作用可以查阅事件上报部分的文档了解.

"装饰器" 和 "修饰器" 都是 "decorator" 的译名, 有一部分是彭彭手写的, 一部分是 AI 写的, 所以出现了差异喵~

回调函数参数

如何对事件做出回复, 事件回调函数的参数是什么?

用户自定义的回调函数接受一个 msg 参数, 该参数描述了上报事件的详细信息.

Message 类型回调函数参数

此类型包括群聊消息和私聊消息.

python
@bot.group_event()
async def on_group_message(msg: GroupMessage):
    _log.info(msg)

msg 是一个 BaseMessage 的派生类, 其成员均符合 OneBot11 标准.

msg 的成员表如下, 有关成员含义的更详细的信息可以参考 OneBot11 消息事件:

  • msg.user_id: Union(str, int): 消息发送者 QQ 号.
  • msg.group_id: Union(str, int): 消息来源群群号(如果是群聊消息).
  • msg.message_id: Union(str, int): 消息 ID.
  • msg.message_seq: Union(str, int): 同上.
  • msg.real_id: Union(str, int): 同上.
  • msg.message_type: str: 消息类型(group/private).
  • msg.sub_type: str: 消息子类型(friend, group, other).
  • msg.raw_message: str: 符合 OneBot11 标准的消息字符串, 需手动解析, 不建议使用.
  • msg.sender: Sender: 消息发送者资料.
  • msg.message: List[dict]: 符合 OneBot11 标准的数组格式消息, 推荐使用它来进行逻辑判断.
  • msg.message_format: str: 消息格式(string/json/markdown).
  • msg.self_id: Union(str, int): 机器人 QQ 号.
  • msg.post_type: str: 事件类型(message/notice/request).
  • msg.time: int: 事件发生时间戳.

常用参考资料:

Notice 类型回调函数参数

msg 是一个 dict, 支持的操作见 NapCat 文档.

以下给出几个常见的事件:

Request 类型回调函数参数

msg 是一个 dict, 支持的操作见 NapCat 文档.

以下给出几个常见的事件:

版权归属：huan-yp

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

© 2025 NcatBot