# 匯入匯出

- Human documentation: [https://docs.univer.ai/zh-TW/guides/sheets/features/import-export](https://docs.univer.ai/zh-TW/guides/sheets/features/import-export)

- Agent Markdown: [https://docs.univer.ai/zh-TW/guides/sheets/features/import-export.md](https://docs.univer.ai/zh-TW/guides/sheets/features/import-export.md)

- Requested language: `zh-TW`

- Content language: `zh-TW`

- Documentation version: `1.2.0`

- Source: [sheets/features/import-export.zh-TW.mdx](https://github.com/dream-num/documentation/blob/dev/content/guides/sheets/features/import-export.zh-TW.mdx)

---

使用下方瀏覽器 API 前，請先完成[匯入匯出整合](https://docs.univer.ai/zh-TW/server/import-export.md)。應用程式需要實作與用戶端匹配的上傳、轉換、任務查詢和受權限保護的下載契約。快照 API 仍需要轉換後端，只是不要求持久化協同 Unit。[Exchange 範例](https://docs.univer.ai/zh-TW/server/collaboration/examples.md#exchange)示範 Sheets；其他產品和格式需核對目標版本的支援範圍。

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/zh-TW",
      "style": "@univerjs/preset-sheets-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/exchange-client",
      "facade": "@univerjs-pro/exchange-client/facade"
    },
    {
      "client": "@univerjs-pro/sheets-exchange-client",
      "facade": "@univerjs-pro/sheets-exchange-client/facade"
    }
  ],
  "license": true,
  "limitations": "CSV/TSV 僅匯出一個工作表，不保留活頁簿格式。本頁瀏覽器 API 不接受 XLSM。",
  "headless": false,
  "server": true
}
```

## 支援的格式

下表列出本頁前端 API 支援的格式。Office 檔案轉換還需要後端支援對應的文件類型和格式。

| 匯入                              | 匯出                      |
| ------------------------------- | ----------------------- |
| `.xls`, `.xlsx`, `.csv`, `.tsv` | `.xlsx`, `.csv`, `.tsv` |

## Facade API

### 匯入

> [!INFO: 外掛模式提示]
> 僅外掛模式需要手動引入 Facade 套件。預設模式已內建對應的 Facade 套件，無需額外引入。

```typescript
import '@univerjs-pro/exchange-client/facade'
import '@univerjs-pro/sheets-exchange-client/facade'
```

### 匯入 `.xlsx`

#### 匯入 `.xlsx` 檔案並獲取 `unitId`

> [!WARNING: 注意事項]
> 此方法依賴協同服務：匯入後會在服務端建立文件並回傳 `unitId`。若未啟用協同，請使用快照匯入。

在啟用協同編輯的時候，每個文件都有一個唯一的 `unitId`。使用 `univerAPI.importSheetToUnitIdAsync` 傳入 `file` 參數會返回 `unitId`，可以透過 `unitId` 來訪問文件。 `file` 參數可以是一個 `File` 物件，也可以是遠端檔案的 URL。

```typescript
import '@univerjs-pro/collaboration-client/facade'

const unitId = await univerAPI.importSheetToUnitIdAsync(file)

if (unitId) {
  await univerAPI.getCollaboration().loadSheetAsync(unitId)
}
```

#### 匯入 `.xlsx` 檔案並獲取 `IWorkbookData`

使用 `univerAPI.importSheetToSnapshotAsync` 匯入 `.xlsx` 檔案，會返回 `IWorkbookData` 格式的文件資料。

```typescript
// 接受 File 物件
const snapshot = await univerAPI.importSheetToSnapshotAsync(file)
// 或者接受遠端檔案的 URL
// const snapshot = await univerAPI.importSheetToSnapshotAsync('https://example.com/filename.xlsx');

// 透過快照建立一個新的工作簿
if (snapshot) univerAPI.createWorkbook(snapshot)
```

### 匯出 `.xlsx`

#### 透過 `unitId` 匯出 `.xlsx` 檔案

> [!WARNING: 注意事項]
> `unitId` 匯出依賴協同服務。若未啟用協同，請使用快照匯出。

在啟用協同編輯的時候，每個文件都有一個唯一的 `unitId`。使用 `univerAPI.exportSheetByUnitIdAsync` 傳入 `unitId` 參數會返回 `File` 物件。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const unitId = fWorkbook.getId()
const file = await univerAPI.exportSheetByUnitIdAsync(unitId)

// 透過 Facade API 下載檔案
if (file) univerAPI.downloadFile(file, 'univer', 'xlsx')
```

#### 透過 `IWorkbookData` 匯出 `.xlsx` 檔案

> [!NOTE]
> 快照匯出不依賴協同服務，適合僅在本機處理資料的場景。

使用 `univerAPI.exportSheetBySnapshotAsync` 傳入 `IWorkbookData` 會返回 `File` 物件。

```typescript
const fWorkbook = univerAPI.getActiveWorkbook()
const snapshot = fWorkbook.save()
const file = await univerAPI.exportSheetBySnapshotAsync(snapshot)

// 透過 Facade API 下載檔案
if (file) univerAPI.downloadFile(file, 'univer', 'xlsx')
```

## 移除內建匯入匯出選單和 UI 互動

Univer 移除了內建的匯入匯出選單和 UI 互動，底層服務及 Facade API 繼續保留。

如果你的應用程式需要保留原有的匯入匯出選單和 UI 互動，可以參考[內建匯入匯出選單和 UI 互動遷移方案](https://office.univer.ai/showcase/sheets/custom-import-export)，透過自訂外掛完成遷移。範例提供完整原始碼，支援線上檢視和下載。