水缸机器人

Appearance

指令面板 ​

概述 ​

指令面板是用户在聊天窗口中快速触发命令的入口。点击面板中的指令项，内容会自动填入聊天输入框。

与键盘按钮的区别

  • 键盘按钮：挂在消息下方，每条消息独立
  • 指令面板：固定在聊天窗口，全局可用，不依赖特定消息

快速上手 ​

创建面板 ​

java
import cn.org.bukkit.bngeuit.Bngeuit;
import cn.org.bukkit.bngeuit.dto.message.panel.*;
import java.util.List;

// 创建全局群聊面板
Panel panel = Panel.of(List.of(
    PanelItem.command("帮助", "查看帮助信息"),
    PanelItem.command("签到", "每日签到"),
    PanelItem.link("官网", "访问官方网站", "https://example.com")
), "通用指令面板");

Bngeuit.createPanel(PanelScope.GROUP, PanelTargetType.ALL, null, null, panel);

创建指定群面板 ​

仅对指定群生效：

java
// 面板仅在指定群生效
Bngeuit.createPanel(
    PanelScope.GROUP,
    PanelTargetType.SPECIFIC,
    null,                                    // userOpenids（群场景不需要）
    List.of("group_openid_1", "group_openid_2"),  // 指定群
    panel
);

创建指定用户面板（C2C） ​

仅对指定用户生效：

java
Bngeuit.createPanel(
    PanelScope.C2C,
    PanelTargetType.SPECIFIC,
    List.of("user_openid_1", "user_openid_2"),  // 指定用户
    null,
    panel
);

查询面板列表 ​

java
// 查询群聊面板
PanelListResponse resp = Bngeuit.getPanels(PanelScope.GROUP);

for (PanelRecord record : resp.records()) {
    System.out.println("ID: " + record.panelId());
    System.out.println("备注: " + record.remark());
    System.out.println("作用范围: " + record.targetType());
}

// 查询 C2C 面板
PanelListResponse c2cResp = Bngeuit.getPanels(PanelScope.C2C);

查询面板详情 ​

java
PanelRecord detail = Bngeuit.getPanelDetail(panelId);
System.out.println("面板ID: " + detail.panelId());
System.out.println("版本: " + detail.version());
System.out.println("元素数量: " + detail.items().size());

修改面板 ​

java
Panel newPanel = Panel.of(List.of(
    PanelItem.command("新命令", "新描述"),
    PanelItem.command("帮助", "更新后的帮助")
), "更新后的面板");

Bngeuit.updatePanel(panelId, newPanel);

修改面板关联对象 ​

java
import cn.org.bukkit.bngeuit.dto.message.panel.PanelTargetOp;

// 添加关联群
Bngeuit.updatePanelTarget(panelId, 
    new PanelTargetRequest(PanelTargetOp.ADD, null, List.of("new_group_openid")));

// 删除关联群
Bngeuit.updatePanelTarget(panelId, 
    new PanelTargetRequest(PanelTargetOp.DEL, null, List.of("old_group_openid")));

删除面板 ​

java
Bngeuit.deletePanel(panelId);

面板元素类型 ​

指令（COMMAND） ​

用户点击后，指令内容填入聊天输入框：

java
// 普通指令
PanelItem.command("帮助", "查看帮助信息")

// 仅管理员可用
PanelItem.command("踢人", "踢出群成员", true)

用户点击后，在浏览器中打开链接：

java
// 普通链接
PanelItem.link("官网", "访问官方网站", "https://example.com")

// 仅管理员可用
PanelItem.link("管理后台", "后台管理", "https://admin.example.com", true)

API 参考 ​

Panel ​

面板配置：

方法说明
Panel.of(items, remark)创建面板配置
Panel.of(items, remark, version)创建带版本号的配置（修改时使用）

PanelItem ​

面板元素：

方法说明
PanelItem.command(name, desc)指令类型
PanelItem.command(name, desc, onlyAdmin)指令类型（可限制管理员）
PanelItem.link(name, desc, url)链接类型
PanelItem.link(name, desc, url, onlyAdmin)链接类型（可限制管理员）

参数说明：

  • name：元素名称，最多 14 个字符
  • desc：元素描述，最多 30 个字符
  • url：跳转链接
  • onlyAdmin：是否仅管理员可操作

PanelScope ​

面板生效场景枚举：

枚举JSON 值说明
C2C"c2c"单聊
GROUP"group"群聊

PanelTargetType ​

面板作用范围枚举：

枚举JSON 值说明
ALL"all"全局生效
SPECIFIC"specific"指定用户/群生效

PanelTargetOp ​

关联对象操作枚举：

枚举JSON 值说明
ADD"add"添加关联
DEL"del"删除关联

PanelRecord ​

面板记录：

字段类型说明
panelId()String面板 ID
scope()PanelScope生效场景
targetType()PanelTargetType作用范围
items()List<PanelItem>面板元素列表
remark()String备注
version()Integer版本号

PanelItemType ​

面板元素类型枚举：

枚举说明
COMMAND指令
LINK链接

限制 ​

  • 一个机器人最多创建 20 个指令面板
  • 面板元素最多 20 个
  • target_type=specific 时，关联用户/群最多 20 个

完整示例 ​

java
import cn.org.bukkit.bngeuit.Bngeuit;
import cn.org.bukkit.bngeuit.dto.message.panel.*;
import java.util.List;

public class PanelExample {
    
    public static void create售后群面板() {
        Panel panel = Panel.of(List.of(
            PanelItem.command("查询订单", "查询订单状态"),
            PanelItem.command("申请退款", "提交退款申请"),
            PanelItem.command("联系客服", "转接人工客服"),
            PanelItem.link("帮助中心", "查看常见问题", "https://help.example.com")
        ), "售后群专用面板");
        
        Bngeuit.createPanel(
            PanelScope.GROUP,
            PanelTargetType.SPECIFIC,
            null,
            List.of("售后群_openid"),
            panel
        );
    }
    
    public static void listAllPanels() {
        // 群聊面板
        System.out.println("=== 群聊面板 ===");
        PanelListResponse groupPanels = Bngeuit.getPanels(PanelScope.GROUP);
        for (PanelRecord r : groupPanels.records()) {
            System.out.printf("ID: %s, 备注: %s, 作用范围: %s%n", 
                r.panelId(), r.remark(), r.targetType());
        }
        
        // C2C 面板
        System.out.println("\n=== C2C 面板 ===");
        PanelListResponse c2cPanels = Bngeuit.getPanels(PanelScope.C2C);
        for (PanelRecord r : c2cPanels.records()) {
            System.out.printf("ID: %s, 备注: %s%n", r.panelId(), r.remark());
        }
    }
}