跨文档嵌入

在表格、文档、幻灯片、白板和多维表格中嵌入其他类型的 Univer 文档,并保留原生编辑能力。

Embed 允许在一种 Univer 文档中编辑另一种 Univer 文档。可以在文档正文中插入表格,在白板上放置幻灯片,或者把多维表格置于工作簿的标签页中。承载嵌入的是父文档,被引用的是子文档,两者各自保留自己的数据模型。

支持的嵌入位置

父文档嵌入位置可嵌入的子文档
Sheets工作表中的浮动对象、工作簿标签页Docs、Slides、Boards、Bases
Docs正文内容块Sheets、Slides、Boards、Bases
Slides页面中的浮动对象、页面列表Sheets、Docs、Boards、Bases
Boards画布中的浮动对象Sheets、Docs、Slides、Bases
Bases数据表列表Sheets、Docs、Slides、Boards

浮动对象和正文内容块在父文档内展示子文档,编辑能力由子文档对应的产品提供。标签页和列表入口把子文档变成可切换的页面;激活该页面后,菜单区域交由子文档接管。

内置能力不支持 PDF、同类产品互嵌,也不支持在嵌入的子文档中再嵌入其他文档。

接入插件

父、子两种产品及其 UI 必须首先运行在同一个 Univer 实例中。Embed 不替代这些产品的基础插件:在 Sheets 中嵌入 Docs 时,Sheets 和 Docs 都需要接入。所有依赖版本应保持一致,并按许可证配置配置 UniverLicensePlugin。

Shell
pnpm add @univerjs-pro/embed @univerjs-pro/embed-ui

在现有应用中添加这些导入,并在创建文档之前注册插件。univer 是现有的 Univer 实例。

TypeScript
import { UniverEmbedPlugin } from '@univerjs-pro/embed'import { UniverEmbedUIPlugin } from '@univerjs-pro/embed-ui'import '@univerjs-pro/embed/facade'import '@univerjs-pro/embed-ui/lib/index.css'univer.registerPlugin(UniverEmbedPlugin)univer.registerPlugin(UniverEmbedUIPlugin)

将 @univerjs-pro/embed-ui/locale/zh-CN 的默认导出合并到现有的 locales 配置中。其他语言使用对应的语言包,参见国际化。

@univerjs-pro/embed 提供嵌入关系、引用解析和 Facade API;@univerjs-pro/embed-ui 提供嵌入容器、焦点切换和菜单;@univerjs-pro/embed-unit-ui 提供独立的引用文档查看器,基础嵌入不需要它。

在表格中嵌入文档

以下函数接收已在同一个 Univer 实例中加载的工作簿和文档,并在当前工作表中插入一个浮动文档。ref 使用子文档的真实 ID,type=doc 必须与 unitType 一致。

TypeScript
import type { FUniver } from '@univerjs/core/facade'import type { FDocument } from '@univerjs/docs/facade'import type { FWorkbook } from '@univerjs/sheets/facade'import '@univerjs-pro/embed/facade'import '@univerjs/docs/facade'import '@univerjs/sheets/facade'async function embedDocument(  univerAPI: FUniver,  workbook: FWorkbook,  document: FDocument,) {  const embed = univerAPI.createEmbed<FDocument>({    host: {      unitId: workbook.getId(),      surface: univerAPI.Enum.FEmbedHostSurface.SheetFloating,      context: { subUnitId: workbook.getActiveSheet().getSheetId() },    },    content: {      unitType: univerAPI.Enum.UniverInstanceType.UNIVER_DOC,      ref: `#unit=${encodeURIComponent(document.getId())}&type=doc`,    },  })  await embed.loadAsync()  return embed}

createEmbed() 建立嵌入关系,并确定嵌入在父文档中的位置;loadAsync() 加载子文档并返回其 Facade。调用方应 await 该函数,并处理加载失败。本地引用要求目标文档已存在于当前实例中;仅提供 ID 不会创建或下载文档。

更换嵌入位置

host.surface 从 univerAPI.Enum.FEmbedHostSurface 中选择。host.context 描述内容在父文档中的插入位置。

位置枚举成员位置参数
工作表浮动对象SheetFloatingsubUnitId 指定工作表;placement 指定锚定方式,省略时使用 Position 锚定
工作簿标签页SheetTabsheetIndex、sheetName
文档正文内容块DocBlockstartIndex:正文 dataStream 中的 UTF-16 偏移量;省略时追加到可编辑正文末尾
幻灯片浮动对象SlideFloatingsubUnitId 指定页面;left、top、width、height 指定位置和尺寸
幻灯片页面列表SlidePagepageIndex、pageName
白板浮动对象BoardFloatingsubUnitId 指定页面;left、top、width、height 指定位置和尺寸
多维表格数据表列表BaseTabletableIndex、tableName

列表的插入索引从 0 开始,省略索引则追加到末尾。浮动对象使用文档模型坐标,而不是浏览器视口坐标,不要将滚动或缩放偏移直接写入这些值。

指定子文档的默认视图

displayTarget 决定子文档初始显示的内容,与子文档在父文档中的位置无关。可在创建嵌入时传入,也可稍后通过 embed.setDisplayTarget() 更改。

子文档默认视图参数
Sheets{ subUnitId: 'sheet-id' }
Slides{ pageId: 'page-id' }
Bases{ tableId: 'table-id', viewId: 'view-id' },也支持 dashboardId

应使用稳定的 ID,而不是显示名称。目标不存在时,子文档会回退到第一个可用的视图。在子文档内部的导航不会覆盖该默认值。Docs 和 Boards 不接受 displayTarget。

保存和移除

父文档快照必须保留 resources 中的 Embed 插件数据,以及正文、绘图或列表中的嵌入位置。嵌入关系只记录子文档引用和默认视图,不会把子文档的最新内容自动合并进父文档快照。数据存储在本地时,应用必须单独保存子文档,并确保恢复后引用仍可解析。

univerAPI.listEmbeds({ hostUnitId }) 列出父文档的所有嵌入,univerAPI.getEmbed({ hostUnitId, embedId }) 获取其中一条。embed.remove() 将嵌入从父文档移除,但不会删除子文档已持久化的数据。

加载协同文档

引用服务端文档时,请先完成协同浏览器接入,再注册协同桥接插件:

Shell
pnpm add @univerjs-pro/collaboration-embed
TypeScript
import { UniverCollaborationEmbedPlugin } from '@univerjs-pro/collaboration-embed'univer.registerPlugin(UniverCollaborationEmbedPlugin)

该插件依赖 UniverCollaborationPlugin、UniverCollaborationClientPlugin 和 UniverEmbedPlugin。它通过协同快照服务加载子文档,然后加入该子文档的协同会话。#unit=...&type=... 中应填写服务端的真实文档 ID;能否访问仍取决于现有的身份与授权配置。

如果数据来自自建存储而不是协同服务,可在 UniverEmbedPlugin 上配置 resourceRefUnitProviderRegistrations,使引用解析为对应的文档实例。

更多配置和方法请参阅 FEmbed API、FUniver API 和 Embed 插件 API。

你觉得这篇文档如何?

© 2026 DreamNum Co., Ltd.