ファイル操作

SpreadJSでは、Excel（XLSX/XLSM/XLTM）、CSV、SSJSON（SpreadJS旧形式）、SJS（SpreadJS新形式）など、多様なファイル形式の入出力をサポートしています。特に新形式のSJSでは、大規模Excelファイルの読み込み速度とメモリ使用量が大幅に改善され、再保存時のファイルサイズも従来比で削減されます。

これらのファイル操作（開く/保存/インポート/エクスポート）を実現するため、SpreadJSは専用プラグインgc.spread.sheets.io.xxx.jsを提供します。

注記:
SpreadJS v16以降、gc.spread.sheets.excelIo.xxx.js モジュールは非推奨となり、拡張された gc.spread.sheets.io.xxx.js プラグインに置き換えられました。

GC.Spread.Sheets.Workbookクラスは、ファイル操作のために次のメソッドを提供します。

メソッド	説明
open	SpreadJSファイル（SJS形式）を読み込みます。
save	SpreadJSファイル（SJS形式）を保存します。
export	Excel （XLSX/XLSM/XLTM）、SSJSON、またはCSV形式でファイルをエクスポートします。
import	Excel（XLSX/XLSM/XLTM）、SSJSON、CSV、またはJavaScript形式のファイルをインポートします。

注記：
マクロはマルウェアを拡散するリスクがあるため、Excel ではインターネット経由で取得したマクロ有効ファイルを不審なファイルとしてマークします。SpreadJS からエクスポートしたマクロブックを Excel で開く際は、最初にマクロを有効化してください。有効化しない場合、マクロは機能しません。詳細は「インターネットからのマクロは、Officeで既定でブロックされます | Microsoft Learn」を参照してください。
.xlsx または SpreadJS 独自形式（.sjs、.ssjson）でエクスポート／保存した場合、マクロは保持されません。
SpreadJS 内では、マクロの閲覧・編集・実行はできません。すべての変更はワークブックのデータにのみ適用され、マクロコードには反映されません。
SpreadJS でワークシートのレイアウトを変更すると、特定のセルアドレスを参照するマクロの処理ロジックに影響を与える可能性があります。

次のセクションでは、さまざまなファイル操作について詳しく説明します。

ファイルを開く

SpreadJSファイル（SJS形式）を読み込むには、openメソッドを使用します。このメソッドは、次のパラメータを提供します。

blob：圧縮されたスプレッドシートのデータファイルを表します。
successCallBack：この関数は、ファイルの読み込みが成功した後に呼び出されます。JSONを引数として受け取ります。
errorCallBack：この関数は、ファイルの読み込みでエラーが発生した場合に呼び出されます。
openOptions：GC.Spread.Sheets.OpenOptions から継承されます。このパラメータは、ファイルを開くオプションを提供します。

openメソッドで指定できるオプションは、次の通りです。

オプション	説明
includeStyles	読み込み時にスタイルを含めるかどうかを示します。デフォルト値は、trueです。
includeFormulas	読み込み時に数式を含めるかどうかを示します。デフォルト値は、trueです。
fullRecalc	データのロード後に再計算を行うかどうかを示します。デフォルト値は、falseです。
dynamicReferences	動的参照を使用して関数を計算できるかどうかを示します。デフォルト値は、trueです。
calcOnDemand	必要な場合にのみ数式を計算できるかどうかを示します。デフォルト値は、falseです。
includeUnusedStyles	未使用の名前付きスタイルを含めるかどうかを示します。デフォルト値は、trueです。
openMode	GC.Spread.Sheets.OpenMode列挙体から継承されます。openModeは、標準、遅延、増分のいずれかを指定します。デフォルトでは、標準です。
progress	GC.Spread.Sheets.ProgressFunctionType から継承されます。各OpenModeの進行状況のコールバック関数です。

次のサンプルコードは、ファイルを開く方法を示します。

//この例では openメソッドを使用しています。
// ファイルblobを取得します。
var file = document.getElementById("fileInput").files[0];
// インポート。
spread.open(file, function () {
    // 成功時のコールバック。
}, function (e) {
    console.log(e); // エラーが発生した時のコールバック。
}, {
    openMode: GC.Spread.Sheets.OpenMode.lazy,
    includeFormulas: false,
    includeStyles: false
});

ファイルを保存する

SpreadJSファイル（SJS形式）を保存するには、saveメソッドを使用します。このメソッドは、次のパラメータを提供します。

successCallBack：この関数は、SpreadJSファイルの保存が成功した後に呼び出されます。Blobを引数として受け取ります。
errorCallBack：この関数は、ファイルの保存でエラーが発生した場合に呼び出されます。
saveOptions：GC.Spread.Sheets.SaveOptions から継承されます。このパラメータは、保存オプションを提供します。

saveメソッドで指定できる、さまざまな保存オプションは次の通りです。

オプション	説明
includeBindingSource	ファイルを保存する時にデータソースを含めるかどうかを示します。デフォルト値はfalseです。
includeStyles	ファイルを保存する時にスタイルを含めるかどうかを示します。デフォルト値は、trueです。
includeFormulas	ファイルを保存する時に数式を含めるかどうかを示します。デフォルト値は、trueです。
saveAsView	ファイルを保存する時に、表示形式の書式を適用するかどうかを示します。デフォルト値は、falseです。
includeAutoMergedCells	ファイルを保存する時に自動的に結合されたセルを含めるかどうかを示します。デフォルト値はfalseです。
includeCalcModelCache	ファイルを保存する時に計算の余分なデータを含めるかどうかを示します。デフォルト値は、falseです。
includeUnusedNames	ファイルを保存する時に未使用のカスタム名を含めるかどうかを示します。デフォルト値は、trueです。
includeEmptyRegionCells	使用されるデータ範囲外に空のセルを含めるかどうかを示します。デフォルト値は、trueです。
saveR1C1Formula	r1c1 数式をファイルに保存するかどうかを示します。SJS ファイルでのみ動作します。デフォルト値は、false です。

次のサンプルコードは、ファイルを保存する方法を示します。

var fileName = "fileNamehere.sjs";
spread.save(function (blob) {
    // blobをファイルに保存します。
    saveAs(blob, fileName);
}, function (e) {
    console.log(e);
}, {
    includeUnusedNames: false,
    includeEmptyRegionCells: false
});

ファイルをエクスポートする

ファイルをExcel（XLSX/XLSM/XLTM）、SSJSON、またはCSV形式でエクスポートできます。exportメソッドは、次のパラメータを提供します。

successCallBack：この関数は、ファイルのエクスポートが成功した後に呼び出されます。Blobを引数として受け取ります。
errorCallBack：この関数は、ファイルのエクスポートでエラーが発生した場合に呼び出されます。
saveOptions：GC.Spread.Sheets.ExportOptions から継承されます。このパラメータは、エクスポートオプションを提供します。

さまざまなエクスポートオプションは、次の通りです。

オプション	説明
FileOptions	GC.Spread.Sheets.FileTypeから継承されます。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）でエクスポートするオプションを提供します。
losslessEditing	`GC.Spread.Sheets.ExportXlsxOptions` から継承される losslessEditing プロパティは、Excel 形式でエクスポートする際にロスレス要素（XML マップやマクロを含む VBA プロジェクト）を保持するかどうかを制御します。 `true` に設定すると、マクロや XML マップを保持します。（デフォルト）

注記：
「ExportXlsxOptions」の「Xlsx」は、Microsoft Excel（具体的には XLSX 形式）を指します。これは、Excel ファイルのエクスポートに関する設定項目を定義します。
excelFileType プロパティ（GC.Spread.Sheets.ExcelFileType クラスから継承）を使用して、以下の対応形式を指定できます：
XLSX（標準形式）
XLSM（マクロ有効ブック）
XLTM（マクロ有効テンプレート）
デフォルトでは、XLSX 形式が設定されています。
SpreadJS にインポートされた XML マップのような XML コンテンツは、互換性の制約により、SpreadJS独自形式（sjs、ssjson）にはエクスポートできません。

以下のコードは、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、またはCSV形式のファイルをインポートできます。importメソッドは、次のパラメータを提供します。

SpreadJS に新たにファイルをインポートする際、既に別のExcelファイルからインポートした lossless コンテンツ（XML マップや VBA プロジェクト）がSpreadJS内部に保存されている場合:
ワークブックレベルのリセット: SJS、SSJSON、または Excel をインポートする場合、ワークブックスコープの lossless コンテンツはすべて破棄され、インポートされたファイルのネイティブ構造に置き換えられます。
ワークシートレベルのリセット: CSV をインポートする場合、アクティブシートのコンテキストのみがリセットされ、シート固有の lossless データが消去されますが、他のシートの lossless コンテンツは保持されます。

file：インポートするSSJSON、CSVまたはExcel（XLSX/XLSM/XLTM）ファイル。
successCallBack：この関数は、ファイルのインポートが成功した後に呼び出されます。
errorCallBack：この関数は、ファイルのインポートでエラーが発生した場合に呼び出されます。
importOptions：GC.Spread.Sheets.ImportOptions から継承されます。このパラメータは、インポートオプションを提供します。

さまざまなインポートオプションは、次の通りです。

オプション	説明
FileOptions	GC.Spread.Sheets.FileTypeから継承されます。FileOptionsは、さまざまなファイル形式を提供します。
ImportCsvOptions	GC.Spread.Sheets.ImportCsvOptionsから継承されます。ImportCsvOptionsは、CSV形式のファイルをインポートするオプションを提供します。
ImportSSJsonOptions	GC.Spread.Sheets.ImportSSJsonOptionsから継承されます。ImporSSJsonOptionsは、SSJSON形式のファイルをインポートするオプションを提供します。
ImportXlsxOptions	GC.Spread.Sheets.ImportXlsxOptionsから継承されます。ImportXlsxOptionsは、Excel形式（XLSX/XLSM/XLTM）のファイルをインポートするオプションを提供します。

注記：
「ImportXlsxOptions」の「Xlsx」は、Microsoft Excel（具体的には XLSX 形式）を指します。これは、Excel ファイルのインポートに関する設定項目を定義します。
excelFileTypeプロパティ（GC.Spread.Sheets.ExcelFileTypeクラスから継承）を使用して、以下の形式を指定できます：
XLSX（標準形式）
XLSM（マクロ有効）
XLTM（マクロ有効テンプレート）
デフォルトでは、XLSX 形式が採用されています。

以下のコードは、XLSM ファイルからインポートする方法を示しています。

// ファイルblobを取得します。
var file = document.getElementById("fileInput").files[0];
// インポート。
spread.import(file, function () {
    // 成功時のコールバック。
}, function (e) {
    console.log(e); // エラーが発生した時のコールバック。
}, {
    fileType: GC.Spread.Sheets.FileType.excel
    excelFileType: 'XLSM'
});