跨文档嵌入
在表格、文档、幻灯片、白板和多维表格中嵌入其他类型的 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。
pnpm add @univerjs-pro/embed @univerjs-pro/embed-uinpm install @univerjs-pro/embed @univerjs-pro/embed-uiyarn add @univerjs-pro/embed @univerjs-pro/embed-uibun add @univerjs-pro/embed @univerjs-pro/embed-ui在现有应用中添加这些导入,并在创建文档之前注册插件。univer 是现有的 Univer 实例。
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 一致。
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 描述内容在父文档中的插入位置。
| 位置 | 枚举成员 | 位置参数 |
|---|---|---|
| 工作表浮动对象 | SheetFloating | subUnitId 指定工作表;placement 指定锚定方式,省略时使用 Position 锚定 |
| 工作簿标签页 | SheetTab | sheetIndex、sheetName |
| 文档正文内容块 | DocBlock | startIndex:正文 dataStream 中的 UTF-16 偏移量;省略时追加到可编辑正文末尾 |
| 幻灯片浮动对象 | SlideFloating | subUnitId 指定页面;left、top、width、height 指定位置和尺寸 |
| 幻灯片页面列表 | SlidePage | pageIndex、pageName |
| 白板浮动对象 | BoardFloating | subUnitId 指定页面;left、top、width、height 指定位置和尺寸 |
| 多维表格数据表列表 | BaseTable | tableIndex、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() 将嵌入从父文档移除,但不会删除子文档已持久化的数据。
加载协同文档
引用服务端文档时,请先完成协同浏览器接入,再注册协同桥接插件:
pnpm add @univerjs-pro/collaboration-embednpm install @univerjs-pro/collaboration-embedyarn add @univerjs-pro/collaboration-embedbun add @univerjs-pro/collaboration-embedimport { UniverCollaborationEmbedPlugin } from '@univerjs-pro/collaboration-embed'univer.registerPlugin(UniverCollaborationEmbedPlugin)该插件依赖 UniverCollaborationPlugin、UniverCollaborationClientPlugin 和 UniverEmbedPlugin。它通过协同快照服务加载子文档,然后加入该子文档的协同会话。#unit=...&type=... 中应填写服务端的真实文档 ID;能否访问仍取决于现有的身份与授权配置。
如果数据来自自建存储而不是协同服务,可在 UniverEmbedPlugin 上配置 resourceRefUnitProviderRegistrations,使引用解析为对应的文档实例。
更多配置和方法请参阅 FEmbed API、FUniver API 和 Embed 插件 API。
你觉得这篇文档如何?