# 跨文档嵌入（Embed block）
> 在另一种 Office 产品中嵌入可编辑内容，复用各产品的原生能力。
- Human documentation: [https://docs.univer.ai/zh-CN/overview/features/shared/embed](https://docs.univer.ai/zh-CN/overview/features/shared/embed)
- Agent Markdown: [https://docs.univer.ai/zh-CN/overview/features/shared/embed.md](https://docs.univer.ai/zh-CN/overview/features/shared/embed.md)
- Requested language: `zh-CN`
- Content language: `zh-CN`
- Documentation version: `1.3.0`
- Source: [features/shared/embed.zh-CN.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/features/shared/embed.zh-CN.mdx)
---
嵌入块把一种 Univer 产品放进另一种产品：在项目文档中维护预算和任务，在演示页中审阅可计算的表格，或在画布中同时查看计划与说明。子内容保留自己的数据模型和原生编辑能力，激活后切换对应的焦点与菜单。
## 原理：宿主与子内容各司其职
**宿主 Unit** 保存块的位置、大小、子 Unit 引用和默认视图；**子 Unit** 保存实际的单元格、段落、记录等内容。Embed 通过引用加载子 Unit，再把它的编辑器放到宿主指定位置。这里的 [Unit（内容单元）](https://docs.univer.ai/zh-CN/guides/sheets/getting-started/quickstart.md#unit) 可以是一份工作簿、文档、演示文稿、关系型表格或画布。
```mermaid
flowchart LR
A["宿主 Unit
正文、页面或画布"]
B["Embed 描述
位置 + 子 Unit 引用"]
C["解析引用
加载子 Unit"]
D["原生子编辑器
显示与交互"]
E["编辑 / 保存
更新子 Unit"]
A --> B --> C --> D --> E
```
嵌入关系和实际内容分别保存。修改嵌入表格中的单元格，更新的是子 Sheet；移动或调整块的大小，更新的是宿主的位置记录。
## 可以放在哪里
| 宿主产品 | 嵌入位置 | 典型用途 |
| --- | --- | --- |
| Sheet | 工作表浮动对象、独立标签页 | 在计算模型旁放说明文档，或切换到任务库。 |
| Doc | 正文内容块 | 把预算、任务与正文组织成项目页面。 |
| Slide | 页面浮动对象、独立页面 | 在评审页中展示可编辑的源数据。 |
| Relational Table | 数据表列表入口 | 在业务数据库中集中访问项目说明。 |
| Canvases | 画布浮动对象 | 把数据、方案与讨论放在同一画布。 |
## 五种宿主的实际案例
以下为使用 Facade API 创建并在浏览器中截取的英文示例。每个案例使用独立的子 Unit；内容与数字均为演示数据。
### Sheet：计算模型与说明文档
控制台在左侧汇总预算，右侧嵌入完整 Doc；底部的 Launch tracker 标签页进入 Relational Table。适合报价模型、经营分析和财务工作簿，把假设、计算与决策说明放在一起。交互形态可参照 [Excel 中插入文档对象](https://support.microsoft.com/en-au/excel/insert-an-object-in-your-excel-spreadsheet)。
### Doc：项目页面中的预算与任务库
正文依次放入预算 Sheet 与 Relational Table，读者可在项目背景下查看数据、维护任务。它类似 [Notion 的页内数据库](https://www.notion.com/help/guides/full-page-vs-inline-databases)组织方式；这里的预算仍由 Sheet 公式引擎计算，任务保留 Relational Table 的字段与视图。
### Slide：评审页中的实时数据
把预算 Sheet 和任务 Relational Table 放在同一页，旁边的公式形状汇总预算。它对应 [PowerPoint 中嵌入 Excel](https://support.microsoft.com/en-gb/powerpoint/insert-and-update-excel-data-in-powerpoint)这类评审体验：审阅结论时，也能回到可编辑的数据模型。图中预算已更新为 $62,100。
### Relational Table：业务库中的项目说明
在数据表列表中增加 Launch brief 文档入口，任务表与说明文档可以互相切换。适合 CRM、项目台账或运营数据库，为结构化记录配套提供长篇说明；这里嵌入的是列表入口，并非给每条记录自动创建文档。
### Canvases：共同讨论的数据画布
画布同时摆放预算 Sheet 与方案 Doc，下面用公式形状显示预算汇总。适合项目作战室、方案评审和研究画布，讨论时可以保留源数据与上下文，而不必先转成静态图片。
## 公式如何联动
**嵌入负责展示和编辑，公式引用负责计算。** 插入一个块不会自动生成汇总公式；接入跨 Unit 引用后，Sheet 单元格以及 Doc、Slide、Canvases 中的公式形状可读取 Sheet 区域或 Relational Table 字段。Relational Table 的公式字段也可引用 Sheet。源数据可用并正确接入更新通知时，相关变更会触发重新计算。
```mermaid
flowchart LR
A["编辑嵌入的 Sheet / Relational Table"]
B["子 Unit 数据变更"]
C["引用与依赖更新"]
D["公式重新计算"]
E["更新单元格 / 公式形状"]
A --> B --> C --> D --> E
```
| 场景与公式 | 验证结果 |
| --- | --- |
| 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](https://docs.univer.ai/zh-CN/reference/facade/formula.md#buildreference)、[Shape Facade](https://docs.univer.ai/zh-CN/reference/facade/shape.md#setformula) 与 [Relational Table 公式](https://docs.univer.ai/zh-CN/guides/bases/features/core/formulas.md)。
## 创建与接入
在同一 Univer 实例中注册宿主、子产品及其 UI，再注册 Embed 与 Embed UI。下面把已存在的 Sheet 加入 Doc 正文；`hostDocument` 和 `budgetWorkbook` 是对应的 Facade 对象。
```ts
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`。完整插件、样式、语言与加载器配置见[跨文档嵌入指南](https://docs.univer.ai/zh-CN/guides/fundamentals/features/embed.md)，其他位置与方法见 [Embed Facade](https://docs.univer.ai/zh-CN/reference/facade/embed.md)。
## 保存、协同与使用范围
- **分别保存**：宿主 Snapshot 保留引用、位置与显示设置，不会自动打包子 Unit 的最新内容。移除块不等于删除子文档。
- **协同加载**：Server SDK 提供子 Unit 的快照与协同服务；浏览器接入 `@univerjs-pro/collaboration-embed` 后，加载并加入子 Unit 的协同会话。父、子内容仍各有自己的变更与版本。
- **访问与权限**：应用负责解析引用、加载数据与授权；宿主可访问，不代表自动获得子内容的编辑权限。
- **当前范围**：支持不同类型的 Sheet、Doc、Slide、Relational Table、Canvases 互嵌；不含 PDF、同类互嵌或继续嵌套。当前同一 Univer 运行时中，一个子 Unit 只能属于一个活动嵌入块。
如果需要用表格驱动应用自有的输入框、指标卡片或图表，可使用[双向绑定](https://docs.univer.ai/zh-CN/overview/features/shared/binding.md)。需要保留子产品编辑器时，使用 Embed Block。
[返回功能总览](https://docs.univer.ai/zh-CN/overview/features.md)