nonebot2/website/versioned_docs/version-2.0.0-beta.2/api/plugin/on.md
2022-02-14 16:27:11 +00:00

25 KiB

sidebar_position description
2 nonebot.plugin.on 模块

nonebot.plugin.on

本模块定义事件响应器便携定义函数。

def on(type='', rule=..., permission=..., *, handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个基础事件响应器,可自定义类型。

  • 参数

    • type (str): 事件响应器类型

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

def on_metaevent(rule=..., *, handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个元事件响应器。

  • 参数

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

def on_message(rule=..., permission=..., *, handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器。

  • 参数

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

def on_notice(rule=..., *, handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个通知事件响应器。

  • 参数

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

def on_request(rule=..., *, handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个请求事件响应器。

  • 参数

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

def on_startswith(msg, rule=..., ignorecase=..., *, permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器,并且当消息的文本部分以指定内容开头时响应。

  • 参数

    • msg (str | tuple[str, ...]): 指定消息开头内容

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • ignorecase (bool): 是否忽略大小写

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

def on_endswith(msg, rule=..., ignorecase=..., *, permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器,并且当消息的文本部分以指定内容结尾时响应。

  • 参数

    • msg (str | tuple[str, ...]): 指定消息结尾内容

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • ignorecase (bool): 是否忽略大小写

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

def on_keyword(keywords, rule=..., *, permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器,并且当消息纯文本部分包含关键词时响应。

  • 参数

    • keywords (set[str]): 关键词列表

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

def on_command(cmd, rule=..., aliases=..., *, permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器,并且当消息以指定命令开头时响应。

    命令匹配规则参考: 命令形式匹配 <rule.md#command-command>_

  • 参数

    • cmd (str | tuple[str, ...]): 指定命令内容

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • aliases (set[str | tuple[str, ...]] | None): 命令别名

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

def on_shell_command(cmd, rule=..., aliases=..., parser=..., *, permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个支持 shell_like 解析参数的命令消息事件响应器。

    与普通的 on_command 不同的是,在添加 parser 参数时, 响应器会自动处理消息。

    并将用户输入的原始参数列表保存在 state["argv"], parser 处理的参数保存在 state["args"]

  • 参数

    • cmd (str | tuple[str, ...]): 指定命令内容

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • aliases (set[str | tuple[str, ...]] | None): 命令别名

    • parser (ArgumentParser | None): nonebot.rule.ArgumentParser 对象

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

def on_regex(pattern, flags=..., rule=..., *, permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器,并且当消息匹配正则表达式时响应。

    命令匹配规则参考: 正则匹配 <rule.md#regex-regex-flags-0>_

  • 参数

    • pattern (str): 正则表达式

    • flags (int | re.RegexFlag): 正则匹配标志

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

class CommandGroup(cmd, *, rule=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 参数

    • cmd (str | tuple[str, ...])

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType)

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType)

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None)

    • temp (bool)

    • priority (int)

    • block (bool)

    • state (dict[Any, Any] | None)

instance-var basecmd

  • 类型:

  • 说明: 命令前缀

instance-var base_kwargs

  • 类型:

  • 说明: 其他传递给 on_command 的参数默认值

method command(self, cmd, *, aliases, rule=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个新的命令。

  • 参数

    • cmd (str | tuple[str, ...]): 命令前缀

      **kwargs: on_command 的参数,将会覆盖命令组默认值

    • aliases (set[str | tuple[str, ...]] | None)

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType)

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType)

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None)

    • temp (bool)

    • priority (int)

    • block (bool)

    • state (dict[Any, Any] | None)

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

method shell_command(self, cmd, *, rule=..., aliases, parser=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个新的命令。

  • 参数

    • cmd (str | tuple[str, ...]): 命令前缀

      **kwargs: on_shell_command 的参数,将会覆盖命令组默认值

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType)

    • aliases (set[str | tuple[str, ...]] | None)

    • parser (ArgumentParser | None)

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType)

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None)

    • temp (bool)

    • priority (int)

    • block (bool)

    • state (dict[Any, Any] | None)

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

class MatcherGroup(*, type=..., rule=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 参数

    • type (str)

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType)

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType)

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None)

    • temp (bool)

    • priority (int)

    • block (bool)

    • state (dict[Any, Any] | None)

instance-var matchers

  • 类型:

  • 说明: 组内事件响应器列表

instance-var base_kwargs

  • 类型:

  • 说明: 其他传递给 on 的参数默认值

method on(self, *, type=..., rule=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个基础事件响应器,可自定义类型。

  • 参数

    • type (str): 事件响应器类型

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

method on_command(self, cmd, aliases=..., *, rule=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器,并且当消息以指定命令开头时响应。

    命令匹配规则参考: 命令形式匹配 <rule.md#command-command>_

  • 参数

    • cmd (str | tuple[str, ...]): 指定命令内容

    • aliases (set[str | tuple[str, ...]] | None): 命令别名

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

method on_endswith(self, msg, *, ignorecase=..., rule=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器,并且当消息的文本部分以指定内容结尾时响应。

  • 参数

    • msg (str | tuple[str, ...]): 指定消息结尾内容

    • ignorecase (bool): 是否忽略大小写

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

method on_keyword(self, keywords, *, rule=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器,并且当消息纯文本部分包含关键词时响应。

  • 参数

    • keywords (set[str]): 关键词列表

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

method on_message(self, *, rule=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器。

  • 参数

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

method on_metaevent(self, *, rule=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个元事件响应器。

  • 参数

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

method on_notice(self, *, rule=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个通知事件响应器。

  • 参数

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

method on_regex(self, pattern, flags=..., *, rule=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器,并且当消息匹配正则表达式时响应。

    命令匹配规则参考: 正则匹配 <rule.md#regex-regex-flags-0>_

  • 参数

    • pattern (str): 正则表达式

    • flags (int | re.RegexFlag): 正则匹配标志

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

method on_request(self, *, rule=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个请求事件响应器。

  • 参数

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

method on_shell_command(self, cmd, aliases=..., parser=..., *, rule=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个支持 shell_like 解析参数的命令消息事件响应器。

    与普通的 on_command 不同的是,在添加 parser 参数时, 响应器会自动处理消息。

    并将用户输入的原始参数列表保存在 state["argv"], parser 处理的参数保存在 state["args"]

  • 参数

    • cmd (str | tuple[str, ...]): 指定命令内容

    • aliases (set[str | tuple[str, ...]] | None): 命令别名

    • parser (ArgumentParser | None): nonebot.rule.ArgumentParser 对象

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]

method on_startswith(self, msg, *, ignorecase=..., rule=..., permission=..., handlers=..., temp=..., priority=..., block=..., state=...)

  • 说明

    注册一个消息事件响应器,并且当消息的文本部分以指定内容开头时响应。

  • 参数

    • msg (str | tuple[str, ...]): 指定消息开头内容

    • ignorecase (bool): 是否忽略大小写

    • rule (nonebot.internal.rule.Rule | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应规则

    • permission (nonebot.internal.permission.Permission | (*Any, **Any) -> bool | Awaitable[bool] | NoneType): 事件响应权限

    • handlers (list[(*Any, **Any) -> Any | Dependent] | None): 事件处理函数列表

    • temp (bool): 是否为临时事件响应器(仅执行一次)

    • priority (int): 事件响应器优先级

    • block (bool): 是否阻止事件向更低优先级传递

    • state (dict[Any, Any] | None): 默认 state

  • 返回

    • Type[nonebot.internal.matcher.Matcher]