# 跨文件嵌入（Embed block）
> 在另一種 Office 產品中嵌入可編輯內容，保留原生編輯能力。
- Human documentation: [https://docs.univer.ai/zh-TW/overview/features/shared/embed](https://docs.univer.ai/zh-TW/overview/features/shared/embed)
- Agent Markdown: [https://docs.univer.ai/zh-TW/overview/features/shared/embed.md](https://docs.univer.ai/zh-TW/overview/features/shared/embed.md)
- Requested language: `zh-TW`
- Content language: `zh-TW`
- Documentation version: `1.3.0`
- Source: [features/shared/embed.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/features/shared/embed.zh-TW.mdx)
---
嵌入區塊將一種 Univer 產品放進另一種產品：在專案文件中維護預算與任務、在簡報中審閱可計算的表格，或在畫布中同時查看計畫與說明。子內容保留自己的資料模型與原生編輯能力，啟用後切換對應的焦點與選單。
## 原理：宿主與子內容各司其職
**宿主 Unit** 儲存區塊位置、大小、子 Unit 參照與預設檢視；**子 Unit** 儲存實際的儲存格、段落或記錄。Embed 解析參照並載入子 Unit，再將其編輯器放在宿主指定位置。[Unit（內容單元）](https://docs.univer.ai/zh-TW/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-TW/reference/facade/formula.md#buildreference)、[Shape Facade](https://docs.univer.ai/zh-TW/reference/facade/shape.md#setformula) 與 [Relational Table 公式](https://docs.univer.ai/zh-TW/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。用 `displayTarget` 指定預設工作表、Slide 頁面或 Relational Table 檢視。完整外掛、樣式、語言與載入器設定見[跨文件嵌入指南](https://docs.univer.ai/zh-TW/guides/fundamentals/features/embed.md)，其他位置與方法見 [Embed Facade](https://docs.univer.ai/zh-TW/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-TW/overview/features/shared/binding.md)；需要保留子產品編輯器時，使用 Embed Block。
[返回功能總覽](https://docs.univer.ai/zh-TW/overview/features.md)