nonebot2/website/docs/advanced/rule.md
Ju4tCode 91f4daa722
📝 add custom rule guide (#914)
Co-authored-by: StarHeart <starheart233@gmail.com>
2022-04-16 10:20:01 +08:00

73 lines
2.8 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

---
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
```