blog

SpreadJSファイルを正しく読み込む

NEXTREE.

• 4 min read
SpreadJSファイルを正しく読み込む

近年、Webアプリケーション内にExcel環境をそのまま実装するため、SpreadJSを導入するプロジェクトが増えています。私が担当するシステムでもSpreadJSを使用しています。SpreadJSを使用する中で発生した問題の一つが、「特定のファイルが画面上でまったく開けない問題」でした。

初期開発では旧バージョンを使用していましたが、新バージョンへのアップデート後、ユーザーがさまざまなファイルをアップロードするようになり、原因不明の解析エラーやランタイムエラーに直面することになりました。この原因は、旧バージョンではファイルを開く際に「open()」だけを使用していた一方、新バージョンで「import()」と「fromJSON()」が導入され、これらを混在させていたことにありました。

この経験を踏まえ、二度と同じミスを繰り返さないよう、3種類のフォーマット（.xlsx、.ssjson、.sjs）に応じた正確なAPIの対応関係と、正しいサンプルコードを整理しました。

エラーの原因：ファイルの特性とmethodの不一致

SpreadJSでファイルを開けない本質的な理由は、「手元にあるファイルデータの物理的な形式（バイナリなのか、JSONオブジェクトなのか）」と「それを読み込むAPIエンジン」を誤って組み合わせていることです。私たちが経験した代表的な失敗例は次のとおりです。

* 失敗例1：ユーザーがブラウザーで選択した元の.xlsxバイナリファイルを文字列データだと思い込み、旧バージョン方式のfromJSON()にそのまま渡していたケース -> SpreadJSエンジンが内部構造を解析できず、画面がフリーズする。

* 失敗例2：サーバーAPI通信でダウンロードした.ssjsonテキストデータを、ファイルオブジェクトのままimport() methodに渡していたケース -> binary stream format headerが存在しないため、ロードエラーが発生する。

* 失敗例3：最新の大容量圧縮フォーマットである.sjsファイルを、従来の旧式モジュール方式であるExcelIO.open()で開こうとしたケース -> 旧式のIOライブラリが新しい圧縮構造をデコードできず、エラーを返す。

この試行錯誤を経て得た重要な教訓は、ファイル拡張子ごとに正しく指定されたmethodとオプションを対応させてこそ、ブラウザーをクラッシュさせずに安全にファイルを開けるということでした。

3種類のフォーマット対応マトリックス

ファイルを開く際にエラーが発生した場合は、まず以下のマトリックスのルールを守っているか確認する必要があります。

  • 拡張子が .xlsx の場合

 * データの実際の形式：　標準Microsoft Excelバイナリファイル

 * 正しい処理method：　 workbook.import()

 * 必須の拡張プラグイン：gc.spread.sheets.io

  • 拡張子が .ssjson の場合

 * データの実際の形式：　テキストベースのJavaScript JSONオブジェクト

 * 正しい処理method：　 workbook.fromJSON()

 * 必須の拡張プラグイン：基本Coreモジュールに内蔵

  • 拡張子が .sjs の場合

 * データの実際の形式：　SpreadJS専用の大容量圧縮バイナリ（Zip）

 * 正しい処理method：　 workbook.import()

 * 必須の拡張プラグイン：gc.spread.sheets.io

旧式のドキュメントや古いブログ記事では、GC.Spread.Excel.IOインスタンスを生成した後、excelIo.open()を呼び出すよう案内されています。しかし、最新のSpreadJSアーキテクチャでは、ワークブックオブジェクトに統合されたworkbook.import()を使用することが公式標準であり、最も安全な方法です。

フォーマット別の正しいファイルオープン実装ガイド

フォーマット別の標準実装ソースコードです。各ファイルの特性に応じて、ブラウザーのFile/Blobオブジェクトの扱い方が異なります。

  • 標準Excel（.xlsx）ファイルを開く

.xlsxファイルは典型的なバイナリファイルです。そのため、ブラウザーのinputタグから取得したファイルオブジェクトをそのままworkbook.import()に渡し、必ずオプションにFileType.excelを明示する必要があります。

image1.png

  • 旧式JSON（.ssjson）ファイルを開く

image2.png

.ssjsonは形式上はファイルに見えますが、実際にはSpreadJSの状態をテキストとして出力したjavaScriptオブジェクトです。これをファイルオブジェクトのままmethodに渡すと、必ずエラーになります。必ずFileReaderを使用してテキストとして読み込んだ後、JSON.parse()で純粋なオブジェクトに変換し、fromJSON()でロードする必要があります。

  • 最新の専用圧縮フォーマット（.sjs）ファイルを開く

.sjsは大容量Excelの遅い読み込み速度とファイルサイズの問題を解決するために導入された専用の圧縮フォーマットです。構造的には.xlsxと同じバイナリ圧縮ファイルであるため、import()メソッドを共有しますが、パーシングエンジン内部の処理を異なるものにする必要があるため、fileTypeオプションをFileType.sjsとして明示する必要があります。 

image3.png

結論

各フォーマットに応じた正しいファイルのオープン方法をルール化し、明確に区別するようになって以降、驚くべきことに、ファイル読み込み時の形式不一致によって発生していたランタイムエラーやパース失敗の頻度が、以前と比べて目に見えて減少しました。エラーの発生頻度が劇的に低下したことで、関連するデバッグに費やしていたリソースを削減し、開発時間を大幅に短縮できました。最終的には、システムの安定性を大きく向上させるという大きな成果を得ることができました。

         

kina.j

Site footer