跨文件嵌入(Embed block)
在另一種 Office 產品中嵌入可編輯內容,保留原生編輯能力。
嵌入塊把一種 Univer 產品放入另一種產品之中。專案文件中可以放置預算和任務,演示頁上可以承載一份可繼續計算的表格,畫布上可以把計劃和說明放在一起。嵌入的內容保留自己的資料模型和原生編輯器,啟用該塊時,焦點和選單會轉移到子 Unit。
原理:宿主與子內容各司其職
宿主 Unit 儲存塊的位置、大小、子 Unit 引用和預設檢視;子 Unit 儲存實際的單元格、段落或記錄。載入一個塊時,先解析該引用,再載入子 Unit,並把它的編輯器掛載到宿主中。這裡的 Unit(內容單元) 可以是一份工作簿、文件、簡報、關係型表格或畫布。
嵌入關係與內容分別持久化。修改嵌入表格中的單元格,更新的是子 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。源資料和變更通知可用時,相關修改會觸發重新計算。
| 情境與公式 | 驗證結果 |
|---|---|
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。
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。
你覺得這篇文檔如何?