[]
        
(Showing Draft Content)

SpreadJS 파일 형식

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

다양한 형식으로 파일을 열고 저장하고, 가져오고 내보내는 작업을 수행하기 위해 SpreadJS는 gc.spread.sheets.io.xxx.js 플러그인을 제공합니다.

참고:

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

GC.Spread.Sheets.Workbook 클래스는 다음과 같은 파일 작업 메서드를 제공합니다:

메서드

설명

open

SpreadJS 파일을 로드합니다.

save

SpreadJS 파일을 저장합니다.

export

Excel, SSJSON, SJS 또는 CSV 형식으로 파일을 내보냅니다.

import

Excel, SSJSON, SJS, CSV 또는 JavaScript 형식의 파일을 가져옵니다.

참고:

  • 매크로는 악성코드를 포함할 수 있으므로, Excel은 인터넷에서 가져온 매크로 사용 가능 파일을 신뢰할 수 없는 파일로 표시합니다. SpreadJS에서 내보낸 매크로 포함 워크북을 Excel에서 열 때는 먼저 매크로를 활성화해야 하며, 그렇지 않으면 매크로가 작동하지 않습니다. 자세한 내용은 인터넷 매크로 기본 차단 | Microsoft Learn 참조.

  • 파일을 .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 열거형에서 상속됩니다.

열기 모드가 일반(normal), 지연(lazy), 점진적(incremental) 중 어떤 것인지 지정합니다. 기본값은 normal입니다.

progress

GC.Spread.Sheets.ProgressFunctionType 타입 정의에서 상속되며, 각 열기 모드에서 호출되는 진행 상황 콜백 함수입니다.

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

Ask ChatGPT

//open 메서드 사용 예제.
//file blob 가져오기 
var file = document.getElementById("fileInput").files[0];
// 가져오기
spread.open(file, function () {
    // 성공 콜백
}, function (e) {
    console.log(e); // error 콜백
}, {
    lazyLoad: true,
    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입니다.

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

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 메서드는 다음과 같은 매개변수를 제공합니다:

  • successCallBack: 파일 내보내기가 완료되면 성공 콜백을 제공하며, 인수로 Blob을 받습니다.

  • errorCallBack: 파일 내보내기 시 오류가 발생하면 오류 콜백을 제공합니다.

  • saveOptions: 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)으로 내보내기 위한 옵션을 제공합니다.

참고:

  • 'ExportXlsxOptions''Xlsx'Excel(특히 XLSX 형식)을 의미하며, Excel 파일로 내보내기 위한 옵션을 정의합니다. 지원되는 형식 중 하나—XLSX, XLSM, XLTM—을 excelFileType 속성(GC.Spread.Sheets.ExcelFileType에서 상속)으로 선택할 수 있습니다. 기본값은 XLSX입니다.

  • ExportXlsxOptionslosslessEditing 속성은 Excel 형식으로 내보낼 때 손실 없는 콘텐츠(XML 맵 및 매크로가 포함된 VBA 프로젝트)를 유지할지 여부를 제어합니다.

    기본값 true로 설정하면 매크로와 XML 맵을 그대로 유지합니다.

  • SpreadJS로 가져온 XML 콘텐츠(XML 맵 등)는 호환성 제한으로 인해 SJS/SSJSON과 같은 SpreadJS 고유 형식으로 내보낼 수 없습니다.

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

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 형식의 파일을 가져올 수도 있습니다.

SpreadJS 워크북에 파일을 가져올 때, 이미 손실 없는 콘텐츠(XML 맵 및 VBA 프로젝트)가 존재하는 경우:

  • 워크북 수준 초기화: SJS, SSJSON 또는 Excel을 가져오는 경우, 워크북 범위의 모든 손실 없는 콘텐츠는 삭제되고 가져온 파일의 기본 구조로 대체됩니다.

  • 시트 수준 초기화: CSV를 가져오는 경우, 활성 시트의 컨텍스트만 초기화되며, 해당 시트의 손실 없는 데이터는 삭제되지만 다른 시트의 손실 없는 콘텐츠는 유지됩니다.

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

  • file: 가져올 SSJSON, SJS, CSV 또는 Excel 파일(XLSX, XLSM, XLTM).

  • successCallBack: 파일 가져오기가 완료되었을 때 성공 콜백을 제공합니다.

  • errorCallBack: 파일 가져오기에 실패했을 때 오류 콜백을 제공합니다.

  • importOptions: 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) 파일을 가져오기 위한 옵션을 제공합니다.

참고:

'ImportXlsxOptions''Xlsx'Excel(특히 XLSX 형식)을 의미합니다. 이는 Excel 파일의 가져오기 옵션을 정의합니다.

excelFileType 속성( GC.Spread.Sheets.ExcelFileType에서 상속됨)을 통해 XLSX, XLSM 또는 XLTM 중 하나를 선택할 수 있습니다. 기본값은 XLSX입니다.

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

// 파일 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'
});