# 导入导出

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

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

- Requested language: `zh-CN`

- Content language: `zh-CN`

- Documentation version: `1.0.0-rc.0`

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

---

下方 API 需要配套的转换后端。请先按[导入导出集成](https://docs.univer.ai/zh-CN/server/import-export.md)接好文件上传、转换、任务查询和下载，再配置前端插件。快照 API 也需要转换后端，但不要求创建协同文档。官方协同 Exchange 示例演示 Sheets，接入前请确认目标版本支持所需的文件类型。

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-docs-advanced",
      "locale": "@univerjs/preset-docs-advanced/locales/zh-CN",
      "style": "@univerjs/preset-docs-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/exchange-client",
      "locale": "@univerjs-pro/exchange-client/locale/zh-CN",
      "style": "@univerjs-pro/exchange-client/lib/index.css",
      "facade": "@univerjs-pro/exchange-client/facade"
    },
    {
      "client": "@univerjs-pro/docs-exchange-client",
      "facade": "@univerjs-pro/docs-exchange-client/facade",
      "locale": "@univerjs-pro/docs-exchange-client/locale/zh-CN"
    }
  ],
  "license": true,
  "server": true
}
```

## 支持的格式

下表列出本页前端 API 支持的格式。Office 文件转换还需要后端支持对应的文档类型和格式。

| 导入              | 导出      |
| --------------- | ------- |
| `.doc`, `.docx` | `.docx` |

`.doc` 和 `.docx` 都使用下方的导入 API。导出统一生成 `.docx`，不支持导出旧版 `.doc`。

## Facade API

### 导入

> [!INFO: 插件模式提示]
> 仅插件模式需要手动引入 Facade 包。预设模式已内置对应的 Facade 包，无需额外导入。

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

### 导入 `.docx`

#### 导入 `.docx` 文件并获取 `unitId`

> [!WARNING: 注意事项]
> 该方法依赖协同服务：导入后会在服务端创建文档并返回 `unitId`。如果未启用协同，请使用快照导入。

在启用协同编辑的时候，每个文档都有一个唯一的 `unitId`。使用 `univerAPI.importDocToUnitIdAsync` 传入 `file` 参数会返回 `unitId`，可以通过 `unitId` 来访问文档。 `file` 参数可以是一个 `File` 对象，也可以是远程文件的 URL。

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

const unitId = await univerAPI.importDocToUnitIdAsync(file)

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

#### 导入 `.docx` 文件并获取 `IDocumentData`

使用 `univerAPI.importDocToSnapshotAsync` 导入 `.docx` 文件，会返回 `IDocumentData` 格式的文档数据。

```typescript
// 接受 File 对象
const snapshot = await univerAPI.importDocToSnapshotAsync(file)
// 或者接受远程文件的 URL
// const snapshot = await univerAPI.importDocToSnapshotAsync('https://example.com/filename.docx');

// 通过快照创建一个新的文档
if (snapshot) univerAPI.createDocument(snapshot)
```

### 导出 `.docx`

#### 通过 `unitId` 导出 `.docx` 文件

> [!WARNING: 注意事项]
> `unitId` 导出依赖协同服务。如果未启用协同，请使用快照导出。

在启用协同编辑的时候，每个文档都有一个唯一的 `unitId`。使用 `univerAPI.exportDocByUnitIdAsync` 传入 `unitId` 参数会返回 `File` 对象。

```typescript
const fDocument = univerAPI.getActiveDocument()
const unitId = fDocument.getId()
const file = await univerAPI.exportDocByUnitIdAsync(unitId)

// 通过 Facade API 下载文件
if (file) univerAPI.downloadFile(file, 'univer', 'docx')
```

#### 通过 `IDocumentData` 导出 `.docx` 文件

> [!NOTE]
> 快照导出不依赖协同服务，适合仅在本地处理数据的场景。

使用 `univerAPI.exportDocBySnapshotAsync` 传入 `IDocumentData` 会返回 `File` 对象。

```typescript
const fDocument = univerAPI.getActiveDocument()
const snapshot = fDocument.save()
const file = await univerAPI.exportDocBySnapshotAsync(snapshot)

// 通过 Facade API 下载文件
if (file) univerAPI.downloadFile(file, 'univer', 'docx')
```