mirror of
https://github.com/nonebot/nonebot2.git
synced 2024-11-27 18:45:05 +08:00
📝 finish plugin guide
This commit is contained in:
yanyongyu
parent
47b1affc56
commit
9803925bbb
@ -105,7 +105,8 @@ module.exports = context => ({
|
||||
"loading-a-plugin",
|
||||
"creating-a-plugin",
|
||||
"creating-a-matcher",
|
||||
"creating-a-handler"
|
||||
"creating-a-handler",
|
||||
"end-or-start"
|
||||
]
|
||||
}
|
||||
],
|
||||
|
||||
@ -47,6 +47,33 @@ async def handle_city(bot: Bot, event: Event, state: dict):
|
||||
|
||||
#### got(key, prompt, args_parser)
|
||||
|
||||
指示 NoneBot 当 `state` 中不存在 `key` 时向用户发送 `prompt` 等待用户回复并赋值给 `state[key]`。
|
||||
|
||||
`prompt` 可以为 `str`, `Message`, `MessageSegment`，若为空则不会向用户发送，若不为空则会在 format 之后发送，即 `prompt.format(**state)`，注意对 `{}` 进行转义。示例：
|
||||
|
||||
```python
|
||||
@matcher.receive()
|
||||
async def handle(bot: Bot, event: Event, state: dict):
|
||||
state["key"] = "hello"
|
||||
|
||||
|
||||
@matcher.got("key2", prompt="{key}!")
|
||||
async def handle2(bot: Bot, event: Event, state: dict):
|
||||
pass
|
||||
```
|
||||
|
||||
`args_parser` 为参数处理函数，在这里传入一个新的函数以覆盖默认的参数处理。详情参照 [args_parser](#参数处理函数-args-parser)
|
||||
|
||||
|
||||
特别的，这些装饰器都可以套娃使用：
|
||||
|
||||
```python
|
||||
@matcher.got("key1")
|
||||
@matcher.got("key2")
|
||||
async def handle(bot: Bot, event: Event, state: dict):
|
||||
pass
|
||||
```
|
||||
|
||||
### 事件处理函数参数
|
||||
|
||||
事件处理函数类型为 `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` 。
|
||||
@ -55,8 +82,78 @@ async def handle_city(bot: Bot, event: Event, state: dict):
|
||||
|
||||
1. [nonebot.typing.Bot](../api/typing.md#bot): 即事件上报连接对应的 Bot 对象，为 BaseBot 的子类。特别注意，此处的类型注释可以替换为指定的 Bot 类型，例如：`nonebot.adapters.cqhttp.Bot`，只有在上报事件的 Bot 类型与类型注释相符时才会执行该处理函数！可用于多平台进行不同的处理。
|
||||
2. [nonebot.typing.Event](../api/typing.md#event): 即上报事件对象，可以获取到上报的所有信息。
|
||||
3. `state`: 状态字典，可以存储任意的信息
|
||||
3. `state`: 状态字典，可以存储任意的信息，其中还包含一些特殊的值以获取 NoneBot 内部处理时的一些信息，如：
|
||||
- `state["_current_key"]`: 存储当前 `got` 获取的参数名
|
||||
- `state["_prefix"]`, `state["_suffix"]`: 存储当前 TRIE 匹配的前缀/后缀，可以通过该值获取用户命令的原始命令
|
||||
|
||||
### 参数处理函数 args_parser
|
||||
|
||||
在使用 `got` 获取用户输入参数时，需要对用户的消息进行处理以转换为我们所需要的信息。在默认情况下，NoneBot 会把用户的消息字符串原封不动的赋值给 `state[key]` 。可以通过以下两种方式修改默认处理逻辑：
|
||||
|
||||
- `@matcher.args_parser` 装饰器：直接装饰一个函数作为参数处理器
|
||||
- `got(key, prompt, args_parser)`：直接把函数作为参数传入
|
||||
|
||||
参数处理函数类型为：`Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]`，即：
|
||||
|
||||
```python
|
||||
async def parser(bot: Bot, event: Event, state: dict):
|
||||
state[state["_current_key"]] = str(event.message)
|
||||
```
|
||||
|
||||
特别的，`state["_current_key"]` 中存储了当前获取的参数名
|
||||
|
||||
### 逻辑控制
|
||||
|
||||
NoneBot 也为事件处理函数提供了一些便捷的逻辑控制函数：
|
||||
|
||||
#### `matcher.send`
|
||||
|
||||
这个函数用于发送一条消息给当前交互的用户。~~其实这并不是一个逻辑控制函数，只是不知道放在哪里……~~
|
||||
|
||||
#### `matcher.pause`
|
||||
|
||||
这个函数用于结束当前事件处理函数，强制接收一条新的消息再运行**下一个消息处理函数**。
|
||||
|
||||
#### `matcher.reject`
|
||||
|
||||
这个函数用于结束当前事件处理函数，强制接收一条新的消息再**再次运行当前消息处理函数**。常用于用户输入信息不符合预期。
|
||||
|
||||
#### `matcher.finish`
|
||||
|
||||
这个函数用于直接结束当前事件处理。
|
||||
|
||||
以上三个函数都拥有一个参数 `message` / `prompt`，用于向用户发送一条消息。以及 `**kwargs` 直接传递给 `bot.send` 的额外参数。
|
||||
|
||||
## 常用事件处理结构
|
||||
|
||||
```python
|
||||
matcher = on_command("test")
|
||||
|
||||
# 修改默认参数处理
|
||||
@matcher.args_parser
|
||||
async def parse(bot: Bot, event: Event, state: dict):
|
||||
print(state["_current_key"], ":", str(event.message))
|
||||
state[state["_current_key"]] = str(event.message)
|
||||
|
||||
@matcher.handle()
|
||||
async def first_receive(bot: Bot, event: Event, state: dict):
|
||||
# 获取用户原始命令，如：/test
|
||||
print(state["_prefix"]["raw_command"])
|
||||
# 处理用户输入参数，如：/test arg1 arg2
|
||||
raw_args = str(event.message).strip()
|
||||
if raw_args:
|
||||
arg_list = raw_args.split()
|
||||
# 将参数存入state以阻止后续再向用户询问参数
|
||||
state["arg1"] = arg_list[0]
|
||||
|
||||
|
||||
@matcher.got("arg1", prompt="参数？")
|
||||
async def arg_handle(bot: Bot, event: Event, state: dict):
|
||||
# 在这里对参数进行验证
|
||||
if state["arg1"] not in ["allow", "list"]:
|
||||
await matcher.reject("参数不正确！请重新输入")
|
||||
# 发送一些信息
|
||||
await bot.send("message")
|
||||
await matcher.send("message")
|
||||
await matcher.finish("message")
|
||||
```
|
||||
|
||||
@ -142,88 +142,4 @@ Rule(async_checker1) & sync_checker & async_checker2
|
||||
:::danger 警告
|
||||
`Rule(*checkers)` 只接受 async function，或使用 `nonebot.utils.run_sync` 自行包裹 sync function。在使用 `与 &` 时，NoneBot 会自动包裹 sync function
|
||||
:::
|
||||
|
||||
### 编写事件处理函数 [Handler](../api/typing.md#handler)
|
||||
|
||||
```python{1,2,8,9}
|
||||
@weather.handle()
|
||||
async def handle_first_receive(bot: Bot, event: Event, state: dict):
|
||||
args = str(event.message).strip() # 首次发送命令时跟随的参数，例：/天气 上海，则args为上海
|
||||
if args:
|
||||
state["city"] = args # 如果用户发送了参数则直接赋值
|
||||
|
||||
|
||||
@weather.got("city", prompt="你想查询哪个城市的天气呢？")
|
||||
async def handle_city(bot: Bot, event: Event, state: dict):
|
||||
city = state["city"]
|
||||
if city not in ["上海", "北京"]:
|
||||
await weather.reject("你想查询的城市暂不支持，请重新输入！")
|
||||
city_weather = await get_weather(city)
|
||||
await weather.finish(city_weather)
|
||||
```
|
||||
|
||||
在上面的代码中，我们给 `weather` 事件响应器添加了两个事件处理函数：`handle_first_receive`, `handle_city`
|
||||
|
||||
其中有几个要点，我们一一解释：
|
||||
|
||||
#### 添加一个事件处理函数
|
||||
|
||||
在事件响应器响应事件时，事件处理函数会依次顺序执行，也就是说，与添加顺序一致。
|
||||
|
||||
我们可以使用 `@matcher.handle()` 装饰器来简单地为该事件响应器添加一个处理函数。
|
||||
|
||||
同时，NoneBot 内置了几种添加事件处理函数方式以方便处理：
|
||||
|
||||
- `@matcher.receive()`: 指示 NoneBot 接收一条新的用户消息以继续执行后续处理函数。
|
||||
- `@matcher.got(key, [prompt="请输入key"], [args_parser=function])`: 指示 NoneBot 当 `state` 中不存在 `key` 时向用户发送 `prompt` 等待用户回复并赋值给 `state[key]`
|
||||
|
||||
这些装饰器可以套娃使用！例如：
|
||||
|
||||
```python
|
||||
@matcher.got("key1")
|
||||
@matcher.got("key2")
|
||||
async def handle(bot: Bot, event: Event, state: dict):
|
||||
pass
|
||||
```
|
||||
|
||||
#### 事件处理函数参数
|
||||
|
||||
事件处理函数类型为 `Callable[[Bot, Event, dict], Union[Awaitable[None], Awaitable[NoReturn]]]` 。
|
||||
|
||||
参数分别为：
|
||||
|
||||
1. [nonebot.typing.Bot](../api/typing.md#bot): 即事件上报连接对应的 Bot 对象，为 BaseBot 的子类。特别注意，此处的类型注释可以替换为指定的 Bot 类型，例如：`nonebot.adapters.cqhttp.Bot`，只有在上报事件的 Bot 类型与类型注释相符时才会执行该处理函数！可用于多平台进行不同的处理。
|
||||
2. [nonebot.typing.Event](../api/typing.md#event): 即上报事件对象，可以获取到上报的所有信息。
|
||||
3. `state`: 状态字典，可以存储任意的信息
|
||||
|
||||
#### 处理事件
|
||||
|
||||
在事件处理函数中，我们只需要对 `event` 做出相应的处理，存入状态字典 `state` 中，或者向用户发送消息、调用某个机器人 API 等等。
|
||||
|
||||
在 NoneBot 中，提供了几种特殊的处理函数：
|
||||
|
||||
##### `@matcher.args_parser`
|
||||
|
||||
这是一个装饰器，装饰一个函数来使它成为参数的默认解析函数，当使用 `matcher.got(xxx, [args_parser])` 获取到一条消息时，会运行 `matcher.got` 的 `args_parser` ，如果不存在则运行 `@matcher.args_parser`。
|
||||
|
||||
##### `matcher.pause`
|
||||
|
||||
这个函数用于结束当前事件处理函数，强制接收一条新的消息再运行**下一个消息处理函数**。
|
||||
|
||||
##### `matcher.reject`
|
||||
|
||||
这个函数用于结束当前事件处理函数，强制接收一条新的消息再**再次运行当前消息处理函数**。
|
||||
|
||||
##### `matcher.finish`
|
||||
|
||||
这个函数用于直接结束当前事件处理。
|
||||
|
||||
以上三个函数都拥有一个参数 `prompt`，用于向用户发送一条消息。
|
||||
|
||||
## 结语
|
||||
|
||||
至此，相信你已经能够写出一个基础的插件了，更多的用法将会在 进阶 部分进行介绍，这里给出几个小提示：
|
||||
|
||||
- 请千万注意事件处理器的优先级设定
|
||||
- 在匹配规则中请勿使用耗时极长的函数
|
||||
- 同一个用户可以跨群（私聊）继续他的事件处理（除非做出权限限制，将在后续介绍）
|
||||
t
|
||||
7
docs/guide/end-or-start.md
Normal file
7
docs/guide/end-or-start.md
Normal file
@ -0,0 +1,7 @@
|
||||
# 结语
|
||||
|
||||
至此，相信你已经能够写出一个基础的插件了，更多的用法将会在 进阶 部分进行介绍，这里给出几个小提示：
|
||||
|
||||
- 请千万注意事件处理器的优先级设定
|
||||
- 在匹配规则中请勿使用耗时极长的函数
|
||||
- 同一个用户可以**跨群**(**私聊**)继续他的事件处理（除非做出权限限制，将在后续介绍）
|
||||
Loading…
Reference in New Issue
Block a user