# 가져오기 및 내보내기

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

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

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.0.4`

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

---

아래 브라우저 API를 사용하기 전에 [가져오기·내보내기 통합](https://docs.univer.ai/ko-KR/server/import-export.md)을 완료하세요. 앱에서 업로드, 변환, 작업 조회 및 권한이 적용된 다운로드 계약을 구현해야 합니다. 스냅샷 API도 변환 백엔드가 필요합니다. [Exchange 예제](https://docs.univer.ai/ko-KR/server/collaboration/examples.md#exchange)는 Sheets를 다루므로 다른 제품과 형식의 지원 범위는 별도로 확인하세요.

#### Package metadata

```json
{
  "preset": [
    {
      "client": "@univerjs/preset-sheets-advanced",
      "locale": "@univerjs/preset-sheets-advanced/locales/en-US",
      "style": "@univerjs/preset-sheets-advanced/lib/index.css"
    }
  ],
  "plugins": [
    {
      "client": "@univerjs-pro/exchange-client",
      "facade": "@univerjs-pro/exchange-client/facade",
      "locale": "@univerjs-pro/exchange-client/locale/en-US",
      "style": "@univerjs-pro/exchange-client/lib/index.css"
    },
    {
      "client": "@univerjs-pro/sheets-exchange-client",
      "facade": "@univerjs-pro/sheets-exchange-client/facade",
      "locale": "@univerjs-pro/sheets-exchange-client/locale/en-US"
    }
  ],
  "license": true,
  "limitations": "CSV/TSV는 서식 없이 워크시트 하나만 내보냅니다. 이 브라우저 API는 XLSM을 허용하지 않습니다.",
  "headless": false,
  "server": true
}
```

## 지원 형식

아래 표는 이 페이지의 브라우저 API가 지원하는 형식입니다. Office 파일 변환에는 해당 문서 유형과 형식을 지원하는 백엔드가 필요합니다.

| 가져오기                            | 내보내기                    |
| ------------------------------- | ----------------------- |
| `.xls`, `.xlsx`, `.csv`, `.tsv` | `.xlsx`, `.csv`, `.tsv` |

## Facade API

### 가져오기

> [!INFO: Plugin mode note]
> 플러그인 모드에서만 Facade 패키지를 직접 가져와야 합니다. 프리셋 모드에는 해당 Facade 패키지가 이미 포함되어 있으므로
> 별도로 가져올 필요가 없습니다.

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

### `.xlsx` 가져오기

#### `.xlsx` 파일을 가져와 `unitId` 얻기

> [!WARNING: Caution]
> 이 방식은 공동 작업 기능이 필요합니다. 서버 문서를 생성하고 `unitId`를 반환합니다. 공동 작업 기능을 사용하지 않는다면
> 스냅샷 가져오기를 사용하세요.

공동 편집이 활성화되면 각 문서에 고유한 `unitId`가 부여됩니다. `file` 매개변수와 함께 `univerAPI.importSheetToUnitIdAsync`를 사용하면 문서에 접근하는 데 사용할 수 있는 `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` 얻기

> [!NOTE]
> 스냅샷 가져오기는 공동 작업 기능이 필요하지 않습니다. 공동 작업 문서에는 `unitId` 가져오기를 사용하세요.

`univerAPI.importSheetToSnapshotAsync`를 사용하여 `.xlsx` 파일을 가져오면 `IWorkbookData` 형식의 문서 데이터가 반환됩니다.

```typescript
// Accept a File object
const snapshot = await univerAPI.importSheetToSnapshotAsync(file)
// Or accept a remote file URL
// const snapshot = await univerAPI.importSheetToSnapshotAsync('https://example.com/filename.xlsx');

// Create a new workbook via snapshot
if (snapshot) univerAPI.createWorkbook(snapshot)
```

### `.xlsx` 내보내기

#### `unitId`를 사용하여 `.xlsx` 파일 내보내기

> [!WARNING: Caution]
> `unitId` 내보내기는 공동 작업 기능이 필요합니다. 공동 작업 기능을 사용하지 않는다면 스냅샷 내보내기를 사용하세요.

공동 편집이 활성화되면 각 문서에 고유한 `unitId`가 부여됩니다. `unitId` 매개변수와 함께 `univerAPI.exportSheetByUnitIdAsync`를 사용하면 `File` 객체가 반환됩니다.

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

// Download the file through the Facade API
if (file) univerAPI.downloadFile(file, 'univer', 'xlsx')
```

#### `IWorkbookData`를 사용하여 `.xlsx` 파일 내보내기

> [!NOTE]
> 스냅샷 내보내기는 공동 작업 기능이 필요하지 않으며 로컬 워크플로에 적합합니다.

`IWorkbookData`와 함께 `univerAPI.exportSheetBySnapshotAsync`를 사용하면 `File` 객체가 반환됩니다.

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

// Download the file through the Facade API
if (file) univerAPI.downloadFile(file, 'univer', 'xlsx')
```