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>

Status 值如下:

  • Frame_Ready:OxOffice Online 的框架已經載入,並且顯示了。
  • 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 是該格式的副檔名。