🔖 Release 2.4.3

website/versioned_docs/version-2.4.3/best-practice/alconna/builtins.mdx

@@ -0,0 +1,294 @@
+---
+sidebar_position: 7
+description: 内置组件
+---
+
+import Messenger from "@site/src/components/Messenger";
+
+# 内置组件
+
+`nonebot_plugin_alconna` 插件提供了一系列内置组件以提升开发者和用户体验。
+
+## 内置插件
+
+类似于 Nonebot 本身提供的内置插件，`nonebot_plugin_alconna` 提供了多个内置插件。
+
+### 加载
+
+你可以用本插件的 `load_builtin_plugin(s)` 来加载它们：
+
+```python
+from nonebot_plugin_alconna import load_builtin_plugin, load_builtin_plugins
+
+load_builtin_plugins("echo")
+load_builtin_plugins("help", "with")
+```
+
+### 使用
+
+#### echo
+
+`echo` 插件能将用户发送的消息原样返回。
+
+<Messenger
+  msgs={[
+    { position: "right", msg: "/echo hello world!" },
+    { position: "left", msg: "hello world!" },
+    { position: "right", msg: "/echo [图片]" },
+    { position: "left", msg: "[图片]" },
+  ]}
+/>
+
+#### help
+
+`help` 插件能列出所有 Alconna 指令。同时还能查询某个指令对应的插件信息。
+
+<Messenger
+  msgs={[
+    { position: "right", msg: "/帮助" },
+    {
+      position: "left",
+      msg: "# 当前可用的命令有:\n 【0】/echo : echo 指令\n 【1】/help : 显示所有命令帮助\n# 输入'命令名 -h|--help' 查看特定命令的语法",
+    },
+    { position: "right", msg: "/help --plugin-info echo" },
+    {
+      position: "left",
+      msg: "插件名称: echo\n插件标识: nonebot_plugin_alconna:echo\n插件模块: nonebot-plugin-alconna\n插件版本: 0.57.2\n插件路径: nonebot_plugin_alconna.builtins.plugins.echo",
+    },
+  ]}
+/>
+
+help 插件的帮助信息如下：
+
+```
+/help <query: str = -1>
+## 注释
+  query: 选择某条命令的id或者名称查看具体帮助
+显示所有命令帮助
+用法:
+可以使用 --hide 参数来显示隐藏命令，使用 -P 参数来显示命令所属插件名称
+
+可用的子命令有:
+* 是否列出命令所属命名空间
+  -N│--namespace│命名空间 [target: str]
+## 注释
+  target: 指定的命名空间
+  该子命令内可用的选项有:
+  * 列出所有命名空间
+    --list
+可用的选项有:
+* 查看指定页数的命令帮助
+  --page <index: int>
+* 查看命令所属插件的信息
+  -P│插件信息│--plugin-info
+* 是否列出隐藏命令
+  隐藏│-H│--hide
+```
+
+#### lang
+
+`lang` 插件能切换 i18n 的语言设置。
+
+<Messenger
+  msgs={[
+    { position: "right", msg: "/lang list" },
+    {
+      position: "left",
+      msg: "支持的语言列表:\n * en-US\n * zh-CN",
+    },
+    { position: "right", msg: "/lang switch en-US" },
+    { position: "left", msg: "Switch to 'en-US' successfully." },
+  ]}
+/>
+
+lang 插件的帮助信息如下：
+
+```
+/lang
+i18n配置相关功能
+
+可用的选项有:
+* 查看支持的语言列表
+  list [name: str]
+* 切换语言
+  switch [locale: str]
+```
+
+其中 `list` 选项可以查找某一插件下的语言支持情况 (例如 `/lang list nonebot_plugin_alconna`)。
+
+#### switch
+
+`switch` 插件能用来启用/禁用某个命令，其使用方法与 `help` 类似。
+
+<Messenger
+  msgs={[
+    { position: "right", msg: "/disable" },
+    {
+      position: "left",
+      msg: "【0】/echo : echo 指令\n【1】/help : 显示所有命令帮助\n【2】/lang : i18n配置相关功能",
+    },
+    { position: "right", msg: "/disable 0" },
+    { position: "left", msg: "已禁用 /echo" },
+    { position: "right", msg: "/echo 1234" },
+    { position: "right", msg: "/enable echo" },
+    { position: "left", msg: "已启用 /echo" },
+    { position: "right", msg: "/echo 1234" },
+    { position: "left", msg: "1234" },
+  ]}
+/>
+
+#### with
+
+`with` 插件能在当前会话中设置一个局部命令前缀，以便于有多个子命令的指令使用。
+
+<Messenger
+  msgs={[
+    { position: "right", msg: "/with" },
+    {
+      position: "left",
+      msg: "当前群组未设置前缀",
+    },
+    { position: "right", msg: "/with lang" },
+    { position: "left", msg: "设置前缀成功" },
+    { position: "right", msg: "list" },
+    {
+      position: "left",
+      msg: "支持的语言列表:\n * en-US\n * zh-CN",
+    },
+  ]}
+/>
+
+with 插件的帮助信息如下：
+
+```
+.with [name: str]
+with 指令
+用法:
+设置局部命令前缀
+
+可用的选项有:
+* 设置可能的生效时间
+  --expire│expire <time: datetime>
+* 取消当前前缀
+  unset│--unset
+
+快捷命令:
+'[.]局部前缀' => [.]with
+```
+
+### 配置
+
+内置插件也有其配置项，并且均以 `NBP_ALC` 开头。
+
+- `nbp_alc_echo_tome`: 是否让 `echo` 插件的消息经过 `to_me` 处理
+- `nbp_alc_page_size`: `help` 与 `switch` 插件的共同配置项，表示每页显示的命令数量
+- `nbp_alc_help_text`: `help` 指令的指令名，默认为 "help"
+- `nbp_alc_help_alias`: `help` 指令的别名，默认为 "帮助", "命令帮助"
+- `nbp_alc_help_all_alias`: `help` 指令显示隐藏指令时的别名，默认为 "所有帮助", "所有命令帮助"
+- `nbp_alc_switch_enable`: `switch` 插件的 `enable` 指令的指令名，默认为 "enable"
+- `nbp_alc_switch_enable_alias`: `switch` 插件的 `enable` 指令的别名，默认为 "启用", "启用指令"
+- `nbp_alc_switch_disable`: `switch` 插件的 `disable` 指令的指令名，默认为 "disable"
+- `nbp_alc_switch_disable_alias`: `switch` 插件的 `disable` 指令的别名，默认为 "disable", "禁用", "禁用指令"
+- `nbp_alc_with_text`: `with` 插件的指令名，默认为 "with"
+- `nbp_alc_with_alias`: `with` 插件的别名，默认为 "局部前缀"
+
+## 内置匹配拓展
+
+目前插件提供了 5 个内置的 `Extension`，它们在 `nonebot_plugin_alconna.builtins.extensions` 下：
+
+### ReplyRecordExtension
+
+`ReplyRecordExtension` 可将消息事件中的回复暂存在 extension 中，使得解析用的消息不带回复信息，同时可以在后续的处理中获取回复信息：
+
+```python
+from nonebot_plugin_alconna import MsgId, on_alconna
+from nonebot_plugin_alconna.builtins.extensions import ReplyRecordExtension
+
+matcher = on_alconna("...", extensions=[ReplyRecordExtension()])
+
+@matcher.handle()
+async def handle(msg_id: MsgId, ext: ReplyRecordExtension):
+    if reply := ext.get_reply(msg_id):
+        ...
+    else:
+        ...
+```
+
+### ReplyMergeExtension
+
+`ReplyMergeExtension` 可将消息事件中的回复指向的原消息合并到当前消息中作为一部分参数：
+
+```python
+from nonebot_plugin_alconna import Match, on_alconna
+from nonebot_plugin_alconna.builtins.extensions.reply import ReplyMergeExtension
+
+matcher = on_alconna("...", extensions=[ReplyMergeExtension()])
+
+@matcher.handle()
+async def handle(content: Match[str]):
+    ...
+```
+
+其构造时可传入两个参数:
+
+- `add_left`: 否在当前消息的左侧合并回复消息，默认为 False
+- `sep`: 合并时的分隔符，默认为空格
+
+### DiscordSlashExtension
+
+`DiscordSlashExtension` 可自动将 Alconna 对象翻译成 Discord 的 slash 指令并注册，且将收到的指令交互事件转为指令供命令解析：
+
+```python
+from nonebot_plugin_alconna import Match, on_alconna
+from nonebot_plugin_alconna.builtins.extensions.discord import DiscordSlashExtension
+
+
+alc = Alconna(
+    ["/"],
+    "permission",
+    Subcommand("add", Args["plugin", str]["priority?", int]),
+    Option("remove", Args["plugin", str]["time?", int]),
+    meta=CommandMeta(description="权限管理"),
+)
+
+matcher = on_alconna(alc, extensions=[DiscordSlashExtension()])
+
+@matcher.assign("add")
+async def add(plugin: Match[str], priority: Match[int], ext: DiscordSlashExtension):
+    await ext.send_followup_msg(f"added {plugin.result} with {priority.result if priority.available else 0}")
+
+@matcher.assign("remove")
+async def remove(plugin: Match[str], time: Match[int]):
+    await matcher.finish(f"removed {plugin.result} with {time.result if time.available else -1}")
+```
+
+### MarkdownOutputExtension
+
+`MarkdownOutputExtension` 可将 Alconna 的自动输出转换为 Markdown 格式
+
+其构造时可传入两个参数:
+
+- `escape_dot`: 是否转义句中的点号（用来避免被识别为 url）
+- `text_to_image` 将文本转换为图片的函数，可不传入。一般用来设置渲染 markdown 为图片的函数
+
+### TelegramSlashExtension
+
+`TelegramSlashExtension` 可将 Alconna 的命令注册在 Telegram 上以获得提示，类似于 `DiscordSlashExtension`。
+
+```python
+from nonebot_plugin_alconna import on_alconna
+from nonebot.adapters.telegram.model import BotCommandScopeChat
+from nonebot_plugin_alconna.builtins.extensions.telegram import TelegramSlashExtension
+
+TelegramSlashExtension.set_scope(BotCommandScopeChat())
+
+matcher = on_alconna("...", extensions=[TelegramSlashExtension()])
+```
+
+## 内置自定义消息段
+
+目前插件提供了 3 个内置的 `Segment`，它们在 `nonebot_plugin_alconna.builtins.segments` 下：
+
+- `Markdown`: 可以传入 **markdown模板** 的元素
+- `MarketFace`: 特指 QQ 的商城表情
+- `MusicShare`: 特指 QQ 的音乐分享卡片