diff --git a/docs/api.md b/docs/api.md
index 0995a27b..2cb81512 100644
--- a/docs/api.md
+++ b/docs/api.md
@@ -783,7 +783,7 @@ sidebar: auto
-插件管理器:用于管理插件的加载以及插件中命令、自然语言处理器、事件处理器的开关
+插件管理器:用于管理插件的加载以及插件中命令、自然语言处理器、事件处理器的开关。
#### `cmd_manager`
@@ -791,7 +791,7 @@ sidebar: auto
- **说明:**
- 命令管理器实例
+ 命令管理器实例。
#### `nlp_manager`
@@ -799,109 +799,279 @@ sidebar: auto
- **说明:**
- 自然语言管理器实例
+ 自然语言管理器实例。
#### _class method_ `add_plugin(cls, module_path, plugin)`
- **说明:**
+ 注册一个 `Plugin` 对象。
+
- **参数:**
+ - `module_path: str`: 模块路径
+ - `plugin: Plugin`: Plugin 对象
+
- **返回:**
+ None
+
- **用法:**
+ ```python
+ plugin = Plugin(module, name, usage, commands, nl_processors, event_handlers)
+ PluginManager.add_plugin("path.to.plugin", plugin)
+ ```
+
#### _class method_ `get_plugin(cls, module_path)`
- **说明:**
+ 获取一个已经注册的 `Plugin` 对象。
+
- **参数:**
+ - `module_path: str`: 模块路径
+
- **返回:**
+ - `Optional[Plugin]`: Plugin 对象
+
- **用法:**
+ ```python
+ plugin = PluginManager.get_plugin("path.to.plugin")
+ ```
+
#### _class method_ `remove_plugin(cls, module_path)`
- **说明:**
+ 删除 Plugin 中的所有命令、自然语言处理器、事件处理器并移除 Plugin 对象。
+
+ :::danger
+ 这个方法实际并没有完全移除 Plugin 。仅是移除 Plugin 中的所有命令、自然语言处理器以及事件处理器。
+ :::
+
- **参数:**
+ - `module_path: str`: 模块路径
+
- **返回:**
+ - `bool`: 是否移除了插件
+
- **用法:**
#### _class method_ `switch_plugin_global(cls, module_path, state=None)`
- **说明:**
+ 根据 `state` 更改 plugin 中 commands, nl_processors, event_handlers 的全局状态。
+
+ :::warning
+ 更改插件状态并不会影响插件内 message_preprocessor, scheduler 等状态
+ :::
+
- **参数:**
+ - `module_path: str`: 模块路径
+ - `state: Optional[bool]`:
+ - `None(default)`: 切换状态,即 开 -> 关、关 -> 开
+ - `bool`: 切换至指定状态,`True` -> 开、`False` -> 关
+
- **返回:**
+ None
+
- **用法:**
+ ```python
+ from nonebot import message_preprocessor
+
+ # 全局关闭插件 path.to.plugin , 对所有消息生效
+ PluginManager.switch_plugin_global("path.to.plugin", state=False)
+
+ @message_preprocessor
+ async def processor(bot: NoneBot, event: CQEvent, plugin_manager: PluginManager):
+ plugin_manager.switch_plugin_global("path.to.plugin", state=False)
+ ```
+
#### _class method_ `switch_command_global(cls, module_path, state=None)`
- **说明:**
+ 根据 `state` 更改 plugin 中 commands 的全局状态。
+
- **参数:**
+ - `module_path: str`: 模块路径
+ - `state: Optional[bool]`:
+ - `None(default)`: 切换状态,即 开 -> 关、关 -> 开
+ - `bool`: 切换至指定状态,`True` -> 开、`False` -> 关
+
- **返回:**
+ None
+
- **用法:**
+ ```python
+ from nonebot import message_preprocessor
+
+ # 全局关闭插件 path.to.plugin 中所有命令, 对所有消息生效
+ PluginManager.switch_command_global("path.to.plugin", state=False)
+
+ @message_preprocessor
+ async def processor(bot: NoneBot, event: CQEvent, plugin_manager: PluginManager):
+ plugin_manager.switch_command_global("path.to.plugin", state=False)
+ ```
+
#### _class method_ `switch_nlprocessor_global(cls, module_path, state=None)`
- **说明:**
+ 根据 `state` 更改 plugin 中 nl_processors 的全局状态。
+
- **参数:**
+ - `module_path: str`: 模块路径
+ - `state: Optional[bool]`:
+ - `None(default)`: 切换状态,即 开 -> 关、关 -> 开
+ - `bool`: 切换至指定状态,`True` -> 开、`False` -> 关
+
- **返回:**
+ None
+
- **用法:**
+ ```python
+ from nonebot import message_preprocessor
+
+ # 全局关闭插件 path.to.plugin 中所有自然语言处理器, 对所有消息生效
+ PluginManager.switch_nlprocessor_global("path.to.plugin", state=False)
+
+ @message_preprocessor
+ async def processor(bot: NoneBot, event: CQEvent, plugin_manager: PluginManager):
+ plugin_manager.switch_nlprocessor_global("path.to.plugin", state=False)
+ ```
+
#### _class method_ `switch_eventhandler_global(cls, module_path, state=None)`
- **说明:**
+ 根据 `state` 更改 plugin 中 event handlers 的全局状态。
+
- **参数:**
+ - `module_path: str`: 模块路径
+ - `state: Optional[bool]`:
+ - `None(default)`: 切换状态,即 开 -> 关、关 -> 开
+ - `bool`: 切换至指定状态,`True` -> 开、`False` -> 关
+
- **返回:**
+ None
+
- **用法:**
+ ```python
+ from nonebot import message_preprocessor
+
+ # 全局关闭插件 path.to.plugin 中所有事件处理器, 对所有消息生效
+ PluginManager.switch_eventhandler_global("path.to.plugin", state=False)
+
+ @message_preprocessor
+ async def processor(bot: NoneBot, event: CQEvent, plugin_manager: PluginManager):
+ plugin_manager.switch_eventhandler_global("path.to.plugin", state=False)
+ ```
+
#### `switch_plugin(cls, module_path, state=None)`
- **说明:**
+ 根据 `state` 修改 plugin 的状态。仅对当前消息有效。
+
- **参数:**
+ - `module_path: str`: 模块路径
+ - `state: Optional[bool]`:
+ - `None(default)`: 切换状态,即 开 -> 关、关 -> 开
+ - `bool`: 切换至指定状态,`True` -> 开、`False` -> 关
+
- **返回:**
+ None
+
- **用法:**
+ ```python
+ from nonebot import message_preprocessor
+
+ # 关闭插件 path.to.plugin , 仅对当前消息生效
+ @message_preprocessor
+ async def processor(bot: NoneBot, event: CQEvent, plugin_manager: PluginManager):
+ plugin_manager.switch_plugin("path.to.plugin", state=False)
+ ```
+
#### `switch_command(cls, module_path, state=None)`
- **说明:**
+ 根据 `state` 修改 plugin 中 commands 的状态。仅对当前消息有效。
+
- **参数:**
+ - `module_path: str`: 模块路径
+ - `state: Optional[bool]`:
+ - `None(default)`: 切换状态,即 开 -> 关、关 -> 开
+ - `bool`: 切换至指定状态,`True` -> 开、`False` -> 关
+
- **返回:**
+ None
+
- **用法:**
+ ```python
+ from nonebot import message_preprocessor
+
+ # 关闭插件 path.to.plugin 中所有命令, 仅对当前消息生效
+ @message_preprocessor
+ async def processor(bot: NoneBot, event: CQEvent, plugin_manager: PluginManager):
+ plugin_manager.switch_command("path.to.plugin", state=False)
+ ```
+
#### `switch_nlprocessor(cls, module_path, state=None)`
- **说明:**
+ 根据 `state` 修改 plugin 中 nl_processors 的状态。仅对当前消息有效。
+
- **参数:**
+ - `module_path: str`: 模块路径
+ - `state: Optional[bool]`:
+ - `None(default)`: 切换状态,即 开 -> 关、关 -> 开
+ - `bool`: 切换至指定状态,`True` -> 开、`False` -> 关
+
- **返回:**
+ None
+
- **用法:**
-### `load_plugin(module_name)`
+ ```python
+ from nonebot import message_preprocessor
+
+ # 关闭插件 path.to.plugin 中所有自然语言处理器, 仅对当前消息生效
+ @message_preprocessor
+ async def processor(bot: NoneBot, event: CQEvent, plugin_manager: PluginManager):
+ plugin_manager.switch_nlprocessor("path.to.plugin", state=False)
+ ```
+
+### `load_plugin(module_path)`
- **说明:**
@@ -923,16 +1093,16 @@ sidebar: auto
加载 `nonebot_tuling` 插件。
-### `reload_plugin(module_name)`
+### `reload_plugin(module_path)`
- **说明:**
+ 重载插件。
+
:::danger
该函数为强制重载,可能导致不可预测的错误!
:::
- 重载插件(等价于)。
-
- **参数:**
- `module_path: str`: 模块路径
@@ -962,7 +1132,7 @@ sidebar: auto
- **返回:**
- - `Set[Plugin]`: 加载成功的插件 Plugin 对象
+ - `Set[Plugin]`: 加载成功的 Plugin 对象
- **用法:**
@@ -978,9 +1148,9 @@ sidebar: auto
加载内置插件。
-- **返回:**
+- **返回:**
- - `int:` 加载成功的插件数量
+ - `Set[Plugin]:`: 加载成功的 Plugin 对象
- **用法:**
@@ -1010,7 +1180,7 @@ sidebar: auto
- **说明:**
- 将函数装饰为命令处理器。
+ 将函数装饰为命令处理器 `CommandHandler_T` 。
被装饰的函数将会获得一个 `args_parser` 属性,是一个装饰器,下面会有详细说明。