mirror of
https://github.com/nonebot/nonebot2.git
synced 2025-07-27 08:11:38 +00:00
Ju4tCode
GitHub
@ -9,7 +9,7 @@ description: 规范定义插件配置项
|
||||
|
||||
## 定义配置模型
|
||||
|
||||
在 NoneBot 中，我们使用强大高效的 [Pydantic](https://pydantic-docs.helpmanual.io/) 来定义配置模型，这个模型可以被用于配置的读取和类型检查等。例如，我们可以定义一个配置模型包含一个 string 类型的配置项：
|
||||
在 NoneBot2 中，我们使用强大高效的 [Pydantic](https://pydantic-docs.helpmanual.io/) 来定义配置模型，这个模型可以被用于配置的读取和类型检查等。例如，我们可以定义一个配置模型包含一个 string 类型的配置项：
|
||||
|
||||
```python title=config.py {3,4}
|
||||
from pydantic import BaseModel, Extra
|
||||
@ -19,7 +19,7 @@ class Config(BaseModel, extra=Extra.ignore):
|
||||
```
|
||||
|
||||
:::important 参考
|
||||
更多丰富的模型定义方法（默认值，自定义 validator 等），请参考 [Pydantic](https://pydantic-docs.helpmanual.io/) 文档。
|
||||
更多丰富的模型定义方法（默认值、自定义 validator 等），请参考 [Pydantic](https://pydantic-docs.helpmanual.io/) 文档。
|
||||
:::
|
||||
|
||||
## 读取配置
|
||||
|
||||
@ -14,7 +14,7 @@ options:
|
||||
|
||||
## 添加一个处理依赖
|
||||
|
||||
在事件响应器中，事件处理流程由一个或多个处理依赖组成，每个处理依赖都是一个 `Dependent`，详情可以参考 [进阶 - 依赖注入](../../advanced/di/dependency-injection.md)。下面介绍如何添加一个处理依赖。
|
||||
在事件响应器中，事件处理流程由一个或多个处理依赖组成，每个处理依赖都是一个 `Dependent`，详情可以参考[进阶 - 依赖注入](../../advanced/di/dependency-injection.md)。下面介绍如何添加一个处理依赖。
|
||||
|
||||
### 使用 `handle` 装饰器
|
||||
|
||||
@ -28,7 +28,7 @@ async def handle_func():
|
||||
|
||||
如上方示例所示，我们使用 `matcher` 响应器的 `handle` 装饰器装饰了一个函数 `handle_func` 。`handle_func` 函数会被自动转换为 `Dependent` 对象，并被添加到 `matcher` 的事件处理流程中。
|
||||
|
||||
在 `handle_func` 函数中，我们可以编写任何事件响应逻辑，如：操作数据库，发送消息等。上下文信息可以通过依赖注入的方式获取，参考：[获取上下文信息](#获取上下文信息)。发送消息可以通过 [事件响应器操作](./matcher-operation.md) 或者直接调用 Bot 的方法（ API 等，由协议适配器决定）。
|
||||
在 `handle_func` 函数中，我们可以编写任何事件响应逻辑，如：操作数据库，发送消息等。上下文信息可以通过依赖注入的方式获取，参考：[获取上下文信息](#获取上下文信息)。发送消息可以通过[事件响应器操作](./matcher-operation.md)或者直接调用 Bot 的方法（ API 等，由协议适配器决定）。
|
||||
|
||||
:::warning 注意
|
||||
`handle_func` 函数虽然会被装饰器自动转换为 `Dependent` 对象，但 `handle_func` 仍然为原本的函数，因此 `handle_func` 函数可以进行复用。如：
|
||||
@ -57,9 +57,9 @@ async def handle_func(e: Event = Received("id")):
|
||||
|
||||
`receive` 装饰器与 `handle` 装饰器一样，可以装饰一个函数添加到事件响应器的事件处理流程中。但与 `handle` 装饰器不同的是，`receive` 装饰器会中断当前事件处理流程，等待接收一个新的事件，就像是会话状态等待用户一个新的事件。可以接收的新的事件类型取决于事件响应器的 [`type`](./create-matcher.md#事件响应器类型-type) 更新值以及 [`permission`](./create-matcher.md#事件触发权限-permission) 更新值，可以通过自定义更新方法来控制会话响应（如进行非消息交互、多人会话、跨群会话等）。
|
||||
|
||||
`receive` 装饰器接受一个可选参数 `id` ，用于标识当前需要接收的事件，如果不指定，则默认为空 `""`。
|
||||
`receive` 装饰器接受一个可选参数 `id`，用于标识当前需要接收的事件，如果不指定，则默认为空 `""`。
|
||||
|
||||
在 `handle_func` 函数中，可以通过依赖注入的方式来获取接收到的事件，参考：[`Received`](#received), [`LastReceived`](#lastreceived)。
|
||||
在 `handle_func` 函数中，可以通过依赖注入的方式来获取接收到的事件，参考：[`Received`](#received)、[`LastReceived`](#lastreceived)。
|
||||
|
||||
:::important 提示
|
||||
`receive` 装饰器可以和自身与 `got` 装饰器嵌套使用
|
||||
@ -93,7 +93,7 @@ async def handle_func(key: Message = Arg()):
|
||||
|
||||
`got` 装饰器接受一个参数 `key` 和一个可选参数 `prompt`，当 `key` 不存在时，会向用户发送 `prompt` 消息，并等待用户回复。
|
||||
|
||||
在 `handle_func` 函数中，可以通过依赖注入的方式来获取接收到的消息，参考：[`Arg`](#arg), [`ArgStr`](#argstr), [`ArgPlainText`](#argplaintext)。
|
||||
在 `handle_func` 函数中，可以通过依赖注入的方式来获取接收到的消息，参考：[`Arg`](#arg)、[`ArgStr`](#argstr)、[`ArgPlainText`](#argplaintext)。
|
||||
|
||||
:::important 提示
|
||||
`got` 装饰器可以和自身与 `receive` 装饰器嵌套使用
|
||||
@ -113,7 +113,7 @@ matcher = on_message(
|
||||
|
||||
## 事件处理流程
|
||||
|
||||
在一个事件响应器中，事件被添加的处理依赖依次执行，直到所有处理依赖都执行完毕，或者遇到了某个处理依赖需要更多的事件来进行下一步的处理。在下一个事件到来并符合响应要求时，继续执行。更多有关 NoneBot 事件分发与处理流程的详细信息，请参考 [进阶 - 深入](../../advanced/README.md)。
|
||||
在一个事件响应器中，事件被添加的处理依赖依次执行，直到所有处理依赖都执行完毕，或者遇到了某个处理依赖需要更多的事件来进行下一步的处理。在下一个事件到来并符合响应要求时，继续执行。更多有关 NoneBot 事件分发与处理流程的详细信息，请参考[进阶 - 深入](../../advanced/README.md)。
|
||||
|
||||
## 获取上下文信息
|
||||
|
||||
|
||||
@ -10,15 +10,15 @@ options:
|
||||
|
||||
# 定义事件响应器
|
||||
|
||||
事件响应器 (`Matcher`) 是对接收到的事件进行响应的基本单元，所有的事件响应器都继承自 `Matcher` 基类。为方便编写插件，NoneBot 在 `nonebot.plugin` 模块中为插件开发定义了一些辅助函数，以便插件开发者可以简化插件开发。首先，让我们来了解一下 `Matcher` 由哪些部分组成。
|
||||
事件响应器（`Matcher`）是对接收到的事件进行响应的基本单元，所有的事件响应器都继承自 `Matcher` 基类。为了方便开发者编写插件，NoneBot2 在 `nonebot.plugin` 模块中为插件开发定义了一些辅助函数。首先，让我们来了解一下 `Matcher` 由哪些部分组成。
|
||||
|
||||
## 事件响应器的基本组成
|
||||
|
||||
### 事件响应器类型 `type`
|
||||
|
||||
事件响应器的类型即是该响应器所要响应的事件类型，只有在接收到的事件类型与该响应器的类型相同时，才会触发该响应器。如果类型留空，则该响应器将会响应所有类型的事件。
|
||||
事件响应器的类型即是该响应器所要响应的事件类型，只有在接收到的事件类型与该响应器的类型相同时，才会触发该响应器。如果类型留空，该响应器将会响应所有类型的事件。
|
||||
|
||||
NoneBot 内置了四种主要类型：`meta_event`, `message`, `notice`, `request`。通常情况下，协议适配器会将事件合理的分类至这四种类型中。如果有其他类型的事件需要响应，可以自行定义新的类型。
|
||||
NoneBot 内置了四种主要类型：`meta_event`、`message`、`notice`、`request`。通常情况下，协议适配器会将事件合理地分类至这四种类型中。如果有其他类型的事件需要响应，可以自行定义新的类型。
|
||||
|
||||
<!-- TODO: move session updater to advanced -->
|
||||
|
||||
@ -37,11 +37,11 @@ async def update_type():
|
||||
|
||||
:::
|
||||
|
||||
### 事件匹配规则 `rule`
|
||||
### 事件匹配规则
|
||||
|
||||
事件响应器的匹配规则是一个 `Rule` 对象，它是一系列 `checker` 的集合，当所有的 `checker` 都返回 `True` 时，才会触发该响应器。
|
||||
|
||||
规则编写方法参考 [自定义规则](#自定义规则)。
|
||||
规则编写方法参考[自定义规则](#自定义规则)。
|
||||
|
||||
:::warning 注意
|
||||
当会话状态更新时，`rule` 会被清空，以便会话收到新事件时能够正确匹配。
|
||||
@ -51,12 +51,12 @@ async def update_type():
|
||||
|
||||
事件响应器的触发权限是一个 `Permission` 对象，它也是一系列 `checker` 的集合，当其中一个 `checker` 返回 `True` 时，就会触发该响应器。
|
||||
|
||||
权限编写方法参考 [自定义权限](#自定义权限)。
|
||||
权限编写方法参考[自定义权限](#自定义权限)。
|
||||
|
||||
:::warning 注意
|
||||
与 `rule` 不同的是，`permission` 不会在会话状态更新时丢失，因此 `permission` 通常用于会话的响应控制。
|
||||
|
||||
并且, 当会话状态更新时，会执行 `permission_updater` 以更新 `permission`。默认情况下，`permission_updater` 会在原有的 `permission` 基础上添加一个 `USER` 条件，以检查事件的 `session_id` 是否与当前会话一致。
|
||||
并且，当会话状态更新时，会执行 `permission_updater` 以更新 `permission`。默认情况下，`permission_updater` 会在原有的 `permission` 基础上添加一个 `USER` 条件，以检查事件的 `session_id` 是否与当前会话一致。
|
||||
|
||||
你可以自行定义 `permission_updater` 来控制会话的响应权限更新。`permission_updater` 是一个返回 `Permission` 的函数，可选依赖注入参数参考类型 `T_PermissionUpdater`。
|
||||
|
||||
@ -75,7 +75,7 @@ async def update_type(matcher: Matcher):
|
||||
事件响应器的优先级代表事件响应器的执行顺序
|
||||
|
||||
:::warning 警告
|
||||
同一优先级的事件响应器会 **同时执行**，优先级数字 **越小** 越先响应！优先级请从 `1` 开始排序！
|
||||
同一优先级的事件响应器会**同时执行**，优先级数字**越小**越先响应！优先级请从 `1` 开始排序！
|
||||
:::
|
||||
|
||||
### 阻断 `block`
|
||||
@ -94,7 +94,7 @@ async def handle(matcher: Matcher):
|
||||
matcher.stop_propagation()
|
||||
```
|
||||
|
||||
### 有效期 `temp` / `expire_time`
|
||||
### 有效期 `temp`/`expire_time`
|
||||
|
||||
事件响应器可以设置有效期，当事件响应器超过有效期时，将会被移除。
|
||||
|
||||
@ -111,7 +111,7 @@ from nonebot import on_message
|
||||
matcher = on_message()
|
||||
```
|
||||
|
||||
用于定义事件响应器的辅助函数已经在 `nonebot` 主模块中被 `re-export` ，所以直接从 `nonebot` 导入即可。
|
||||
用于定义事件响应器的辅助函数已经在 `nonebot` 主模块中被 `re-export`，所以直接从 `nonebot` 导入即可。
|
||||
|
||||
辅助函数有以下几种：
|
||||
|
||||
|
||||
@ -9,13 +9,13 @@ description: 插件入门
|
||||
|
||||
在编写插件之前，首先我们需要了解一下插件的概念。
|
||||
|
||||
在 NoneBot 中，插件可以是 Python 的一个模块 `module` ，也可以是一个包 `package` 。NoneBot 会在导入时对这些模块或包做一些特殊的处理使得他们成为一个插件。插件间应尽量减少耦合，可以进行有限制的插件间调用，NoneBot 能够正确解析插件间的依赖关系。
|
||||
在 NoneBot 中，插件可以是 Python 的一个模块 `module`，也可以是一个包 `package` 。NoneBot 会在导入时对这些模块或包做一些特殊的处理使得他们成为一个插件。插件间应尽量减少耦合，可以进行有限制的插件间调用，NoneBot 能够正确解析插件间的依赖关系。
|
||||
|
||||
下面详细介绍两种插件的结构：
|
||||
|
||||
### 模块插件（单文件形式）
|
||||
|
||||
在合适的路径创建一个 `.py` 文件即可。例如在 [创建项目](../create-project.mdx) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件 `foo.py`。
|
||||
在合适的路径创建一个 `.py` 文件即可。例如在[创建项目](../create-project.mdx)中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件 `foo.py`。
|
||||
|
||||
```tree title=Project {4}
|
||||
📦 AweSome-Bot
|
||||
@ -37,7 +37,7 @@ description: 插件入门
|
||||
|
||||
### 包插件（文件夹形式）
|
||||
|
||||
在合适的路径创建一个文件夹，并在文件夹内创建文件 `__init__.py` 即可。例如在 [创建项目](../create-project.mdx) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件夹 `foo`，并在这个文件夹内创建一个文件 `__init__.py`。
|
||||
在合适的路径创建一个文件夹，并在文件夹内创建文件 `__init__.py` 即可。例如在[创建项目](../create-project.mdx)中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件夹 `foo`，并在这个文件夹内创建一个文件 `__init__.py`。
|
||||
|
||||
```tree title=Project {4,5}
|
||||
📦 AweSome-Bot
|
||||
@ -64,7 +64,7 @@ description: 插件入门
|
||||
请注意，插件名称不能存在重复，即所有模块插件的文件名和所有包插件的文件夹名不能存在相同。
|
||||
:::
|
||||
|
||||
除了通过手动创建的方式以外，还可以通过 `nb-cli` 来创建插件，`nb-cli` 会为你在合适的位置创建一个模板包插件。
|
||||
除了通过手动创建的方式以外，还可以通过 nb-cli 来创建插件，nb-cli 会为你在合适的位置创建一个模板包插件。
|
||||
|
||||
```bash
|
||||
nb plugin create
|
||||
|
||||
@ -11,10 +11,10 @@ options:
|
||||
# 加载插件
|
||||
|
||||
:::danger 警告
|
||||
请勿在插件被加载前 `import` 插件模块，这会导致 NoneBot 无法将其转换为插件而损失部分功能。
|
||||
请勿在插件被加载前 `import` 插件模块，这会导致 NoneBot2 无法将其转换为插件而损失部分功能。
|
||||
:::
|
||||
|
||||
加载插件通常在机器人的入口文件进行，例如在 [创建项目](../create-project.mdx) 中创建的项目中的 `bot.py` 文件。在 NoneBot 初始化完成后即可加载插件。
|
||||
加载插件通常在机器人的入口文件进行，例如在[创建项目](../create-project.mdx)中创建的项目中的 `bot.py` 文件。在 NoneBot2 初始化完成后即可加载插件。
|
||||
|
||||
```python title=bot.py {5}
|
||||
import nonebot
|
||||
@ -50,7 +50,7 @@ nonebot.load_plugins("src/plugins", "path/to/your/plugins")
|
||||
|
||||
## `load_all_plugins`
|
||||
|
||||
这种加载方式是以上两种方式的融合，加载所有传入的插件模块名称，以及所有给定目录下的插件。例如：
|
||||
这种加载方式是以上两种方式的混合，加载所有传入的插件模块名称，以及所有给定目录下的插件。例如：
|
||||
|
||||
```python
|
||||
nonebot.load_all_plugins(["path.to.your.plugin"], ["path/to/your/plugins"])
|
||||
|
||||
@ -16,7 +16,7 @@ options:
|
||||
|
||||
向用户回复一条消息。回复的方式或途径由协议适配器自行实现。
|
||||
|
||||
可以是 `str`, [`Message`](../../api/adapters/index.md#Message), [`MessageSegment`](../../api/adapters/index.md#MessageSegment) 或 [`MessageTemplate`](../../api/adapters/index.md#MessageTemplate)。
|
||||
可以是 `str`、[`Message`](../../api/adapters/index.md#Message)、[`MessageSegment`](../../api/adapters/index.md#MessageSegment) 或 [`MessageTemplate`](../../api/adapters/index.md#MessageTemplate)。
|
||||
|
||||
这个操作等同于使用 `bot.send(event, message, **kwargs)` 但不需要自行传入 `event`。
|
||||
|
||||
|
||||
Reference in New Issue
Block a user