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

server-ui模組基礎

系列教學

所屬系列

編寫腳本API

難易度

初級

實踐裝置

所需軟件

◄ Entity類基礎

server-gametest模組基礎 ►

引言

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

匯入

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

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

接下來你同樣只需要一行指令就可以匯入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);
    });
};