Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Docs: 添加 Alconna 响应器介绍 #2069

Merged
merged 7 commits into from
May 31, 2023
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
📝 remove some inline code
RF-Tar-Railt authored May 31, 2023

Verified

This commit was created on GitHub.com and signed with GitHub’s verified signature.
commit d4f085011266ce69d9682268a40e7b32e39ed2b8
23 changes: 10 additions & 13 deletions website/docs/advanced/matcher.md
Original file line number Diff line number Diff line change
@@ -308,7 +308,7 @@ matcher2 = group.on_message()
### Alconna

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

特点包括:
@@ -325,19 +325,16 @@ matcher2 = group.on_message()

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

同时,基于 [`Annotated` 支持](https://github.com/nonebot/nonebot2/pull/1832), 添加了两类注解 `AlcMatches` 与`AlcResult`
同时,基于 [Annotated 支持](https://github.com/nonebot/nonebot2/pull/1832), 添加了两类注解 `AlcMatches` 与 `AlcResult`

该插件还可以通过 `handle(parameterless)` 来控制一个具体的响应函数是否在不满足条件时跳过响应:

- `pip.handle([Check(assign("add.name", "nb"))])` 表示仅在命令为 `role-group add` 并且 name 为 `nb` 时响应
- `pip.handle([Check(assign("list"))])` 表示仅在命令为 `role-group list` 时响应
- `pip.handle([Check(assign("add"))])` 表示仅在命令为 `role-group add` 时响应

基于 `Alconna` 的特性,该插件同时提供了一系列便捷的 `MessageSegment` 标注。

标注可用于在 `Alconna` 中匹配消息中除 text 外的其他 `MessageSegment`,也可用于快速创建各适配器下的 `MessageSegment`

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

#### 插件安装

@@ -351,7 +348,7 @@ nb plugin install nonebot-plugin-alconna
pip install nonebot-plugin-alconna
```

#### 展示
#### 示例

```python
from nonebot_plugin_alconna.adapters import At
@@ -386,11 +383,11 @@ async def _(result: Arparma = AlconnaMatches()):
await rg.finish("添加成功")
```

我们可以看到主要的两大组件:**Option****Subcommand**
我们可以看到主要的两大组件:`Option``Subcommand`

`Option` 可以传入一组 `alias`,如 `Option("--foo|-F|--FOO|-f")``Option("--foo", alias=["-F"]`
`Option` 可以传入一组别名,如 `Option("--foo|-F|--FOO|-f")``Option("--foo", alias=["-F"]`

`Subcommand` 则可以传入自己的 **Option****Subcommand**
`Subcommand` 则可以传入自己的 `Option``Subcommand`

他们拥有如下共同参数:

@@ -399,14 +396,14 @@ async def _(result: Arparma = AlconnaMatches()):
- `requires`: 一段指定顺序的字符串列表,作为唯一的前置序列与命令嵌套替换
- `default`: 默认值,在该组件未被解析时使用使用该值替换。

其次使用了 `MessageSegment` 标注,其中 `At` 属于通用标注,而 `Image` 属于 `onebot12` 适配器下的标注。
其次使用了消息段标注,其中 `At` 属于通用标注,而 `Image` 属于 `onebot12` 适配器下的标注。

`on_alconna` 的所有参数如下:

- `command: Alconna | str`: Alconna 命令
- `skip_for_unmatch: bool = True`: 是否在命令不匹配时跳过该响应
- `auto_send_output: bool = False`: 是否自动发送输出信息并跳过响应
- `output_converter: TConvert | None = None`: 输出信息字符串转换为 Message 方法
- `output_converter: TConvert | None = None`: 输出信息字符串转换为消息序列方法
- `aliases: set[str | tuple[str, ...]] | None = None`: 命令别名, 作用类似于 `on_command` 中的 aliases
- `comp_config: CompConfig | None = None`: 补全会话配置, 不传入则不启用补全会话