摘要

本文围绕 HarmonyOS 6.1.1(API 24) 新增的 Content Embed Kit，讨论应用间文档嵌入与协同编辑的工程设计。文章以护理工作台嵌入病历模板为案例，讲解客户端与服务端职责、嵌入会话、细粒度权限、版本冲突、草稿恢复、隐私安全和能力降级。

关键词：HarmonyOS 6.1.1；API 24；Content Embed Kit；内容嵌入；跨应用协作；协同编辑；版本冲突

图 1  Content Embed Kit 跨应用协作能力地图

文章目录

• 1. Content Embed Kit 为什么值得单独研究
• 2. 文件分享、拉起应用和内容嵌入有什么区别
• 3. 客户端与服务端角色如何划分
• 4. 会话模型是协同编辑的核心
• 5. 推荐架构：业务页面不要直接持有外部编辑器状态
• 6. 医护案例：护理工作台嵌入病历模板
• 7. 权限必须细到能力而不是只有读写
• 8. 版本冲突不能靠最后一次保存覆盖
• 9. 代码案例一：嵌入会话模型
• 10. 代码案例二：宿主侧会话管理
• 11. 代码案例三：冲突处理
• 12. 断连、清后台和进程回收如何恢复
• 13. 隐私与安全边界
• 14. 降级设计
• 15. 测试清单
• 16. 本文小结
• 17. 场景与权限矩阵
• 18. 参考资料

1. Content Embed Kit 为什么值得单独研究

HarmonyOS 6.1.1(API 24) 正式引入 Content Embed Kit。官方版本说明将其定义为内容嵌入服务，为应用间文档互相嵌入和协同编辑提供框架能力，并封装客户端与服务端开发接口。它解决的不是简单的文件打开问题，而是用户如何在当前业务页面中使用另一个应用提供的文档能力，同时保持业务上下文、编辑状态和权限边界。

2. 文件分享、拉起应用和内容嵌入有什么区别

传统文件分享通常把文件交给另一个应用，用户离开原页面完成编辑后再返回；拉起应用强调页面跳转；内容嵌入则把提供方的内容能力放到宿主应用的界面和任务流程中。用户不必理解多个应用之间的切换，宿主仍掌握任务上下文，提供方负责专业文档能力。这种方式特别适合办公套件、医疗工作台、教育批注、政务材料和企业审批。

3. 客户端与服务端角色如何划分

宿主应用是客户端，负责发起嵌入、携带文档标识和业务上下文、展示容器并接收结果；内容提供应用是服务端，负责加载文档、呈现编辑能力、执行操作和回传状态。双方不应共享内部数据库结构，而应通过稳定的会话协议交互。这样提供方升级编辑器时，宿主业务无需重写。

4. 会话模型是协同编辑的核心

每次嵌入都应该建立独立会话，至少包含 sessionId、documentId、provider、mode、permission、baseVersion、draftVersion、status 和 expireAt。会话模型是双方的共同语言，也是断连恢复和冲突处理的依据。如果只传一个文件路径，应用无法判断谁在编辑、基于哪个版本、是否允许保存、会话何时结束。

5. 推荐架构：业务页面不要直接持有外部编辑器状态

宿主页面只提交打开、保存、取消等业务意图；EmbedSessionManager 维护会话和生命周期；ContentEmbedAdapter 封装系统客户端接口；提供方服务维护文档操作；DraftStore 保存本地草稿；ConflictResolver 处理版本冲突。分层后，设备不支持、提供应用未安装或会话异常时，都可以统一降级。

图 2  跨应用文档嵌入推荐架构

6. 医护案例：护理工作台嵌入病历模板

护士在护理工作台查看患者任务，需要填写护理记录。通过 Content Embed Kit，可在当前工作台嵌入专业文档应用提供的护理模板。患者姓名、住院号等敏感字段由宿主以最小上下文传递并设置只读；护理过程允许编辑；提交后医生可以复核。整个过程要记录模板版本、编辑人、提交时间和最终状态。

图 3  护理工作台嵌入病历模板案例

7. 权限必须细到能力而不是只有读写

真实协同编辑不只有可读和可写。权限还可能包括评论、批注、复制、导出、打印、分享和签名。宿主应根据业务角色生成权限清单，提供方只展示允许的工具。护理人员可以填写但不能修改诊断结论，审核人员可以评论和确认，普通查看者只能阅读。细粒度权限可以减少误操作和数据外泄。

8. 版本冲突不能靠最后一次保存覆盖

跨应用编辑可能遇到同一文档被其他人修改、服务端版本升级或用户在多个设备继续编辑。保存时要比较 baseVersion 与当前版本；一致时正常提交，不一致时提示合并、另存为草稿或放弃本次修改。医疗、合同和审批文档不适合自动静默覆盖，因为覆盖会破坏审计链。

图 4  一次跨应用嵌入编辑的完整流程

9. 代码案例一：嵌入会话模型

会话对象应该保持精简，不传完整业务数据。文档标识、权限、版本和追踪号足以建立稳定协议，具体内容由提供方按授权读取。

export interface EmbedSession {
  sessionId: string
  documentId: string
  providerBundle: string
  mode: 'read' | 'comment' | 'edit'
  permissions: Array<'copy' | 'export' | 'print' | 'sign'>
  baseVersion: string
  draftVersion?: string
  status: 'opening' | 'active' | 'saving' | 'conflict' | 'closed'
  traceId: string
}

10. 代码案例二：宿主侧会话管理

宿主侧要处理能力检测、会话创建、草稿保存、完成回调和资源释放。下面用伪代码表达职责划分，具体接口应以 Content Embed Kit 官方 API 为准。

class EmbedSessionManager {
  async open(input: OpenEmbedInput): Promise<EmbedSession> {
    await this.ensureCapability(input.providerBundle)
    const session = await this.adapter.createSession(input)
    await this.store.save(session)
    return session
  }

  async close(session: EmbedSession, commit: boolean): Promise<void> {
    if (commit) await this.adapter.commit(session.sessionId)
    await this.adapter.release(session.sessionId)
    await this.store.markClosed(session.sessionId)
  }
}

11. 代码案例三：冲突处理

冲突不是异常弹窗后结束，而是一条可恢复路径。用户至少应知道冲突来自哪里，以及保留哪个版本。

async function saveWithVersion(session: EmbedSession, changes: ChangeSet) {
  const current = await provider.queryVersion(session.documentId)
  if (current !== session.baseVersion) {
    session.status = 'conflict'
    return showConflictOptions(['合并修改', '另存为草稿', '放弃本次修改'])
  }
  await provider.commit(session.documentId, changes, current)
}

12. 断连、清后台和进程回收如何恢复

会话关键状态必须落盘。宿主重新启动后读取未完成会话，向提供方查询会话状态；如果仍有效，则恢复到对应文档和编辑位置；如果已失效，则保留草稿并提示重新建立会话。提供方也要处理宿主意外退出，及时释放渲染、文件锁和监听资源，避免下一次打开提示文件被占用。

13. 隐私与安全边界

跨应用嵌入意味着数据跨越应用边界，因此必须坚持最小化原则。优先传 documentId、recordId 和一次性授权令牌，不传完整病历、合同或用户资料。令牌要有有效期和作用域，日志只记录脱敏标识。嵌入区域退出后撤销临时权限，截图、复制和导出是否允许应由业务策略明确控制。

14. 降级设计

如果目标设备不支持 Content Embed Kit、提供应用未安装或能力协商失败，宿主仍应让用户完成任务。可降级为只读预览、导出副本后编辑、跳转提供应用或使用内置简化编辑器。降级时要说明能力差异，避免用户误以为数据丢失。

15. 测试清单

测试应覆盖正常打开、保存、取消、只读模式、权限变化、提供方未安装、版本冲突、断网、清后台、进程回收、超时、同文档多端编辑、敏感字段遮罩、会话结束资源释放和 API 23 设备降级。协同能力不能只测页面能否显示，更要验证状态和数据是否一致。

图 5  跨应用协同风险与高质量做法

16. 本文小结

Content Embed Kit 把鸿蒙跨应用协作从文件传递推进到能力嵌入。高质量方案的关键不是把另一个页面塞进当前页面，而是建立清晰的客户端与服务端协议、会话状态、细粒度权限、版本冲突处理、草稿恢复和安全审计。

17. 场景与权限矩阵

协作场景	推荐模式	关键控制
护理记录填写	编辑	身份字段只读、护理过程可写、提交留痕
合同审阅	评论/批注	禁止导出、保留意见作者和版本
课件批改	批注	按学生隔离文档、允许教师导出结果
政务材料核对	只读/补充字段	材料来源可追踪、敏感字段遮罩