跨文档嵌入（Embed block）

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

嵌入块把一种 Univer 产品放进另一种产品：在项目文档中维护预算和任务，在演示页中审阅可计算的表格，或在画布中同时查看计划与说明。子内容保留自己的数据模型和原生编辑能力，激活后切换对应的焦点与菜单。

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

宿主 Unit 保存块的位置、大小、子 Unit 引用和默认视图；子 Unit 保存实际的单元格、段落、记录等内容。Embed 通过引用加载子 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：评审页中的实时数据

把预算 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。需要指定默认工作表、Slide 页面或 Relational Table 视图时，使用 displayTarget。完整插件、样式、语言与加载器配置见跨文档嵌入指南，其他位置与方法见 Embed Facade。

保存、协同与使用范围

  • 分别保存：宿主 Snapshot 保留引用、位置与显示设置，不会自动打包子 Unit 的最新内容。移除块不等于删除子文档。
  • 协同加载：Server SDK 提供子 Unit 的快照与协同服务；浏览器接入 @univerjs-pro/collaboration-embed 后，加载并加入子 Unit 的协同会话。父、子内容仍各有自己的变更与版本。
  • 访问与权限：应用负责解析引用、加载数据与授权；宿主可访问，不代表自动获得子内容的编辑权限。
  • 当前范围：支持不同类型的 Sheet、Doc、Slide、Relational Table、Canvases 互嵌；不含 PDF、同类互嵌或继续嵌套。当前同一 Univer 运行时中，一个子 Unit 只能属于一个活动嵌入块。

如果需要用表格驱动应用自有的输入框、指标卡片或图表，可使用双向绑定。需要保留子产品编辑器时，使用 Embed Block。

返回功能总览

你觉得这篇文档如何？

© 2026 DreamNum Co., Ltd.