# 檔案匯入與匯出

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

- Human documentation: [https://docs.univer.ai/zh-TW/overview/features/shared/file-conversion](https://docs.univer.ai/zh-TW/overview/features/shared/file-conversion)

- Agent Markdown: [https://docs.univer.ai/zh-TW/overview/features/shared/file-conversion.md](https://docs.univer.ai/zh-TW/overview/features/shared/file-conversion.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.3.0`

- Source: [features/shared/file-conversion.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/docs/features/shared/file-conversion.zh-TW.mdx)

---

檔案匯入匯出連接外部檔案格式與 Univer 內容模型：匯入時將檔案解析為對應產品的 Snapshot（快照），匯出時則將產品快照序列化為所選格式的檔案。

## 從檔案到快照

以 Office 檔案為例，`.xlsx`、`.docx`、`.pptx` 是包含 XML、圖片等資源的 OOXML 套件；`.xls`、`.doc`、`.ppt` 使用舊版二進位結構。CSV、TSV 則是文字格式。應用程式直接提交支援格式的原始檔案，由轉換模組負責解碼、解析套件與映射資源。

Snapshot 是產品可儲存、還原的內容狀態。 [查看六個產品的資料結構](#snapshot-資料結構)

### 匯入：檔案 → Snapshot

解析內容、樣式與資源，映射至 Sheet、Doc、Slide、Relational Table 等對應產品的內容模型。

```mermaid
flowchart LR
    A["1. 原始檔案<br/>XLSX / DOCX / PPTX 等"]
    B["2. 解析為 Snapshot<br/>Server SDK"]
    C["3. 按需計算<br/>更新 Snapshot"]
    D["4. Web SDK<br/>編輯或處理內容"]
    A --> B --> C --> D
    classDef calculation stroke-dasharray:5 4
    class C calculation
```

### 匯出：Snapshot → 檔案

讀取目前產品快照，產生目標格式的檔案結構與資源。快照是執行時期讀寫的內容模型，通常以 JSON 傳遞或儲存。

```mermaid
flowchart LR
    A["1. 目前 Snapshot<br/>編輯後的內容"]
    B["2. 按需計算<br/>更新 Snapshot"]
    C["3. Server SDK<br/>轉換為目標格式"]
    D["4. 目標檔案<br/>XLSX / DOCX / PPTX 等"]
    A --> B --> C --> D
    classDef calculation stroke-dasharray:5 4
    class B calculation
```

以 Sheet 為例，依策略計算公式、樞紐分析與數字格式，結果寫回 Snapshot。詳見[伺服器端計算](https://docs.univer.ai/zh-TW/overview/features/shared/server-calculation.md)。

### Snapshot 資料結構

各產品都有對應的 Snapshot 介面，用於持久化內容與資源參照，通常以 JSON 儲存。點選介面名稱可查看欄位定義、型別與範例。

| 產品 | Snapshot 介面 | 主要內容 |
| --- | --- | --- |
| 試算表（Sheet） | [`IWorkbookData`](https://docs.univer.ai/zh-TW/guides/sheets/model/workbook-data.md#iworkbookdata) | 工作表、儲存格、共用樣式與外掛資源。 |
| 文件（Doc） | [`IDocumentData`](https://docs.univer.ai/zh-TW/guides/docs/model/document-data.md#idocumentdata) | 本文、段落、樣式、頁首頁尾與資源。 |
| 簡報（Slide） | [`ISlideData`](https://docs.univer.ai/zh-TW/guides/slides/model/slide-data.md#islidedata) | 投影片、元素、母片、主題與資源。 |
| 關聯式表格（Relational Table） | [`IBaseSnapshot`](https://docs.univer.ai/zh-TW/guides/bases/model/base-snapshot.md#ibasesnapshot) | 資料表、欄位、記錄、檢視及各自順序。 |
| 畫布（Canvases） | [`IBoardData`](https://docs.univer.ai/zh-TW/guides/boards/model/board-data.md#iboarddata) | 頁面、元素、主題與資源。 |
| PDF | [`IPdfUnitData`](https://docs.univer.ai/zh-TW/guides/pdfs/model/pdf-data.md#ipdfunitdata) | 來源文件、持久化編輯狀態與資源綁定。 |

透過各產品 Facade 的 `save()` 取得目前快照，再由對應的建立介面還原；執行中的內容透過 Facade API 修改。PDF 使用 `pdf.save()`，可同時保留來源基線與 `editState`。

## 各產品支援的格式

下表的 Office 與表格資料格式依目前 Rust Exchange 直接轉換入口整理；PDF 使用獨立轉換模組，於表中註明。

| 產品 | 匯入 / 編譯 | 匯出 | 說明 |
| --- | --- | --- | --- |
| [試算表（Sheet）](https://docs.univer.ai/zh-TW/guides/sheets/features/import-export.md) | `.xls`, `.xlsx`, `.csv`, `.tsv` | `.xlsx`, `.csv`, `.tsv` | CSV/TSV 對應單一工作表。 |
| [文件（Doc）](https://docs.univer.ai/zh-TW/guides/docs/features/import-export.md) | `.doc`, `.docx` | `.docx` | 舊版 DOC 匯入為文件模型，匯出使用 DOCX。 |
| [簡報（Slide）](https://docs.univer.ai/zh-TW/guides/slides/features/import-export.md) | `.ppt`, `.pptx` | `.pptx` | 舊版 PPT 匯入為簡報模型，匯出使用 PPTX。 |
| [關聯式表格（Relational Table）](https://docs.univer.ai/zh-TW/guides/bases/features/import-export.md) | `.xls`, `.xlsx`, `.csv`, `.tsv` | `.xlsx`, `.csv`, `.tsv` | CSV/TSV 對應單一資料表；XLSX 支援資料表與欄位映射。 |
| [畫布（Canvases）](https://docs.univer.ai/zh-TW/guides/boards/features/import-export.md) | Mermaid（`.mmd` / 原始碼文字） | `.pptx` | Mermaid 先產生匯入草稿，經 Canvases Facade 套用後儲存快照；PPTX 匯出目前頁面。 |
| [PDF](https://docs.univer.ai/zh-TW/guides/pdfs/features/import-export.md) | `.pdf` | `.pdf` | 需要 PDF 轉換服務，與 Rust Exchange CLI 的入口分開。 |

- 舊版 `.xls`、`.doc`、`.ppt` 支援匯入，匯出分別產生 `.xlsx`、`.docx`、`.pptx`。
- CSV/TSV 每次選擇單一工作表或 Relational Table 資料表匯出；保留完整內容模型與資源時，請儲存產品快照。
- 不同 SDK 入口接受的副檔名可能不同。`.xlsm`、`.pptm`、`.ppsx`、`.ppsm`、`.potx` 須核對部署的後端與瀏覽器 API，不是額外的 Rust CLI 直接格式名稱。

## 轉換過程中的計算

支援的試算表轉換流程可結合伺服器端計算：

- **公式計算：** 匯入時補齊缺少的公式快取結果，或於匯出前依策略重新計算。
- **樞紐分析計算：** 依來源資料與設定計算分組及彙總結果，寫入快照或匯出活頁簿。
- **數字格式計算：** 依數值與格式碼產生日期、百分比、貨幣等顯示文字；CSV/TSV 可選顯示值或原始值。

相關內容處理流程見[無頭與伺服器端計算](https://docs.univer.ai/zh-TW/overview/features/shared/server-calculation.md)。

## 接入方式

檔案轉換屬於 Server SDK，上傳、任務處理、儲存與下載由應用程式提供。快照轉換可獨立執行；共用文件匯出前，需等待修改同步，再讀取已確認版本。

從[匯入匯出整合](https://docs.univer.ai/zh-TW/server/import-export.md)與 [Node.js 檔案轉換](https://docs.univer.ai/zh-TW/server/import-export/node.md)開始。

格式支援與個別功能能否完整往返分別說明。請結合產品功能清單，以真實檔案檢查匯入、編輯、匯出後的公式、圖片、樣式與版面。

[返回功能總覽](https://docs.univer.ai/zh-TW/overview/features.md)