跨文档嵌入(Embed block)
在另一种 Office 产品中嵌入可编辑内容,复用各产品的原生能力。
嵌入块把一种 Univer 产品放入另一种产品之中。项目文档中可以放置预算和任务,演示页上可以承载一份可继续计算的表格,画布上可以把计划和说明放在一起。嵌入的内容保留自己的数据模型和原生编辑器,激活该块时,焦点和菜单会转移到子 Unit。
原理:宿主与子内容各司其职
宿主 Unit 保存块的位置、大小、子 Unit 引用和默认视图;子 Unit 保存实际的单元格、段落或记录。加载一个块时,先解析该引用,再加载子 Unit,并把它的编辑器挂载到宿主中。这里的 Unit(内容单元) 可以是一份工作簿、文档、演示文稿、关系型表格或画布。
嵌入关系与内容分别持久化。修改嵌入表格中的单元格,更新的是子 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。源数据和变更通知可用时,相关修改会触发重新计算。
| 场景与公式 | 验证结果 |
|---|---|
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。
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。
你觉得这篇文档如何?