跨文件嵌入(Embed block)

在另一種 Office 產品中嵌入可編輯內容,保留原生編輯能力。

嵌入塊把一種 Univer 產品放入另一種產品之中。專案文件中可以放置預算和任務,演示頁上可以承載一份可繼續計算的表格,畫布上可以把計劃和說明放在一起。嵌入的內容保留自己的資料模型和原生編輯器,啟用該塊時,焦點和選單會轉移到子 Unit。

原理:宿主與子內容各司其職

宿主 Unit 儲存塊的位置、大小、子 Unit 引用和預設檢視;子 Unit 儲存實際的單元格、段落或記錄。載入一個塊時,先解析該引用,再載入子 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:審閱頁面的即時資料

一張 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。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。

返回功能總覽

你覺得這篇文檔如何?

© 2026 DreamNum Co., Ltd.