Skip to main content
Version: 2.3.3

Alconna 插件

nonebot-plugin-alconna 是一类提供了拓展响应规则的插件。 该插件使用 Alconna 作为命令解析器, 是一个简单、灵活、高效的命令参数解析器,并且不局限于解析命令式字符串。

该插件提供了一类新的事件响应器辅助函数 on_alconna,以及 AlconnaResult 等依赖注入函数。

该插件声明了一个 Matcher 的子类 AlconnaMatcher,并在 AlconnaMatcher 中添加了一些新的方法,例如:

  • assign:基于 Alconna 解析结果,执行满足目标路径的处理函数
  • dispatch:类似 CommandGroup,对目标路径创建一个新的 AlconnaMatcher,并将解析结果分配给该 AlconnaMatcher
  • got_path:类似 got,但是可以指定目标路径,并且能够验证解析结果是否可用
  • ...

基于 Alconna 的特性,该插件同时提供了一系列便捷的消息段标注。 标注可用于在 Alconna 中匹配消息中除 text 外的其他消息段,也可用于快速创建各适配器下的消息段。所有标注位于 nonebot_plugin_alconna.adapters 中。

该插件同时通过提供 UniMessage (通用消息模型) 实现了跨平台接收和发送消息的功能。

安装插件

在使用前请先安装 nonebot-plugin-alconna 插件至项目环境中,可参考获取商店插件来了解并选择安装插件的方式。如:

项目目录下执行以下命令:

nb plugin install nonebot-plugin-alconna

导入插件

由于 nonebot-plugin-alconna 作为插件,因此需要在使用前对其进行加载导入其中的 on_alconna 来使用命令拓展。使用 require 方法可轻松完成这一过程,可参考 跨插件访问 一节进行了解。

from nonebot import require

require("nonebot_plugin_alconna")

from nonebot_plugin_alconna import on_alconna

使用插件

在前面的深入指南中,我们已经得到了一个天气插件。 现在我们将使用 Alconna 来改写这个插件。

插件示例
from nonebot import on_command
from nonebot.rule import to_me
from nonebot.matcher import Matcher
from nonebot.adapters import Message
from nonebot.params import CommandArg, ArgPlainText

weather = on_command("天气", rule=to_me(), aliases={"weather", "天气预报"})

@weather.handle()
async def handle_function(matcher: Matcher, args: Message = CommandArg()):
if args.extract_plain_text():
matcher.set_arg("location", args)

@weather.got("location", prompt="请输入地名")
async def got_location(location: str = ArgPlainText()):
if location not in ["北京", "上海", "广州", "深圳"]:
await weather.reject(f"你想查询的城市 {location} 暂不支持,请重新输入!")
await weather.finish(f"今天{location}的天气是...")
from nonebot.rule import to_me
from arclet.alconna import Alconna, Args
from nonebot_plugin_alconna import Match, on_alconna

weather = on_alconna(
Alconna("天气", Args["location?", str]),
aliases={"weather", "天气预报"},
rule=to_me(),
)


@weather.handle()
async def handle_function(location: Match[str]):
if location.available:
weather.set_path_arg("location", location.result)

@weather.got_path("location", prompt="请输入地名")
async def got_location(location: str):
if location not in ["北京", "上海", "广州", "深圳"]:
await weather.reject(f"你想查询的城市 {location} 暂不支持,请重新输入!")
await weather.finish(f"今天{location}的天气是...")

在上面的代码中,我们使用 Alconna 来解析命令,on_alconna 用来创建响应器,使用 Match 来获取解析结果。

关于更多 Alconna 的使用方法,可参考 Alconna 文档, 或阅读 Alconna 基本介绍 一节。

关于更多 on_alconna 的使用方法,可参考 插件文档, 或阅读 响应规则的使用 一节。

交流与反馈

QQ 交流群: 🔗 链接

友链: 📚 文档