跨文件嵌入（Embed block）

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

嵌入區塊將一種 Univer 產品放進另一種產品：在專案文件中維護預算與任務、在簡報中審閱可計算的表格，或在畫布中同時查看計畫與說明。子內容保留自己的資料模型與原生編輯能力，啟用後切換對應的焦點與選單。

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

宿主 Unit 儲存區塊位置、大小、子 Unit 參照與預設檢視；子 Unit 儲存實際的儲存格、段落或記錄。Embed 解析參照並載入子 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：審閱頁面的即時資料

將預算 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 提供子 Unit 快照與協作服務；瀏覽器接入 @univerjs-pro/collaboration-embed 後載入並加入子 Unit 的協作工作階段。父子內容仍各有變更與版本。
  • 存取與權限：應用程式負責解析參照、載入資料與授權；能存取宿主並不代表自動取得子內容的編輯權限。
  • 目前範圍：支援不同類型的 Sheet、Doc、Slide、Relational Table、Canvases 互嵌；不含 PDF、同類互嵌或繼續巢狀嵌入。同一 Univer 執行環境中，一個子 Unit 只能屬於一個使用中的嵌入區塊。

若要以表格驅動應用程式自己的輸入框、指標或圖表，請使用雙向綁定；需要保留子產品編輯器時，使用 Embed Block。

返回功能總覽

你覺得這篇文檔如何？

© 2026 DreamNum Co., Ltd.