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 相同。

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

Actions

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

Description說明

App_VersionRestore

 
Status: <string>

這是對 Host_VersionRestore 訊息的回應。

目前 Status 的值為 Pre_Restore_Ack

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

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

Miscellaneous

其他

WOPI host主機 to🡆 editor
編輯器

MessageId

Values

Description說明

Insert_Button

 
id: <string>
imgurl: <string>


hint: <string>

accessKey: <string>

mobile: <boolean>
tablet: <boolean>

label: <string>


insertBefore: <string>


unoCommand: <string>

Inserts a button to the top toolbar. It responds with Clicked_Button post message event on which hosts can react accordingly (except when the unoCommand id parameter is a unique id of the toolbar button. It is recommended to prefix such ids given here given here with some host namespace so that it doesn’t conflict with existing toolbar IDs. In case of conflict, button is not added. imgurl parameter is the link to the image that will be set as button image in the toolbar. The ideal size of the image is 24x24px. The image must be hosted on the host URL to not violate Content-Security-Policy. hint This is used as a tooltip of the button.

This is used by acceleratore definitions class. Users can press alt or alt+shift and use this key. One should be careful to not introduce conflicting access keys. mobile whether the button should be shown when the interface switches to mobile mode. tablet whether the button should be shown in tablet mode (true if absent)

label When a read-only document is opened, we don’t have the toolbar at all. In this case, this newly added button is present in file menubar. The text against this label is used as text of the menubar item.

insertBefore Specify the position where the button should be inserted. insertBefore is the button ID (see Finding toolbar button IDs).

unoCommand UNO Command to be executed on button click (Reference). When this property is set, no ‘Clicked_Button’ response is sent. The button click will be handled by LibreOffice.

Hide_Button

 
id: <string>

Hides a button from the toolbar.

id is the button ID (see Finding toolbar button IDs).

Show_Button

 
id: <string>

Hides a button from the toolbar.

id is the button ID (see Finding toolbar button IDs).

Remove_Button

 
id: <string>

Removes a button from the toolbar.

id is the button ID (see Finding toolbar button IDs).

Remove_Statusbar_Element

 
id: <string>

Removes an element from the status bar. id is the element ID (see Finding status bar element IDs).

Hide_Menubar

Hides the menu bar.

Show_Menubar

Shows the menu bar.

Grab_Focus

This restores focus to the application, activating it, and removing any overlay indicating quiescence, and re-connecting to the server if necessary. Useful after leaving the application for a lengthy period, or when wanting to restore browser focus after presenting an overlaid dialog.

Hide_Ruler

Hides the horizontal document ruler (Writer only)

Show_Ruler

Shows the horizontal document ruler (Writer only)

Hide_Menu_Item

 
id: <string>

Hides an item from the menu.

id is the item ID as defined in the browser/src/control/Control.Menubar.js.

Show_Menu_Item

 
id: <string>

Shows an item from the menu.

id` is the item ID as defined in the browser/src/control/Control.Menubar.js.

Disable_Default_UIAction

 
action: <string>
action: <string>
disable: <Boolean>

Disable the default handler and action for a UI command.

action is the action name to enable/disable the default action for. disable controls whether to disable (true) or enable (false) the default action. When set to true, the given UI command will only issue a postMessage without invoking the default action, leaving it up to the client to intercept the postMessage event and handle as necessary. Notice that some actions do not have any default handler to begin with (such as UI_SaveAs and UI_Share) and therefore this will have no effect on them; they only issue postMessage notification anyway without taking any action beyond that. For example, UI_Save will be issued for invoking the save command (from the menu, toolbar, or keyboard shortcut) and no action will take place if ‘UI_Save’ is disabled via the Disable_Default_UIAction ``ommand. Clients who disable ``UI_Save  `` should then issue ``Action_Save themselves, when and if they desire to save the document. Similarly, when disabling UI_Close, the document will not close upon invoking the UI_Close action, instead a postMessage notification will be issued and it will be up to the client to issue Action_Close when they desire. Clients must be careful not to issue duplicate actions when the default handler is enabled, instead, they should only issue actions themselves when the default is disabled. Note: currently only UI_Save and UI_Close are supported.

Send_UNO_Command

 
Command: <string>
Args: <object>

Send an UNO command to the editor.

See examples in browser/html/framed.doc.html.

Finding toolbar button IDs

Toolbar button IDs are defined in getToolItems/create functions in:

Note that they usually don’t change but there is no guarantee that they are stable.

Finding status bar element IDs

Status bar button IDs are defined in the onDocLayerInit function in Control.StatusBar.js. Note that they usually don’t change but there is no guarantee that they are stable.

Editor

編輯器 to🡆 WOPI host
主機

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.

Calling

呼叫 Python scripts

WOPI host主機 to🡆 editor
編輯器

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.

Editor

編輯器 to🡆 WOPI host
主機

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

Editor

編輯器 to🡆 WOPI host
主機

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 host主機 to🡆 editor
編輯器

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