雙向綁定
透過 Server SDK,讓 HTML 應用程式與試算表共用資料、公式結果及協作更新。
實驗性功能
雙向綁定目前仍處於實驗階段,後續版本將有破壞性更新,API 與整合方式可能調整。
Univer Server SDK 可以將普通的 HTML、CSS、JavaScript 頁面接入 Sheet。資料和公式保留在表格中,頁面負責表單、指標、圖表和業務互動。任意一側的輸入發生變化,另一側都會收到更新。藉助它,應用可以將表格模型轉化為報價工具、經營看板或可互動的業務應用。
範例:應用程式與試算表連動
Project Summit 範例把增長率、報價和現金支付比例放在左側控制元件中,右側是完整的財務表格。修改某個假設後,相關的公式、指標卡片和圖表會隨之更新。使用者也可以開啟表格,檢查輸入以及背後的計算過程。
截圖展示的是在本地瀏覽器中執行的模型。共享編輯和持久化使用下文介紹的協同接入方式。點選圖片可以放大檢視。
同一份 Sheet,多種互動介面
HTML 檢視透過頁面執行時與宿主通訊。實際的 Sheet 內容由 Binding Engine 透過其自身獨立的 headless Univer 例項讀寫。公式和協同由 Univer SDK 處理,繫結層負責將變化後的值傳遞到頁面。
使用者在表格中直接修改,或其他使用者產生協同變更時,繫結頁面同樣會重新整理。一個 HTML 檢視可以訪問多個已獲授權的 Unit。宿主為每個 Unit 載入一個 Engine,每個 Engine 各自持有一個獨立的 headless Univer 例項。
以 HTML 宣告綁定
在元素上宣告資料引用後,其文字或表單控制元件會自動保持同步。單元格引用的格式為 unitId:sheetId:A1。兩個 ID 分別使用 encodeURIComponent 編碼,工作表 ID 必須保持不變。
| 屬性 | 用途 |
|---|---|
data-univer-cell-text | 將單元格的值顯示為元素的文字。 |
data-univer-cell-model | 使單元格與表單控制元件雙向同步。 |
data-univer-cell-subscribe | 宣告儲存格訂閱,供自訂 JavaScript 呈現。 |
data-univer-range-subscribe | 宣告矩形區域訂閱,供圖表、列表等讀取二維資料的元件使用。 |
例如,單價位於 B2,數量位於 B3,B4 中為公式 =B2*B3。下面的模板片段將兩個輸入和總價連線到這幾個單元格:
<label> 單價 <input type="number" min="0" step="0.01" data-univer-cell-model="book:sheet:B2" /></label><label> 數量 <input type="number" min="0" step="1" data-univer-cell-model="book:sheet:B3" /></label><p>總價: <span data-univer-cell-text="book:sheet:B4"></span></p>將 book 和 sheet 替換為真實且已授權的 ID,再透過 Renderer 載入模板。公式定義在 Sheet 中,頁面只讀取計算結果。文字輸入框、數字輸入框、滑塊、核取方塊、文字域和單選下拉框都會按各自的值型別繫結。
以 JavaScript 擴充圖表與互動
頁面執行時會在任何模板指令碼執行之前準備好 window.univerBinding。圖表使用 data-univer-range-subscribe 宣告資料區域,然後呼叫 subscribeRangeById(elementId, callback) 取得二維矩陣並更新圖表。只顯示單個值的元件使用 subscribeCellById()。
僅需讀取一次時,使用 getCellState() / getRangeState();寫入單個值時使用 setCellValue();插入行並同時填充值時使用 insertRowsWithValues()。訂閱會先返回當前狀態,之後僅在值實際發生變化時通知。本地編輯、協同修改和公式結果應用都會觸發重新整理。
引用讀取的是固定座標,因此在插入或刪除行列後不會跟隨原記錄移動。標量寫入會覆蓋單元格中原有的公式或富文字,因此只應繫結存放業務輸入的單元格。
接入宿主與 Agent
應用需要提供容器、HTML 模板和 loadEngine。載入器負責校驗 Unit 訪問權限、配置協同連線,然後返回一個已載入的 Engine。Renderer 負責隔離頁面本身、頁面與宿主之間的訊息通訊,以及所交付 Engine 的生命週期。下面這個入口接收的就是這三個參數:
import { renderHtmlView, type RenderHtmlViewOptions,} from '@univerjs-labs/html-view-renderer/render';export function createPreview( container: HTMLElement, html: string, loadEngine: RenderHtmlViewOptions['loadEngine'],) { return renderHtmlView({ container, html, loadEngine });}模板生成、原始碼編輯、檔案儲存和業務導航均由應用負責。Agent 可以生成帶繫結宣告的 HTML,複用 Sheet 中的資料和計算規則;呼叫 view.inspect.open() 可以檢視 Unit、Sheet、引用和頁面元素之間的對應關係。
協同憑據儲存在宿主側,實際的訪問校驗由伺服器端執行。Sheet UI 和 Headless Engine 必須分別放在不同的 JavaScript 環境中,例如兩個頁面或 iframe。目前的繫結包只覆蓋 Sheet。
區分本機更新與儲存確認
| 操作 | 含義 |
|---|---|
| 頁面寫入完成 | 本地操作已執行,但伺服器端可能尚未確認。 |
await view.flush() | 提交控制元件中的草稿值,等待此前的寫入和協同確認完成,然後繼續編輯。 |
await view.prepareToLeave() | 暫停編輯並儲存。儲存成功後可以離開;如果導航被取消,呼叫 view.resume()。 |
view.dispose() | 釋放連線、Engine 和訂閱。它不會儲存任何資料。 |
公式結果應用後,訂閱會重新整理頁面上的值。儲存失敗時,應保持頁面開啟並重試儲存。頁面寫入完成本身並不表示資料已經儲存。
繼續接入
相關能力:無頭與伺服器計算 · 即時協作 · Agent 與自動化。
你覺得這篇文檔如何?