📃 普通表單構建器 API

這些API可以協助開發者方便地構造一個普通表單

腳本引擎提供了普通表單對象來方便地創建一個自定義表單併發送至指定玩家。

創建表單對象

在使用這些API之前，你需要先用這個函數創建一個空白的普通表單對象

mc.newSimpleForm()

• 返回值：新創建的空白表單對象
• 返回值類型：SimpleForm

添加表單元素

創建完之後，你就可以用下面這些成員函數（成員方法）向對象中增加新的表單元素。
對於某個特定的表單對象fm，有以下這些函數可以使用：

設置表單的標題

fm.setTitle(title)

• 參數：
  • title : String
    表單的標題
• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：SimpleForm

設置表單的內容

fm.setContent(content)

• 參數：
  • content: String
    表單的文本內容
• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：SimpleForm

向表單內增加一行按鈕

fm.addButton(text[,image])

• 參數：
  • text : String
    按鈕文本的字符串
  • image: String
    （可選參數）按鈕圖片所在路徑
• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：SimpleForm

圖片路徑參數 image 使用材質包路徑或者URL來標識按鈕對應的圖標。
對於表單上的每個按鈕，如下設置對應的圖標

1. 如果使用材質包路徑，圖片路徑應該形如 textures/items/apple
2. 如果使用URL路徑，那麼在這裡放入完整的URL即可，形如 https://www.baidu.com/img/flexible/logo/pc/result.png
3. 如果這個按鈕你不需要顯示圖片，那不傳入此參數即可

向表單內增加標頭

fm.addHeader(text)

• 參數：
  • text : String
    標頭內容
• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：SimpleForm

向表單內增加一行文本

fm.addLabel(text)

• 參數：
  • text : String
    一行文本
• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：SimpleForm

向表單內增加分隔線

fm.addDivider()

• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：SimpleForm

發送表單

最後，在一切就緒之後，你可以將配置好的表單對象發送給玩家，並監聽玩家的互動消息
表單對象可以被反覆發送，每次發送都會返回一個不同的表單ID，並在有玩家互動時調用各自設置的回調函數，不會打架。

對於某個玩家對象pl，使用函數：

pl.sendForm(fm,callback[,forUpdating])

• 參數：
  • fm : SimpleForm
    配置好的表單對象
  • callback : Function
    玩家與表單元素互動之後被調用的回調函數。
  • forUpdating : Boolean （可選參數，在0.11.0中加入）是否為表單更新，默認值為false，即非表單更新
• 返回值：發送的表單ID
• 返回值類型：Integer
  • 如果返回值為Null，則代表發送失敗

參數callback的回調函數原型：function(player,id,reason) - player : Player
與表單互動的玩家對象 - id : Integer
玩家點擊的表單按鈕的序號，從0開始編號
如果id為Null，則代表玩家取消了表單 - reason : Integer 表單被取消的原因 0 = UserClosed, 1 = UserBusy reason可能會是null.

📰 自定義表單構建器 API

這些API可以協助開發者方便地構造一個自定義表單，不再需要為編寫JSON麻煩而頭疼

腳本引擎提供了自定義表單對象來方便地創建一個自定義表單併發送至指定玩家。

創建表單對象

在使用這些API之前，你需要先用這個函數創建一個空白的自定義表單對象

mc.newCustomForm()

• 返回值：新創建的空白表單對象
• 返回值類型：CustomForm

添加表單元素

創建完之後，你就可以用下面這些成員函數（成員方法）向對象中增加新的表單元素。
對於某個特定的表單對象fm，有以下這些函數可以使用：

設置表單的標題

fm.setTitle(title)

• 參數：
  • title : String
    表單的標題
• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：CustomForm

向表單內增加標頭

fm.addHeader(text)

• 參數：
  • text : String
    標頭內容
• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：CustomForm

向表單內增加一行文本

fm.addLabel(text)

• 參數：
  • text : String
    一行文本
• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：CustomForm

向表單內增加分隔線

fm.addDivider()

• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：CustomForm

向表單內增加一行輸入框

fm.addInput(title[,placeholder,default,tooltip])

• 參數：

  • title : String
    輸入框描述文本
  • placeholder : String
    （可選參數）輸入框內的提示字符
  • default : String
    （可選參數）輸入框中默認存在的內容
  • tooltip : String （可選參數，在0.12.0中加入）提示文本

• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）

• 返回值類型：CustomForm

向表單內增加一行開關選項

fm.addSwitch(title[,default,tooltip])

• 參數：
  • title : String
    開關選項描述文本
  • default : Boolean
    （可選參數）開關的默認狀態 開 / 關
  • tooltip : String （可選參數，在0.12.0中加入）提示文本
• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：CustomForm

向表單內增加一行下拉菜單

fm.addDropdown(title,items[,default,tooltip])

• 參數：

  • title : String
    下拉菜單描述文本

  • items : Array<String,String,...>
    下拉菜單中的選項文本列表

  • default : Integer
    （可選參數）下拉菜單默認選中的列表項序號。
    序號從0開始編號。默認為0，即默認選中列表的第一項

  • tooltip : String （可選參數，在0.12.0中加入）提示文本

• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）

• 返回值類型：CustomForm

向表單內增加一行遊標滑塊

fm.addSlider(title,min,max[,step,default,tooltip])

• 參數：
  • title : String
    游標滑塊描述文本
  • min : Integer
    游標滑塊最小值
  • max : Integer
    游標滑塊最大值
  • step : Integer
    （可選參數）游標滑塊調整的最小分度值，默認為1
  • default : Integer
    （可選參數）游標滑塊默認初始格數，數值必須在最小和最大格數之間。
    默認為0，即滑塊位於滑塊行的開頭
  • tooltip : String （可選參數，在0.12.0中加入）提示文本
• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：CustomForm

向表單內增加一行步進滑塊

fm.addStepSlider(title,items[,default,tooltip])

• 參數：

  • title : String
    步進滑塊描述文本

  • items : Array<String,String,...>
    步進滑塊的選項文本列表

  • default : Integer
    （可選參數）步進滑塊默認初始選項。序號從0開始編號
    默認為0，即滑塊位於滑塊行的開頭

  • tooltip : String （可選參數，在0.12.0中加入）提示文本

• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：CustomForm

設置提交按鈕的文本

fm.setSubmitButton(text)

• 參數：
  • text : String
    提交按鈕的文本
• 返回值：處理完畢的表單對象（便於連鎖進行其他操作）
• 返回值類型：CustomForm

發送表單

最後，在一切就緒之後，你可以將配置好的表單對象發送給玩家，並監聽玩家的互動消息
表單對象可以被反覆發送，每次發送都會返回一個不同的表單ID，並在有玩家互動時調用各自設置的回調函數，不會打架。

對於某個玩家對象pl，使用函數：

pl.sendForm(fm,callback[,forUpdating])

• 參數：
  • fm : CustomForm
    配置好的自定義表單對象
  • callback : Function
    玩家提交表單之後被調用的回調函數。
  • forUpdating : Boolean （可選參數，在0.11.0中加入）是否為表單更新，默認值為false，即非表單更新
• 返回值：發送的表單ID
• 返回值類型：Integer
  • 如果返回值為Null，則代表發送失敗

參數callback的回調函數原型：function(player,data,reason)

• player : Player
  與表單互動的玩家對象
• data : Array<...>
  返回的表單內容數組
  數組中中按表單上的控件順序儲存了每一個控件的內容
  如果data為Null，則代表玩家取消了表單
• reason : Integer 表單被取消的原因 0 = UserClosed, 1 = UserBusy reason可能會是null.