跳到正文
本頁目錄

Form(表單 UI)

ll/api/form/ · 通用

概述

Form 模塊提供了三種可發送給玩家的交互式 UI 表單:SimpleForm(按鈕列表)、ModalForm(雙按鈕對話框)和 CustomForm(多字段輸入表單)。

頭文件

頭文件說明
ll/api/form/SimpleForm.h按鈕列表表單
ll/api/form/ModalForm.h雙按鈕確認對話框
ll/api/form/CustomForm.h多字段輸入表單
ll/api/form/FormBase.h表單基類

SimpleForm

具有標題、可選內容文本和按鈕列表的表單。

C++
namespace ll::form {
class SimpleForm : public Form {
public:
    using Callback       = std::function<void(Player&, int, FormCancelReason)>;
    using ButtonCallback = std::function<void(Player&)>;

    SimpleForm();
    SimpleForm(std::string const& title, std::string const& content = {});

    SimpleForm& setTitle(std::string const& title);
    SimpleForm& setContent(std::string const& content);
    SimpleForm& appendHeader(std::string const& text);
    SimpleForm& appendLabel(std::string const& text);
    SimpleForm& appendDivider();

    SimpleForm& appendButton(std::string const& text, ButtonCallback callback = {});
    SimpleForm& appendButton(std::string const& text, std::string const& imageData,
                             std::string const& imageType, ButtonCallback callback = {});

    SimpleForm& sendTo(Player& player, Callback callback = {});
    SimpleForm& sendUpdate(Player& player, Callback callback = {});
};
}

示例

C++
#include "ll/api/form/SimpleForm.h"
#include "mc/world/actor/player/Player.h"

void showMenu(Player& player) {
    ll::form::SimpleForm form("主菜单", "请选择一个选项:");

    form.appendButton("传送回家", [](Player& p) {
        // 传送玩家回家
    });

    form.appendButton("查看余额", [](Player& p) {
        // 显示余额
    });

    form.appendButton("设置", "textures/ui/settings_glyph_color_2x", "path",
        [](Player& p) {
            // 打开设置
        }
    );

    form.sendTo(player);
}

ModalForm

雙按鈕確認對話框。

C++
namespace ll::form {
enum class ModalFormSelectedButton : bool { Upper = true, Lower = false };
using ModalFormResult = std::optional<ModalFormSelectedButton>;

class ModalForm : public Form {
public:
    using Callback = std::function<void(Player&, ModalFormResult, FormCancelReason)>;

    ModalForm();
    ModalForm(std::string title, std::string content, std::string upperButton, std::string lowerButton);

    ModalForm& setTitle(std::string const& title);
    ModalForm& setContent(std::string const& content);
    ModalForm& setUpperButton(std::string const& upperButton);
    ModalForm& setLowerButton(std::string const& lowerButton);

    bool sendTo(Player& player, Callback callback = {});
    bool sendUpdate(Player& player, Callback callback = {});
};
}

示例

C++
#include "ll/api/form/ModalForm.h"

void confirmAction(Player& player) {
    ll::form::ModalForm form(
        "确认",
        "你确定要重置数据吗?",
        "是,重置",
        "取消"
    );

    form.sendTo(player, [](Player& p, ll::form::ModalFormResult result, ll::form::FormCancelReason) {
        if (result == ll::form::ModalFormSelectedButton::Upper) {
            // 用户点击了"是,重置"
        } else {
            // 用户点击了"取消"或关闭了表单
        }
    });
}

CustomForm

具有多種輸入元素的表單:文本輸入、開關、下拉菜單、滑塊和步進滑塊。

C++
namespace ll::form {
using CustomFormElementResult = std::variant<std::monostate, uint64, double, std::string>;
using CustomFormResult = std::optional<std::unordered_map<std::string, CustomFormElementResult>>;

class CustomForm : public Form {
public:
    using Callback = std::function<void(Player&, CustomFormResult const&, FormCancelReason)>;

    CustomForm();
    CustomForm(std::string const& title);

    CustomForm& setTitle(std::string const& title);
    CustomForm& setSubmitButton(std::string const& text);
    CustomForm& appendHeader(std::string const& text);
    CustomForm& appendLabel(std::string const& text);
    CustomForm& appendDivider();

    CustomForm& appendInput(std::string const& name, std::string const& text,
                            std::string const& placeholder = {},
                            std::string const& defaultVal = {},
                            std::string const& tooltip = {});

    CustomForm& appendToggle(std::string const& name, std::string const& text,
                             bool defaultVal = false, std::string const& tooltip = {});

    CustomForm& appendDropdown(std::string const& name, std::string const& text,
                               std::vector<std::string> const& options,
                               size_t defaultVal = 0, std::string const& tooltip = {});

    CustomForm& appendSlider(std::string const& name, std::string const& text,
                             double min, double max, double step = 0.0,
                             double defaultVal = 0.0, std::string const& tooltip = {});

    CustomForm& appendStepSlider(std::string const& name, std::string const& text,
                                 std::vector<std::string> const& steps,
                                 size_t defaultVal = 0, std::string const& tooltip = {});

    CustomForm& sendTo(Player& player, Callback callback = {});
    CustomForm& sendUpdate(Player& player, Callback callback = {});
};
}

示例

C++
#include "ll/api/form/CustomForm.h"

void showSettings(Player& player) {
    ll::form::CustomForm form("服务器设置");

    form.appendInput("motd", "服务器 MOTD", "输入 MOTD...", "A Minecraft Server");
    form.appendToggle("pvp", "启用 PvP", true);
    form.appendSlider("renderDistance", "视距", 2, 32, 1, 10);
    form.appendDropdown("difficulty", "难度", {"和平", "简单", "普通", "困难"}, 2);
    form.appendStepSlider("gamemode", "默认游戏模式", {"生存", "创造", "冒险"}, 0);

    form.sendTo(player, [](Player& p, ll::form::CustomFormResult const& result, ll::form::FormCancelReason) {
        if (!result) return; // 表单被取消

        auto& data = *result;
        auto motd = std::get<std::string>(data.at("motd"));
        auto pvp = std::get<uint64>(data.at("pvp"));            // 0 或 1
        auto renderDist = std::get<double>(data.at("renderDistance"));
        auto difficulty = std::get<uint64>(data.at("difficulty")); // 索引
    });
}

相關模塊