##### WOPI 主機 🡆 編輯器

MessageId	Values	說明
`Action_Save`	```json DontTerminateEdit: DontSaveIfUnmodified: Notify: ExtendedData: ```	儲存文件。 - `DontTerminateEdit` 和試算表相關，這會中斷編輯模式（文字游標消失）。設為 true 的話，就能儲存檔案，而不會終止編輯模式，也不會中斷使用者編輯試算表。 - `DontSaveIfUnmodified` 如果文件內容沒有變更（只是移動了游標），這會阻止 OxOffice Online 把檔案回存雲端硬碟，如此可防止不必要的版本修訂。 - `Notify` 設為 true 時，會在文件儲存完後，通知 WOPI 主機。詳情請參考 `Action_Save_Resp` - `ExtendedData` 如果標頭`X-LOOL-WOPI-ExtendedData` 有資料，則會原封不動地傳給WOPI 主機。資料內容不可是空白、換行或其他不可列印字元。 OxOffice Online 可以傳遞多個值，然後 WOPI 主機可以進一步對處理這些值。
`Action_SaveAs`	``` Filename: Notify: ```	建立文件副本，並給予新檔名（另存新檔）。 - `Filename` 新文件檔名。 - `Notify` 設為 true 時，會在文件儲存完後，通知 WOPI 主機。詳情請參考 `Action_Save_Resp`
`Action_FollowUser`	``` Follow: ViewId: ```	開啟或關閉跟隨特定編輯者功能。這會讓編輯畫面和指定對象同步。 - `Follow` true 開啟/ false 關閉。 - `ViewId` 要跟隨的編輯者 ID。
`Action_Close`		關閉文件。
`Action_Print`		列印文件。
`Action_Export`	``` Format: ```	以 `Format` 指定的格式下載文件。格式只能是 `Get_Export_Formats` 所指定列表其中之一。
`Action_InsertGraphics`	``` url: ```	從指定的位址下載圖片並插入文件中。
`Action_ShowBusy`	``` Label: ```	顯示具有 Lable 文字的忙碌畫面，類似存檔中的畫面。
`Action_HideBusy`		如果有忙碌畫面的話，關掉忙碌畫面。
`Action_ChangeUIMode`	``` Mode:'classic' 或 'notebookbar' ```	變更使用者介面： - classic：傳統下拉選單＋工具列。 - notebookbar：分頁式介面。
`Action_Paste`	``` Mimetype: Data: ```	繞過內部貼上機制，直接貼上資料到文件內。例如： `Values: {Mimetype: "text/plain;charset=utf-8", Data: "haha"}};`

##### 編輯器 🡆 WOPI 主機（回應）

MessageId	Values	說明
`Action_Load_Resp`	``` success: result: errorMsg: ```	文件載入完成。 - `success` true 成功、false 失敗。 - `result` 文件未載入的原因。 - `errorMsg` 載入失敗時的詳細錯誤訊息。也可能包含從 WOPI 主機傳回的錯誤訊息。
`Action_Save_Resp`	``` success: result: errorMsg: fileName: ```	文件儲存完成。只有`Action_Save` 或 `Action_SaveAs` PostMessage API 將 `Notify` 參數設為 true 時，才會得到這個回應。 - `success` true 成功、false 失敗。 - `result` 文件未儲存的原因。如果文件因未修改而未儲存，則此參數包含字串「unmodified」。這種情況下，WOPI 主機可以確保不會儲存到位編耕的文件。 - `errorMsg` 儲存失敗時的詳細錯誤訊息。也可能包含從 WOPI 主機傳回的錯誤訊息。 - `fileName` 如果 `success `為 true 則包含已儲存的檔案名稱。
`FollowUser_Changed`	``` FollowedViewId: IsFollowUser: IsFollowEditor: ```	跟隨狀態變更。 - `FollowedViewId` 哪個編輯者被跟隨。 - `IsFollowUser`是否啟用跟隨編輯者。 - `IsFollowEditor` 是否啟用跟隨編輯器。 - 如果 `IsFollowUser` 和 `IsFollowEditor` 都是 false，表示取消跟隨功能。
`Action_ChangeUIMode_Resp`	``` Mode: ```	變更使用介面。 `Mode` 使用哪種介面。

### **文件版本復原**

##### WOPI 主機 🡆 編輯器

MessageId	Values	說明
`Host_VersionRestore`	``` Status: ```	復原版本。唯一可能的值是 Pre\_Restore 此訊息由主機在實際復原文件之前以及使用者確定復原之後傳送。這樣，如果目前文件，還有未儲存的修改，OxOffice Online 可以在恢復文件之前將它們儲存到雲端硬碟中。

##### 編輯器 🡆 WOPI 主機

MessageId	Values	說明
`App_VersionRestore`	``` Status: ```	這是對 `Host_VersionRestore` 訊息的回應。目前 `Status` 的值為 `Pre_Restore_Ack` 表示 WOPI 主機可以繼續將文件回復到較早的版本。

只有當 `App_LoadingStatus` 包含功能中的 **VersionStates** 時，才會發出這些訊息。否則，主機可以立即將版本還原到早期版本。

### **其他**

##### WOPI 主機 🡆 編輯器

MessageId	Values	說明
`Insert_Button`	```json id: imgurl: hint: accessKey: mobile: tablet: insertBefore: unoCommand: ```	在頂端工具列插入自訂按鈕（僅顯示在傳統介面）。該按鈕被點擊時，若未指定 `unoCommand` 屬性，會觸發 `Clicked_Button` 的事件給 WOPI 主機，讓 WOPI 主機做相應處理。 - `id` 代表該按鈕的不可重複 ID。為了避免和原先工具列的其他按鈕 ID 衝突，建議在此類 ID 前，加上主機特有的名稱。如果和其他按鈕衝突，則不會新增按鈕。 - `imgurl` 按鈕圖示位址。建議的大小為 24x24 px。圖片位址應和 WOPI 主機為同一來源，易免違反 `Content-Security-Policy`。 - `hint` 按鈕的提示。 - `accessKey` 快捷鍵。使用者可以搭配 Alt 或 Alt+Shift 加上此鍵。注意不要和其他快捷鍵衝突。 - `mobile` 手機模式時，是否顯示該按鈕。 - `tablet` 平板模式時，是否顯示該按鈕。 - `insertBefore` 新增在哪個按鈕 ID 之前。請參考[查詢工具列按鈕 ID](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api#bkmrk-%E6%9F%A5%E8%A9%A2%E5%B7%A5%E5%85%B7%E5%88%97%E6%8C%89%E9%88%95-id) - `unoCommand` UNO 命令（[請參閱此處](https://wiki.documentfoundation.org/Development/DispatchCommands)）。設置這個屬性，就不會傳送 `Clicked_Button` 訊息給 WOPI 主機，而會交由 LibreOffice 直接執行此命令。
`Hide_Button`	``` id: ```	隱藏工具列按鈕。`id` 為按鈕 ID（[查詢工具列按鈕 ID](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api#bkmrk-%E6%9F%A5%E8%A9%A2%E5%B7%A5%E5%85%B7%E5%88%97%E6%8C%89%E9%88%95-id)）
`Show_Button`	``` id: ```	顯示工具列按鈕。`id` 為按鈕 ID（[查詢工具列按鈕 ID](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api#bkmrk-%E6%9F%A5%E8%A9%A2%E5%B7%A5%E5%85%B7%E5%88%97%E6%8C%89%E9%88%95-id)）
`Remove_Button`	``` id: ```	移除工具列按鈕。`id` 為按鈕 ID（[查詢工具列按鈕 ID](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api#bkmrk-%E6%9F%A5%E8%A9%A2%E5%B7%A5%E5%85%B7%E5%88%97%E6%8C%89%E9%88%95-id)）
`Remove_Statusbar_Element`	``` id: ```	移除狀態列元件。 `id` 是狀態列元件 ID（請參考：[查詢狀態列元件 ID](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api#bkmrk-%E6%9F%A5%E8%A9%A2%E7%8B%80%E6%85%8B%E5%88%97%E5%85%83%E4%BB%B6-id)）
`Hide_Menubar`		隱藏下拉選單列。
`Show_Menubar`		顯示下拉選單列。
`Grab_Focus`		喚醒休眠中的編輯器。通常編輯者在一段時間後沒有任何動作時，編輯器會進入休眠狀態（編輯介面變暗，並有訊息顯示），必要時，會中斷與伺服器連線。`Grab_Focus` 會重新喚醒編輯器，必要時重新連線伺服器。
`Hide_Ruler`		隱藏水平尺規（僅適用文字文件 Writer）。
`Show_Ruler`		隱藏水平尺規（僅適用文字文件 Writer）。
`Hide_Menu_Item`	``` id: ```	隱藏下拉選單中的選項。`id` 是指選項 ID ，它們分別定義在： - 文字文件：[uiconfig/text/menubar.json](https://github.com/OSSII/oxool-community/blob/v4/loleaflet/uiconfig/text/menubar.json) - 試算表文件：[uiconfig/spreadsheet/menubar.json](https://github.com/OSSII/oxool-community/blob/v4/loleaflet/uiconfig/spreadsheet/menubar.json) - 簡報文件：[uiconfig/presentation/menubar.json](https://github.com/OSSII/oxool-community/blob/v4/loleaflet/uiconfig/presentation/menubar.json) - 繪圖文件：[uiconfig/drawing/menubar.json](https://github.com/OSSII/oxool-community/blob/v4/loleaflet/uiconfig/drawing/menubar.json)
`Show_Menu_Item`	``` id: ```	顯示下拉選單中的選項。`id` 是指選項 ID。請參閱前項 `Hide_Menu_Item`
`Disable_Default_UIAction`	``` action: disable: ```	停用或啟用某個 UI 命令的預設行為。 - `action` 動作名稱。 - `disable` 表示停用 (true) 或啟用 (false) 預設行為。設為 true 時，指定的動作只會發出 `postMessage` 而不會執行預設行為。這讓 WOPI 主機可以根據 `postMessage` 事件，進行必要處理。請注意，某些動作沒有任何預設行為（如 `UI_SaveAs` 和 `UI_Share`），因此，這對它們沒有影響；但無論如何，他們只會發出 `postMessage` 通知，而不會採取預設行為舉例來說，`UI_Save` 預設會呼叫儲存命令（透過選單、工具列按鈕或鍵盤快捷鍵）。如果透過 `Disable_Default_UIAction` 停用 `UI_Save`，則不會呼叫儲存命令。停用 `UI_Save` 的 WOPI 主機，應該在文件需要儲存時，自行發出 `Action_Save`。同樣地，當停用 `UI_Close` 時，呼叫 `UI_Close`，並不會真的文件關閉，而是會發出 postMessage 通知，並且由 WOPI 主機在需要時發出 `Action_Close`。 WOPI 主機必須很小心，不要在啟用預設行為的狀態下，發出重複的`Action_xxyyzz` 等指令。相反地，只能在停用預設行為時，才能自行發出操作。注意：目前也只有 `UI_Save` 和 `UI_Close` 以及 `UI_Hyperlink` 能停用🤣
`Send_UNO_Command`	```json Command: Args:	向編輯器傳送 UNO 命令。請參考：[framed.doc.html](https://github.com/OSSII/oxool-community/blob/v4/loleaflet/html/framed.doc.html)

### **查詢狀態列元件 ID** 狀態列元件 ID 定義在 [Control.StatusBar.js](https://github.com/OSSII/oxool-community/blob/v4/loleaflet/src/control/Control.StatusBar.js) 的 `onDocLayerInit` 函數中。通常不會改變，但並不保證這些 ID 會穩定存在。 ### **事件通知**

##### 編輯器 🡆 WOPI 主機

MessageId	Values	說明
`Clicked_Button`	``` id: ```	點擊透過前面的 `Insert_Button` API 新增的自訂按鈕時會發出此事件。
`Download_As`	``` Type: 'print'\|'slideshow'\|'export' URL: ```	當使用者選擇「列印」或「全螢幕投影」或「下載為…」，且 WOPI 主機在 [CheckFileInfo](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/8efb1#bkmrk-oxoffice-online-%E5%8F%AF%E7%94%A8%E7%9A%84-) 的`DownloadAsPostMessage` 屬性中，指定要接管時，就會觸發此事件。這應用於無法依賴瀏覽器下載的情況，例如手機的 Web view 模式。
`UI_Close`	```json EverModified: true \| false ```	當使用者選擇關閉文件，或點擊關閉按鈕，將觸發此事件。`EverModified` 指出此文件是否修改過。
`UI_Save`	```json source: 'filemenu' \| 'notebookbar' \| 'toolbar' ```	使用者選擇儲存。`source` 指出透過何種方式儲存。
`UI_CreateFile`	```json DocumentType: 'text' \| 'spreadsheet' \| 'presentation' \| 'drawing' ```	要求 WOPI 主機開啟新的瀏覽器分頁，並建立新文件。文件類型以 DocumentType 參數傳遞，可以是「text（文字文件）」、「spreadsheet（試算表）」、「presentation（簡報）」或「drawing（繪圖）」。
`UI_SaveAs`		要求 WOPI 主機顯示另存新檔 UI，以便使用者可以選擇路徑和檔案名稱來建立目前檔案的副本。若使用者確定存檔，則 WOPI 主機需以 `Action_SaveAs` 命令編輯器發送檔案內容。
`UI_Cancel_Password`		通知 WOPI 主機使用者在開啟有密碼保護的檔案時，點擊了「取消」，而不是輸入密碼。
`UI_Hyperlink`		通知 WOPI 主機只用者點擊了超連結，並確認確實想要離開文件以開啟超連結。這對於將 OxOffice Online 嵌入到行動裝置 iframe 中的 App 特別有用，實際嘗試開啟新視窗，應觸發在 Android 上的 Activity（或在 iOS 上類似的操作）。 WOPI 主機可能也想利用 `Disable_Default_UIAction` 來接管 `UI_Hyperlink`
`Doc_ModifiedStatus`	```json Modified: true \| false ```	更新文件的修改狀態。如果文件自上次儲存後被修改，則 `Modified `將為 true，否則，如果文件已儲存，則 `Modified `為 false。請注意，這個通知可能會在不更改先前值的情況下觸發，因此必須檢查 `Modified `的值，不要假設這個通知暗示文件的修改狀態。

### **呼叫 Python 巨集**

##### WOPI 主機 🡆 編輯器

MessageId	Values	說明
`CallPythonScript`	``` ScriptFile: Function: Values:	執行指定功能的 Python 巨集： - ScriptFile：巨集檔名 - Function：函數名稱 - Values：參數內容（key: value, ...）

##### 編輯器 🡆 WOPI 主機

MessageId	Values	說明
`CallPythonScript-Result`	``` commandName: Values:	傳回 Python 執行結果。`commandName `放的是巨集的 URL。

屬性	型別（Data type）	必要 Required	說明
BaseFileName	string	yes	不含路徑的檔案名稱，用來顯示在使用者的編輯畫面。
OwnerId	string	yes	識別該檔案擁有者的唯一 ID
Size	number (int64)	yes	以 bytes 為單位的檔案大小，64 位元長整數。
UserId	string	yes	存取該檔案的使用者 ID。
UserFriendlyName	string	no	使用者名稱，用來顯示在使用者的編輯畫面。
UserCanWrite	boolean	no	如果要能夠編輯，必須設為 true，預設為 false。
UserCanNotWriteRelative	boolean	no	禁止使用者重新命名或另存新檔。預設 true。
PostMessageOrigin	string	no	這是告訴 OxOffice Online。 [PostMessage API](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api) 的 WOPI 主機位址。若未指定，將無法接收 OxOffice Online 傳來的狀態。
HidePrintOption	boolean	no	隱藏 OxOffice Online 的列印按鈕。但可透過 [PostMessage API](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api) 來實作 WOPI 主機自己的列印 UI。
DisablePrint	boolean	no	禁止列印文件。此外，也會在 UI 中隱藏列印選項。
HideSaveOption	boolean	no	隱藏 OxOffice Online 的存檔按鈕。但仍可透過 [PostMessage API](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api) 觸發，這並不會影響自動存檔功能。
HideExportOption	boolean	no	隱藏 OxOffice Online「下載為…」按鈕及選項，但仍可透過 [PostMessage API](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api) 觸發。
DisableInactiveMessages	boolean	no	當停止編輯文件一段時間後，預設會在文件編輯區顯示提示文字。若禁用此功能，您監聽的 JavaScript，就必須在取得 Session\_Closed 或 User\_Idle 的 [PostMessage API](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api) 時，自行向使用者提供適當的訊息。
DisableExport	boolean	no	禁止匯出或下載文件。此外，也會在 UI 中隱藏下載選項。
DisableCopy	boolean	no	禁止複製內容到剪貼簿，但文件內部仍然可以複製以及貼上外部資料。
DownloadAsPostMessage	boolean	no	WOPI 主機自行接管下載任務，例如使用者觸發列印、權螢幕投影簡報以及其他檔案下載功能時，將觸發名為 Download\_As 的 [PostMessage API](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api)，傳送的值中，包含以下 JSON： ```json { Type: 'print'\|'slideshow'\|'export', URL: '...實際下載的 URL...' } ```
EnableOwnerTermination	boolean	no	授予檔案擁有者可以終止其他共編者編輯的權利，意即可在共編時，將其他共編者踢出共編行列。
LastModifiedTime	string	no	檔案最後修改時間。使用 ISO8601 格式表示之 UTC 日期時間（YYYY-MM-DDThh:mm:ss.nnnnZ）。
UserExtraInfo	object	no	使用者延伸資訊。請參考：[UserExtraInfo Details](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/8efb1#bkmrk-userextrainfo-detail-0)。

屬性	型別（Data type）	必要 Required	說明
avatar	string	no	使用者頭像位址。
mail	string	no	使用者的電子郵件位址。
ip	string	no	使用者的 IP 位址。由於 OxOffice Online 可能透過 reverse proxy 轉址，所以自行抓取的 IP 可能不正確，此種狀況下，需透過您的應用程式，將使用者 IP 置於此屬性。
watermark	object	no	自訂編輯浮水印。請參考[ Watermark Details](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/8efb1#bkmrk-watermark-details%EF%BC%9A)。

屬性	型別（Data type）	必要 Required	說明
editing	boolean	no	編輯時啟用，預設為 false。
printing	boolean	no	列印時啟用，預設為 false。
opacity	number(double)	no	不透明度。範圍 0.01-1.00預設為 0.20。此值愈小愈透明。
familyname	string	no	字型名稱。
angle	number(int)	no	旋轉角度。範圍 0-360，預設為 45°
color	string	no	CSS #rrggbb 表示之顏色。預設 #000000
bold	boolean	no	粗體。預設為 false。
italic	boolean	no	斜體。預設為 false。
outline	boolean	no	空心字。預設為 false。
shadow	boolean	no	陰影字。預設為 false。
text	string	no	浮水印文字，若需多行，各行需以 \\n 分隔。

MessageID	Values	說明
`App_LoadingStatus`	```json Status: DocumentLoadedTime: Features: {"VersionStates":true} ```	Status 值如下： - `Frame_Ready`：OxOffice Online 的框架已經載入，並且顯示了。 - `Features`：編輯器的能力。支援的值有 - VersionStates，表示編輯器支援文件版本復原的功能。詳請請見：[文件版本復原](https://docs.ossii.com.tw/books/oxoffice-online-8LU/page/postmessage-api#bkmrk-%E6%96%87%E4%BB%B6%E7%89%88%E6%9C%AC%E5%BE%A9%E5%8E%9F) - `Document_Loaded`：使用者文件已經完全載入，WOPI 主機可以開始使用 PostMessage API。 `DocumentLoadedTime` 代表載入文件所花費的時間。 - `Failed`：文件載入失敗，WOPI 主機可以顯示 OxOffice Online 框架，向使用者顯示錯誤訊息。

MessageID	Values	說明
`Host_PostmessageReady`		通知 OxOffice Online，WOPI 主機已經準備好收送 PostMessage 了。

MessageID	Values	說明
`Get_Views`		向編輯器查詢，目前正在編輯文件所有使用者資訊。回應會以 MessageID 為 `Get_Views_Resp` 的格式傳回。
`Get_Export_Formats`		向編輯器查詢，目前開啟的文件，支援哪些匯出格式。

MessageID	Values	說明
`Get_Views_Resp`	```json [ { ViewId: UserId: UserName: Color: ReadOnly: IsCurrentView: },... ] ```	使用 `Get_Views` 查詢，所得到的所有使用者詳細資訊。
`Get_Export_Formats_Resp`	```json [ { Label: Format: },... ] ```	使用 `Get_Export_Formats` 查詢，所得到的回應。 - `Label` 是解釋該格式的本地語系內容。 - `Format` 是該格式的副檔名。

MessageID	Values	說明
`Views_List`	與 `Get_Views_Resp` 相同。	所有正在參與該文件編輯的使用者詳細資訊。每次有編輯者加入或離開都會觸發此資訊。