檔案匯入與匯出
將 Office 檔案轉換為對應產品的 Snapshot,再將編輯後的快照匯出為檔案。
檔案匯入匯出負責連線外部檔案格式與 Univer 使用的內容模型。匯入把檔案解析為對應產品的 Snapshot,匯出把產品的 Snapshot 序列化為選定的輸出格式。
從檔案到快照
Office 檔案分為兩類。.xlsx、.docx、.pptx 是 OOXML 檔案包,包含 XML 和圖片等資源;.xls、.doc、.ppt 使用舊版二進位制結構。CSV 和 TSV 是純文字。提交支援格式的原檔案後,解碼、檔案包解析和資源對映均由轉換模組完成。
Snapshot 是產品的內容狀態,可以儲存,也可以恢復。六個產品的資料結構見下文。
匯入:檔案 → Snapshot
匯入將內容、樣式和資源解析為對應的產品模型:Sheet、Doc、Slide、Relational Table 等。
匯出:Snapshot → 檔案
匯出讀取當前的產品 Snapshot,寫出目標格式的結構和資源。Snapshot 是執行時使用的內容模型,通常以 JSON 傳輸或儲存。
以 Sheet 為例,按選定的策略計算公式、透視表和數字格式,然後更新 Snapshot。詳見伺服器端計算。
Snapshot 資料結構
每個產品都定義了自己的 Snapshot 介面,用於持久化內容和資源引用,通常以 JSON 儲存。介面連結指向欄位定義、型別和範例。
| 產品 | Snapshot 介面 | 主要內容 |
|---|---|---|
| 試算表(Sheet) | IWorkbookData | 工作表、儲存格、共用樣式與外掛資源。 |
| 文件(Doc) | IDocumentData | 本文、段落、樣式、頁首頁尾與資源。 |
| 簡報(Slide) | ISlideData | 投影片、元素、母片、主題與資源。 |
| 關聯式表格(Relational Table) | IBaseSnapshot | 資料表、欄位、記錄、檢視及各自順序。 |
| 畫布(Canvases) | IBoardData | 頁面、元素、主題與資源。 |
IPdfUnitData | 來源文件、持久化編輯狀態與資源綁定。 |
透過產品 Facade 的 save() 取得當前 Snapshot,再使用對應的建立介面恢復。已載入的內容透過 Facade API 修改。PDF 使用 pdf.save(),可同時保留源基線和 editState。
各產品支援的格式
下表中的 Office 與表格格式使用 Rust Exchange 的直接轉換入口。PDF 使用獨立的轉換模組,因此在同一張表中單獨列出。
| 產品 | 匯入 / 編譯 | 匯出 | 說明 |
|---|---|---|---|
| 試算表(Sheet) | .xls, .xlsx, .csv, .tsv | .xlsx, .csv, .tsv | CSV/TSV 對應單一工作表。 |
| 文件(Doc) | .doc, .docx | .docx | 舊版 DOC 匯入文件模型,匯出為 DOCX。 |
| 簡報(Slide) | .ppt, .pptx | .pptx | 舊版 PPT 匯入簡報模型,匯出為 PPTX。 |
| 關聯式表格(Relational Table) | .xls, .xlsx, .csv, .tsv | .xlsx, .csv, .tsv | CSV/TSV 對應單一資料表;XLSX 支援資料表與欄位映射。 |
| 畫布(Canvases) | Mermaid(.mmd / 原始碼文字) | .pptx | Mermaid 先生成匯入草稿,經 Canvases Facade 應用後再儲存 Snapshot;PPTX 匯出當前頁面。 |
.pdf | .pdf | 需要 PDF 轉換服務,與 Rust Exchange CLI 的入口分開。 |
.xls、.doc、.ppt是匯入格式,匯出格式分別為.xlsx、.docx、.pptx。- CSV/TSV 每次匯出一個工作表或一個 Relational Table 資料表。需要保留完整的內容模型及其資源時,儲存對應的產品 Snapshot。
- 不同 SDK 入口接受的副檔名不同。
.xlsm、.pptm、.ppsx、.ppsm、.potx等格式需要確認所部署的後端和瀏覽器 API,它們不是 Rust CLI 額外支援的直接格式名。
轉換過程中的計算
在支援的電子表格轉換鏈路中,檔案轉換可以與伺服器端計算組合使用:
- 公式計算在匯入時補齊缺失的快取結果,或在匯出前按選定的策略重新計算。
- 透視表計算根據源資料和透視配置得出分組與聚合結果,再將其寫入 Snapshot 或匯出的工作簿。
- 數字格式計算根據數值和格式碼生成日期、百分比、貨幣等顯示文字。CSV/TSV 匯出可以選擇寫入顯示值或原始值。
相關的內容處理流程見無頭與伺服器端計算。
接入方式
檔案轉換屬於 Server SDK。上傳、任務處理、儲存和下載介面由應用提供。Snapshot 轉換可以不依賴協同執行。匯出共享文件則不同:需等待改動同步完成,再讀取已確認的版本。
可以從匯入匯出整合和 Node.js 檔案轉換開始。
格式支援與單項功能的保留是兩個不同的問題。請結合各產品的功能清單,使用真實的業務檔案檢查公式、圖片、樣式和版面配置經過匯入、編輯、匯出後的結果。
你覺得這篇文檔如何?