mirror of
https://github.com/nonebot/nonebot2.git
synced 2025-08-01 10:40:06 +00:00
🏗️ change doc theme
This commit is contained in:
yanyongyu
4
website/docs/guide/coding/_category_.json
Normal file
4
website/docs/guide/coding/_category_.json
Normal file
@ -0,0 +1,4 @@
|
||||
{
|
||||
"label": "编写插件",
|
||||
"position": 2
|
||||
}
|
||||
206
website/docs/guide/coding/creating-a-handler.md
Normal file
206
website/docs/guide/coding/creating-a-handler.md
Normal file
@ -0,0 +1,206 @@
|
||||
---
|
||||
sidebar_position: 4
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 140
|
||||
catogory: guide
|
||||
---
|
||||
|
||||
# 事件处理
|
||||
|
||||
在上一章中，我们已经注册了事件响应器，现在我们可以正式编写事件处理逻辑了！
|
||||
|
||||
## [事件处理函数](../api/typing.md#handler)
|
||||
|
||||
```python{1,2,8,9}
|
||||
@weather.handle()
|
||||
async def handle_first_receive(bot: Bot, event: Event, state: T_State):
|
||||
args = str(event.get_message()).strip() # 首次发送命令时跟随的参数，例：/天气 上海，则args为上海
|
||||
if args:
|
||||
state["city"] = args # 如果用户发送了参数则直接赋值
|
||||
|
||||
|
||||
@weather.got("city", prompt="你想查询哪个城市的天气呢？")
|
||||
async def handle_city(bot: Bot, event: Event, state: T_State):
|
||||
city = state["city"]
|
||||
if city not in ["上海", "北京"]:
|
||||
await weather.reject("你想查询的城市暂不支持，请重新输入！")
|
||||
city_weather = await get_weather(city)
|
||||
await weather.finish(city_weather)
|
||||
```
|
||||
|
||||
在之前的样例中，我们定义了两个函数 `handle_first_receive`, `handle_city`，他们被事件响应器的装饰器装饰从而成为事件响应器的事件处理函数。
|
||||
|
||||
:::tip 提示
|
||||
在事件响应器中，事件处理函数是**顺序**执行的！
|
||||
:::
|
||||
|
||||
### 添加一个事件处理函数
|
||||
|
||||
事件响应器提供了三种装饰事件处理函数的装饰器，分别是：
|
||||
|
||||
1. [handle()](../api/matcher.md#classmethod-handle)
|
||||
2. [receive()](../api/matcher.md#classmethod-receive)
|
||||
3. [got(key, prompt, args_parser)](../api/matcher.md#classmethod-got-key-prompt-none-args-parser-none)
|
||||
|
||||
#### handle()
|
||||
|
||||
简单的为事件响应器添加一个事件处理函数，这个函数将会在上一个处理函数正常返回执行完毕后立即执行。
|
||||
|
||||
#### receive()
|
||||
|
||||
指示 NoneBot 接收一条新的用户消息后继续执行该处理函数。此时函数将会接收到新的消息而非前一条消息，之前相关信息可以存储在 state 中。
|
||||
|
||||
特别地，当装饰的函数前没有其他事件处理函数，那么 `receive()` 不会接收一条新的消息而是直接使用第一条接收到的消息。
|
||||
|
||||
#### 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: T_State):
|
||||
state["key"] = "hello"
|
||||
|
||||
|
||||
@matcher.got("key2", prompt="{key}!")
|
||||
async def handle2(bot: Bot, event: Event, state: T_State):
|
||||
pass
|
||||
```
|
||||
|
||||
`args_parser` 为参数处理函数，在这里传入一个新的函数以覆盖默认的参数处理。详情参照 [args_parser](#参数处理函数-args-parser)
|
||||
|
||||
特别的，这些装饰器都可以套娃使用：
|
||||
|
||||
```python
|
||||
@matcher.got("key1")
|
||||
@matcher.got("key2")
|
||||
async def handle(bot: Bot, event: Event, state: T_State):
|
||||
pass
|
||||
```
|
||||
|
||||
### 事件处理函数参数
|
||||
|
||||
事件处理函数类型为：
|
||||
|
||||
- `Callable[[Bot, Event, T_State, Matcher], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, Event, T_State], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, Event, Matcher], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, T_State, Matcher], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, Event], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, T_State], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot, Matcher], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
- `Callable[[Bot], Union[Awaitable[None], Awaitable[NoReturn]]]`
|
||||
|
||||
简单说就是：除了 `bot` 参数，其他都是可选的。
|
||||
|
||||
以下函数都是合法的事件处理函数（仅列举常用的）：
|
||||
|
||||
```python
|
||||
async def handle(bot: Bot, event: Event, state: T_State):
|
||||
pass
|
||||
|
||||
async def handle(bot: Bot, event: Event, state: T_State, matcher: Matcher):
|
||||
pass
|
||||
|
||||
async def handle(bot: Bot, event: Event):
|
||||
pass
|
||||
|
||||
async def handle(bot: Bot, state: T_State):
|
||||
pass
|
||||
|
||||
async def handle(bot: Bot):
|
||||
pass
|
||||
```
|
||||
|
||||
:::danger 警告
|
||||
函数的参数名固定不能修改！
|
||||
:::
|
||||
|
||||
参数分别为：
|
||||
|
||||
1. [nonebot.adapters.Bot](../api/adapters/#class-bot): 即事件上报连接对应的 Bot 对象，为 BaseBot 的子类。特别注意，此处的类型注释可以替换为指定的 Bot 类型，例如：`nonebot.adapters.cqhttp.Bot`，只有在上报事件的 Bot 类型与类型注释相符时才会执行该处理函数！可用于多平台进行不同的处理。
|
||||
2. [nonebot.adapters.Event](../api/adapters/#class-event): 即上报事件对象，可以获取到上报的所有信息。
|
||||
3. [state](../api/typing.md#t-state): 状态字典，可以存储任意的信息，其中还包含一些特殊的值以获取 NoneBot 内部处理时的一些信息，如：
|
||||
|
||||
- `state["_current_key"]`: 存储当前 `got` 获取的参数名
|
||||
- `state["_prefix"]`, `state["_suffix"]`: 存储当前 TRIE 匹配的前缀/后缀，可以通过该值获取用户命令的原始命令
|
||||
|
||||
:::tip 提示
|
||||
NoneBot 会对不同类型的参数进行不同的操作，详情查看 [事件处理函数重载](../advanced/overloaded-handlers.md)
|
||||
:::
|
||||
|
||||
### 参数处理函数 args_parser
|
||||
|
||||
在使用 `got` 获取用户输入参数时，需要对用户的消息进行处理以转换为我们所需要的信息。在默认情况下，NoneBot 会把用户的消息字符串原封不动的赋值给 `state[key]` 。可以通过以下两种方式修改默认处理逻辑：
|
||||
|
||||
- `@matcher.args_parser` 装饰器：直接装饰一个函数作为参数处理器
|
||||
- `got(key, prompt, args_parser)`：直接把函数作为参数传入
|
||||
|
||||
参数处理函数类型为：`Callable[[Bot, Event, T_State], Union[Awaitable[None], Awaitable[NoReturn]]]`，即：
|
||||
|
||||
```python
|
||||
async def parser(bot: Bot, event: Event, state: T_State):
|
||||
state[state["_current_key"]] = str(event.get_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: T_State):
|
||||
print(state["_current_key"], ":", str(event.get_message()))
|
||||
state[state["_current_key"]] = str(event.get_message())
|
||||
|
||||
@matcher.handle()
|
||||
async def first_receive(bot: Bot, event: Event, state: T_State):
|
||||
# 获取用户原始命令，如：/test
|
||||
print(state["_prefix"]["raw_command"])
|
||||
# 处理用户输入参数，如：/test arg1 arg2
|
||||
raw_args = str(event.get_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: T_State):
|
||||
# 在这里对参数进行验证
|
||||
if state["arg1"] not in ["allow", "list"]:
|
||||
await matcher.reject("参数不正确！请重新输入")
|
||||
# 发送一些信息
|
||||
await bot.send(event, "message")
|
||||
await matcher.send("message")
|
||||
await matcher.finish("message")
|
||||
```
|
||||
157
website/docs/guide/coding/creating-a-matcher.md
Normal file
157
website/docs/guide/coding/creating-a-matcher.md
Normal file
@ -0,0 +1,157 @@
|
||||
---
|
||||
sidebar_position: 3
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 130
|
||||
catogory: guide
|
||||
---
|
||||
|
||||
# 注册事件响应器
|
||||
|
||||
好了，现在插件已经创建完毕，我们可以开始编写实际代码了，下面将以一个简易单文件天气查询插件为例。
|
||||
|
||||
在插件目录下 `weather.py` 中添加如下代码：
|
||||
|
||||
```python
|
||||
from nonebot import on_command
|
||||
from nonebot.rule import to_me
|
||||
from nonebot.typing import T_State
|
||||
from nonebot.adapters import Bot, Event
|
||||
|
||||
weather = on_command("天气", rule=to_me(), priority=5)
|
||||
|
||||
|
||||
@weather.handle()
|
||||
async def handle_first_receive(bot: Bot, event: Event, state: T_State):
|
||||
args = str(event.get_message()).strip() # 首次发送命令时跟随的参数，例：/天气 上海，则args为上海
|
||||
if args:
|
||||
state["city"] = args # 如果用户发送了参数则直接赋值
|
||||
|
||||
|
||||
@weather.got("city", prompt="你想查询哪个城市的天气呢？")
|
||||
async def handle_city(bot: Bot, event: Event, state: T_State):
|
||||
city = state["city"]
|
||||
if city not in ["上海", "北京"]:
|
||||
await weather.reject("你想查询的城市暂不支持，请重新输入！")
|
||||
city_weather = await get_weather(city)
|
||||
await weather.finish(city_weather)
|
||||
|
||||
|
||||
async def get_weather(city: str):
|
||||
return f"{city}的天气是..."
|
||||
```
|
||||
|
||||
为了简单起见，我们在这里的例子中没有接入真实的天气数据，但要接入也非常简单，你可以使用中国天气网、和风天气等网站提供的 API。
|
||||
|
||||
接下来我们来说明这段代码是如何工作的。
|
||||
|
||||
:::tip 提示
|
||||
从这里开始，你需要对 Python 的 asyncio 编程有所了解，因为 NoneBot 是完全基于 asyncio 的，具体可以参考 [廖雪峰的 Python 教程](https://www.liaoxuefeng.com/wiki/1016959663602400/1017959540289152)
|
||||
:::
|
||||
|
||||
## [事件响应器](../../api/matcher.md)
|
||||
|
||||
```python{5}
|
||||
from nonebot import on_command
|
||||
from nonebot.rule import to_me
|
||||
from nonebot.permission import Permission
|
||||
|
||||
weather = on_command("天气", rule=to_me(), permission=Permission(), priority=5)
|
||||
```
|
||||
|
||||
在上方代码中，我们注册了一个事件响应器 `Matcher`，它由几个部分组成：
|
||||
|
||||
1. `on_command` 注册一个消息类型的命令处理器
|
||||
2. `"天气"` 指定 command 参数 - 命令名
|
||||
3. `rule` 补充事件响应器的匹配规则
|
||||
4. `priority` 事件响应器优先级
|
||||
5. `block` 是否阻止事件传递
|
||||
|
||||
其他详细配置可以参考 API 文档，下面我们详细说明各个部分：
|
||||
|
||||
### 事件响应器类型 type
|
||||
|
||||
事件响应器类型其实就是对应事件的类型 `Event.get_type()` ，NoneBot 提供了一个基础类型事件响应器 `on()` 以及一些其他内置的事件响应器。
|
||||
|
||||
以下所有类型的事件响应器都是由 `on(type, rule)` 的形式进行了简化封装。
|
||||
|
||||
- `on("事件类型")`: 基础事件响应器，第一个参数为事件类型，空字符串表示不限
|
||||
- `on_metaevent()` ~ `on("meta_event")`: 元事件响应器
|
||||
- `on_message()` ~ `on("message")`: 消息事件响应器
|
||||
- `on_request()` ~ `on("request")`: 请求事件响应器
|
||||
- `on_notice()` ~ `on("notice")`: 通知事件响应器
|
||||
- `on_startswith(str)` ~ `on("message", startswith(str))`: 消息开头匹配响应器，参考 [startswith](../../api/rule.md#startswith-msg)
|
||||
- `on_endswith(str)` ~ `on("message", endswith(str))`: 消息结尾匹配响应器，参考 [endswith](../../api/rule.md#endswith-msg)
|
||||
- `on_keyword(set)` ~ `on("message", keyword(str))`: 消息关键词匹配响应器，参考 [keyword](../../api/rule.md#keyword-keywords)
|
||||
- `on_command(str|tuple)` ~ `on("message", command(str|tuple))`: 命令响应器，参考 [command](../../api/rule.md#command-cmds)
|
||||
- `on_regex(pattern_str)` ~ `on("message", regex(pattern_str))`: 正则匹配处理器，参考 [regex](../../api/rule.md#regex-regex-flags-0)
|
||||
|
||||
### 匹配规则 rule
|
||||
|
||||
事件响应器的匹配规则即 `Rule`，详细内容在下方介绍。[直达](#自定义-rule)
|
||||
|
||||
### 优先级 priority
|
||||
|
||||
事件响应器的优先级代表事件响应器的执行顺序，同一优先级的事件响应器会 **同时执行！**，优先级数字**越小**越先响应！优先级请从 `1` 开始排序！
|
||||
|
||||
:::tip 提示
|
||||
使用 `nonebot-plugin-test` 可以在网页端查看当前所有事件响应器的执行流程，有助理解事件响应流程！
|
||||
|
||||
```bash
|
||||
nb plugin install nonebot_plugin_test
|
||||
```
|
||||
|
||||
:::
|
||||
|
||||
### 阻断 block
|
||||
|
||||
当有任意事件响应器发出了阻止事件传递信号时，该事件将不再会传递给下一优先级，直接结束处理。
|
||||
|
||||
NoneBot 内置的事件响应器中，所有 `message` 类的事件响应器默认会阻断事件传递，其他则不会。
|
||||
|
||||
在部分情况中，可以使用 `matcher.stop_propagation()` 方法动态阻止事件传播，该方法需要 `handler` 在参数中获取 `matcher` 实例后调用方法。
|
||||
|
||||
## 自定义 rule
|
||||
|
||||
rule 的出现使得 nonebot 对事件的响应可以非常自由，nonebot 内置了一些规则：
|
||||
|
||||
- [startswith(msg)](../../api/rule.md#startswith-msg)
|
||||
- [endswith(msg)](../../api/rule.md#endswith-msg)
|
||||
- [keyword(\*keywords)](../../api/rule.md#keyword-keywords)
|
||||
- [command(\*cmds)](../../api/rule.md#command-cmds)
|
||||
- [regex(regex, flag)](../../api/rule.md#regex-regex-flags-0)
|
||||
|
||||
以上规则都是返回类型为 `Rule` 的函数，`Rule` 由非负个 `RuleChecker` 组成，当所有 `RuleChecker` 返回 `True` 时匹配成功。这些 `Rule`, `RuleChecker` 的形式如下：
|
||||
|
||||
```python
|
||||
from nonebot.rule import Rule
|
||||
from nonebot.typing import T_State
|
||||
|
||||
async def async_checker(bot: Bot, event: Event, state: T_State) -> bool:
|
||||
return True
|
||||
|
||||
def sync_checker(bot: Bot, event: Event, state: T_State) -> bool:
|
||||
return True
|
||||
|
||||
def check(arg1, arg2):
|
||||
|
||||
async def _checker(bot: Bot, event: Event, state: T_State) -> bool:
|
||||
return bool(arg1 + arg2)
|
||||
|
||||
return Rule(_checker)
|
||||
```
|
||||
|
||||
`Rule` 和 `RuleChecker` 之间可以使用 `与 &` 互相组合：
|
||||
|
||||
```python
|
||||
from nonebot.rule import Rule
|
||||
|
||||
Rule(async_checker1) & sync_checker & async_checker2
|
||||
```
|
||||
|
||||
**_请勿将事件处理的逻辑写入 `rule` 中，这会使得事件处理返回奇怪的响应。_**
|
||||
|
||||
:::danger 警告
|
||||
`Rule(*checkers)` 只接受 async function，或使用 `nonebot.utils.run_sync` 自行包裹 sync function。在使用 `与 &` 时，NoneBot 会自动包裹 sync function
|
||||
:::
|
||||
128
website/docs/guide/coding/creating-a-plugin.md
Normal file
128
website/docs/guide/coding/creating-a-plugin.md
Normal file
@ -0,0 +1,128 @@
|
||||
---
|
||||
sidebar_position: 2
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 120
|
||||
catogory: guide
|
||||
---
|
||||
|
||||
# 创建插件
|
||||
|
||||
如果之前使用 `nb-cli` 生成了项目结构，那我们已经有了一个空的插件目录 `Awesome-Bot/awesome_bot/plugins`，并且它已在 `bot.py` 中被加载，我们现在可以开始创建插件了！
|
||||
|
||||
使用 `nb-cli` 创建包形式插件，或自行创建文件(夹)
|
||||
|
||||
```bash
|
||||
nb plugin new
|
||||
```
|
||||
|
||||
下面分别对两种通常的插件形式做具体介绍
|
||||
|
||||
## 单文件形式
|
||||
|
||||
在插件目录下创建名为 `foo.py` 的 Python 文件，暂时留空，此时目录结构如下：
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
:::vue
|
||||
AweSome-Bot
|
||||
├── awesome_bot
|
||||
│ └── plugins
|
||||
│ └── `foo.py`
|
||||
├── .env
|
||||
├── .env.dev
|
||||
├── .env.prod
|
||||
├── .gitignore
|
||||
├── bot.py
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
├── pyproject.toml
|
||||
└── README.md
|
||||
:::
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
这个时候它已经可以被称为一个插件了，尽管它还什么都没做。
|
||||
|
||||
## 包形式(推荐)
|
||||
|
||||
在插件目录下创建文件夹 `foo`，并在该文件夹下创建文件 `__init__.py`，此时目录结构如下：
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
:::vue
|
||||
AweSome-Bot
|
||||
├── awesome_bot
|
||||
│ └── plugins
|
||||
│ └── `foo`
|
||||
│ └── `__init__.py`
|
||||
├── .env
|
||||
├── .env.dev
|
||||
├── .env.prod
|
||||
├── .gitignore
|
||||
├── bot.py
|
||||
├── docker-compose.yml
|
||||
├── Dockerfile
|
||||
├── pyproject.toml
|
||||
└── README.md
|
||||
:::
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
这个时候 `foo` 就是一个合法的 Python 包了，同时也是合法的 NoneBot 插件，插件内容可以在 `__init__.py` 中编写。
|
||||
|
||||
### 推荐结构(仅供参考)
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
:::vue
|
||||
foo
|
||||
├── `__init__.py`
|
||||
├── `config.py`
|
||||
├── `data_source.py`
|
||||
└── `model.py`
|
||||
:::
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
#### \_\_init\_\_.py
|
||||
|
||||
在该文件中编写各类事件响应及处理逻辑。
|
||||
|
||||
#### config.py
|
||||
|
||||
在该文件中使用 `pydantic` 定义插件所需要的配置项以及类型。
|
||||
|
||||
示例：
|
||||
|
||||
```python
|
||||
from pydantic import BaseSettings
|
||||
|
||||
|
||||
class Config(BaseSettings):
|
||||
|
||||
# plugin custom config
|
||||
plugin_setting: str = "default"
|
||||
|
||||
class Config:
|
||||
extra = "ignore"
|
||||
```
|
||||
|
||||
并在 `__init__.py` 文件中添加以下行
|
||||
|
||||
```python
|
||||
import nonebot
|
||||
from .config import Config
|
||||
|
||||
global_config = nonebot.get_driver().config
|
||||
plugin_config = Config(**global_config.dict())
|
||||
```
|
||||
|
||||
此时就可以通过 `plugin_config.plugin_setting` 获取到插件所需要的配置项了。
|
||||
|
||||
#### data_source.py
|
||||
|
||||
在该文件中编写数据获取函数。
|
||||
|
||||
:::warning 警告
|
||||
数据获取应尽量使用**异步**处理！例如使用 [httpx](https://www.python-httpx.org/) 而非 [requests](https://requests.readthedocs.io/en/master/)
|
||||
:::
|
||||
|
||||
#### model.py
|
||||
|
||||
在该文件中编写数据库模型。
|
||||
12
website/docs/guide/coding/end-or-start.md
Normal file
12
website/docs/guide/coding/end-or-start.md
Normal file
@ -0,0 +1,12 @@
|
||||
---
|
||||
sidebar_position: 5
|
||||
---
|
||||
|
||||
# 结语
|
||||
|
||||
至此，相信你已经能够写出一个基础的插件了。这里给出几个小提示：
|
||||
|
||||
- 请千万注意事件处理器的优先级设定
|
||||
- 在匹配规则中请勿使用耗时极长的函数
|
||||
|
||||
如果「指南」还不能满足你，前往 [进阶](../advanced/README.md) 查看更多的功能信息。
|
||||
193
website/docs/guide/coding/loading-a-plugin.md
Normal file
193
website/docs/guide/coding/loading-a-plugin.md
Normal file
@ -0,0 +1,193 @@
|
||||
---
|
||||
sidebar_position: 1
|
||||
|
||||
options:
|
||||
menu:
|
||||
weight: 110
|
||||
catogory: guide
|
||||
---
|
||||
|
||||
# 加载插件
|
||||
|
||||
在 [创建一个完整的项目](creating-a-project) 一章节中，我们已经创建了插件目录 `awesome_bot/plugins`，现在我们在机器人入口文件中加载它。当然，你也可以单独加载一个插件。
|
||||
|
||||
## 加载内置插件
|
||||
|
||||
在 `bot.py` 文件中添加以下行：
|
||||
|
||||
```python{8}
|
||||
import nonebot
|
||||
from nonebot.adapters.cqhttp import Bot
|
||||
|
||||
nonebot.init()
|
||||
|
||||
driver = nonebot.get_driver()
|
||||
driver.register_adapter("cqhttp", Bot) # 注册 CQHTTP 的 Adapter
|
||||
nonebot.load_builtin_plugins() # 加载 nonebot 内置插件
|
||||
|
||||
app = nonebot.get_asgi()
|
||||
|
||||
if __name__ == "__main__":
|
||||
nonebot.run()
|
||||
```
|
||||
|
||||
::: warning
|
||||
目前, 内建插件仅支持 CQHTTP 的 Adapter
|
||||
|
||||
如果您使用的是其他 Adapter, 请移步该 Adapter 相应的文档
|
||||
:::
|
||||
|
||||
这将会加载 nonebot 内置的插件，它包含：
|
||||
|
||||
- 命令 `say`：可由**superuser**使用，可以将消息内容由特殊纯文本转为富文本
|
||||
- 命令 `echo`：可由任何人使用，将消息原样返回
|
||||
|
||||
以上命令均需要指定机器人，即私聊、群聊内@机器人、群聊内称呼机器人昵称。参考 [Rule: to_me](../../api/rule.md#to-me)
|
||||
|
||||
## 加载插件目录
|
||||
|
||||
在 `bot.py` 文件中添加以下行：
|
||||
|
||||
```python{6}
|
||||
import nonebot
|
||||
|
||||
nonebot.init()
|
||||
|
||||
# 加载插件目录，该目录下为各插件，以下划线开头的插件将不会被加载
|
||||
nonebot.load_plugins("awesome_bot/plugins")
|
||||
|
||||
app = nonebot.get_asgi()
|
||||
|
||||
if __name__ == "__main__":
|
||||
nonebot.run()
|
||||
```
|
||||
|
||||
:::tip 提示
|
||||
加载插件目录时，目录下以 `_` 下划线开头的插件将不会被加载！
|
||||
:::
|
||||
|
||||
:::warning 提示
|
||||
**不能存在相同名称的插件！**
|
||||
:::
|
||||
|
||||
:::danger 警告
|
||||
插件间不应该存在过多的耦合，如果确实需要导入某个插件内的数据，可以参考 [进阶-跨插件访问](../../advanced/export-and-require.md)
|
||||
:::
|
||||
|
||||
## 加载单个插件
|
||||
|
||||
在 `bot.py` 文件中添加以下行：
|
||||
|
||||
```python{6,8}
|
||||
import nonebot
|
||||
|
||||
nonebot.init()
|
||||
|
||||
# 加载一个 pip 安装的插件
|
||||
nonebot.load_plugin("nonebot_plugin_status")
|
||||
# 加载本地的单独插件
|
||||
nonebot.load_plugin("awesome_bot.plugins.xxx")
|
||||
|
||||
app = nonebot.get_asgi()
|
||||
|
||||
if __name__ == "__main__":
|
||||
nonebot.run()
|
||||
```
|
||||
|
||||
## 从 json 文件中加载插件
|
||||
|
||||
在 `bot.py` 文件中添加以下行：
|
||||
|
||||
```python{6}
|
||||
import nonebot
|
||||
|
||||
nonebot.init()
|
||||
|
||||
# 从 plugin.json 加载插件
|
||||
nonebot.load_from_json("plugin.json")
|
||||
|
||||
app = nonebot.get_asgi()
|
||||
|
||||
if __name__ == "__main__":
|
||||
nonebot.run()
|
||||
```
|
||||
|
||||
**json 文件示例**
|
||||
|
||||
```json
|
||||
{
|
||||
"plugins": ["nonebot_plugin_status", "awesome_bot.plugins.xxx"],
|
||||
"plugin_dirs": ["awesome_bot/plugins"]
|
||||
}
|
||||
```
|
||||
|
||||
## 从 toml 文件中加载插件
|
||||
|
||||
在 `bot.py` 文件中添加以下行：
|
||||
|
||||
```python{6}
|
||||
import nonebot
|
||||
|
||||
nonebot.init()
|
||||
|
||||
# 从 pyproject.toml 加载插件
|
||||
nonebot.load_from_toml("pyproject.toml")
|
||||
|
||||
app = nonebot.get_asgi()
|
||||
|
||||
if __name__ == "__main__":
|
||||
nonebot.run()
|
||||
```
|
||||
|
||||
**toml 文件示例：**
|
||||
|
||||
```toml
|
||||
[nonebot.plugins]
|
||||
plugins = ["nonebot_plugin_status", "awesome_bot.plugins.xxx"]
|
||||
plugin_dirs = ["awesome_bot/plugins"]
|
||||
```
|
||||
|
||||
::: tip
|
||||
nb-cli 默认使用 `pyproject.toml` 加载插件。
|
||||
:::
|
||||
|
||||
## 子插件(嵌套插件)
|
||||
|
||||
在插件中同样可以加载子插件，例如如下插件目录结构：
|
||||
|
||||
<!-- prettier-ignore-start -->
|
||||
:::vue
|
||||
foo_plugin
|
||||
├── `plugins`
|
||||
│ ├── `sub_plugin1`
|
||||
│ │ └── \_\_init\_\_.py
|
||||
│ └── `sub_plugin2.py`
|
||||
├── `__init__.py`
|
||||
└── config.py
|
||||
:::
|
||||
<!-- prettier-ignore-end -->
|
||||
|
||||
在插件目录下的 `__init__.py` 中添加如下代码：
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
import nonebot
|
||||
|
||||
# store all subplugins
|
||||
_sub_plugins = set()
|
||||
# load sub plugins
|
||||
_sub_plugins |= nonebot.load_plugins(
|
||||
str((Path(__file__).parent / "plugins").resolve()))
|
||||
```
|
||||
|
||||
插件将会被加载并存储于 `_sub_plugins` 中。
|
||||
|
||||
## 运行结果
|
||||
|
||||
尝试运行 `nb run` 或者 `python bot.py`，可以看到日志输出了类似如下内容：
|
||||
|
||||
```plain
|
||||
09-19 21:51:59 [INFO] nonebot | Succeeded to import "nonebot.plugins.base"
|
||||
09-19 21:51:59 [INFO] nonebot | Succeeded to import "plugin_in_folder"
|
||||
```
|
||||
Reference in New Issue
Block a user