PostMessage API 用于在 Collabora Online 的浏览器部分被包含在一个父框架中时，与其进行交互。这对于希望将 Collabora Online 集成到自身应用中的宿主（Host）非常有用。
此 API 主要基于 WOPI 规范，并带有少量扩展/修改。所有发送的消息都采用以下形式：
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 的高度。 |
wren