Skip to main content

PostMessage API

當 WOPI 主機將 OxOffice Online 包在一個框架（ iFrame）時，可以使用 PostMessage API 用來於和 OxOffice Online 互動。這對想要完善整合的 WOPI 主機來講，非常有用。

這個 API 主要基於 WOPI 規範，很少擴充或修改。 所有送出的訊息，都採用以下形式：

{
      "MessageId": "<MessageId>",
      "SendTime": "<Timestamp when message is sent>",
      "Values": {
             "<key>": "<value>"
      }
}

SendTime 是瀏覽器的 Date.now() 傳回的時間戳記。從 WOPI 主機發送的 post 訊息也應該使用相同的格式。

需要注意的是，如 WOPI 規範中所提到的，如果尚未收到 Host_PostmessageReady，OxOffice Online 框架將忽略來自 WOPI 主機框架所有訊息。

另外，由於將 OxOffice Online 嵌入 iFrame 中，因此，OxOffice Online 要求 WOPI 主機回應 CheckFileInfo 中的 PostMessageOrigin 屬性，必須指定，否則 OxOffice Online 將不會送出任何訊息。

初始化

編輯器 🡆 WOPI 主機
MessageID Values 說明
App_LoadingStatus 
Status: <String>
DocumentLoadedTime: <Timestamp>
Features: {"VersionStates":true}

Status 值如下：

  • Frame_Ready：OxOffice Online 的框架已經載入，並且顯示了。
  • Features：編輯器的能力。支援的值有 - VersionStates，表示編輯器支援文件版本復原的功能。
    詳請請見：文件版本復原
  • Document_Loaded：使用者文件已經完全載入，WOPI 主機可以開始使用　PostMessage API。
    DocumentLoadedTime 代表載入文件所花費的時間。
  • Failed：文件載入失敗，WOPI 主機可以顯示 OxOffice Online 框架，向使用者顯示錯誤訊息。
WOPI 主機 🡆 編輯器
MessageID Values 說明
Host_PostmessageReady
通知 OxOffice Online，WOPI 主機已經準備好收送 PostMessage 了。

查詢

WOPI 主機可以透過 PostMessage API 向編輯器查詢資料。所有來自編輯器回應的 MessageID，都會在您所傳遞的 MessageID 後面加上 "_Resp"。

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

得到的回應。

編輯器 🡆 WOPI 主機
MessageID Values 說明
Get_Views_Resp 
[
  {
    ViewId: <Number>
	UserId: <String>
	UserName: <String>
	Color: <Number>
	ReadOnly: <Boolean>
	IsCurrentView: <Boolean>
  },...
]
 使用 Get_Views 查詢，所得到的所有使用者詳細資訊。
Get_Export_Formats_Resp 
[
  {
    Label: <String>
	Format: <String>
  },...
]

使用 Get_Export_Formats 查詢，所得到的回應。

  • Label 是解釋該格式的本地語系內容。
  • Format 是該格式的副檔名。

編輯者管理

WOPI 主機 🡆 編輯器
MessageID Values 說明
Action_RemoveView 
ViewId: <Number>
 移除指定 Id 的編編者，也就是將某位編輯者踢出共編行列。
編輯器 🡆 WOPI 主機
MessageID Values 說明
Views_List 與 Get_Views_Resp 相同。

所有正在參與該文件編輯的使用者詳細資訊。每次有編輯者加入或離開都會觸發此資訊。

各類指令

WOPI 主機 🡆 編輯器

MessageId

Values

說明

Action_Save

 
DontTerminateEdit: <boolean>
DontSaveIfUnmodified: <boolean>
Notify: <boolean>
ExtendedData: <String>

儲存文件。

  • DontTerminateEdit 和試算表相關，這會中斷編輯模式（文字游標消失）。設為 true 的話，就能儲存檔案，而不會終止編輯模式，也不會中斷使用者編輯試算表。
  • DontSaveIfUnmodified 如果文件內容沒有變更（只是移動了游標），這會阻止 OxOffice Online 把檔案回存雲端硬碟， 如此可防止不必要的版本修訂。
  • Notify 設為 true 時，會在文件儲存完後，通知 WOPI 主機。詳情請參考 Action_Save_Resp
  • ExtendedData 如果標頭X-LOOL-WOPI-ExtendedData 有資料，則會原封不動地傳給WOPI 主機。
    資料內容不可是空白、換行或其他不可列印字元。
    OxOffice Online 可以傳遞多個值，然後 WOPI 主機可以進一步對處理這些值。

Action_SaveAs

 
Filename: <String>
Notify: <boolean>

建立文件副本，並給予新檔名（另存新檔）。

  • Filename 新文件檔名。
  • Notify 設為 true 時，會在文件儲存完後，通知 WOPI 主機。詳情請參考 Action_Save_Resp

Action_FollowUser

 
Follow: <Boolean>
ViewId: <Number>

開啟或關閉跟隨特定編輯者功能。這會讓編輯畫面和指定對象同步。

  • Follow true 開啟/ false 關閉。
  • ViewId 要跟隨的編輯者 ID。

Action_Close

關閉文件。

Action_Print

列印文件。

Action_Export

 
Format: <String>

以 Format 指定的格式下載文件。格式只能是 Get_Export_Formats 所指定列表其中之一。

Action_InsertGraphics

 
url: <String>

從指定的位址下載圖片並插入文件中。

Action_ShowBusy

 
Label: <String>

顯示具有 Lable 文字的忙碌畫面，類似存檔中的畫面。

Action_HideBusy

如果有忙碌畫面的話，關掉忙碌畫面。

Action_ChangeUIMode

 
Mode:'classic' 或 'notebookbar'

變更使用者介面：

  • classic：傳統下拉選單＋工具列。
  • notebookbar：分頁式介面。

Action_Paste

 
Mimetype: <string>
Data: <string>

繞過內部貼上機制，直接貼上資料到文件內。

例如：

Values: {Mimetype: "text/plain;charset=utf-8", Data: "haha"}};
編輯器 🡆 WOPI 主機（回應）

MessageId

Values

說明

Action_Load_Resp

 
success: <boolean>
result:  <string>
errorMsg: <string>

文件載入完成。

  • success true 成功、false 失敗。
  • result 文件未載入的原因。
  • errorMsg 載入失敗時的詳細錯誤訊息。也可能包含從 WOPI 主機傳回的錯誤訊息。

Action_Save_Resp

 
success: <boolean>
result: <string>
errorMsg: <string>
fileName: <string>

文件儲存完成。只有Action_Save 或 Action_SaveAs PostMessage API 將 Notify 參數設為 true 時，才會得到這個回應。

  • success true 成功、false 失敗。
  • result 文件未儲存的原因。如果文件因未修改而未儲存，則此參數包含字串「unmodified」。 這種情況下，WOPI 主機可以確保不會儲存到位編耕的文件。
  • errorMsg 儲存失敗時的詳細錯誤訊息。 也可能包含從 WOPI 主機傳回的錯誤訊息。
  • fileName 如果 success 為 true 則包含已儲存的檔案名稱。

FollowUser_Changed

 
FollowedViewId: <Number>
IsFollowUser: <Boolean>
IsFollowEditor: <Boolean>

跟隨狀態變更。

  • FollowedViewId 哪個編輯者被跟隨。
  • IsFollowUser是否啟用跟隨編輯者。
  • IsFollowEditor 是否啟用跟隨編輯器。
  • 如果 IsFollowUser 和 IsFollowEditor 都是 false，表示取消跟隨功能。

Action_ChangeUIMode_Resp

 
Mode: <string>

變更使用介面。

Mode 使用哪種介面。

文件版本復原

WOPI 主機 🡆 編輯器

MessageId

Values

說明

Host_VersionRestore

 
Status: <string>

復原版本。唯一可能的值是 Pre_Restore

此訊息由主機在實際復原文件之前以及使用者確定復原之後傳送。

這樣，如果目前文件，還有未儲存的修改，OxOffice Online 可以在恢復文件之前將它們儲存到雲端硬碟中。
編輯器 🡆 WOPI 主機

MessageId

Values

說明

App_VersionRestore

 
Status: <string>

這是對 Host_VersionRestore 訊息的回應。

目前 Status 的值為 Pre_Restore_Ack

表示 WOPI 主機可以繼續將文件回復到較早的版本。

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

其他

WOPI 主機 🡆 編輯器

MessageId

Values

說明

Insert_Button

 
id: <string>
imgurl: <string>
hint: <string>
accessKey: <string>
mobile: <boolean>
tablet: <boolean>
insertBefore: <string>
unoCommand: <string>

在頂端工具列插入特定按鈕（僅顯示在傳統介面）。該按鈕被點擊時，若未指定 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
  • unoCommand UNO 命令（請參閱此處）。 設置這個屬性，就不會傳送 Clicked_Button 訊息給 WOPI 主機，而會交由  LibreOffice 直接執行此命令。

Hide_Button

 
id: <string>

隱藏工具列按鈕。id 為按鈕 ID（查詢工具列按鈕 ID）

Show_Button

 
id: <string>

顯示工具列按鈕。id 為按鈕 ID（查詢工具列按鈕 ID）

Remove_Button

 
id: <string>

移除工具列按鈕。id 為按鈕 ID（查詢工具列按鈕 ID）

Remove_Statusbar_Element

 
id: <string>

移除狀態列元件。 id 是狀態列元件 ID（請參考：查詢狀態列元件 ID）

Hide_Menubar

隱藏下拉選單列。

Show_Menubar

顯示下拉選單列。

Grab_Focus

喚醒休眠中的編輯器。通常編輯者在一段時間後沒有任何動作時，編輯器會進入休眠狀態（編輯介面變暗，並有訊息顯示），必要時，會中斷與伺服器連線。Grab_Focus 會重新喚醒編輯器，必要時重新連線伺服器。

Hide_Ruler

隱藏水平尺規（僅適用文字文件 Writer）。

Show_Ruler

隱藏水平尺規（僅適用文字文件 Writer）。

Hide_Menu_Item

 
id: <string>

隱藏下拉選單中的選項。id 是指選項 ID ，它們分別定義在：

Show_Menu_Item

 
id: <string>

顯示下拉選單中的選項。id 是指選項 ID。請參閱前項 Hide_Menu_Item

Disable_Default_UIAction

 
action: <string>
disable: <Boolean>

停用或啟用某個 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 能停用🤣

Send_UNO_Command

 
Command: <string>
Args: <object>

向編輯器傳送 UNO 命令。請參考：framed.doc.html

查詢工具列按鈕 ID

工具列按鈕 ID 在下列程式中的 getToolItems/create 函數定義：

這些通常不會改變，但並不保證這些 ID 會穩定存在。

查詢狀態列元件 ID

狀態列元件 ID 定義在 Control.StatusBar.js 的 onDocLayerInit 函數中。通常不會改變，但並不保證這些 ID 會穩定存在。

編輯器 🡆 WOPI 主機

MessageId

Values

Description

Clicked_Button

 
id: <string>

This event is emitted when the custom button added

via Insert_Button API above is clicked.

Download_As

 
Type: 'print'|'slideshow'|'export'
URL: <string>

This event is emitted when the user chooses ‘Print’

or ‘Show slideshow’ or ‘Download As [some type'] and the integration indicates via DownloadAsPostMessage in the CheckFileInfo that it wants to handle the downloading of pdf for printing or svg for slideshows or exported document. This is in situations when the integration cannot rely on browser’s support for downloading like in mobile apps that use the Online in a Web View.

UI_CreateFile

Requests WOPI host to open a new browser tab and create a new document. The document type is passed as DocumentType argument, and can be ‘text’,’spreadsheet’,’presentation’ or ‘drawing’.

UI_SaveAs

 
Args: {format: '<extension>' }

Requests WOPI host to create appropriate UI, so that the user can choose path and File name for creating a copy of the current file. Response to this query is sent via Action_SaveAs message.

Optional arguments: file extension. When this parameter is passed a dropdown appears and the newly saved file is loaded in the integration instead of downloaded.

UI_Cancel_Password

Notifies WOPI host that the user clicked on the ‘cancel’ option when opening a password protected file, instead of providing the password to decrypt it.

UI_Hyperlink

Notifies WOPI host that the user clicked a hyperlink and confirmed they really want to leave the document to follow the hyperlink. This is especially useful for integrations that embed Collabora Online into an iframe in a mobile app, where actually trying to open a new window should trigger starting a new Activity on Android (or something similar on iOS).

The integration using this most probably also wants to trigger the Disable_Default_UIAction for UI_Hyperlink.

Doc_ModifiedStatus

Notification to update the modified status of the document. Values.Modified will be true, if the document has been modified since the last save, otherwise, it will be false if the document has been saved.

Note that this notification may be published without a change from the prior value, so care must be taken to check the Values.Modified value and not assume the notification itself implies the modified state of the document on its own.

呼叫 Python

WOPI 主機 🡆 編輯器

MessageId

Values

Description

CallPythonScript

 
script. The Values
ScriptFile: <string>
Function: <string>
Values: <object>

Calls a Python parameter contains an object with named

parameters that are passed to the script.
編輯器 🡆 WOPI 主機

MessageId

Values

Description

CallPythonScript-Result

 
commandName: <string>
Values: <object>

Returns the result The URL of the script called

is in the commandName parameter.

Mentions

Note

Mentions are only working in Writer for now

編輯器 🡆 WOPI 主機

MessageId

Values

Description

UI_Mention

 
type: autocomplete
text: <string>

When user starts typing with “@”, CollaboraOnline will send this postMessage with partial text followed by “@” to get the list of usernames from the integrator

 
type: selected
username: <string>

When user selects the a username from list given by the integrator this message gets fired
WOPI 主機 🡆 編輯器

MessageId

Values

Description

Action_Mention

 
list: [{
          username: "example-username1",
          profile: "link-to-the-profile"
        },
        {
          username: "example-username2",
          profile: "link-to-the-profile"
        }.....]

Based on UI_Mention message of type autocomplete, integrator should send this message with list of user object. Each user object contains username and profile
Back to top