diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index f2656b4d..15bea39f 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -86,8 +86,7 @@ module.exports = context => ({ sidebar: { "/guide/": [ { - title: "指南", - path: "", + title: "开始", collapsable: false, sidebar: "auto", children: [ @@ -95,7 +94,15 @@ module.exports = context => ({ "installation", "getting-started", "creating-a-project", - "basic-configuration", + "basic-configuration" + ] + }, + { + title: "编写插件", + collapsable: false, + sidebar: "auto", + children: [ + "loading-a-plugin", "writing-a-plugin" ] } diff --git a/docs/README.md b/docs/README.md index e568de9f..a1607904 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,7 +3,7 @@ home: true heroImage: /logo.png tagline: An asynchronous QQ bot framework. actionText: 开始使用 -actionLink: /guide/ +actionLink: guide/ features: - title: 简洁 details: 提供极其简洁易懂的 API,使你可以毫无压力地开始验证你的绝佳创意,只需编写最少量的代码,即可实现丰富的功能。 diff --git a/docs/guide/loading-a-plugin.md b/docs/guide/loading-a-plugin.md new file mode 100644 index 00000000..bb7db02d --- /dev/null +++ b/docs/guide/loading-a-plugin.md @@ -0,0 +1,95 @@ +# 加载插件 + +在 [创建一个完整的项目](creating-a-project) 一章节中,我们已经创建了插件目录 `awesome_bot/plugins`,现在我们在机器人入口文件中加载它。当然,你也可以单独加载一个插件。 + +## 加载内置插件 + +在 `bot.py` 文件中添加以下行: + +```python{5} +import nonebot + +nonebot.init() +# 加载 nonebot 内置插件 +nonebot.load_bulitin_plugins() + +app = nonebot.get_asgi() + +if __name__ == "__main__": + nonebot.run() +``` + +这将会加载 nonebot 内置的插件,它包含: + +- 命令 `say`:可由**superuser**使用,可以将消息内容由特殊纯文本转为富文本 +- 命令 `echo`:可由任何人使用,将消息原样返回 + +以上命令均需要指定机器人,即私聊、群聊内@机器人、群聊内称呼机器人昵称。参考 [Rule: to_me](../api/rule.md#to-me) + +## 加载插件目录 + +在 `bot.py` 文件中添加以下行: + +```python{5} +import nonebot + +nonebot.init() +# 加载插件目录,该目录下为各插件,以下划线开头的插件将不会被加载 +nonebot.load_plugins("awesome_bot/plugins") + +app = nonebot.get_asgi() + +if __name__ == "__main__": + nonebot.run() +``` + +:::tip 提示 +加载插件目录时,目录下以 `_` 下划线开头的插件将不会被加载! +::: + +:::warning 提示 +**插件不能存在相同名称!** +::: + +:::danger 警告 +插件间不应该存在过多的耦合,如果确实需要导入某个插件内的数据,可以使用如下两种方法: + +1. (推荐) `from plugin_name import xxx` 而非 `from awesome_bot.plugins.plugin_name import xxx` +2. 在需要导入其他插件的文件中添加 `__package__ = "plugins"; from .plugin_name import xxx` (将共同的上层目录设定为父包后使用相对导入) + +具体可以参考:[nonebot/nonebot2#32](https://github.com/nonebot/nonebot2/issues/32) +::: + +## 加载单个插件 + +在 `bot.py` 文件中添加以下行: + +```python{5,7} +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() +``` + +## 子插件(嵌套插件) + + + +~~待填坑~~ + +## 运行结果 + +尝试运行 `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" +``` diff --git a/docs/guide/writing-a-plugin.md b/docs/guide/writing-a-plugin.md index 42657d9d..9953bfe7 100644 --- a/docs/guide/writing-a-plugin.md +++ b/docs/guide/writing-a-plugin.md @@ -2,38 +2,6 @@ 本章将以一个天气查询插件为例,教学如何编写自己的命令。 -## 加载插件 - -在 [创建一个完整的项目](creating-a-project) 一章节中,我们已经创建了插件目录 `awesome_bot/plugins`,现在我们在机器人入口文件中加载它。当然,你也可以单独加载一个插件。 - -:::tip 提示 -加载插件目录时,目录下以 `_` 下划线开头的插件将不会被加载! -::: - -在 `bot.py` 文件中添加以下行: - -```python{5,7} -import nonebot - -nonebot.init() -# 加载单独的一个插件,参数为合法的python包名 -nonebot.load_plugin("nonebot.plugins.base") -# 加载插件目录,该目录下为各插件,以下划线开头的插件将不会被加载 -nonebot.load_plugins("awesome_bot/plugins") - -app = nonebot.get_asgi() - -if __name__ == "__main__": - nonebot.run() -``` - -尝试运行 `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" -``` - ## 创建插件 现在我们已经有了一个空的插件目录,我们可以开始创建插件了!插件有两种形式 diff --git a/nonebot/plugins/base.py b/nonebot/plugins/base.py index 075ddd20..67ed40af 100644 --- a/nonebot/plugins/base.py +++ b/nonebot/plugins/base.py @@ -26,9 +26,9 @@ echo = on_command("echo", to_me()) @echo.handle() async def echo_escape(bot: Bot, event: Event, state: dict): - Message = event.message.__class__ - MessageSegment = event.message[0].__class__ + # Message = event.message.__class__ + # MessageSegment = event.message[0].__class__ - message = Message().append( # type: ignore - MessageSegment.text(str(event.message))) - await bot.send(message=message, event=event) + # message = Message().append( # type: ignore + # MessageSegment.text(str(event.message))) + await bot.send(message=event.message, event=event)