From 6290d8bb236726b19a53c02c047314840ebb87a2 Mon Sep 17 00:00:00 2001 From: crazywhalecc Date: Fri, 6 Jan 2023 16:08:25 +0800 Subject: [PATCH 1/4] update class alias --- src/Globals/global_class_alias.php | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/src/Globals/global_class_alias.php b/src/Globals/global_class_alias.php index b300a620..1fdaaac5 100644 --- a/src/Globals/global_class_alias.php +++ b/src/Globals/global_class_alias.php @@ -3,17 +3,25 @@ declare(strict_types=1); class_alias(\ZM\Annotation\Framework\BindEvent::class, 'BindEvent'); +class_alias(\ZM\Annotation\Framework\Cron::class, 'Cron'); class_alias(\ZM\Annotation\Framework\Init::class, 'Init'); class_alias(\ZM\Annotation\Framework\Setup::class, 'Setup'); + class_alias(\ZM\Annotation\Http\Controller::class, 'Controller'); class_alias(\ZM\Annotation\Http\Route::class, 'Route'); + class_alias(\ZM\Annotation\Middleware\Middleware::class, 'Middleware'); + +class_alias(\ZM\Annotation\OneBot\BotAction::class, 'BotAction'); +class_alias(\ZM\Annotation\OneBot\BotActionResponse::class, 'BotActionResponse'); class_alias(\ZM\Annotation\OneBot\BotCommand::class, 'BotCommand'); class_alias(\ZM\Annotation\OneBot\BotEvent::class, 'BotEvent'); class_alias(\ZM\Annotation\OneBot\CommandArgument::class, 'CommandArgument'); +class_alias(\ZM\Annotation\OneBot\CommandHelp::class, 'CommandHelp'); + class_alias(\ZM\Annotation\Closed::class, 'Closed'); + class_alias(\ZM\Plugin\ZMPlugin::class, 'ZMPlugin'); -class_alias(\OneBot\V12\Object\OneBotEvent::class, 'OneBotEvent'); class_alias(\ZM\Context\BotContext::class, 'BotContext'); class_alias(\ZM\Store\KV\LightCache::class, 'LightCache'); class_alias(\ZM\Store\KV\Redis\KVRedis::class, 'KVRedis'); @@ -23,3 +31,5 @@ class_alias(\OneBot\Driver\Event\WebSocket\WebSocketOpenEvent::class, 'WebSocket class_alias(\OneBot\Driver\Event\WebSocket\WebSocketCloseEvent::class, 'WebSocketCloseEvent'); class_alias(\OneBot\Driver\Event\WebSocket\WebSocketMessageEvent::class, 'WebSocketMessageEvent'); class_alias(\OneBot\Driver\Event\Http\HttpRequestEvent::class, 'HttpRequestEvent'); + +class_alias(\OneBot\V12\Object\OneBotEvent::class, 'OneBotEvent'); From c634968020e42dc683e1c54df8cd596c56958272 Mon Sep 17 00:00:00 2001 From: crazywhalecc Date: Fri, 6 Jan 2023 16:08:59 +0800 Subject: [PATCH 2/4] add class alias doc generator --- .../Command/Generate/TextGenerateCommand.php | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 src/ZM/Command/Generate/TextGenerateCommand.php diff --git a/src/ZM/Command/Generate/TextGenerateCommand.php b/src/ZM/Command/Generate/TextGenerateCommand.php new file mode 100644 index 00000000..28989a5c --- /dev/null +++ b/src/ZM/Command/Generate/TextGenerateCommand.php @@ -0,0 +1,52 @@ +addArgument('name', InputArgument::REQUIRED, '生成的文本内容'); + } + + /** + * {@inheritDoc} + */ + protected function handle(): int + { + return match ($this->input->getArgument('name')) { + 'class-alias-md' => $this->generateClassAliasDoc(), + default => static::FAILURE, + }; + } + + private function generateClassAliasDoc(): int + { + $file = file_get_contents(FRAMEWORK_ROOT_DIR . '/src/Globals/global_class_alias.php'); + // 提取class_alias函数的参数 + preg_match_all('/class_alias\((.+?), \'(.+?)\'\);/', $file, $matches); + $full_maxlen = 0; + $short_maxlen = 0; + $line = []; + foreach ($matches[1] as $k => $v) { + $full_class = substr($v, 0, -7); + $short_class = $matches[2][$k]; + $line[] = [$full_class, $short_class]; + $full_maxlen = max($full_maxlen, strlen('`' . $full_class . '`')); + $short_maxlen = max($short_maxlen, strlen('`' . $short_class . '`')); + } + $this->write('| ' . str_pad('全类名', $full_maxlen) . ' | ' . str_pad('别名', $short_maxlen) . ' |'); + $this->write('| ' . str_pad('', $full_maxlen, '-') . ' | ' . str_pad('', $short_maxlen, '-') . ' |'); + foreach ($line as $v) { + $this->write('| ' . str_pad('`' . $v[0] . '`', $full_maxlen) . ' | ' . str_pad('`' . $v[1] . '`', $short_maxlen) . ' |'); + } + return static::SUCCESS; + } +} From 52e545d8b0a05468747aff8a791f4242fdae9a5b Mon Sep 17 00:00:00 2001 From: crazywhalecc Date: Fri, 6 Jan 2023 16:09:15 +0800 Subject: [PATCH 3/4] update some docs --- docs/.vuepress/config.js | 3 +- docs/components/bot/bot-context.md | 9 +++- docs/components/bot/message-segment.md | 60 +++++++++++++++++++++++++- docs/components/common/class-alias.md | 40 +++++++++++++++++ 4 files changed, 108 insertions(+), 4 deletions(-) create mode 100644 docs/components/common/class-alias.md diff --git a/docs/.vuepress/config.js b/docs/.vuepress/config.js index 0a5ad324..d91077e4 100644 --- a/docs/.vuepress/config.js +++ b/docs/.vuepress/config.js @@ -64,11 +64,12 @@ module.exports = { '/components/': [ { title: '组件', - collapsable: false, + collapsable: true, sidebarDepth: 2, children: [ 'bot/bot-context', 'bot/message-segment', + 'common/class-alias', ] } ] diff --git a/docs/components/bot/bot-context.md b/docs/components/bot/bot-context.md index efe09357..d5a22a2b 100644 --- a/docs/components/bot/bot-context.md +++ b/docs/components/bot/bot-context.md @@ -16,7 +16,11 @@ public function sos(\BotContext $ctx) 关于 BotContext 机器人上下文，如果你不喜欢上方通过参数绑定的依赖注入（DI）形式获取，还可以在相关事件内使用全局函数 `bot()` 获取： ```php -bot()->reply('牛逼'); +#[\BotCommand(match: 'SOS')] +public function sos() +{ + bot()->reply('不许求救！'); +} ``` ## reply() - 快速回复消息 @@ -33,9 +37,10 @@ bot()->reply('牛逼'); 回复模式说明： -- `ZM_REPLY_NONE`：不回复，直接发送消息。 +- `ZM_REPLY_NONE`：仅回复文本本身，直接发送消息。 - `ZM_REPLY_MENTION`：回复并 @ 消息发送者。 - `ZM_REPLY_QUOTE`：回复并引用消息。 +- `ZM_REPLY_` 其中 `$message` 和下方的 `sendMessage()` 内的 `$message` 参数格式一致，可参考下方。 `$reply_mode` 可以通过 `ZM_REPLY_MENTION` 和 `ZM_REPLY_QUOTE` 两个常量来设置，例如： diff --git a/docs/components/bot/message-segment.md b/docs/components/bot/message-segment.md index fcab558f..c9d89e3b 100644 --- a/docs/components/bot/message-segment.md +++ b/docs/components/bot/message-segment.md @@ -1,3 +1,61 @@ # 机器人消息段格式 -TODO。 +消息段是 OneBot 12 标准中约定的一部分内容，如果你想对 OneBot 12 标准的消息段部分深入了解，请到 [OneBot - 消息段](https://12.onebot.dev/interface/message/segments/)。 + +因为聊天信息不仅仅含有文字，还会有图片、语音、文件、at、表情包等富文本，所以消息段就是用来描述这些富文本的。 + +## 格式样例 + +消息段不同于字符串，消息段默认是一个数组，数组中的每个元素都是一个消息段对象，每个消息段对象都有一个 `type` 字段，用来描述这个消息段的类型。 +下面是一个以 JSON 格式表达的消息段样例： + +```json +[ + { + "type": "text", + "data": { + "text": "Hello, World!" + } + }, + { + "type": "image", + "data": { + "file_id": "blablablablabla" + } + } +] +``` + +这个消息段在实际的聊天机器人对应的窗口中可能表示为：“Hello, World!\[假设这里是一张图片\]”。 + +## 使用消息段 + +一般情况下，框架提供的消息发送和接收接口均会自动识别和转换字符串到消息段，所以你不需要手动构造消息段。 +但如果你想发送富文本时，需要通过 `\MessageSegment` 对象进行构造。此对象等同于上方消息段中的单个消息段元素，在传入后发送时会自动转换为数组形式的消息段。 + +在框架任意位置，你可以使用全局函数 `segment()` 生成一个消息段对象。 + +- 定义：`segment(string $type, array $daa)` +- 返回：`OneBot\V12\Object\MessageSegment` + +```php +#[BotCommand(match: '来个at')] +public function at() +{ + bot()->reply([segment('at', ['user_id' => bot()->getEvent()->getUserId()]), segment('text', ['text' => ' 这是一条at你的消息'])]); +} + +#[BotCommand(match: '来个图片')] +public function image() +{ + // 我们假设你发送的图片已经上传 + bot()->reply([segment('image', ['file_id' => 'blablablablabla'])]); +} +``` + + diff --git a/docs/components/common/class-alias.md b/docs/components/common/class-alias.md new file mode 100644 index 00000000..ee844120 --- /dev/null +++ b/docs/components/common/class-alias.md @@ -0,0 +1,40 @@ +# 类全局别名 + +在框架 1.x 和 2.x 老版本中，我们发现许多开发者在使用框架时，往往不会使用 PhpStorm 这类大型 IDE，而即使使用 VSCode 这类编辑器的时候也不一定会安装补全插件， +这样在编写机器人模块或插件时会因寻找每个对象的完整命名空间而烦恼。 + +在 3.0 版本起，框架对常用的注解事件和对象均使用了类别名功能，方便非 IDE 开发者编写插件。 + +## 别名使用 + +框架对别名的定义比较简单，由于内部暂时没有不同命名空间下重复类名的情况，所以我们目前只对需要别名类名的命名空间移除，例如： + +`\ZM\Annotation\OneBot\BotCommand` 注解事件类，在经过全局别名后，你也可以使用 `\BotCommand` 作为注解事件，效果相同。 + +## 别名列表 + +| 全类名 | 别名 | +|--------------------------------------------------------|-------------------------| +| `\ZM\Annotation\Framework\BindEvent` | `BindEvent` | +| `\ZM\Annotation\Framework\Cron` | `Cron` | +| `\ZM\Annotation\Framework\Init` | `Init` | +| `\ZM\Annotation\Framework\Setup` | `Setup` | +| `\ZM\Annotation\Http\Controller` | `Controller` | +| `\ZM\Annotation\Http\Route` | `Route` | +| `\ZM\Annotation\Middleware\Middleware` | `Middleware` | +| `\ZM\Annotation\OneBot\BotAction` | `BotAction` | +| `\ZM\Annotation\OneBot\BotActionResponse` | `BotActionResponse` | +| `\ZM\Annotation\OneBot\BotCommand` | `BotCommand` | +| `\ZM\Annotation\OneBot\BotEvent` | `BotEvent` | +| `\ZM\Annotation\OneBot\CommandArgument` | `CommandArgument` | +| `\ZM\Annotation\OneBot\CommandHelp` | `CommandHelp` | +| `\ZM\Annotation\Closed` | `Closed` | +| `\ZM\Plugin\ZMPlugin` | `ZMPlugin` | +| `\ZM\Context\BotContext` | `BotContext` | +| `\ZM\Store\KV\LightCache` | `LightCache` | +| `\ZM\Store\KV\Redis\KVRedis` | `KVRedis` | +| `\OneBot\Driver\Event\WebSocket\WebSocketOpenEvent` | `WebSocketOpenEvent` | +| `\OneBot\Driver\Event\WebSocket\WebSocketCloseEvent` | `WebSocketCloseEvent` | +| `\OneBot\Driver\Event\WebSocket\WebSocketMessageEvent` | `WebSocketMessageEvent` | +| `\OneBot\Driver\Event\Http\HttpRequestEvent` | `HttpRequestEvent` | +| `\OneBot\V12\Object\OneBotEvent` | `OneBotEvent` | From c678ead45d47d6cf08268ce35725d02aed1512ca Mon Sep 17 00:00:00 2001 From: crazywhalecc Date: Fri, 6 Jan 2023 16:12:59 +0800 Subject: [PATCH 4/4] update some docs --- docs/components/bot/bot-context.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/components/bot/bot-context.md b/docs/components/bot/bot-context.md index d5a22a2b..d620c8ff 100644 --- a/docs/components/bot/bot-context.md +++ b/docs/components/bot/bot-context.md @@ -40,7 +40,6 @@ public function sos() - `ZM_REPLY_NONE`：仅回复文本本身，直接发送消息。 - `ZM_REPLY_MENTION`：回复并 @ 消息发送者。 - `ZM_REPLY_QUOTE`：回复并引用消息。 -- `ZM_REPLY_` 其中 `$message` 和下方的 `sendMessage()` 内的 `$message` 参数格式一致，可参考下方。 `$reply_mode` 可以通过 `ZM_REPLY_MENTION` 和 `ZM_REPLY_QUOTE` 两个常量来设置，例如：