# SpreadJS 파일 형식

## Content

SpreadJS는 사용자가 대용량 파일을 빠르게 열고 저장할 수 있도록 하며, Excel, CSV, SSJSON(이전 SpreadJS 형식), SJS(새롭고 더 빠른 SpreadJS 형식) 등 다양한 파일 형식으로 내보내기 또는 가져오기를 지원합니다. 특히, 새로운 SJS 형식은 매우 큰 Excel 파일을 다룰 때 로딩 속도와 메모리 사용량을 크게 개선하며, 이전 SpreadJS 버전에 비해 파일을 다시 저장할 경우 파일 크기를 현저히 줄여줍니다.
다양한 형식으로 파일을 열고 저장하고, 가져오고 내보내는 작업을 수행하기 위해 SpreadJS는 `gc.spread.sheets.io.xxx.js` 플러그인을 제공합니다.

>type=note
> **참고:**
> v16.0.0부터 `gc.spread.sheets.excelIo.xxx.js` 모듈은 더 이상 사용되지 않으며, 향상된 `gc.spread.sheets.io.xxx.js` 플러그인으로 대체되었습니다.

[GC.Spread.Sheets.Workbook](/spreadjs/api/v19/classes/GC.Spread.Sheets.Workbook) 클래스는 다음과 같은 파일 작업 메서드를 제공합니다:

| 메서드 | 설명 |
| --- | --- |
| [open](/spreadjs/api/v19/classes/GC.Spread.Sheets.Workbook#open) | SpreadJS 파일을 로드합니다. |
| [save](/spreadjs/api/v19/classes/GC.Spread.Sheets.Workbook#save) | SpreadJS 파일을 저장합니다. |
| [export](/spreadjs/api/v19/classes/GC.Spread.Sheets.Workbook#export) | Excel (XLSX, XLTX, XLSM, XLTM), SSJSON, SJS 또는 CSV 형식으로 파일을 내보냅니다. |
| [import](/spreadjs/api/v19/classes/GC.Spread.Sheets.Workbook#import) | Excel (XLSX, XLTX, XLSM, XLTM), SSJSON, SJS, CSV 또는 JavaScript 형식의 파일을 가져옵니다. |

>type=note
> **참고:**
>
> * 매크로는 악성코드를 포함할 수 있으므로, Excel은 인터넷에서 가져온 매크로 사용 가능 파일을 신뢰할 수 없는 파일로 표시합니다. SpreadJS에서 내보낸 매크로 포함 워크북을 Excel에서 열 때는 **먼저 매크로를 활성화**해야 하며, 그렇지 않으면 매크로가 작동하지 않습니다. 자세한 내용은 [인터넷 매크로 기본 차단 | Microsoft Learn](https://learn.microsoft.com/en-us/microsoft-365-apps/security/internet-macros-blocked) 참조.
> * 파일을 .xlsx 또는 SpreadJS 내부 형식(.sjs, .ssjson)으로 내보내거나 저장할 경우, 매크로는 **보존되지 않습니다**.
> * SpreadJS 내에서는 매크로를 조회, 편집, 실행할 수 없으며, 모든 변경은 워크북 데이터에만 적용되고 매크로 코드에는 영향을 주지 않습니다.
> * SpreadJS에서 워크시트 레이아웃을 변경하면 특정 셀 주소를 참조하는 매크로 로직에 영향을 줄 수 있습니다.

다음 섹션에서는 다양한 파일 작업을 자세히 살펴보겠습니다.

## 파일 열기

`open` 메서드를 사용하여 SpreadJS 파일을 로드할 수 있습니다. 이 메서드는 다음과 같은 파라미터를 사용합니다:

* **file blob**: 압축된 스프레드시트 데이터 파일을 나타냅니다.
* **successCallBack**: 파일 로딩이 완료되었을 때 호출되는 콜백 함수이며, 인자로 JSON 데이터를 받습니다.
* **errorCallBack**: 파일 로딩 중 오류가 발생했을 때 호출되는 콜백 함수입니다.
* **openOptions**: `GC.Spread.Sheets.OpenOptions` 타입에서 상속된 옵션 객체입니다.

아래는 파일 열기(open) 시 사용할 수 있는 다양한 옵션입니다.

| 옵션 | 설명 |
| --- | --- |
| includeStyles | 로드 시 스타일을 포함할지 여부를 나타냅니다. 기본값은 true입니다. |
| includeFormulas | 로드 시 수식을 포함할지 여부를 나타냅니다. 기본값은 true입니다. |
| fullRecalc | JSON 데이터를 로드한 후 계산을 수행할지 여부를 나타냅니다. 기본값은 true입니다. |
| dynamicReferences | 동적 참조를 사용하여 함수가 계산될 수 있는지 여부를 나타냅니다. 기본값은 true입니다. |
| calcOnDemand | 수식이 필요할 때만 계산될 수 있는지 여부를 나타냅니다. 기본값은 true입니다. |
| includeUnusedStyles | Excel XML 파일을 JSON으로 변환할 때 이름 스타일을 포함할지 여부를 나타냅니다. 기본값은 true입니다. |
| openMode | [GC.Spread.Sheets.OpenMode](/spreadjs/api/v19/enums/GC.Spread.Sheets.OpenMode) 열거형에서 상속됩니다.<br>열기 모드가 일반(normal), 지연(lazy), 점진적(incremental) 중 어떤 것인지 지정합니다. 기본값은 normal입니다. |
| progress | GC.Spread.Sheets.ProgressFunctionType 타입 정의에서 상속되며, 각 열기 모드에서 호출되는 진행 상황 콜백 함수입니다. |

다음 코드 구현은 파일 열기 작업을 수행하는 방법을 보여줍니다:

```JavaScript
//open 메서드 사용 예제.
//file blob 가져오기 
var file = document.getElementById("fileInput").files[0];
// 가져오기
spread.open(file, function () {
    // 성공 콜백
}, function (e) {
    console.log(e); // error 콜백
}, {
    openMode: GC.Spread.Sheets.OpenMode.lazy,
    includeFormulas: false,
    includeStyles: false
});
```

## 파일 저장

SpreadJS 파일은 `save` 메서드를 사용하여 저장할 수 있으며, 이 메서드는 다음과 같은 매개변수를 제공합니다:

* **successCallBack**: SpreadJS 파일이 완전히 저장되었을 때 호출되는 성공 콜백 함수이며, `Blob`을 인자로 받습니다.
* **errorCallBack**: SpreadJS 파일 저장 중 오류가 발생했을 때 호출되는 오류 콜백 함수입니다.
* **saveOptions**: `GC.Spread.Sheets.SaveOptions` 타입 정의에서 상속되며, 저장 옵션을 제공합니다.

다음은 다양한 저장 옵션입니다:

| 저장 옵션 | 설명 |
| ----- | --- |
| **includeBindingSource** | 파일 저장 시 바인딩 소스를 포함할지 여부를 나타냅니다. 기본값은 `false`입니다. |
| **includeStyles** | 파일 저장 시 스타일을 포함할지 여부를 나타냅니다. 기본값은 `true`입니다. |
| **includeFormulas** | 파일 저장 시 수식을 포함할지 여부를 나타냅니다. 기본값은 `true`입니다. |
| **saveAsView** | 저장된 파일이 현재 스프레드의 서식 문자열을 무시할지 여부를 나타냅니다. 기본값은 `false`입니다. |
| **includeAutoMergedCells** | 파일 저장 시 자동 병합된 셀을 포함할지 여부를 나타냅니다. 기본값은 `false`입니다. |
| **includeCalcModelCache** | 파일 저장 시 계산 관련 추가 데이터를 포함할지 여부를 나타냅니다. 기본값은 `true`입니다. |
| **includeUnusedNames** | 파일 저장 시 사용되지 않는 사용자 정의 이름을 포함할지 여부를 나타냅니다. 기본값은 `true`입니다. |
| **includeEmptyRegionCells** | 사용된 데이터 범위 외의 빈 셀을 포함할지 여부를 나타냅니다. 기본값은 `true`입니다. |
| **saveR1C1Formula** | 파일에 r1c1 수식을 저장할지 여부를 나타냅니다. 기본값은 `false`입니다. |

다음 코드 구현은 파일 저장 작업을 수행하는 방법을 보여줍니다:

```JavaScript
var fileName = "fileNamehere.sjs";
spread.save(function (blob) {
    // blob을 파일로 저장
    saveAs(blob, fileName);
}, function (e) {
    console.log(e);
}, {
    includeUnusedNames: false,
    includeEmptyRegionCells: false
    saveR1C1Formula: true
});
```

## **파일 내보내기**

Spread에서는 파일을 Excel(XLSX, XLSM, XLTM), SSJSON, SJS 또는 CSV 형식으로 내보낼 수 있습니다.
**export** 메서드는 다음과 같은 매개변수를 제공합니다:

* <strong>successCallBack</strong>: 파일 내보내기가 완료되면 성공 콜백을 제공하며, 인수로 Blob을 받습니다.
* <strong>errorCallBack</strong>: 파일 내보내기 시 오류가 발생하면 오류 콜백을 제공합니다.
* <strong>saveOptions</strong>: **GC.Spread.Sheets.ExportOptions** Typedef에서 상속되며, 내보내기 옵션을 제공합니다.

다양한 내보내기 옵션은 아래와 같습니다:

| 옵션 | 설명 |
| --- | --- |
| FileOptions | GC.Spread.Sheets.FileType Typedef에서 상속되며, FileOptions는 다양한 파일 형식을 제공합니다. |
| ExportCsvOptions | GC.Spread.Sheets.ExportCsvOptions에서 상속되며, ExportCsvOptions는 파일을 CSV 형식으로 내보내기 위한 옵션을 제공합니다. |
| ExportSSJsonOptions | GC.Spread.Sheets.ExportSSJsonOptions에서 상속되며, ExportSSJsonOptions는 파일을 SSJSON 형식으로 내보내기 위한 옵션을 제공합니다. |
| ExportXlsxOptions | GC.Spread.Sheets.ExportXlsxOptions에서 상속되며, ExportXlsxOptions는 파일을 Excel 형식(XLSX, XLSM, XLTM)으로 내보내기 위한 옵션을 제공합니다. |

>type=note
> **참고:**
>
> * `'ExportXlsxOptions'`의 `'Xlsx'`는 **Excel**(특히 XLSX 형식)을 의미하며, Excel 파일로 내보내기 위한 옵션을 정의합니다. 지원되는 형식 중 하나—**XLSX, XLSM, XLTM**—을 `excelFileType` 속성(`GC.Spread.Sheets.ExcelFileType`에서 상속)으로 선택할 수 있습니다. 기본값은 **XLSX**입니다.
> * `ExportXlsxOptions`의 `losslessEditing` 속성은 Excel 형식으로 내보낼 때 손실 없는 콘텐츠(XML 맵 및 매크로가 포함된 VBA 프로젝트)를 유지할지 여부를 제어합니다.
>     기본값 `true`로 설정하면 매크로와 XML 맵을 그대로 유지합니다.
> * SpreadJS로 가져온 XML 콘텐츠(XML 맵 등)는 호환성 제한으로 인해 SJS/SSJSON과 같은 SpreadJS 고유 형식으로 내보낼 수 없습니다.

코드 구현 예시는 XLSM 파일로 내보내는 방법을 보여줍니다:

```JavaScript
var fileName = "fileNamehere.xlsm";           
spread.export(function (blob) {
    // blob을 파일로 저장
    saveAs(blob, fileName);
}, function (e) {
    console.log(e);
}, {
    fileType: GC.Spread.Sheets.FileType.excel,
    excelFileType: 'XLSM'
});
```

## **파일 가져오기**

Spread에서는 Excel(XLSX, XLSM, XLTM), SSJSON, SJS 또는 CSV 형식의 파일을 가져올 수도 있습니다.

>type=note
> SpreadJS 워크북에 파일을 가져올 때, 이미 손실 없는 콘텐츠(XML 맵 및 VBA 프로젝트)가 존재하는 경우:
>
> * **워크북 수준 초기화**: SJS, SSJSON 또는 Excel을 가져오는 경우, 워크북 범위의 모든 손실 없는 콘텐츠는 삭제되고 가져온 파일의 기본 구조로 대체됩니다.
> * **시트 수준 초기화**: CSV를 가져오는 경우, 활성 시트의 컨텍스트만 초기화되며, 해당 시트의 손실 없는 데이터는 삭제되지만 다른 시트의 손실 없는 콘텐츠는 유지됩니다.

가져오기 메서드는 다음과 같은 인수를 제공합니다:

* <strong>file</strong>: 가져올 SSJSON, SJS, CSV 또는 Excel 파일(XLSX, XLSM, XLTM).
* <strong>successCallBack</strong>: 파일 가져오기가 완료되었을 때 성공 콜백을 제공합니다.
* <strong>errorCallBack</strong>: 파일 가져오기에 실패했을 때 오류 콜백을 제공합니다.
* <strong>importOptions</strong>: **GC.Spread.Sheets.ImportOptions** Typedef에서 상속되며, 가져오기 옵션을 제공합니다.

다양한 가져오기 옵션은 아래와 같습니다:

| Options | Description |
| ------- | ----------- |
| FileOptions | GC.Spread.Sheets.FileType Typedef에서 상속되며, 다양한 파일 형식을 제공합니다. |
| ImportCsvOptions | GC.Spread.Sheets.ImportCsvOptions에서 상속되며, CSV 형식 파일을 가져오기 위한 옵션을 제공합니다. |
| ImportSSJsonOptions | GC.Spread.Sheets.ImportSSJsonOptions에서 상속되며, SSJSON 형식 파일을 가져오기 위한 옵션을 제공합니다. |
| ImportXlsxOptions | GC.Spread.Sheets.ImportXlsxOptions에서 상속되며, Excel 형식(XLSX, XLSM, XLTM) 파일을 가져오기 위한 옵션을 제공합니다. |

>type=note
> **참고:**
> `'ImportXlsxOptions'`의 `'Xlsx'`는 **Excel**(특히 XLSX 형식)을 의미합니다. 이는 Excel 파일의 가져오기 옵션을 정의합니다.
> `excelFileType` 속성( **GC.Spread.Sheets.ExcelFileType**에서 상속됨)을 통해 **XLSX, XLSM 또는 XLTM** 중 하나를 선택할 수 있습니다. 기본값은 **XLSX**입니다.

아래 코드 구현 예시는 XLSM 파일에서 가져오는 방법을 보여줍니다:

```JavaScript
// 파일 blob 가져오기
var file = document.getElementById("fileInput").files[0];
// import
spread.import(file, function () {
    // 성공 콜백에서 작업 수행
}, function (e) {
    console.log(e); // 오류 콜백
}, {
    fileType: GC.Spread.Sheets.FileType.excel,
    excelFileType: 'XLSM'
});
```