LegacyScriptEngine API:表單與界面顯示
LSE 中玩家關閉表單(按 Esc/返回)時回調收到什麼?文檔寫的是 Null,但 JS 裡 data === null 判斷失效,怎麼辦?
玩家取消表單時,回調中的結果(SimpleForm 的 id、CustomForm 的 data、ModalForm 的 result)為空值。由於 ScriptX 在 C++ 層不區分 null 和 undefined,LSE 返回的空 Local<Value> 在 JS 中實際是 undefined,所以 data === null 會失效。請用 data == null 或 !data(注意 id 為 0 時 !id 也為真,SimpleForm 建議用 id == null)判斷玩家是否關閉了表單。回調第三個參數 reason 表示取消原因(0 = UserClosed,1 = UserBusy),也可能為空。
適用版本:當前所有 LSE 版本
LSE/LLSE 腳本插件中,玩家點擊表單後如何讓玩家返回上一個表單?如何判斷玩家關閉了表單?
再次調用 pl.sendForm(form, callback) 把上一個表單發給玩家即可。常見寫法:
- 把表單的構建和發送封裝成一個具名函數(回調也定義為具名函數),需要返回時在回調裡再次調用該函數;
- 緩存上一個表單實例,返回時用
player.sendForm傳入緩存的實例和回調; - 用一個類維護“當前表單/上一個表單”的會話棧實現多級返回。
玩家直接關閉表單時,回調的結果參數為空(JS 中為 undefined),用 data == null 判斷即可。
適用版本:當前所有 LSE 版本(LLSE 時期寫法同樣適用)
LSE/LLSE 表單按鈕(SimpleForm.addButton)的圖片參數可以用哪些來源?怎麼用自定義圖片?
addButton(text, image) 的 image 有兩種:
- 資源包紋理路徑,如原版的
textures/items/diamond,或在自制資源包中放textures/test/test.png後填textures/test/test,需要玩家加載該資源包; - 以
http開頭的網絡圖片 URL(LSE 會自動識別為 url 類型)。
URL 圖片在客戶端加載較慢、偶有顯示問題,屬於客戶端行為,追求穩定建議用資源包路徑。圖片尺寸沒有硬性限制,主要影響顯示比例。
適用版本:當前所有 LSE 版本
覺得 LSE 自帶的表單 API 不好用,有沒有可以直接給按鈕綁定回調、支持 async 的表單封裝庫?
可以使用第三方庫 FormAPIEx(https://github.com/lgc-LLDev/FormAPIEx),提供帶類型提示(d.ts)、async 語法、按鈕直接綁定回調的表單封裝,示例見倉庫中的 FormAPIExExample.js。另外 XYSDK(https://github.com/xianyubb/XYSDK)中也有類似封裝。也可以自己把 LSE 的 mc.newSimpleForm / mc.newCustomForm 封裝成 Promise 風格。
適用版本:LSE(JS);第三方庫兼容性需自行確認。未能從源碼或文檔中直接證實,僅供參考。
LSE 自定義表單 fm.addDropdown 傳入在線玩家列表時報錯 "can't cast value as string",如何在下拉菜單中列出所有在線玩家名字?
mc.getOnlinePlayers() 返回的是 Array<Player>,而 fm.addDropdown(title, items[, default, tooltip]) 的 items 要求 Array<String>,直接傳 Player 對象會在轉換為字符串時報 can't cast value as string。先轉成名字數組再傳入:
let names = mc.getOnlinePlayers().map(player => player.name);
fm.addDropdown("选择玩家", names);玩家名通過 Player 的 name(或 realName)屬性獲取。
適用版本:LegacyScriptEngine 當前版本
LSE 中發送給玩家的表單(Form)只能由客戶端交互關閉嗎?有沒有辦法用代碼強制關閉或覆蓋已打開的表單?
現在 LSE 直接提供了 pl.closeForm(),會向客戶端發送關閉表單的數據包(ClientboundCloseFormPacket),不需要再手動構造數據包(closeForm 於 2025-05 加入)。
要覆蓋/更新已打開的表單,可以在發送時傳入可選參數 forUpdating=true(於 0.11.0 加入),例如 pl.sendForm(fm, callback, true)(sendModalForm/sendSimpleForm/sendCustomForm 同樣支持),此時以表單更新的方式發送;各 send* 函數也會返回發送的表單 ID。
適用版本:LSE 0.11.0 及以上
LSE 中如何創建併發送自定義表單(CustomForm)?
文檔見 https://levimc.org/zh-Hant/LegacyScriptEngine/apis/GuiAPI/FormBuilder/。示例:
var fm = mc.newCustomForm();
fm.setTitle("标题");
fm.addLabel("文本");
fm.addInput("描述", "提示", "默认内容");
fm.addSwitch("开关", false);
fm.addDropdown("下拉", ["选项1", "选项2"], 0);
fm.addSlider("滑块", 最小, 最大, 步长, 初始值);
fm.addStepSlider("步进滑块", ["选项1", "选项2"], 0);
pl.sendForm(fm, (player, data, reason) => { /* ... */ });回調中的 data 是按控件順序排列的數組,為 null 表示玩家取消了表單;reason 為取消原因:0 = UserClosed,1 = UserBusy,也可能為 null。新版還支持 addHeader/addDivider、各控件的 tooltip 參數以及 setSubmitButton。
在 LSE 中用 CustomForm(mc.newCustomForm)做自定義表單時,怎樣取輸入框的值?怎樣區分玩家點了提交還是關掉了表單?
CustomForm 自帶提交按鈕,不用自己加。pl.sendForm(fm, callback) 的回調原型是 function(player, data, reason):
data是按控件添加順序排列的數組,取輸入框的值用對應下標,比如第 3 個控件就是data[2]。data為null表示玩家取消或關閉了表單,不為null才是提交。reason是取消原因(0= UserClosed,1= UserBusy),可能為null。
不確定時可以把回調參數全部 log 出來看。
適用版本:LSE 0.23.x
LSE 的 player.sendForm 等表單回調現在能拿到玩家取消表單的原因嗎?
可以。自 LSE 0.9.0 起表單回調多了一個取消原因參數 reason(Integer,對應 LeviLamina 的 FormCancelReason),例如 SimpleForm 回調為 function(player, id, reason),CustomForm 回調為 function(player, data, reason);正常提交時 reason 可能為 null。
適用版本:LSE 0.9.0 及以上
LSE 自定義表單 addDropdown(title, [a, b]) 選中某項後,回調 data 中返回的是選項序號還是選項值?
返回的是選中項的序號(index,從 0 開始),例如選中第一項 a 返回 0,需要自己用 items[data[i]] 取值。
LSE 自定義表單(mc.newCustomForm)中 addInput 輸入框不填內容直接提交,回調返回的是空字符串、undefined 還是 null?玩家關閉表單時如何處理?
未輸入內容就提交時,該項返回空字符串 ""。玩家直接關閉或放棄表單時,回調的 data(SimpleForm 則是 id)為空(null / undefined),第三個參數 reason 表示取消原因(0 = UserClosed,1 = UserBusy,也可能為 null)。應在回調開頭用 if (data == null) return; 判斷,並可以提示用戶表單已關閉。
LSE(JS)中用 pl.sendModalForm 發送模式表單(確認/取消兩個按鈕)後,回調的 result 有哪些取值?需要額外判斷 null 嗎?
回調原型為 function(player, result, reason)。result 為 true 表示點擊了確認(上方/按鈕1),false 表示點擊了取消(下方/按鈕2);玩家直接點 X 關閉表單時 result 沒有值(文檔寫作 Null,JS 中實際拿到的是 undefined)。一般把它和取消按同樣處理即可,例如 if (result) {...} else {...},不必再單獨 else if 判斷 null。如需區分關閉原因,可看第三個參數 reason(表單取消原因,僅在取消時有值)。
適用版本:LSE 0.9 及以上;當前 0.23.x