注册功能

约 752 字大约 3 分钟

2025-03-27

注意

这是 3.x.y 版本的常用方法；从 4.0.0 版本起，更推荐使用统一命令注册器来注册命令和功能。

使用功能

功能是对事件发布和处理的进一步封装, 使用功能可以方便快捷的接入 NcatBot 的权限管理机制.

功能的运作对象是消息事件, 只有群聊和私聊消息事件才会进行下面的判定.

注册功能

注册功能需要在插件==加载时==进行.

以下函数用于注册功能:

def register_user_func(
    self,
    name: str,
    handler: Callable[[BaseMessageEvent], Any],
    filter: Callable = None,
    prefix: str = None,
    regex: str = None,
    description: str = "",
    usage: str = "",
    examples: List[str] = None,
    tags: List[str] = None,
    metadata: Dict[str, Any] = None,
    timeout: float = None,
) -> Func:
  ...

def register_admin_func(...)

`register_user_func`

注册一个用户功能, 如果能满足触发条件则触发该功能.

name: 功能名称, 用于建立权限结构, 该功能的权限路径为 <plugin_name>.<name>. 功能.
handler: 功能处理函数, 接受一个 BaseMessageEvent 类型的参数, .
filter: 自定义过滤函数, 接受一个 NcatBotEvent 类型的参数, 返回布尔值表示是否触发功能. 如果为 None 则不进行过滤.
prefix: 前缀匹配字符串, 如果消息以该前缀开头则触发功能. 例如 prefix="/help" 会匹配以 "/help" 开头的消息.
regex: 正则表达式字符串, 如果消息匹配该正则表达式则触发功能. 例如 regex="\d*" 会匹配包含任意数量数字的消息. 可以使用 Python 的 re 模块支持的所有正则表达式语法.
description: 功能描述, 用于帮助文档.
permission_raise: 是否针对群聊提权, 如果 user_id (消息发送者 QQ 号) 为 admin 级别及以上权限, 则临时提升消息来源群聊的权限为 root. 私聊被分在一个特殊的群组, 权限为 root.
usage: 使用说明, 用于帮助文档.
examples: 使用示例列表, 用于帮助文档.
tags: 功能标签列表, 用于功能分类.
metadata: 额外元数据字典, 可以存储任意自定义数据.