diff --git a/website/docs/advanced/permission.md b/website/docs/advanced/permission.md index ef9a0701..7217ebc7 100644 --- a/website/docs/advanced/permission.md +++ b/website/docs/advanced/permission.md @@ -11,7 +11,7 @@ options: ## 应用 -如同 `Rule` 一样,`Permission` 可以在[注册事件响应器](../tutorial/plugin/create-matcher.md)时添加 `permission` 参数来加以应用,这样 NoneBot2 会在事件响应时检测事件主体的权限。下面我们以 `SUPERUSER` 为例,对该机制的应用做一下介绍。 +如同 `Rule` 一样,`Permission` 可以在[定义事件响应器](../tutorial/plugin/create-matcher.md)时添加 `permission` 参数来加以应用,这样 NoneBot2 会在事件响应时检测事件主体的权限。下面我们以 `SUPERUSER` 为例,对该机制的应用做一下介绍。 ```python from nonebot.permission import SUPERUSER diff --git a/website/docs/advanced/rule.md b/website/docs/advanced/rule.md new file mode 100644 index 00000000..d333a825 --- /dev/null +++ b/website/docs/advanced/rule.md @@ -0,0 +1,72 @@ +--- +options: + menu: + weight: 30 + category: advanced +--- + +# 自定义匹配规则 + +机器人在实际应用中,往往会接收到多种多样的事件类型,NoneBot2 提供了可自定义的匹配规则 ── `Rule`。在[定义事件响应器](../tutorial/plugin/create-matcher.md#创建事件响应器)中,已经介绍了多种内置的事件响应器,接下来我们将说明自定义匹配规则的基本用法。 + +## 创建匹配规则 + +匹配规则可以是一个 `Rule` 对象,也可以是一个 `RuleChecker` 类型。`Rule` 是多个 `RuleChecker` 的集合,只有当所有 `RuleChecker` 检查通过时匹配成功。`RuleChecker` 是一个返回值为 `Bool` 类型的依赖函数,即,`RuleChecker` 支持依赖注入。 + +### 创建 `RuleChecker` + +```python {1-2} +async def user_checker(event: Event) -> bool: + return event.get_user_id() == "123123" + +matcher = on_message(rule=user_checker) +``` + +在上面的代码中,我们定义了一个函数 `user_checker`,它检查事件的用户 ID 是否等于 `"123123"`。这个函数 `user_checker` 即为一个 `RuleChecker`。 + +### 创建 `Rule` + +```python {1-2,4-5,7} +async def user_checker(event: Event) -> bool: + return event.get_user_id() == "123123" + +async def message_checker(event: Event) -> bool: + return event.get_plaintext() == "hello" + +rule = Rule(user_checker, message_checker) +matcher = on_message(rule=rule) +``` + +在上面的代码中,我们定义了两个函数 `user_checker` 和 `message_checker`,它们检查事件的用户 ID 是否等于 `"123123"`,以及消息的内容是否等于 `"hello"`。随后,我们定义了一个 `Rule` 对象,它包含了这两个函数。 + +## 注册匹配规则 + +在[定义事件响应器](../tutorial/plugin/create-matcher.md#创建事件响应器)中,我们已经了解了如何事件响应器的组成。现在,我们仅需要将匹配规则注册到事件响应器中。 + +```python {4} +async def user_checker(event: Event) -> bool: + return event.get_user_id() == "123123" + +matcher = on_message(rule=user_checker) +``` + +在定义事件响应器的辅助函数中,都有一个 `rule` 参数,用于指定自定义的匹配规则。辅助函数会为你将自定义匹配规则与内置规则组合,并注册到事件响应器中。 + +## 合并匹配规则 + +在定义匹配规则时,我们往往希望将规则进行细分,来更好地复用规则。而在使用时,我们需要合并多个规则。除了使用 `Rule` 对象来组合多个 `RuleChecker` 外,我们还可以对 `Rule` 对象进行合并。 + +```python {4-6} +rule1 = Rule(foo_checker) +rule2 = Rule(bar_checker) + +rule = rule1 & rule2 +rule = rule1 & bar_checker +rule = foo_checker & rule2 +``` + +同时,你也无需担心合并了一个 `None` 值,`Rule` 会忽略 `None` 值。 + +```python +assert (rule & None) is rule +``` diff --git a/website/docs/tutorial/plugin/create-matcher.md b/website/docs/tutorial/plugin/create-matcher.md index b6a834ff..7e408579 100644 --- a/website/docs/tutorial/plugin/create-matcher.md +++ b/website/docs/tutorial/plugin/create-matcher.md @@ -41,7 +41,7 @@ async def update_type(): 事件响应器的匹配规则是一个 `Rule` 对象,它是一系列 `checker` 的集合,当所有的 `checker` 都返回 `True` 时,才会触发该响应器。 -规则编写方法参考[自定义规则](#自定义规则)。 +规则编写方法参考[进阶 - 自定义规则](../../advanced/rule.md)。 :::warning 注意 当会话状态更新时,`rule` 会被清空,以便会话收到新事件时能够正确匹配。 @@ -51,7 +51,7 @@ async def update_type(): 事件响应器的触发权限是一个 `Permission` 对象,它也是一系列 `checker` 的集合,当其中一个 `checker` 返回 `True` 时,就会触发该响应器。 -权限编写方法参考[自定义权限](#自定义权限)。 +权限编写方法参考[进阶 - 自定义权限](../../advanced/permission.md)。 :::warning 注意 与 `rule` 不同的是,`permission` 不会在会话状态更新时丢失,因此 `permission` 通常用于会话的响应控制。 @@ -131,9 +131,3 @@ matcher = on_message() 14. `MatcherGroup`: 创建具有共同参数的响应器组。 其中,`on_metaevent` `on_message` `on_request` `on_notice` 函数都是在 `on` 的基础上添加了对应的事件类型 `type`;`on_startswith` `on_endswith` `on_fullmatch` `on_keyword` `on_command` `on_shell_command` `on_regex` 函数都是在 `on_message` 的基础上添加了对应的匹配规则 `rule`。 - -## 自定义规则 - - - -## 自定义权限