Excel / Excelize

アダプターの選び方

@alneas/data-engine/excelには共通データ形式ExcelWorkbookData、 ExcelAdapter、HTTP・自作Go WASM・CSV・モックの各アダプターがあります。モックの出力は利用可能なXLSXではありません。CSVは1シートの値のみを出力します。 HttpServerExcelAdapterには別途バックエンド、WasmExcelAdapterには generateExcel(JSON)を提供する自作Go WASMが必要です。

自前のGoビルドやExcelサービスなしでXLSXを生成する場合は、専用入口 @alneas/data-engine/excel/excelizeのExcelizeExcelAdapterを使います。任意peerは利用するアプリで明示的に導入します。

npm install @alneas/data-engine excelize-wasm@0.1.3

peerのライセンスはBSD-3-Clauseです。WASM等を再配布するときはライセンス表示を保持してください。engineルートと通常の/excelはpeerなしで利用できます。 Excelize専用入口もimport時にはpeerを読み込まず、load()・generate()で初めて読み込みます。専用入口のTypeScript型解決にはpeerの導入が必要です。

Node.jsで生成する

import { createRequire } from 'node:module';
import { writeFile } from 'node:fs/promises';
import { ExcelizeExcelAdapter } from '@alneas/data-engine/excel/excelize';

const require = createRequire(import.meta.url);
const adapter = new ExcelizeExcelAdapter({
  wasmPath: require.resolve('excelize-wasm/excelize.wasm.gz'),
});
const workbook = {
  metadata: { title: '売上' },
  sheets: [{
    name: '売上',
    columns: [
      { header: '商品', key: 'item', width: 25 },
      { header: '金額', key: 'amount', format: '#,##0.00' },
    ],
    rows: [{ item: 'りんご', amount: 150 }],
    cells: [{ cell: 'B4', formula: '=SUM(B2:B3)' }],
    startRow: 1,
  }],
};
await writeFile('sales.xlsx', await adapter.generate(workbook));

CommonJSではrequire('@alneas/data-engine/excel/excelize')を使えます。サーバーではgenerate()でバイト列を取得してください。既存アダプターと同様に、 download()のファイル保存操作はブラウザーのdocumentがある場合に限ります。

ブラウザーのWASM配置

アプリのビルド時にnode_modules/excelize-wasm/excelize.wasm.gzを公開アセットへコピーします。gzipアーカイブのバイト列を保ち、Content-Encoding: gzipを付けずに配信してください。付けるとブラウザーが先に展開し、上流ローダーに期待と異なるデータが渡ります。別途wasm_exec.jsは不要です。本番でnode_modulesがURLとして公開されることを前提にしないでください。

import { ExcelizeExcelAdapter } from '@alneas/data-engine/excel/excelize';
const adapter = new ExcelizeExcelAdapter({
  wasmPath: '/assets/excelize.wasm.gz',
});
await adapter.load(); // 任意の事前読み込み。generate/downloadでも初期化します。
await adapter.download(workbook, 'sales.xlsx');

サブディレクトリへ配置するアプリは、そのベースパスをWASMのURLにも含めます。別オリジンならCORSを設定し、HTMLのフォールバックではなくWASMアーカイブが返ることを確認してください。bundlerはpeerのブラウザー向けmain.jsを解決する必要があります。Node向け入口はCommonJSです。パッケージ側ではブラウザー向け bundle生成に加え、Chromiumで実際のWASM読み込み・生成・ダウンロードを検証します。本番の配信設定・CSPとの組合せは利用アプリでも検証してください。WASMコンパイルと上流ローダーの JavaScript実装がCSPで許可されている必要がありますが、アダプターが自動でCSPを緩めることはありません。Edge/Workers実行はこのアダプターの実行テスト対象外です。

同じJavaScript実行領域では、複数のアダプターおよびESM/CJSが1つの初期化結果を共有します。wasmPathは同じ文字列に統一してください。初期化後に別パスを指定するとエラーになります。初期化失敗後は再試行できます。同じ実行領域で別途上流の excelize-wasm.init()を呼ぶと、既存ブックの使うグローバルランタイムが置き換わるため併用しないでください。importだけではアセットを読み込みません。

データ形式・対応範囲・制約

1シート以上が必要です。シート名は大文字小文字を無視して一意とし、Excelizeの命名規則に従ってください。不要な既定シートは残しません。
表の見出し行はstartRowです。省略時はcellsの最大行の次、直接指定セルがなければ1行目です。データは見出しの次の行から書きます。cellsは表の後に適用し、同じ座標を上書きできます。null・undefinedは書き込まないため、既に書いた表の値を消す操作にはなりません。
値は文字列、有限数値、真偽値、Dateに対応します。オブジェクト・配列・bigint・非有限数はエラーです。=で始まる文字列も通常の文字列です。数式はformulaで明示してください。
type: 'date'の列はDate、YYYY-MM-DD、タイムゾーンを明示したISO日時を受け取り、UTC基準でExcelの1900日付システムの連続値へ変換します。時刻は小数部になります。対応年は1900〜9999年です。日付列と直接指定のDateセルは既定で yyyy-mm-dd、明示した書式があればそちらを使います。それ以外の型ヒントでは型変換しないため、数値・真偽値はその型の値を渡してください。
列のstyleは見出し、formatはデータセルの書式です。セルではフォント・色・配置・折返し・罫線・表示形式に対応します。色はRGBで#は任意です。同じ書式はブック内で再利用します。
セル結合・列幅・行高・グリッド線の表示・文書メタデータに対応します。 colWidthsは表の列幅指定より優先します。幅を省略した列はExcelの既定幅です。このアダプターは列の自動幅調整を行いません。
数式は保存し、開いたときの再計算を要求します。生成時には評価せず、計算結果のキャッシュも作りません。表計算アプリごとに対応数式が異なります。このアダプターは Excelの計算エンジンではありません。チャート・画像・既存ブック編集は共通データ形式の対象外です。
XLSX専用です。CSVにはCsvExcelAdapterを使います。timeoutMsとHTTP用headersはエラーにします。初期化後のWASM処理は同期実行で、JavaScriptのタイマーでは中断できません。大量データはWASM本体・ブック・出力用のメモリーが必要です。 UI応答性が必要ならアプリ側でWorkerやバックエンドへ処理を分離してください。

loadExcelize(wasmPath)で共有の上流ランタイムを取得し、OpenReader(bytes)なども利用できます。その場合は上流の戻り値のerrorを自分で確認してください。アダプター経由の上流エラーはPromiseのrejectとして伝えます。既存アダプターと帳票テンプレートのAPIは変更しません。日本語請求書テンプレートは @alneas/business-jp/excelに残し、そのデータ定義をこのアダプターへ渡します。 ExcelAdapterを受け取る既存のuseExcelExportも、そのまま利用できます。

検証

bun run test:excelizeはpeerを導入した隔離環境に実際の配布tarballをインストールし、 XLSX生成・Excelizeでの再読み込みを検証します。日本語、数値・真偽値、日付、数式、書式、結合、行列寸法、メタデータ、複数シート、初期化共有・再試行、不正入力を確認します。 Node/BunのESM/CJS実行、Node型なしの厳密なNodeNext型解決、ブラウザーbundle生成を含みます。bun run test:excelize:browserはPlaywrightのChromiumで実WASM・再読込・ダウンロードも検証し、品質CIでも実行します。ブラウザーバイナリはPlaywright 1.63.0に合わせて隔離fixtureへ取得し、終了時に削除します。EXCELIZE_BROWSERS=chromium,firefox,webkitで対象を増やせます。test:consumerではpeerなしのengine/Excelとpeer不足のエラーも検証します。既存のverifyおよびNode 24/26の品質CIに含まれます。テストにExcelサービスの運用や npm公開は不要です。