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 值如下:
|
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 |
|
使用 Get_Views 查詢,所得到的所有使用者詳細資訊。 |
Get_Export_Formats_Resp |
|
使用
|
編輯者管理
WOPI 主機 🡆 編輯器
MessageID | Values | 說明 |
Action_RemoveView |
|
移除指定 Id 的編編者,也就是將某位編輯者踢出共編行列。 |
編輯器 🡆 WOPI 主機
MessageID | Values | 說明 |
Views_List |
與 Get_Views_Resp 相同。 |
所有正在參與該文件編輯的使用者詳細資訊。每次有編輯者加入或離開都會觸發此資訊。 |
Actions
WOPI 主機 🡆 編輯器
MessageId |
Values |
說明 |
---|---|---|
|
|
儲存文件。
|
|
|
建立文件副本,並給予新檔名(另存新檔)。
|
|
|
開啟或關閉跟隨特定編輯者功能。這會讓編輯畫面和指定對象同步。
|
|
關閉文件。 |
|
|
列印文件。 |
|
|
|
以 |
|
|
從指定的位址下載圖片並插入文件中。 |
|
|
顯示具有 Lable 文字的忙碌畫面,類似存檔中的畫面。 |
|
如果有忙碌畫面的話,關掉忙碌畫面。 |
|
|
|
變更使用者介面:
|
|
|
繞過內部貼上機制,直接貼上資料到文件內。 例如:
|
編輯器 🡆 WOPI 主機(回應)
MessageId |
Values |
說明 |
---|---|---|
|
|
文件載入完成。
|
|
|
文件儲存完成。只有
|
|
|
跟隨狀態變更。
|
|
|
變更使用介面。
|
文件版本復原
WOPI 主機 🡆 編輯器
MessageId |
Values |
說明 |
---|---|---|
|
|
復原版本。唯一可能的值是 Pre_Restore 此訊息由主機在實際復原文件之前以及使用者確定復原之後傳送。 這樣,如果目前文件,還有未儲存的修改,OxOffice Online 可以在恢復文件之前將它們儲存到雲端硬碟中。 |
編輯器 🡆 WOPI 主機
MessageId |
Values |
說明 |
---|---|---|
|
|
這是對 目前 表示 WOPI 主機可以繼續將文件回復到較早的版本。 |
只有當 App_LoadingStatus
包含功能中的 VersionStates 時,才會發出這些訊息。 否則,主機可以立即將版本還原到早期版本。
其他
WOPI 主機 🡆 編輯器
MessageId |
Values |
說明 |
---|---|---|
|
|
在頂端工具列插入特定按鈕(僅顯示在傳統介面)。該按鈕被點擊時,會回應
|
|
id: <string> |
Hides a button from the toolbar.
|
|
id: <string> |
Hides a button from the toolbar.
|
|
id: <string> |
Removes a button from the toolbar.
|
|
id: <string> |
Removes an element from the status bar. |
|
Hides the menu bar. |
|
|
Shows the menu bar. |
|
|
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. |
|
|
Hides the horizontal document ruler (Writer only) |
|
|
Shows the horizontal document ruler (Writer only) |
|
|
id: <string> |
Hides an item from the menu.
|
|
id: <string> |
Shows an item from the menu. id` is the item ID as defined in the browser/src/control/Control.Menubar.js. |
|
action: <string> action: <string> disable: <Boolean> |
Disable the default handler and action for a UI command.
|
|
Command: <string> Args: <object> |
Send an UNO command to the editor. See examples in browser/html/framed.doc.html. |
Finding查詢工具列按鈕 toolbar button IDsID
Toolbar button IDs are defined in getToolItems/create
functions in:
-
Control.TopToolbar.js for the top toolbar on desktop or tablet.
-
Control.MobileTopBar.js for the top toolbar on smartphone.
-
Control.MobileBottomBar.js for the bottom toolbar on smartphone.
-
Control.StatusBar.js for the statusbar on desktop.
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.
編輯器 🡆 WOPI 主機
MessageId |
Values |
Description |
---|---|---|
|
id: <string> |
This event is emitted when the custom button added via |
|
Type: 'print'|'slideshow'|'export' URL: <string> |
This event is emitted when the user chooses ‘Print’ or ‘Show slideshow’ or ‘Download As |
|
Requests WOPI host to open a new browser tab and create a new document. The document type is passed as |
|
|
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 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. |
|
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. |
|
|
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 The integration using this most probably also wants to trigger the |
|
|
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 |
---|---|---|
|
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 |
---|---|---|
|
|
Returns the result The URL of the script called
|
Mentions
Note
Mentions are only working in Writer for now
編輯器 🡆 WOPI 主機
MessageId |
Values |
Description |
---|---|---|
|
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 |
---|---|---|
|
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 |