教學:編寫腳本API/server-ui模組基礎

server-ui模組基礎

系列教學

所屬系列

編寫腳本API

難易度

初級

實踐裝置

所需軟體

◄ Entity類基礎

server-gametest模組基礎 ►

引言

server-ui模組是 server 模組的一個支撐模組，它擁有強大的功能，我們將幫助您了解和使用此類。

匯入

在確保你已經匯入了server模組的前提下，在清單檔案中先匯入server-ui模組(參見 Tutorial:編寫腳本API/開始之前)，像下面這個樣子:

{
    "module_name": "@minecraft/server-ui",
    "version": "1.3.0-beta"
}

接下來你同樣只需要一行就可以匯入server-ui:

import * as ui from "@minecraft/server-ui";

構建ui

@minecraft/server-ui 模組包含用於表達簡單資訊的ui，下面是目前提供的可用ui:

• ActionFormData: 包含一個帶有標題和圖片的按鈕列表，可用於向玩家呈現一組選項。
• MessageFormData: 是簡單的雙按鈕訊息ui，適用於Yes/No或OK/Cancel問題。
• ModalFormData: 允許更靈活的「瀏覽器風格」控制項列表，可用於取得輸入。

ActionFormData

這是包含一堆積按鈕的表單。這個表單非常適合商店UI，小遊戲選擇等。
先看它的建構函式:

new ActionFormData()

let form = new ui.ActionFormData();

這個表單有三個屬性:標題，主體，按鈕。

標題

標題是表單頂部的文字。

// title(titleText: minecraftserver.RawMessage | string): ActionFormData

form.title("Test");    //例

主體

這是一段文字出現在標題的下方，按鈕的上方，一般用於解釋這個ui的功能(可以理解為正文)。

// body(bodyText: minecraftserver.RawMessage | string): ActionFormData

form.body("Body");    //例

按鈕

按鈕是窗體的主要功能。表單可以有許多按鈕供玩家選擇。

// button(text: minecraftserver.RawMessage | string, iconPath?: string): ActionFormData

//例
form.button("Button 1");    //无图标仅文字
form.button("Button 2", "textures/items/compass");    //图标加文字

圖示是從已應用的資源包(可以不是內建資源包)中取得。

MessageFormData

訊息表單是由2個按鈕組成的表單，具有較大的描述（主體）。此表單適用於 是/否 問題或 確定/取消 表單。

let form = new ui.MessageFormData();

它擁有三個屬性:標題，主體，雙按鈕。

標題

// title(titleText: minecraftserver.RawMessage | string): MessageFormData

form.title("wiki");    //例

這和ActionFormData差不多。

主體

// body(bodyText: minecraftserver.RawMessage | string): MessageFormData

form.body("Body");    //例

雙按鈕

雙按鈕事實上是兩個函式，這兩個函式缺一不可，它們分別是:

/* button1:
button1(text: minecraftserver.RawMessage | string): MessageFormData */
form.button1("确定用按钮");
/* button2:
button2(text: minecraftserver.RawMessage | string): MessageFormData */
form.button2("否定用按钮");

ModalFormData

這個表單在所有ui中擁有最多的輸入型別。它有文字欄位，滑塊，下拉選單和切換。

let form = new ModalFormData();

和別的ui不同的是它沒有主體。

標題

// title(titleText: minecraftserver.RawMessage | string): ModalFormData

form.title("wiki");    //例

提交按鈕

這個函式相對特殊，它不是必要的，就算沒有它提交按鈕也必然出現(顯示文字採用玩家所選擇的語言中的「提交」)，它的主要功能是設定提交按鈕的展現文字。

// submitButton(submitButtonText: minecraftserver.RawMessage | string): ModalFormData

form.submitButton("点这里提交");

下拉

下拉是一個常見的ui，例如模式修改的ui就是下拉。

// dropdown(label: minecraftserver.RawMessage | string, options: (minecraftserver.RawMessage | string)[], defaultValueIndex?: number): ModalFormData

form.dropdown(["选项1","选项2"]);

var list = ["选项1"];

form.dropdown(list, 0);

滑塊

滑塊並不常用，它用於展示一個僅傳回數字的拉條。

// slider(label: minecraftserver.RawMessage | string, minimumValue: number, maximumValue: number, valueStep: number, defaultValue?: number): ModalFormData

form.slider("标题", 1, 100, 1);

form.slider("滑块标题", 0, 10, 2, 10);

輸入框

輸入框允許您輸入字串，它比較方便，可以用來製作指定座標的傳送系統等。它傳回一個字串。

// textField(label: minecraftserver.RawMessage | string, placeholderText: minecraftserver.RawMessage | string, defaultValue?: minecraftserver.RawMessage | string): ModalFormData

form.textField("输入框", "提示文字");

form.textField("输入框标题", "提示文字", "默认值");

切換

它看起來像一個開關，僅傳回布林值。

// toggle(label: minecraftserver.RawMessage | string, defaultValue?: boolean): ModalFormData

form.toggle("标题"); 

form.toggle("切换框标题", true);

擴充套件提示

這裡提供幫助您建立ui的一些想法。

展示ui

在我們建立表單之後，我們需要向玩家顯示錶單並儲存響應以執行其他任務。我們需要一些活動來展示我們的形式。
比較常用的是使用itemUse事件(具體參考請見server.itemUse)。

mc.world.beforeEvents.itemUse.subscribe(event => {
	if (event.itemStack.typeId === "minecraft:stick" && event.itemStack.nameTag === "打开用的工具名字") {
		// 打开窗口的函数
        uiShow(event.source);
    }
});

現在你可以使用一個叫 開啟用的工具名字 的木棒來開啟視窗。
這裡推薦使用一個專門的函式來開啟視窗。
下一步我們就需要進行意見回饋了。

基本展示

我們需要一個專門的函式.show()來開啟ui，這個函式每個form都有，它需要一個玩家(Player)型別的參數。
然後再使用.then()來做出響應。

function uiShow(target) {
    form.show(target)
        .then(r => {
        // 操作
    })
        .
    catch ((e) => {
        console.error(e, e.stack);
    });
};

當玩家關閉表單時，即使沒有給出輸入，其中的函式.then()也會執行。這可能會導致在播放器關閉窗體幸運行意外程式碼。為防止這種情況，您需要使用.canceled取消腳本。

form.show(target)
    .then(r => {
        if (r.canceled) return;
        // 操作
    })
    // ...

部分情況下會有更複雜的取消要求:

form.show(target)
    .then(r => {
        if (r.canceled || r.selection === undefined) {
            // 关闭后的操作
            return;
        }
        // 操作
    })
    //...

或者是

function uiShow(target) {
    form.show(target)
        .then(r => {
        if (r.canceled) {
            if (r.cancelationReason === "UserBusy" || r.cancelationReason === undefined) {
                uiShow(target);    // 当玩家因已打开其他UI(即 "UserBusy")而无法打开此UI时，再此打开此UI，直至玩家正常打开
            } else {
                // 关闭后的操作
            }
            return;
        }
        // 操作
    })
    // ...
}

接下來為您介紹每種Form獨有的操作資料。

ActionFormData

r.selection是此Form玩家的選擇按鈕索引。

read-only selection?: number;

switch (r.selection) {
    case 0:
        break;
    case 1:
        break;
    default:
        return;    // 使用 return 而非 break
}

MessageFormData

r.selection是此Form玩家所按按鈕的索引。

   注意:虽然看上去此UI并没有关闭按钮，但事实上按“Escape”(手机版使用手机版退出页面的方法)即可退出。

if (r.selection === 0) {
    // ...
} else {
    // ...
}

ModalFormData

r.formValues可能是最難懂的。他是指這個UI所有輸入內容的有序列表。

read-only formValues?: (boolean | number | string)[];

let form = new ui.ModalFormData();
form.title(...);
form.textField(...);
form.dropdown(...);
form.slider(...);
form.toggle(...);
form.show(...).then(r => {
    // ...
    let [ textField, dropdown, slider, toggle ] = r.formValues;
    // ...
})

範例

import * as mc from "@minecraft/server";
import * as ui from "@minecraft/server-ui";

mc.world.beforeEvents.itemUse.subscribe(event => {
	if (event.itemStack.typeId === "minecraft:stick" && event.itemStack.nameTag === "打开用的工具名字") {
		// 打开窗口的函数
        uiShow(event.source);
	}
});

function uiShow(target) {
    let form = new ui.ActionFormData()
        .title("测试用UI")
        .body("主体")
        .button("1")
        .button("2");
    
    form.show(target)
        .then(r => {
        if (r.canceled) {
            if (r.cancelationReason === "UserBusy" || r.cancelationReason === undefined) {
                uiShow(target);    // 当玩家因已打开其他UI(即 "UserBusy")而无法打开此UI时，再此打开此UI，直至玩家正常打开
            }
            return;
        }
        // 操作
    })
}

UI管理

UIManager是本模組的一個類，它提供了一些方法來管理我們的UI。

closeAllForms

這個函式可以用來關閉目前顯示給玩家的所有視窗UI，它還能關閉其他的外掛所開啟的ui，同時被關閉的ui將不傳回cancelationReason‌^{[需要驗證]}。

// closeAllForms(player: minecraftserver.Player): void

ui.UIManager.closeAllForms(mc.world.getAllPlayers()[0]);

引用

1. 官方文件