跨文档嵌入(Embed block)

在另一种 Office 产品中嵌入可编辑内容,复用各产品的原生能力。

嵌入块把一种 Univer 产品放入另一种产品之中。项目文档中可以放置预算和任务,演示页上可以承载一份可继续计算的表格,画布上可以把计划和说明放在一起。嵌入的内容保留自己的数据模型和原生编辑器,激活该块时,焦点和菜单会转移到子 Unit。

原理:宿主与子内容各司其职

宿主 Unit 保存块的位置、大小、子 Unit 引用和默认视图;子 Unit 保存实际的单元格、段落或记录。加载一个块时,先解析该引用,再加载子 Unit,并把它的编辑器挂载到宿主中。这里的 Unit(内容单元) 可以是一份工作簿、文档、演示文稿、关系型表格或画布。

100%

嵌入关系与内容分别持久化。修改嵌入表格中的单元格,更新的是子 Sheet;移动或调整块的大小,更新的是宿主中保存的锚点。

可以放在哪里

宿主产品嵌入位置典型用途
Sheet工作表浮动对象、独立标签页在计算模型旁放置一份说明文档,或在独立标签页中打开任务库。
Doc正文内容块正文、预算和任务放在同一个项目页面中。
Slide页面浮动对象、独立页面在结论旁展示可编辑的源数据。
Relational Table数据表列表入口项目说明保留在业务数据库内。
Canvases画布浮动对象数据、方案和讨论放在同一张画布上。

五种宿主的实际案例

以下示例均通过 Facade API 制作,并在浏览器中截图,因此界面为英文。每个案例使用独立的子 Unit,所有内容和数字均为演示数据。

Sheet:计算模型与说明文档

控制台左侧汇总支出,右侧嵌入一份完整的 Doc;Launch tracker 标签页打开一个 Relational Table。报价、运营或财务工作簿需要把假设、计算和书面结论放在一起时,适合采用这种布局。交互上最接近的是在 Excel 中插入文档对象。

Doc:项目页面中的预算与任务库

正文先放预算 Sheet,后放 Relational Table,读者可以在原处查看模型、维护任务。这种组织方式接近 Notion 的页内数据库,区别在于预算仍由 Sheet 公式引擎计算,任务保留 Relational Table 的字段和视图。

Slide:评审页中的实时数据

一张 Slide 上同时放置预算 Sheet、任务 Relational Table 和一个由公式驱动的预算指标。其交互体验接近在 PowerPoint 中嵌入 Excel:评审者可以从结论出发,再回到可编辑的数据模型。图中的预算已更新为 $62,100。

Relational Table:业务库中的项目说明

在数据表列表中,Launch brief 文档位于任务表旁边。在 CRM、项目台账或运营数据库中,人们可以在结构化的工作与配套的文字说明之间切换。它是数据表列表中的一个入口,不会为每条记录自动创建文档。

Canvases:共同讨论的数据画布

画布同时包含预算 Sheet、方案 Doc 和一个由公式计算的支出汇总。项目作战室、方案评审和研究画布需要讨论期间随时查看源数据和上下文时,适合采用这种组合。

公式如何联动

嵌入只负责显示和编辑,计算值来自引用。插入一个块不会生成汇总公式,需要先配置跨 Unit 引用。配置完成后,Sheet 单元格以及 Doc、Slide、Canvases 中的公式形状可以读取 Sheet 区域或 Relational Table 字段,Relational Table 的公式字段也可以引用 Sheet。源数据和变更通知可用时,相关修改会触发重新计算。

100%
场景与公式验证结果
Slide 汇总预算:=SUM('[Leadership Budget]Budget'!C5:C8)C7 从 17,100 改为 18,000 时,汇总由 61,200 → 62,100。
Sheet 汇总 Relational Table 成本:=SUM([Control Tasks]!Launch_tasks[Cost])一条 Cost 从 4,000 改为 4,500 时,汇总由 18,000 → 18,500。

公式中的名称是可读的限定符,接入时还必须持久化其背后的稳定 Unit ID。使用 getFormula().buildReference() 生成引用及其所需的宿主侧外部映射。对于 Relational Table 中的表,应使用 table.getFormulaName(),不要直接拼接显示名称或 ID。公式形状使用 shape.setFormula({ formula, externalReferences }),并在计算完成后读取结果。详见 Formula Facade、Shape Facade 和 Relational Table 公式。

创建与接入

在同一个 Univer 实例中注册宿主产品、子产品及其 UI,然后注册 Embed 与 Embed UI。以下示例将一份已有的 Sheet 插入 Doc 正文;hostDocument 和 budgetWorkbook 是对应的 Facade。

TypeScript
import '@univerjs-pro/embed/facade'const block = univerAPI.createEmbed({  host: {    unitId: hostDocument.getId(),    surface: univerAPI.Enum.FEmbedHostSurface.DocBlock,  },  content: {    unitType: univerAPI.Enum.UniverInstanceType.UNIVER_SHEET,    ref: `#unit=${encodeURIComponent(budgetWorkbook.getId())}&type=sheet`,  },})const embeddedWorkbook = await block.loadAsync()

createEmbed() 创建关系和宿主锚点。loadAsync() 加载子 Unit 并返回其 Facade。displayTarget 用于指定初始显示的工作表、Slide 页面或 Relational Table 视图。插件、样式、语言和加载器的配置见跨文档嵌入指南,其他位置和方法见 Embed Facade。

保存、协同与使用范围

  • 宿主 Snapshot 保留引用、位置和显示设置,但不会自动打包子 Unit 的最新内容。移除一个块不会删除对应的子文档。
  • Server SDK 提供子快照以及配套的协同服务。浏览器接入 @univerjs-pro/collaboration-embed 后,会加载子 Unit 并加入其协同会话。父、子各自保留自己的变更和版本。
  • 引用解析、数据加载和访问授权由应用负责。能够打开宿主,并不代表自动获得子内容的编辑权限。
  • Sheet、Doc、Slide、Relational Table 和 Canvases 可以跨类型互相嵌入;PDF、同类互嵌和更深的嵌套不在支持范围内。在同一个 Univer 运行时中,一个子 Unit 只能属于一个活动嵌入。

如果要用电子表格驱动应用自己的输入框、指标和图表,请使用双向绑定。需要使用子产品自己的编辑器时,请使用 Embed Block。

返回功能总览

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.