69-Custom UI · WPS Office JavaScript 宏教程（JS宏）

[TOC] > Tue May 11 2021 04:44:50 GMT+0800 (GMT+08:00) WPS JS 插件功能區菜單貌似是基于 Office 2007 UI 標準的，你可以用它的 Ribbon UI 標準庫來給自己的插件設計菜單。差別在于： 1. 面向 Office 設計的功能區菜單一般需要 VBA 宏作為菜單元素的事件響應，比如按鈕、輸入框等等。而 WPS 插件則需要用 JavaScript 的函數來響應。 > 注意：單文件`"注入"式(嵌入)`的 CustomUI 在 WPS 中打開雖然能顯示自定義界面，但不會響應——除非你的 WPS 安裝了 VBA 環境且切換到 VBA 環境。 > > WPS 支持的 CustomUI 是針對 JS 加載項（JS插件）的（通常它是全局的），而 Micro Office 的 CustomUI 是可以鑲嵌到單個文件中（非全局，和文件一起保存，僅對這個文件生效），`WPS 沒有提供這個功能支持——將CustomUI注入單個文件中配合JS宏一起使用`。 2. RibbonUI 的配置文件 XML 中各組件的配置大同小異，主要差異是在組件回調上。了解Custom UI 的話很容易就做好。我們來看看官方文檔中的示例： 1. Ribbon xml ```XML <customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui" onLoad="OnAddinLoad"> <ribbon startFromScratch="false"> <tabs> <tab id="wpsAddinTab" label="wps加載項示例"> <group id="btnDemoGroup" label="group1"> <button id="btnShowMsg" label="彈出消息框" onAction="OnAction" getEnabled="OnGetEnabled" getImage="GetImage" visible="true" size="large"/> <button id="btnIsEnbable" getLabel="OnGetLabel" onAction="OnAction" enabled="true" getImage="GetImage" visible="true" size="large"/> <button id="btnShowDialog" label="彈對話框網頁" onAction="OnAction" getEnabled="OnGetEnabled" getImage="GetImage" getVisible="OnGetVisible" size="large"/> <button id="btnShowTaskPane" label="彈任務窗格網頁" onAction="OnAction" getEnabled="OnGetEnabled" getImage="GetImage" getVisible="OnGetVisible" size="large"/> <button id="btnApiEvent" getLabel="OnGetLabel" onAction="OnAction" getEnabled="OnGetEnabled" getImage="GetImage" getVisible="OnGetVisible" size="large"/> <button id="btnWebNotify" label="給業務系統發通知" onAction="OnAction" enabled="true" getImage="GetImage" getVisible="OnGetVisible" size="large"/> </group> </tab> </tabs> </ribbon> </customUI> ``` UI 組件回調響應 JS： ```js //這個函數在整個wps加載項中是第一個執行的 function OnAddinLoad(ribbonUI){ if (typeof (wps.ribbonUI) != "object"){ wps.ribbonUI = ribbonUI } if (typeof (wps.Enum) != "object") { // 如果沒有內置枚舉值 wps.Enum = WPS_Enum } wps.PluginStorage.setItem("EnableFlag", false) //往PluginStorage中設置一個標記，用于控制兩個按鈕的置灰 wps.PluginStorage.setItem("ApiEventFlag", false) //往PluginStorage中設置一個標記，用于控制ApiEvent的按鈕label return true } var WebNotifycount = 0; function OnAction(control) { const eleId = control.Id switch (eleId) { case "btnShowMsg": { const doc = wps.WpsApplication().ActiveDocument if (!doc) { alert("當前沒有打開任何文檔") return } alert(doc.Name) } break; case "btnIsEnbable": { let bFlag = wps.PluginStorage.getItem("EnableFlag") wps.PluginStorage.setItem("EnableFlag", !bFlag) //通知wps刷新以下幾個按飾的狀態 wps.ribbonUI.InvalidateControl("btnIsEnbable") wps.ribbonUI.InvalidateControl("btnShowDialog") wps.ribbonUI.InvalidateControl("btnShowTaskPane") //wps.ribbonUI.Invalidate(); 這行代碼打開則是刷新所有的按鈕狀態 break } case "btnShowDialog": wps.ShowDialog(GetUrlPath() + "/ui/dialog.html", "這是一個對話框網頁", 400 * window.devicePixelRatio, 400 * window.devicePixelRatio, false) break case "btnShowTaskPane": { let tsId = wps.PluginStorage.getItem("taskpane_id") if (!tsId) { let tskpane = wps.CreateTaskPane(GetUrlPath() + "/ui/taskpane.html") let id = tskpane.ID wps.PluginStorage.setItem("taskpane_id", id) tskpane.Visible = true } else { let tskpane = wps.GetTaskPane(tsId) tskpane.Visible = !tskpane.Visible } } break case "btnApiEvent": { let bFlag = wps.PluginStorage.getItem("ApiEventFlag") let bRegister = bFlag ? false : true wps.PluginStorage.setItem("ApiEventFlag", bRegister) if (bRegister){ wps.ApiEvent.AddApiEventListener('DocumentNew', OnNewDocumentApiEvent) } else{ wps.ApiEvent.RemoveApiEventListener('DocumentNew', OnNewDocumentApiEvent) } wps.ribbonUI.InvalidateControl("btnApiEvent") } break case "btnWebNotify": { let currentTime = new Date() let timeStr = currentTime.toLocaleDateString() + ", " + currentTime.toLocaleTimeString() wps.OAAssist.WebNotify("這行內容由wps加載項主動送達給業務系統，可以任意自定義, 比如時間值:" + timeStr + "，次數：" + (++WebNotifycount), true) } break default: break } return true } function GetImage(control) { const eleId = control.Id switch (eleId) { case "btnShowMsg": return "images/1.svg" case "btnShowDialog": return "images/2.svg" case "btnShowTaskPane": return "images/3.svg" default: ; } return "images/newFromTemp.svg" } function OnGetEnabled(control) { const eleId = control.Id switch (eleId) { case "btnShowMsg": return true break case "btnShowDialog": { let bFlag = wps.PluginStorage.getItem("EnableFlag") return bFlag break } case "btnShowTaskPane": { let bFlag = wps.PluginStorage.getItem("EnableFlag") return bFlag break } default: break } return true } function OnGetVisible(control){ return true } function OnGetLabel(control){ const eleId = control.Id switch (eleId) { case "btnIsEnbable": { let bFlag = wps.PluginStorage.getItem("EnableFlag") return bFlag ? "按鈕Disable" : "按鈕Enable" break } case "btnApiEvent": { let bFlag = wps.PluginStorage.getItem("ApiEventFlag") return bFlag ? "清除新建文件事件" : "注冊新建文件事件" break } } return "" } function OnNewDocumentApiEvent(doc){ alert("新建文件事件響應，取文件名: " + doc.Name) } ``` > 能在 JS 中找到組件中的一些屬性（配置項）吧，函數名對應組件的ID或者其他屬性值。 ## 工具集 1. Office Ribbon Editor [GitHub](https://github.com/fernandreu/office-ribbonx-editor) 2. visualribboneditor （據說不支持中文 label）加載項 https://andypope.info 上面兩個都是針對 Microsoft Office 的工具，可定制 Office Menu UI（加載項的菜單\功能區自定義界面），因為 WPS 沒有類似的工具，如果你不熟悉 Custom UI 標準，可以先在 Micro Office 上設計好，然后拿到 WPS 上使用。 custom UI 文檔 https://docs.microsoft.com/en-us/openspecs/office_standards/ms-customui/574eeee8-7a03-406a-b95f-f9e51e53dd9d 貌似都用 Ribbon 這個組件。沒太深入了解，大家自行研究。自定義的菜單、功能區是由 xml 配置的，你還得為為這些自定義的菜單、按鈕等寫代碼以響應其動作以及實現其功能。上面兩個工具生成的組件回調函數都是 VBA 的 Sub 過程，你要自己手動改成 JS 的 function。并進一步完善功能邏輯。如果你很熟悉這一套流程，可以： 1. Custom UI XML 轉為 JSON。 2. JSON 中提取組件 ID、方法、事件名稱，然后用字符模板生成組件的事件、功能對應的 JS 函數。 > 目的是不必在 XML 中一個一個組件地去找，然后一個一個組件地去寫功能實現。當然了，一個一個組件地去實現，靠譜些。