檔案匯入與匯出

將 Office 檔案轉換為對應產品的 Snapshot,再將編輯後的快照匯出為檔案。

檔案匯入匯出負責連線外部檔案格式與 Univer 使用的內容模型。匯入把檔案解析為對應產品的 Snapshot,匯出把產品的 Snapshot 序列化為選定的輸出格式。

從檔案到快照

Office 檔案分為兩類。.xlsx、.docx、.pptx 是 OOXML 檔案包,包含 XML 和圖片等資源;.xls、.doc、.ppt 使用舊版二進位制結構。CSV 和 TSV 是純文字。提交支援格式的原檔案後,解碼、檔案包解析和資源對映均由轉換模組完成。

Snapshot 是產品的內容狀態,可以儲存,也可以恢復。六個產品的資料結構見下文。

匯入:檔案 → Snapshot

匯入將內容、樣式和資源解析為對應的產品模型:Sheet、Doc、Slide、Relational Table 等。

100%

匯出:Snapshot → 檔案

匯出讀取當前的產品 Snapshot,寫出目標格式的結構和資源。Snapshot 是執行時使用的內容模型,通常以 JSON 傳輸或儲存。

100%

以 Sheet 為例,按選定的策略計算公式、透視表和數字格式,然後更新 Snapshot。詳見伺服器端計算。

Snapshot 資料結構

每個產品都定義了自己的 Snapshot 介面,用於持久化內容和資源引用,通常以 JSON 儲存。介面連結指向欄位定義、型別和範例。

產品Snapshot 介面主要內容
試算表(Sheet)IWorkbookData工作表、儲存格、共用樣式與外掛資源。
文件(Doc)IDocumentData本文、段落、樣式、頁首頁尾與資源。
簡報(Slide)ISlideData投影片、元素、母片、主題與資源。
關聯式表格(Relational Table)IBaseSnapshot資料表、欄位、記錄、檢視及各自順序。
畫布(Canvases)IBoardData頁面、元素、主題與資源。
PDFIPdfUnitData來源文件、持久化編輯狀態與資源綁定。

透過產品 Facade 的 save() 取得當前 Snapshot,再使用對應的建立介面恢復。已載入的內容透過 Facade API 修改。PDF 使用 pdf.save(),可同時保留源基線和 editState。

各產品支援的格式

下表中的 Office 與表格格式使用 Rust Exchange 的直接轉換入口。PDF 使用獨立的轉換模組,因此在同一張表中單獨列出。

產品匯入 / 編譯匯出說明
試算表(Sheet).xls, .xlsx, .csv, .tsv.xlsx, .csv, .tsvCSV/TSV 對應單一工作表。
文件(Doc).doc, .docx.docx舊版 DOC 匯入文件模型,匯出為 DOCX。
簡報(Slide).ppt, .pptx.pptx舊版 PPT 匯入簡報模型,匯出為 PPTX。
關聯式表格(Relational Table).xls, .xlsx, .csv, .tsv.xlsx, .csv, .tsvCSV/TSV 對應單一資料表;XLSX 支援資料表與欄位映射。
畫布(Canvases)Mermaid(.mmd / 原始碼文字).pptxMermaid 先生成匯入草稿,經 Canvases Facade 應用後再儲存 Snapshot;PPTX 匯出當前頁面。
PDF.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 檔案轉換開始。

格式支援與單項功能的保留是兩個不同的問題。請結合各產品的功能清單,使用真實的業務檔案檢查公式、圖片、樣式和版面配置經過匯入、編輯、匯出後的結果。

返回功能總覽

你覺得這篇文檔如何?

© 2026 DreamNum Co., Ltd.