無頭與伺服器端計算
在 Node.js 中讀寫內容,結合 Rust 預先計算與陣列展開,為應用程式和 Agent 提供結構化與視覺結果。
Headless Univer 是 Univer 的內容執行時,不包含可互動的編輯器介面。它與瀏覽器編輯器共用同一套內容模型、命令、計算和 Facade API。應用可以在 Node.js 中執行它來處理內容,也可以在瀏覽器中執行它來執行不需要介面的任務。它具備哪些能力,取決於註冊了哪些產品和功能外掛。
本頁介紹的 JavaScript/TypeScript 內容執行時與 univer-rs 是兩套彼此獨立的實現。後者負責伺服器端計算和檔案轉換,可以基於同一份快照與 Headless 工作流配合使用。
Headless 能做什麼
- 讀寫內容和結構。建立或載入 Univer 快照,使用 Facade API 讀寫單元格、段落、頁面、圖形物件或記錄,然後儲存更新後的快照。批次處理、資料生成、內容檢查和 Agent 自動化均以這套能力為基礎。
- 執行已註冊的業務邏輯。執行時支援公式計算、排序、篩選、資料驗證和透視表外掛,也可以修改圖片、圖表、形狀和評論等資源。可執行的操作取決於註冊的產品和功能外掛及其依賴。
- 連線其他服務。接入 Node.js 協同客戶端後,可以載入協同 Unit、提交修改並等待同步。將 Server SDK 的轉換模組與執行時結合,可以匯入和匯出 Office 檔案。
Headless 不提供編輯器介面,包括選單、工具欄、彈窗、滑鼠鍵盤互動、截圖和列印。它也不自帶持久化、使用者認證、協同伺服器和檔案轉換能力。save() 返回的是 Univer 快照,不會寫入資料庫,也不會匯出 XLSX、DOCX 或 PDF。截圖和視覺版面配置檢查需要單獨接入渲染執行時,因為無介面瀏覽器仍然執行渲染層。
哪些套件屬於 Headless 範疇
按需選擇內容層的包,然後註冊它們對應的產品外掛和依賴。使用 Pro 功能還需要配置相應的許可證。
內容模型
這些包提供例項、內容模型、命令和基礎內容操作。
@univerjs/core@univerjs/sheets@univerjs/docs
公式與數字格式
這些包提供公式執行、表格公式接入和數字格式。根據所需功能選擇開源引擎或 Pro 引擎。
@univerjs/engine-formula@univerjs/sheets-formula@univerjs/sheets-numfmt@univerjs-pro/engine-formula
試算表資料與規則
表格資料和規則操作可以正常執行,但執行時不提供通常配套的面板和可視互動。資料驗證還需要引入 @univerjs/data-validation。
@univerjs/sheets-filter@univerjs/sheets-sort@univerjs/sheets-conditional-formatting@univerjs/sheets-data-validation@univerjs/sheets-table@univerjs/sheets-hyper-link@univerjs/sheets-note
圖片、連結與留言
這些包提供圖片、連結和評論的模型、資源和命令。顯示、上傳和外部資料來源按需單獨接入。
@univerjs/drawing@univerjs/sheets-drawing@univerjs/docs-drawing@univerjs/docs-hyper-link@univerjs/thread-comment@univerjs/sheets-thread-comment@univerjs/docs-thread-comment
試算表進階功能
這些包提供透視表、圖表、形狀、迷你圖、分組和切片器的內容與計算邏輯。圖形相關的依賴可能還包括 @univerjs-pro/engine-chart 和 @univerjs-pro/engine-shape。
@univerjs-pro/sheets-pivot@univerjs-pro/sheets-chart@univerjs-pro/sheets-shape@univerjs-pro/sheets-sparkline@univerjs-pro/sheets-outline@univerjs-pro/sheets-slicer
文件擴充
文件塊、表格、分欄、公式和形狀支援內容操作,但不提供編輯器控制元件。
@univerjs-pro/docs-callout@univerjs-pro/docs-code@univerjs-pro/docs-list@univerjs-pro/docs-quote@univerjs-pro/docs-table@univerjs-pro/docs-column@univerjs-pro/docs-latex@univerjs-pro/docs-formula@univerjs-pro/docs-shape
其他產品模型
這些包提供其他產品的模型和命令。pdfs-editor 配置 PDF 編輯器的生命週期和協同接入;包名中包含 editor 不代表提供介面。各產品可用的 API 不同。
@univerjs-pro/slides@univerjs-pro/bases@univerjs-pro/boards@univerjs-pro/pdfs@univerjs-pro/pdfs-editor
網路、計算程序與協同
基礎設施按需引入。@univerjs/network 和 @univerjs/rpc-node 提供網路能力和 Node.js 計算程序,@univerjs-pro/license 負責許可證接入。@univerjs-pro/collaboration、@univerjs-pro/collaboration-client 和 @univerjs-pro/collaboration-client-node 共同構成 Headless 協同客戶端,不是協同伺服器。處理本地快照不需要接入協同服務。
哪些套件不屬於純內容執行環境
@univerjs/ui、@univerjs/design,以及產品或功能的*-ui包(例如@univerjs/sheets-ui、@univerjs/docs-ui、@univerjs-pro/slides-ui)提供介面、渲染接入或互動能力,不應加入僅處理內容的 Node.js 配置。@univerjs/sheets-find-replace和@univerjs/sheets-crosshair-highlight沒有-ui字尾,但依賴@univerjs/sheets-ui,因此不能僅憑包名認定它們是 Headless 外掛。@univerjs/preset-sheets-core和@univerjs/preset-docs-core這兩個預設預設會註冊 UI 外掛,不是 Node.js Headless 預設。這類場景應使用外掛模式,明確選擇內容層的依賴。
@univerjs/engine-render 需要單獨說明。 當前的 Node.js 範例會註冊它,用於提供渲染管理等共享依賴。註冊外掛並不建立 Canvas,也不掛載編輯器。它可以出現在 Headless 組合中,但繪製、字型測量和截圖 API 仍然需要合適的渲染環境。因此,不能認為該包的所有 API 都能在純 Node.js 中使用。
Facade 是操作 API,不是執行環境的適配層。 對於所用的內容外掛,匯入其 /facade 擴充套件,並註冊提供相應能力的外掛。@univerjs/ui/facade、@univerjs/sheets-ui/facade 這類 UI 擴充套件仍然需要 UI,它們提供的選單、滾動和選擇區互動同樣如此。判斷時應檢查外掛依賴和實際呼叫路徑,不能只看包名,也不能只看是否存在 Facade API。
可執行的外掛組合見 Sheets Headless 入門與 Docs Headless 入門。
前端即時計算,伺服器依版本計算
前端和伺服器端都執行公式引擎。前端隨編輯響應,伺服器端在生成快照或處理檔案時,對抓取到的內容版本執行計算。
- 編輯時,瀏覽器在本地計算受影響的公式,也可以放在 Worker 中執行,計算結果立即顯示。協同服務記錄這些內容修改並將其同步。
- 生成快照時,伺服器端的快照策略觸發儲存流程。伺服器端先抓取該操作對應的內容版本,使用
univer-rs計算,再將該版本的內容和結果一起儲存。 - 重新開啟文件時,前端複用快照中仍然有效的結果,應用後續修改並繼續計算,避免每次全量重算。
內容修改持續同步;伺服器端在生成快照時執行計算,結果與對應的內容版本一起儲存。
首次載入時,應用根據已儲存的結果決定初始計算的方式:
WHEN_EMPTY:複用已儲存的公式值,只計算缺失的結果。NO_CALCULATION:初始化時不計算,結果由應用提供。FORCED:已儲存的結果需要重新整理時,全部重算。
這些選項僅控制首次載入。此後的編輯仍在前端計算;伺服器端在生成帶版本的快照或處理檔案時按需計算。配置見公式文件,同步機制見協同總覽,檔案處理見匯入與匯出。
公式引擎效能
10 份工作簿的 Univer Rust 公式引擎效能實測涵蓋 Rust 輸入載入、各階段耗時、輸入格式邊界和樣張下載。
陣列公式的計算與展開
在支援的函式和格式範圍內,Rust 遵循 Excel 的陣列公式和溢位規則進行計算。計算結果連同錨點和展開範圍一併返回,同時支援動態陣列和舊式陣列公式的宣告區域。
例如,在空白的 A1 裡寫入 =SEQUENCE(3,2),得到的結果是:
| A | B |
|---|---|
| 1 | 2 |
| 3 | 4 |
| 5 | 6 |
公式仍保留在 A1,結果佔據 A1:B3。陣列縮小時,舊的展開值會被清除;展開區域被佔用時返回 #SPILL!。前端展示、Agent 讀取和檔案匯出都可以複用這份計算好的快照。
具體函式和範圍規則見公式支援和 Excel 陣列展開行為。
接入 Agent 的執行與驗證流程
模型、對話和工具編排沿用現有方案。AI SDK 提供一組操作 Office 內容的工具,供該 Agent 呼叫:
- 檢查結構,讀取目標內容。
- 在無頭執行時中執行 Facade 修改和所需的計算。
- 待計算和提交確認後,讀取更新後的狀態。
- 核對值和結構;需要視覺驗證時,補充截圖或版面配置檢查。
內容操作和視覺檢查可以配合使用。需要人工審閱時,先將修改放入 Worktree,再進行比較和合並。Univer CLI 演示瞭如何將這些能力組合成 Agent 可驅動的應用。
如何接入
| 能力 | 可以完成什麼 |
|---|---|
| Node.js 內容執行環境 | 從 headless Univer 開始,按需啟用所需的產品和計算外掛。 |
| 背景檔案處理 | 將 Rust 計算與 Node.js 檔案轉換 結合,然後儲存或返回更新後的快照。 |
| 共用編輯與 Agent | 接入協同服務和 AI SDK,使人和 Agent 都在已確認的內容上操作。 |
你覺得這篇文檔如何?