TanWenyan/leaudit-platform-backend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
0af41e370c74270b399d38254343469d255cd019
leaudit-platform-backend/docs/Collabora/参考资料/PostMessage API 接口.md
T

237 lines
18 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
PostMessage API 用于在 Collabora Online 的浏览器部分被包含在一个父框架中时，与其进行交互。这对于希望将 Collabora Online 集成到自身应用中的宿主（Host）非常有用。
此 API 主要基于 **WOPI 规范**，并带有少量扩展/修改。所有发送的消息都采用以下形式：
```plain
{
"MessageId": "",
"SendTime": "",
"Values": {
"": ""
}
}
```
`SendTime` 是浏览器 `Date.now()` 返回的时间戳。从 WOPI 宿主发送的 Post 消息也应采用相同的格式。
需要注意的是，正如 WOPI 规范中提到的，如果尚未收到 `Host_PostmessageReady` 消息，Collabora Online 框架将忽略所有来自宿主框架的 Post 消息。此外，由于将 Collabora Online 嵌入为 iframe 必须实现 WOPI，因此要求 WOPI 宿主的 `CheckFileInfo` 响应中必须包含 `PostMessageOrigin` 属性。否则，将不会发出任何 Post 消息。
---
## 初始化（Initialization）
### 编辑器（Editor）发送给 WOPI 宿主（WOPI Host）
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **App_LoadingStatus** | `Status:`（状态） `DocumentLoadedTime:`（文档加载时间） `Features:`（功能） | **状态 (**`Status`**)：** - `Frame_Ready`: Collabora Online 框架已加载，可显示 UI。 - `Document_Loaded`: 文档已完全加载，宿主可以开始使用 PostMessage API。 - `Failed`: 文档加载失败，但宿主可显示 Collabora Online 框架以呈现错误。 - `Initialized`: 编辑器中的 PostMessage 监听器已初始化。WOPI 宿主可以开始发送 Post 消息（甚至在 `Frame_Ready` 之前）。 **附加键值：** - `Features`: 此客户端的功能。支持的值包括：`VersionStates`（通知宿主客户端支持不同的版本状态）。 - `DocumentLoadedTime`: 当 Status 为 `Document_Loaded` 时可用。 |
### WOPI 宿主（WOPI Host）发送给编辑器（Editor）
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **Host_PostmessageReady** | _无_ | 详情请参见 WOPI 文档。 |
---
## 查询（Query）
您可以使用 Post 消息 API 从编辑器查询数据。所有响应的 `MessageId` 都以查询消息的 `MessageId` 加上 `_Resp` 后缀返回。
### 查询消息（WOPI 宿主发送给 Editor）
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **Get_Views** | _无_ | 查询编辑器中当前活跃的文档视图。响应以 `Get_Views_Resp` 形式返回。 |
| **Get_Export_Formats** | _无_ | 查询编辑器中当前打开文档支持的所有导出格式。响应以 `Get_Export_Formats_Resp` 形式返回。 |
| **Get_User_State** | _无_ | 查询编辑器中当前用户活动状态（是空闲或活跃）。响应以 `Get_User_State_Resp` 形式返回。 |
### 查询响应（Editor 发送给 WOPI Host）
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **Get_Views_Resp** | `ViewId:`（视图 ID） `UserId:`（用户 ID） `UserName:`（用户名） `Color:`（颜色） `ReadOnly:`（只读） `IsCurrentView:`（是否为当前视图） | 提供使用 `Get_Views` 查询时所有当前视图的详细信息。 |
| **Get_Export_Formats_Resp** | `Label:`（标签） `Format:`（格式） | 对 `Get_Export_Formats` 查询的响应。 `Label` 包含解释格式的本地化字符串。 `Format` 是请求文档导出时所需的文件扩展名。 |
| **Get_User_State_Resp** | `State:`（状态） `Elapsed:`（已逝时间） | 对 `Get_User_State` 查询的响应。 `State` 包含用户活动状态的非本地化字符串（“active”或“idle”）。 `Elapsed` 是用户上次活动以来的秒数。 |
---
## 会话管理（Session Management）
### WOPI 宿主发送给 Editor
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **Action_RemoveView** | `ViewId:`（视图 ID） | 移除会话。 |
| **Reset_Access_Token** | `token:`（令牌） | 重置访问令牌。从现在起将使用新的令牌。 |
### Editor 发送给 WOPI Host
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **View_Added** | `ViewId:` `UserId:` `UserName:` `Color:` `ReadOnly:` | **已弃用 (Deprecated: true)**; 新成员已添加。 _注：此消息已弃用，请转而实现对 _`Views_List`_ 的处理，其有效载荷与 _`Get_Views_Resp`_ 相同。_ |
| **View_Removed** | `ViewId:`（视图 ID） | **已弃用 (Deprecated: true)**; `ViewId` 对应的视图已关闭文档。 _注：此消息已弃用，请转而实现对 _`Get_Views_Resp`_ 或 _`Views_List`_ 的处理。_ |
| **Session_Closed** | `Reason:`（原因） | 会话已关闭。`Reason` 字段详细说明了来源：`OwnerTermination` (所有者终止), `DocumentIdle` (文档空闲), `OOM` (内存不足), `ShuttingDown` (服务器维护关机), `DocumentDisconnected` (文档问题)。 |
| **Views_List** | _参见 Get_Views_Resp_ | 关于当前连接视图的完整信息。 |
| **User_Idle** | _无_ | 指示用户进入空闲状态。发生在配置文件 `/etc/coolwsd/coolwsd.xml` 中定义的较长非活动时间之后。 |
| **User_Active** | _无_ | 指示用户再次变为活跃状态。发生在用户点击空闲屏幕之后。 |
---
## 动作（Actions）
### WOPI 宿主发送给 Editor
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **Action_Save** | `DontTerminateEdit:`（不终止编辑） `DontSaveIfUnmodified:`（未修改不保存） `Notify:`（通知） `ExtendedData:`（扩展数据） | 保存文档。 - `DontTerminateEdit`: 与电子表格相关，设置 true 不会终止编辑模式。 - `DontSaveIfUnmodified`: 如果文档未修改，则阻止保存到存储。 - `Notify`: 如果为 true，则在保存文档时通知宿主（参见 `Action_Save_Resp`）。 - `ExtendedData`: 可选数据，通过 `X-COOL-WOPI-ExtendedData` 头部传递给 WOPI 宿主。 |
| **Action_SaveAs** | `Filename:`（文件名） `Notify:`（通知） | 以给定 `Filename` 创建文档副本。 |
| **Action_FollowUser** | `Follow:`（跟随） `ViewId:`（视图 ID） | 开启或关闭跟随用户功能。 - `Follow`: `true` 开启跟随，`false` 关闭。 - `ViewId`: 指定要跟随的用户。未定义时，跟随当前编辑器。 |
| **Action_Close** | _无_ | 关闭文档。 |
| **Close_Session** | _无_ | 允许在文档完全加载之前关闭会话。 |
| **Action_Fullscreen** | _无_ | 切换到全屏模式。 |
| **Action_FullscreenPresentation** | `StartSlideNumber:`（起始幻灯片编号） `CurrentSlide:`（当前幻灯片） | 在 Impress 中开始演示。 - `StartSlideNumber`: 可选，指定起始幻灯片（从 0 开始）。 - `CurrentSlide`: 如果为 true，则从当前幻灯片开始演示。 |
| **Action_Print** | _无_ | 打印文档。 |
| **Action_Export** | `Format:`（格式） `Notify:`（通知） | 以下载指定 `Format` 的文档（`Format` 必须来自 `Get_Export_Formats` 列表）。 |
| **Action_InsertGraphic** | `url:` | 从 URL 下载图像并将其插入到文档中。通常是对 `UI_InsertGraphic` 的响应。 |
| **Action_InsertLink** | `url:` | 在文档中插入链接。通常是对 `UI_PickLink` 的响应。 |
| **Action_InsertMultimedia** | `url:` | _24.04.10 版本新增。_ 从 URL 下载多媒体并插入。可能是对 `UI_InsertFile` 的响应。 |
| **Action_ShowBusy** | `Label:`（标签） | 显示一个进行中的覆盖层，带有给定的 `Label`。 |
| **Action_HideBusy** | _无_ | 隐藏任何进行中的覆盖层。 |
| **Action_ChangeUIMode** | `Mode:`（模式） | 更改用户界面：`'classic'` (经典工具栏) 或 `'notebookbar'` (笔记本栏)。 |
| **Action_Paste** | `Mimetype:`（MIME 类型） `Data:`（数据） | 将数据直接粘贴到文档中，绕过内部粘贴机制。 示例：`{Mimetype: "text/plain;charset=utf-8", Data: "foo"}`。 |
### Editor 发送给 WOPI 宿主（响应）
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **Action_Load_Resp** | `success:`（成功） `result:`（结果） `errorMsg:`（错误消息） `errorType:`（错误类型） | 加载完成时的确认。 - `success`: COOL 是否成功加载文档。 - `result`: 文档未加载的原因。 - `errorMsg`: 详细的错误消息。 - `errorType`: 可选的错误标识符。 |
| **Action_Save_Resp** | `success:`（成功） `result:`（结果） `errorMsg:`（错误消息） `fileName:`（文件名） | 保存完成时的确认。仅当 `Action_Save` 包含 `Notify` 参数时发出。 - `result`: 文档未保存的原因（例如，'unmodified'）。 - `fileName`: 如果成功为 true，则包含保存的文件名。 |
| **FollowUser_Changed** | `FollowedViewId:`（被跟随视图 ID） `IsFollowUser:`（是否跟随用户） `IsFollowEditor:`（是否跟随编辑器） | 当前跟随状态的通知。 |
| **Action_ChangeUIMode_Resp** | `Mode:`（模式） | 关于 UI 模式切换（标签式/紧凑式）的通知。 |
---
## 版本恢复（Version Restore）
### WOPI 宿主发送给 Editor
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **Host_VersionRestore** | `Status:`（状态） | 唯一可能的值是 `Pre_Restore`。在实际恢复文档之前发送，以便 Online 可以在恢复前保存任何未保存的更改。 |
### Editor 发送给 WOPI Host
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **App_VersionRestore** | `Status:`（状态） | 对 `Host_VersionRestore` 消息的回复。可能的值（目前）是：`Pre_Restore_Ack`。意味着宿主可以继续将文档恢复到较早的版本。 |
> **注意：** 仅当 `App_LoadingStatus` 中的 `Features` 包含 `VersionStates` 时，才会发出这些消息。否则，宿主可以立即将版本恢复到较早的修订。
>
---
## 杂项（Miscellaneous）
### WOPI 宿主发送给 Editor
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **Insert_Button** | `id:`（ID） `imgurl:`（图像 URL） `hint:`（提示） `accessKey:`（访问键） `mobile:`（移动端） `tablet:`（平板端） `label:`（标签） `insertBefore:`（插入到之前） `unoCommand:`（UNO 命令） | 在顶部工具栏插入一个按钮。如果未设置 `unoCommand`，则在点击时响应 `Clicked_Button` Post 消息事件。 |
| **Insert_ContextualButton** | `id:` `imgurl:` `hint:` `unoCommand:` | _25.04.5.3 版本新增。_ 在上下文工具栏（选中时出现）中插入按钮。如果未设置 `unoCommand`，则在点击时响应 `Clicked_ContextualButton`。 |
| **Hide_Button** | `id:`（ID） | 从工具栏隐藏按钮。 |
| **Show_Button** | `id:`（ID） | 在工具栏显示按钮。 |
| **Remove_Button** | `id:`（ID） | 从工具栏移除按钮。 |
| **Hide_Command** | `id:`（ID） | 隐藏某个命令的 UI（包括菜单项、上下文菜单项和工具栏按钮）。 |
| **Show_Command** | `id:`（ID） | 显示某个命令的 UI。 |
| **Hide_NotebookTab** | `id:`（ID） | _24.04.11.1 版本新增。_ 永久隐藏特定的笔记本栏选项卡。 |
| **Show_NotebookTab** | `id:`（ID） | _24.04.11.1 版本新增。_ 显示特定的笔记本栏选项卡。 |
| **Collapse_Notebookbar** | _无_ | 隐藏笔记本栏按钮。 |
| **Extend_Notebookbar** | _无_ | 显示笔记本栏按钮。 |
| **Hide_StatusBar** | _无_ | 隐藏状态栏。 |
| **Show_StatusBar** | _无_ | 显示状态栏。 |
| **Remove_Statusbar_Element** | `id:`（ID） | 从状态栏移除元素。 |
| **Hide_Menubar** | _无_ | 隐藏菜单栏。 |
| **Show_Menubar** | _无_ | 显示菜单栏。 |
| **Grab_Focus** | _无_ | 将焦点恢复到应用程序。 |
| **Hide_Ruler** | _无_ | 隐藏水平文档标尺（仅限 Writer）。 |
| **Show_Ruler** | _无_ | 显示水平文档标尺（仅限 Writer）。 |
| **Hide_Menu_Item** | `id:`（ID） | 隐藏菜单项。`id` 在 `browser/src/control/Control.Menubar.js` 中定义。 |
| **Show_Menu_Item** | `id:`（ID） | 显示菜单项。 |
| **Show_Sidebar** | `id:`（ID） | _24.04.10 版本新增。_ 显示侧边栏。可选 `id`：`Navigator`, `ModifyPage`, `SlideChangeWindow`, `CustomAnimation`, `MasterSlidesPanel`。 |
| **Hide_Sidebar** | _无_ | _24.04.10 版本新增。_ 隐藏侧边栏。 |
| **Disable_Default_UIAction** | `action:`（动作） `disable:`（禁用） | 禁用 UI 命令的默认处理程序和动作（例如 `UI_Save`、`UI_Close`）。当 `disable` 为 true 时，仅发出 Post 消息。 |
| **Send_UNO_Command** | `Command:`（命令） `Args:`（参数） | 向编辑器发送 UNO 命令。 |
| **Error_Messages** | `list:`（列表） | 用于覆盖编辑器中错误消息的对象列表（`{type: , msg: }`）。 |
| **Hint_OnscreenKeyboard** | _无_ | 指示设备使用屏幕键盘（例如平板）。 |
| **Hint_NoOnscreenKeyboard** | _无_ | 指示设备不是平板。 |
#### 查找工具栏按钮 ID
工具栏按钮 ID 在以下文件中的 `getToolItems`/`create` 函数中定义：
+ `Control.TopToolbar.js` (桌面/平板顶部工具栏)
+ `Control.MobileTopBar.ts` (智能手机顶部工具栏)
+ `Control.MobileBottomBar.js` (智能手机底部工具栏)
+ `Control.StatusBar.js` (桌面状态栏)
#### 查找状态栏元素 ID
状态栏按钮 ID 在 `Control.StatusBar.js` 中的 `onDocLayerInit` 函数中定义。
### Editor 发送给 WOPI Host
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **Clicked_Button** | `id:`（ID） | 点击通过 `Insert_Button` 添加的自定义按钮时发出。 |
| **Clicked_ContextualButton** | `id:`（ID） | 点击通过 `Insert_ContextualButton` 添加的自定义按钮时发出。 |
| **Download_As** | `Type:`（类型） `URL:` | 当用户选择 'Print'、'Show slideshow' 或 'Download As...' 且 CheckFileInfo 中的 `DownloadAsPostMessage` 为 true 时发出。`Type` 值: `'print'`, `'slideshow'`, `'export'`。 |
| **UI_OpenDocument** | _无_ | 请求 WOPI 宿主打开一个弹出窗口，用户可在其中选择要查看和编辑的另一个文档。 |
| **UI_CreateFile** | `DocumentType:`（文档类型） | 请求 WOPI 宿主打开一个新浏览器标签并创建新文档。`DocumentType` 可以是 `'text'`, `'spreadsheet'`, `'presentation'` 或 `'drawing'`。 |
| **UI_SaveAs** | `Args: {format: ''}`（参数） | 请求 WOPI 宿主创建相应的 UI，供用户选择路径和文件名以创建当前文件的副本。对该查询的响应通过 `Action_SaveAs` 消息发送。 |
| **UI_InsertGraphic** | _无_ | 请求 WOPI 宿主打开弹出窗口供用户选择图像插入。成功后，WOPI 宿主将发送 `Action_InsertGraphic` Post 消息。 |
| **UI_PickLink** | _无_ | 请求 WOPI 宿主打开弹出窗口供用户选择链接插入。成功后，WOPI 宿主将发送 `Action_InsertLink` Post 消息。 |
| **UI_InsertFile** | `callback:`（回调） `mimeTypeFilter:`（MIME 类型过滤器） | _24.04.10 版本新增。_ 请求 WOPI 宿主打开弹出窗口供用户选择文件插入。成功后，WOPI 宿主将发送 `callback` 参数中定义的 Post 消息。 |
| **UI_InsertAIContent** | _无_ | _24.04.12 版本新增。_ 请求 WOPI 宿主打开弹出窗口供用户选择插入 AI 生成的内容。 |
| **UI_Cancel_Password** | _无_ | 通知 WOPI 宿主用户在打开受密码保护的文件时点击了“取消”。 |
| **UI_Hyperlink** | _无_ | 通知 WOPI 宿主用户点击了超链接并确认要离开文档以跟随该超链接。 |
| **UI_Paste** | _无_ | 在移动端请求粘贴时发送。允许嵌入的移动应用程序处理剪贴板内容。 |
| **Doc_ModifiedStatus** | `Values.Modified`（已修改值） | 通知以更新文档的修改状态。`Values.Modified` 为 true 表示自上次保存以来已修改，否则为 false。 |
---
## 调用 Python 脚本（Calling Python scripts）
### WOPI 宿主发送给 Editor
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **CallPythonScript** | `ScriptFile:`（脚本文件） `Function:`（函数） `Values:`（值） | 调用 Python 脚本。`Values` 包含传递给脚本的命名参数对象。 |
### Editor 发送给 WOPI Host
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **CallPythonScript-Result** | `commandName:`（命令名称） `Values:`（值） | 返回结果。`commandName` 中是调用脚本的 URL。 |
---
## 提及功能（Mentions）
_注意：目前提及功能仅在 Writer 中可用。_
### Editor 发送给 WOPI Host
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **UI_Mention** | `type: autocomplete`（类型: 自动完成） `text:`（文本） | 当用户输入“@”时，Collabora Online 会发送此 Post 消息，附带部分文本，以获取集成商提供的用户名列表。 |
| **UI_Mention** | `type: selected`（类型: 已选择） `username:`（用户名） | 当用户从集成商提供的列表中选择一个用户名时触发此消息。 |
### WOPI 宿主发送给 Editor
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **Action_Mention** | `list:`（列表） | 集成商应发送此消息作为对 `UI_Mention` (自动完成类型) 消息的响应。消息必须包含用户对象列表： `{ username: "...", profile: "...", label: "..." }` |
---
## 嵌入 Iframe（Embedding Iframe）
### Editor 发送给 WOPI Host
Collabora Online 发送 `Iframe_Height` Post 消息给 WOPI 宿主，以动态调整嵌入式 iframe 的高度并防止出现滚动条。
| MessageId | Values（值） | Description（描述） |
| :--- | :--- | :--- |
| **Iframe_Height** | `ContentHeight:`（内容高度） | 使用 `ContentHeight` 值在 UI 中动态设置嵌入式 iframe 的高度。 |
Reference in New Issue View Git Blame Copy Permalink