EnderRealm 技术文档

外观

Easy4Form 业务代码示例 ​

推荐导入方式 ​

始终使用代理层的 API，不要直接导入 v1 或 v2 的类：

java
// ✅ 正确：使用代理层
import cn.enderrealm.easy4form.api.Easy4FormAPI;
import cn.enderrealm.easy4form.api.SimpleFormBuilder;
import cn.enderrealm.easy4form.api.CustomFormBuilder;
import cn.enderrealm.easy4form.api.ModalFormBuilder;

// ❌ 错误：直接使用版本特定的类
import cn.enderrealm.easy4form.api.v1.Easy4FormAPI;
import cn.enderrealm.easy4form.api.v2.Easy4FormAPI;

简单表单 (Simple Form) ​

按钮列表形式的表单，玩家点击按钮后返回按钮索引。

基本用法 ​

java
import cn.enderrealm.easy4form.api.Easy4FormAPI;
import java.util.Arrays;
import java.util.List;

public void sendMenu(Player player) {
    List<String> buttons = Arrays.asList("商店", "传送", "设置", "退出");
    
    Easy4FormAPI.sendSimpleForm(
        player,
        "主菜单",
        "请选择一个选项：",
        buttons,
        response -> {
            if (response == null) {
                player.sendMessage("你关闭了表单");
                return;
            }
            
            switch (response) {
                case 0: openShop(player); break;
                case 1: openTeleport(player); break;
                case 2: openSettings(player); break;
                case 3: player.sendMessage("再见！"); break;
            }
        }
    );
}

带图片的按钮 ​

java
// 使用资源包中的图片
Easy4FormAPI.sendSimpleFormWithImages(
    player,
    "商店",
    "选择商品类别",
    Arrays.asList("武器", " armor", "食物"),
    Arrays.asList("textures/items/diamond_sword.png", 
                  "textures/items/diamond_chestplate.png",
                  "textures/items/apple.png"),
    response -> {
        // 处理响应
    }
);

// 使用 URL 图片
Easy4FormAPI.sendSimpleFormWithUrlImages(
    player,
    "商店",
    "选择商品类别",
    Arrays.asList("武器", "防具", "食物"),
    Arrays.asList("https://example.com/sword.png",
                  "https://example.com/armor.png",
                  "https://example.com/food.png"),
    response -> {
        // 处理响应
    }
);

使用 Builder 模式 ​

java
import cn.enderrealm.easy4form.api.SimpleFormBuilder;

public void sendCustomMenu(Player player) {
    new SimpleFormBuilder()
        .title("自定义菜单")
        .content("请选择操作")
        .button("选项1")
        .button("选项2")
        .button("选项3")
        .responseHandler(response -> {
            if (response != null) {
                player.sendMessage("你点击了按钮 " + (response + 1));
            }
        })
        .send(player);
}

模态表单 (Modal Form) ​

包含两个按钮的对话框（通常是 确认/取消）。

基本用法 ​

java
public void confirmAction(Player player) {
    Easy4FormAPI.sendModalForm(
        player,
        "确认删除",
        "确定要删除这个物品吗？此操作不可撤销。",
        "确定删除",  // true 按钮文本
        "取消",      // false 按钮文本
        response -> {
            if (response == null) {
                player.sendMessage("你关闭了对话框");
            } else if (response) {
                deleteItem(player);
                player.sendMessage("物品已删除");
            } else {
                player.sendMessage("操作已取消");
            }
        }
    );
}

使用 Builder 模式 ​

java
import cn.enderrealm.easy4form.api.ModalFormBuilder;

public void confirmTeleport(Player player, Location target) {
    new ModalFormBuilder()
        .title("确认传送")
        .content("即将传送到 " + target.getWorld().getName() + " 世界")
        .button1("立即传送")
        .button2("取消")
        .responseHandler(confirmed -> {
            if (confirmed != null && confirmed) {
                player.teleport(target);
                player.sendMessage("传送成功！");
            }
        })
        .send(player);
}

自定义表单 (Custom Form) ​

包含各种输入元素的表单：文本框、开关、滑块、下拉菜单等。

基本用法 ​

java
public void openSettings(Player player) {
    Easy4FormAPI.createCustomForm(
        player,
        "个人设置",
        response -> {
            if (response == null) {
                player.sendMessage("你关闭了设置");
                return;
            }
            
            String name = (String) response.get("player_name");
            boolean notifications = (boolean) response.get("notifications");
            int volume = (int) response.get("volume");
            String language = (String) response.get("language");
            
            // 保存设置
            saveSettings(player, name, notifications, volume, language);
            player.sendMessage("设置已保存！");
        }
    )
    .input("player_name", "玩家名称", "输入你的名称", player.getName())
    .toggle("notifications", "启用通知", true)
    .slider("volume", "音量", 0, 100, 10, 50)
    .dropdown("language", "语言", Arrays.asList("中文", "English", "日本語"), 0)
    .send(player);
}

完整示例：商店系统 ​

java
public void openShop(Player player, ShopCategory category) {
    Easy4FormAPI.createCustomForm(
        player,
        "商品详情 - " + category.getName(),
        response -> {
            if (response == null) return;
            
            int quantity = ((Number) response.get("quantity")).intValue();
            boolean useCoupon = (boolean) response.get("use_coupon");
            String paymentMethod = (String) response.get("payment");
            
            // 计算价格
            double price = category.getPrice() * quantity;
            if (useCoupon) price *= 0.9; // 9折优惠
            
            // 处理购买
            processPurchase(player, category, quantity, price, paymentMethod);
        }
    )
    .labelAuto("商品: " + category.getName())
    .labelAuto("单价: " + category.getPrice() + " 金币")
    .input("quantity", "购买数量", "输入数量", "1")
    .toggle("use_coupon", "使用优惠券 (9折)", false)
    .dropdown("payment", "支付方式", Arrays.asList("金币", "点券", "银行"), 0)
    .send(player);
}

表单组件类型 ​

组件方法参数返回值
标签.label(id, text)id, text无
文本框.input(id, text, placeholder, default)id, text, placeholder, defaultString
开关.toggle(id, text, default)id, text, defaultboolean
滑块.slider(id, text, min, max, step, default)id, text, min, max, step, defaultint
步进滑块.stepSlider(id, text, steps, default)id, text, steps, defaultString
下拉菜单.dropdown(id, text, options, default)id, text, options, defaultString

玩家检测 ​

java
import cn.enderrealm.easy4form.api.Easy4FormAPI;

// 通过 Player 对象检测
if (Easy4FormAPI.isBedrockPlayer(player)) {
    // 发送表单
}

// 通过 UUID 检测
UUID uuid = player.getUniqueId();
if (Easy4FormAPI.isBedrockPlayer(uuid)) {
    // 发送表单
}

// 获取 FloodgatePlayer 实例
FloodgatePlayer floodgatePlayer = Easy4FormAPI.getFloodgatePlayer(player);
if (floodgatePlayer != null) {
    // 使用 FloodgatePlayer
}

错误处理 ​

java
public void safeSendForm(Player player) {
    try {
        Easy4FormAPI.sendSimpleForm(
            player,
            "测试表单",
            "内容",
            Arrays.asList("按钮1"),
            response -> {
                // 处理响应
            }
        );
    } catch (Exception e) {
        player.sendMessage("表单发送失败，请联系管理员");
        e.printStackTrace();
    }
}

最佳实践 ​

  1. 始终检查玩家类型：在发送表单前检查是否为基岩版玩家
  2. 处理 null 响应：玩家关闭表单时响应为 null
  3. 使用代理层 API：不要直接使用 v1 或 v2 的类
  4. 链式调用：使用 Builder 模式保持代码简洁
  5. 异步处理：表单响应是异步的，不要在响应处理器中执行阻塞操作

© 2022-present EnderRealm. All rights reserved.