diff --git a/nonebot/plugin/load.py b/nonebot/plugin/load.py index bfd08918..26d2d7e3 100644 --- a/nonebot/plugin/load.py +++ b/nonebot/plugin/load.py @@ -131,11 +131,11 @@ def load_from_toml(file_path: str, encoding: str = "utf-8") -> Set[Plugin]: return load_all_plugins(plugins, plugin_dirs) -def load_builtin_plugins(name: str = "echo") -> Optional[Plugin]: +def load_builtin_plugins(name: str) -> Optional[Plugin]: """ :说明: - 导入 NoneBot 内置插件, 默认导入 ``echo`` 插件 + 导入 NoneBot 内置插件 :返回: diff --git a/website/docs/advanced/README.md b/website/docs/advanced/README.md index ed1065f1..ea64f8ec 100644 --- a/website/docs/advanced/README.md +++ b/website/docs/advanced/README.md @@ -12,7 +12,7 @@ options: ## 它如何工作？ -如同[概览](../guide/README.md)所言: +如同[概览](../README.md)所言: > NoneBot2 是一个可扩展的 Python 异步机器人框架，它会对机器人收到的事件进行解析和处理，并以插件化的形式，按优先级分发给事件所对应的事件响应器，来完成具体的功能。 diff --git a/website/docs/tutorial/creating-a-project.md b/website/docs/tutorial/create-project.md similarity index 100% rename from website/docs/tutorial/creating-a-project.md rename to website/docs/tutorial/create-project.md diff --git a/website/docs/tutorial/plugin/config-plugin.md b/website/docs/tutorial/plugin/config-plugin.md index e397da91..28a40a07 100644 --- a/website/docs/tutorial/plugin/config-plugin.md +++ b/website/docs/tutorial/plugin/config-plugin.md @@ -4,3 +4,34 @@ description: 规范定义插件配置项 --- # 定义插件配置 + +通常，插件可以从配置文件中读取自己的配置项，但是由于额外的全局配置项没有预先定义的问题，导致开发时编辑器无法提示字段与类型，以及运行时没有对配置项直接进行检查。那么就需要一种方式来规范定义插件配置项。 + +## 定义配置模型 + +在 NoneBot 中，我们使用强大高效的 [Pydantic](https://pydantic-docs.helpmanual.io/) 来定义配置模型，这个模型可以被用于配置的读取和类型检查等。例如，我们可以定义一个配置模型包含一个 string 类型的配置项： + +```python title=config.py {3,4} +from pydantic import BaseModel, Extra + +class Config(BaseModel, extra=Extra.ignore): + token: str +``` + +:::important 参考 +更多丰富的模型定义方法（默认值，自定义 validator 等），请参考 [Pydantic](https://pydantic-docs.helpmanual.io/) 文档。 +::: + +## 读取配置 + +定义完成配置模型后，我们可以在插件加载时获取全局配置，导入插件自身的配置模型： + +```python title=__init__.py {5} +from nonebot import get_driver + +from .config import Config + +plugin_config = Config.parse_obj(get_driver().config) +``` + +至此，插件已经成功读取了自身所需的配置项，并且具有字段和类型提示，也可以对配置进行运行时修改。 diff --git a/website/docs/tutorial/plugin/introduction.md b/website/docs/tutorial/plugin/introduction.md index d85c46b7..fcc50161 100644 --- a/website/docs/tutorial/plugin/introduction.md +++ b/website/docs/tutorial/plugin/introduction.md @@ -15,7 +15,7 @@ description: 插件入门 ### 模块插件（单文件形式） -在合适的路径创建一个 `.py` 文件即可。例如在 [创建项目](../creating-a-project.md) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件 `foo.py`。 +在合适的路径创建一个 `.py` 文件即可。例如在 [创建项目](../create-project.md) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件 `foo.py`。 ```bash title=Project {4} AweSome-Bot @@ -37,7 +37,7 @@ AweSome-Bot ### 包插件（文件夹形式） -在合适的路径创建一个文件夹，并在文件夹内创建文件 `__init__.py` 即可。例如在 [创建项目](../creating-a-project.md) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件夹 `foo`，并在这个文件夹内创建一个文件 `__init__.py`。 +在合适的路径创建一个文件夹，并在文件夹内创建文件 `__init__.py` 即可。例如在 [创建项目](../create-project.md) 中创建的项目中，我们可以在 `awesome_bot/plugins/` 目录中创建一个文件夹 `foo`，并在这个文件夹内创建一个文件 `__init__.py`。 ```bash title=Project {4,5} AweSome-Bot @@ -60,6 +60,10 @@ AweSome-Bot ## 创建插件 +:::danger 警告 +请注意，插件名称不能存在重复，即所有模块插件的文件名和所有包插件的文件夹名不能存在相同。 +::: + 除了通过手动创建的方式以外，还可以通过 `nb-cli` 来创建插件，`nb-cli` 会为你在合适的位置创建一个模板包插件。 ```bash diff --git a/website/docs/tutorial/plugin/load-plugin.md b/website/docs/tutorial/plugin/load-plugin.md index 19071da6..3b92dc6e 100644 --- a/website/docs/tutorial/plugin/load-plugin.md +++ b/website/docs/tutorial/plugin/load-plugin.md @@ -9,3 +9,94 @@ options: --- # 加载插件 + +:::danger 警告 +请勿在插件被加载前 `import` 插件模块，这会导致 NoneBot 无法将其转换为插件而损失部分功能。 +::: + +加载插件通常在机器人的入口文件进行，例如在 [创建项目](../create-project.md) 中创建的项目中的 `bot.py` 文件。在 NoneBot 初始化完成后即可加载插件。 + +```python title=bot.py {5} +import nonebot + +nonebot.init() + +# load your plugin here + +nonebot.run() +``` + +加载插件的方式有多种，但在底层的加载逻辑是一致的。以下是为加载插件提供的几种方式： + +## `load_plugin` + +通过点分割模块名称来加载插件，通常用于加载单个插件或者是第三方插件。例如： + +```python +nonebot.load_plugin("path.to.your.plugin") +``` + +## `load_plugins` + +加载传入插件目录中的所有插件，通常用于加载一系列本地编写的插件。例如： + +```python +nonebot.load_plugins("src/plugins", "path/to/your/plugins") +``` + +:::warning 警告 +请注意，插件所在目录应该为相对机器人入口文件可导入的，例如与入口文件在同一目录下。 +::: + +## `load_all_plugins` + +这种加载方式是以上两种方式的融合，加载所有传入的插件模块名称，以及所有给定目录下的插件。例如： + +```python +nonebot.load_all_plugins(["path.to.your.plugin"], ["path/to/your/plugins"]) +``` + +## `load_from_json` + +通过 JSON 文件加载插件，是 [`load_all_plugins`](#load_all_plugins) 的 JSON 变种。通过读取 JSON 文件中的 `plugins` 字段和 `plugin_dirs` 字段进行加载。例如： + +```json title=plugin_config.json +{ + "plugins": ["path.to.your.plugin"], + "plugin_dirs": ["path/to/your/plugins"] +} +``` + +```python +nonebot.load_from_json("plugin_config.json", encoding="utf-8") +``` + +:::tip 提示 +如果 JSON 配置文件中的字段无法满足你的需求，可以使用 [`load_all_plugins`](#load_all_plugins) 方法自行读取配置来加载插件。 +::: + +## `load_from_toml` + +通过 TOML 文件加载插件，是 [`load_all_plugins`](#load_all_plugins) 的 TOML 变种。通过读取 TOML 文件中的 `[tool.nonebot]` Table 中的 `plugins` 和 `plugin_dirs` Array 进行加载。例如： + +```toml title=plugin_config.toml +[tool.nonebot] +plugins = ["path.to.your.plugin"] +plugin_dirs = ["path/to/your/plugins"] +``` + +```python +nonebot.load_from_toml("plugin_config.toml", encoding="utf-8") +``` + +:::tip 提示 +如果 TOML 配置文件中的字段无法满足你的需求，可以使用 [`load_all_plugins`](#load_all_plugins) 方法自行读取配置来加载插件。 +::: + +## `load_builtin_plugin` + +加载一个内置插件，是 [`load_plugin`](#load_plugin) 的封装。例如： + +```python +nonebot.load_builtin_plugin("echo") +``` diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js index 28bf30f2..bc8dce24 100644 --- a/website/docusaurus.config.js +++ b/website/docusaurus.config.js @@ -104,8 +104,8 @@ const config = { title: "Learn", icon: ["fas", "book"], items: [ - { label: "Introduction", to: "/docs/guide" }, - { label: "Installation", to: "/docs/guide/start/installation" }, + { label: "Introduction", to: "/docs/" }, + { label: "Installation", to: "/docs/start/installation" }, ], }, { diff --git a/website/src/components/Hero.tsx b/website/src/components/Hero.tsx index 37eace6a..7d6c6112 100644 --- a/website/src/components/Hero.tsx +++ b/website/src/components/Hero.tsx @@ -21,7 +21,7 @@ export function Hero(): JSX.Element {

开始使用 diff --git a/website/src/pages/index.tsx b/website/src/pages/index.tsx index fb8a6cfa..71ef0276 100644 --- a/website/src/pages/index.tsx +++ b/website/src/pages/index.tsx @@ -2,7 +2,6 @@ import clsx from "clsx"; import React from "react"; import CodeBlock from "@theme/CodeBlock"; -import { HeroFeatureDouble, HeroFeatureSingle } from "@theme/Hero"; import Layout from "@theme/Layout"; import { Hero, HeroFeature } from "../components/Hero";