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 以及 UI_Hyperlink 能停用🤣

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

說明

Clicked_Button

 
id: <string>

 

點擊透過前面的 Insert_Button API 新增的自訂按鈕時會發出此事件。

 

Download_As

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

當使用者選擇「列印」或「全螢幕投影」或「下載為…」，且 WOPI 主機在 CheckFileInfo 的DownloadAsPostMessage 屬性中，指定要接管時，就會觸發此事件。

 

這應用於無法依賴瀏覽器下載的情況，例如手機的 Web view 模式。

UI_CreateFile

 
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

 
Modified: true | false

更新文件的修改狀態。如果文件自上次儲存後被修改，則 Modified 將為 true，否則，如果文件已儲存，則 Modified 為 false。

 

請注意，這個通知可能會在不更改先前值的情況下觸發，因此必須檢查 Modified 的值，不要假設這個通知暗示文件的修改狀態。

呼叫 Python 巨集

WOPI 主機 🡆 編輯器

MessageId

Values

說明

CallPythonScript

 
ScriptFile: <string>
Function: <string>
Values: <object>

執行指定功能的 Python 巨集：

  • ScriptFile：巨集檔名
  • Function：函數名稱
  • Values：參數內容（key: value, ...）
編輯器 🡆 WOPI 主機

MessageId

Values

說明

CallPythonScript-Result

 
commandName: <string>
Values: <object>
 傳回 Python 執行結果。commandName 放的是巨集的 URL。

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