# 파일 가져오기와 내보내기

> Office 파일을 제품별 스냅샷으로 변환하고 편집한 스냅샷을 파일로 내보냅니다.

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

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

- Requested language: `ko-KR`

- Content language: `ko-KR`

- Documentation version: `1.3.0`

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

---

파일 변환은 외부 형식과 Univer 콘텐츠 모델을 연결합니다. 가져올 때 파일을 해당 제품의 Snapshot으로 파싱하고, 내보낼 때 스냅샷을 선택한 출력 형식으로 직렬화합니다.

## 파일에서 스냅샷으로

`.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/ko-KR/overview/features/shared/server-calculation.md)을 참고하세요.

### Snapshot 데이터 구조

각 제품은 콘텐츠와 리소스 참조를 저장하는 Snapshot 인터페이스를 제공하며 보통 JSON으로 저장합니다. 인터페이스 이름을 클릭하면 필드 정의, 타입, 예제를 볼 수 있습니다.

| 제품 | Snapshot 인터페이스 | 주요 내용 |
| --- | --- | --- |
| 스프레드시트 (Sheet) | [`IWorkbookData`](https://docs.univer.ai/ko-KR/guides/sheets/model/workbook-data.md#iworkbookdata) | 워크시트, 셀, 공유 스타일, 플러그인 리소스. |
| 문서 (Doc) | [`IDocumentData`](https://docs.univer.ai/ko-KR/guides/docs/model/document-data.md#idocumentdata) | 본문, 문단, 스타일, 머리글, 바닥글, 리소스. |
| 슬라이드 (Slide) | [`ISlideData`](https://docs.univer.ai/ko-KR/guides/slides/model/slide-data.md#islidedata) | 슬라이드, 요소, 마스터, 테마, 리소스. |
| 관계형 테이블 (Relational Table) | [`IBaseSnapshot`](https://docs.univer.ai/ko-KR/guides/bases/model/base-snapshot.md#ibasesnapshot) | 테이블, 필드, 레코드, 뷰와 각 항목의 순서. |
| 캔버스 (Canvases) | [`IBoardData`](https://docs.univer.ai/ko-KR/guides/boards/model/board-data.md#iboarddata) | 페이지, 요소, 테마, 리소스. |
| PDF | [`IPdfUnitData`](https://docs.univer.ai/ko-KR/guides/pdfs/model/pdf-data.md#ipdfunitdata) | 원본 문서, 저장된 편집 상태, 리소스 바인딩. |

제품 Facade의 `save()`로 현재 스냅샷을 얻고 해당 생성 API로 복원합니다. 실행 중인 콘텐츠는 Facade API로 수정합니다. PDF는 `pdf.save()`를 사용하면 원본 기준 문서와 `editState`를 함께 보존합니다.

## 제품별 지원 형식

아래 Office 및 표 데이터 형식은 현재 Rust Exchange의 직접 변환 경로를 기준으로 합니다. PDF는 별도 변환 모듈을 사용합니다.

| 제품 | 가져오기 / 컴파일 | 내보내기 | 범위 |
| --- | --- | --- | --- |
| [스프레드시트 (Sheet)](https://docs.univer.ai/ko-KR/guides/sheets/features/import-export.md) | `.xls`, `.xlsx`, `.csv`, `.tsv` | `.xlsx`, `.csv`, `.tsv` | CSV/TSV는 워크시트 하나를 처리합니다. |
| [문서 (Doc)](https://docs.univer.ai/ko-KR/guides/docs/features/import-export.md) | `.doc`, `.docx` | `.docx` | 기존 DOC를 문서 모델로 가져오며 출력은 DOCX입니다. |
| [슬라이드 (Slide)](https://docs.univer.ai/ko-KR/guides/slides/features/import-export.md) | `.ppt`, `.pptx` | `.pptx` | 기존 PPT를 슬라이드 모델로 가져오며 출력은 PPTX입니다. |
| [관계형 테이블 (Relational Table)](https://docs.univer.ai/ko-KR/guides/bases/features/import-export.md) | `.xls`, `.xlsx`, `.csv`, `.tsv` | `.xlsx`, `.csv`, `.tsv` | CSV/TSV는 테이블 하나를 처리하며 XLSX는 테이블과 필드 매핑을 지원합니다. |
| [캔버스 (Canvases)](https://docs.univer.ai/ko-KR/guides/boards/features/import-export.md) | Mermaid (`.mmd` / 소스 텍스트) | `.pptx` | Mermaid는 가져오기 초안을 생성합니다. Canvases Facade로 적용한 후 스냅샷을 저장하며 PPTX는 현재 페이지를 내보냅니다. |
| [PDF](https://docs.univer.ai/ko-KR/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/ko-KR/overview/features/shared/server-calculation.md)을 참고하세요.

## 연동 방법

파일 변환은 Server SDK 기능이며 업로드, 작업 처리, 저장소, 다운로드는 앱이 제공합니다. 스냅샷 변환은 협업 없이 실행할 수 있습니다. 공유 문서를 내보낼 때는 변경 사항 동기화 후 확정된 리비전을 읽습니다.

[파일 변환 연동](https://docs.univer.ai/ko-KR/server/import-export.md)과 [Node.js 파일 변환](https://docs.univer.ai/ko-KR/server/import-export/node.md)에서 시작하세요.

형식 지원과 개별 기능의 왕복 보존은 별도로 확인합니다. 제품 기능 목록과 실제 업무 파일로 수식, 이미지, 스타일, 레이아웃을 검증하세요.

[전체 기능으로 돌아가기](https://docs.univer.ai/ko-KR/overview/features.md)