89 lines
3.3 KiB
Markdown
89 lines
3.3 KiB
Markdown
# 💻 Command组件详解
|
||
|
||
## 📖 什么是Command
|
||
|
||
Command是直接响应用户明确指令的组件，与Action不同，Command是**被动触发**的，当用户输入特定格式的命令时立即执行。
|
||
|
||
Command通过正则表达式匹配用户输入，提供确定性的功能服务。
|
||
|
||
### 🎯 Command的特点
|
||
|
||
- 🎯 **确定性执行**：匹配到命令立即执行，无随机性
|
||
- ⚡ **即时响应**：用户主动触发，快速响应
|
||
- 🔍 **正则匹配**：通过正则表达式精确匹配用户输入
|
||
- 🛑 **拦截控制**：可以控制是否阻止消息继续处理
|
||
- 📝 **参数解析**：支持从用户输入中提取参数
|
||
|
||
---
|
||
|
||
## 🛠️ Command组件的基本结构
|
||
|
||
首先，Command组件需要继承自`BaseCommand`类，并实现必要的方法。
|
||
|
||
```python
|
||
class ExampleCommand(BaseCommand):
|
||
command_name = "example" # 命令名称，作为唯一标识符
|
||
command_description = "这是一个示例命令" # 命令描述
|
||
command_pattern = r"" # 命令匹配的正则表达式
|
||
|
||
async def execute(self) -> Tuple[bool, Optional[str], bool]:
|
||
"""
|
||
执行Command的主要逻辑
|
||
|
||
Returns:
|
||
Tuple[bool, str, bool]:
|
||
- 第一个bool表示是否成功执行
|
||
- 第二个str是执行结果消息
|
||
- 第三个bool表示是否需要阻止消息继续处理
|
||
"""
|
||
# ---- 执行命令的逻辑 ----
|
||
return True, "执行成功", False
|
||
```
|
||
**`command_pattern`**: 该Command匹配的正则表达式，用于精确匹配用户输入。
|
||
|
||
请注意：如果希望能获取到命令中的参数，请在正则表达式中使用有命名的捕获组，例如`(?P<param_name>pattern)`。
|
||
|
||
这样在匹配时，内部实现可以使用`re.match.groupdict()`方法获取到所有捕获组的参数，并以字典的形式存储在`self.matched_groups`中。
|
||
|
||
### 匹配样例
|
||
假设我们有一个命令`/example param1=value1 param2=value2`，对应的正则表达式可以是：
|
||
|
||
```python
|
||
class ExampleCommand(BaseCommand):
|
||
command_name = "example"
|
||
command_description = "这是一个示例命令"
|
||
command_pattern = r"/example (?P<param1>\w+) (?P<param2>\w+)"
|
||
|
||
async def execute(self) -> Tuple[bool, Optional[str], bool]:
|
||
# 获取匹配的参数
|
||
param1 = self.matched_groups.get("param1")
|
||
param2 = self.matched_groups.get("param2")
|
||
|
||
# 执行逻辑
|
||
return True, f"参数1: {param1}, 参数2: {param2}", False
|
||
```
|
||
|
||
---
|
||
|
||
## Command 内置方法说明
|
||
```python
|
||
class BaseCommand:
|
||
def get_config(self, key: str, default=None):
|
||
"""获取插件配置值，使用嵌套键访问"""
|
||
|
||
async def send_text(self, content: str, reply_to: str = "") -> bool:
|
||
"""发送回复消息"""
|
||
|
||
async def send_type(self, message_type: str, content: str, display_message: str = "", typing: bool = False, reply_to: str = "") -> bool:
|
||
"""发送指定类型的回复消息到当前聊天环境"""
|
||
|
||
async def send_command(self, command_name: str, args: Optional[dict] = None, display_message: str = "", storage_message: bool = True) -> bool:
|
||
"""发送命令消息"""
|
||
|
||
async def send_emoji(self, emoji_base64: str) -> bool:
|
||
"""发送表情包"""
|
||
|
||
async def send_image(self, image_base64: str) -> bool:
|
||
"""发送图片"""
|
||
```
|
||
具体参数与用法参见`BaseCommand`基类的定义。 |