ファイル形式
Formulon は現代的な Office Open XML 系・バイナリ系のスプレッドシート形式を中心にサポートします。各リーダー / ライターの背後には同じ計算コアがあるため、形式層が担うのは構造の保持と機能の対応付けであり、計算挙動は形式によって変わりません。
用語: OOXML
Office Open XML（ISO/IEC 29500）。.xlsx / .xlsm / .xltx などの ZIP コンテナ形式で、内部はワークブック、シート、スタイル、共有文字列、リレーションシップなどの XML パーツで構成されます。
用語: そのまま保持するパーツ（passthrough）
Formulon が「意味を解釈しないが、保存時に消えないように構造だけ保持する」パーツです。エンジンが評価しない機能でも、再計算して保存し直す間にバイト列が消失しません。
XLSX
OOXML リーダー / ライターは以下を扱います。
- ワークブックのパーツとリレーションシップ
- ワークシート（セル、数式、キャッシュ値）
- スタイル、表示形式、フォント、塗りつぶし、罫線、テーマ
- 共有文字列
- テーブル、定義名
- コメント / スレッドコメント
- ワークシート / テーブルの型付き AutoFilter
- ハイパーリンク
- セル結合
- 入力規則
- 条件付き書式
- ピボットテーブル / ピボットキャッシュ
- 描画オブジェクトとラスター画像
- 外部リンク
- ふりがな注釈（要素ごとの UTF-16 範囲と
phoneticPrの表示プロパティを含む） - 保護情報
- シート表示、ウィンドウ枠の固定、非表示シート
- 行・列単位の上書き設定
印刷設定には型付きの設定メソッドがあります（ワークブック操作 を参照）。モデルが扱わない項目には生の XML を設定するメソッドを使えますが、不正な断片は格納前に拒否します。数式に入力した外部参照は外部リンクレコードを作成または再利用し、どちらのライターも保存と再読み込みの間でリンク表と数式を保持します。値は引き続きファイル内のキャッシュだけから取得します。型付き AutoFilter、入力規則の判定、画像の編集は フィルターと入力規則 と コメントと画像 で説明しています。
ふりがなの各ランと表示プロパティは、XLSX と XLSB の間でラウンドトリップします。セルごとの「ふりがなの表示」フラグは getCellShowPhonetic(sheet, row, col) / setCellShowPhonetic(sheet, row, col, show)（Python は get_show_phonetic / set_show_phonetic）で読み書きします。このフラグを持つのは定数セルと空白セルだけです。Excel は数式セルには保持しないため、数式セルのフラグは保存されず、ファイルからも読み込まれません。フォントテーマの scheme 値も保持されるため、テーマにリンクした標準フォントは保存後もリンクされたままです。
モデルが解釈しない、コメント・条件付き書式・スタイル・ピボットキャッシュ・テーブルの属性と子要素は、再保存後も保持されます。ファイルから読み込むサイズは、読み込み・再計算・保存の各段階で上限が検査され、2^25 を超えるレコードスロットを持つピボットキャッシュは kIoFileTooLarge で読み込みに失敗します。アポストロフィで始まる、または終わるシート名を含むファイルは、Excel もその名前を拒否するため、kIoSheetCorrupt で読み込みに失敗します。
getNumFmt(numFmtId)（Python は get_num_fmt）は、ECMA-376 に書式コードがない組み込み ID も解決します。東アジアの日付 ID の 31 と 55〜58、タイ数字の ID 59〜81、通貨の ID 5〜8 などが該当し、ワークブックの Excel プロファイルが描画に使うコードを返します。そのため、日本語・中国語・韓国語のデスクトップ版表計算ソフトが保存したセルは、その日付書式を報告します。ECMA-376 に書式コードがある ID は、そのコードを返します。
キャッシュ値の扱い
読み込み時、数式セルは数式テキストとファイル内のキャッシュ値の両方を保持します。recalc() 後、キャッシュ値はエンジンの計算結果で置き換わり、保存時に「数式と値が整合した」ファイルが書き出されます。
XLSB
XLSB は XLSX と同じワークブックモデルを使いますが、モデルが持つ内容をすべて書き出せるわけではありません。何が省かれたかは、診断付きで保存すると確認できます。
const out = wb.saveWithDiagnostics(WorkbookFormat.Xlsb)
if (!out.status.ok || out.bytes === null) throw new Error(out.status.message)
console.log(out.deferredFeatureCount, out.downgradedFormulaCount)out = wb.save_with_diagnostics(WorkbookFormat.XLSB)
print(out.deferred_feature_count, out.downgraded_formula_count)deferredFeatureCount は、ノートや型付き AutoFilter の変更など、XLSB ライターが出力しなかった機能の件数です。downgradedFormulaCount は、XLSB のトークン形式で表せずキャッシュ済みのリテラルとして書き出した数式の件数です。XLSB から読み込んだ、モデル化していないワークシート末尾のレコード（AutoFilter、印刷設定、改ページ、図形やテーブルへの参照など）は、リレーションシップとともにバイト列のまま保持します。そのため XLSB から読み込んだ AutoFilter は不透明なままで、型付き API からは見えません。XLSB のピボット関連パーツは、レコード形式が対応済みであればデコードして評価し、未計測の形式は推測せずスキップします。機能ごとの現在の挙動は下の表のとおりです。
| XLSB の機能 | 現在の挙動 |
|---|---|
スタイル（BrtFmt / BrtXF）と差分書式（BrtDXF） | モデル化して出力。読み込み時に BrtDXF をデコードするため、条件付き書式のルールは解決できる dxfId を保ち、.xlsb から .xlsx に変換しても書式が残ります。編集していないスタイルテーブルはバイト単位でそのまま書き出し、addDxf() などでスタイルを編集した後は、モデルからスタイルパートを再生成します |
| 行 / 列レイアウト、結合 | モデル化して出力 |
ワークブックのプロパティ（date1904 を含む BrtWbProp）と計算設定（BrtCalcProp） | モデル化して出力。手動計算や反復計算の設定も保存後に残ります。workbookPr dateCompatibility / allowRefreshQuery は書き出さず、報告します |
| シートビュー、表示倍率、ウィンドウ枠の固定と分割、選択範囲 | モデル化して出力。ウィンドウ枠は列の分割を先にした BrtPane、選択範囲はウィンドウ枠ごとに 1 つの BrtSel、すべてのブックビュー（BrtBookView）と追加ウィンドウのシートビューも対象 |
| グラデーション塗りつぶし、差分書式のフォントの輪郭 / 影 / 狭く / 広く | モデル化して出力（BrtFill、BrtDXF） |
| 動的配列メタデータと対応するトークン化数式 | モデル化して出力 |
| ピボットキャッシュ / ピボットテーブルのパーツ | 対応するレコード形式は評価。未計測の形式はスキップ。ピボットのフィルターとスタイル情報は読み込む。XLSX 由来のピボットテーブルは書き出さず、報告 |
| 条件付き書式 | モデル化して出力。対応する判定式を評価し、x14 データバーや独自アイコンセット（BrtCFIcon）の表示情報も扱う。Excel が x14 ルールの横に追加する従来形式のコピーは、1 つのルールとして読み込まれる |
| 入力規則 | モデル化して出力。入力候補と保存済みセルを明示的に確認できるが、自動的な値の変更や強制は行わない |
| シート / ワークブック保護 | メタデータとしてモデル化して出力。lockWindows、lockRevision、リビジョンパスワード（BrtBookProtection、BrtBookProtectionIso）と保護された範囲（BrtRangeProtection）を含む。セルロックはエンジンで強制しない。保護された範囲のセキュリティ記述子は書き出さず、報告する |
| AutoFilter | XLSB から読み込んだ定義は不透明なまま保持し、型付き API からは取得しない。型付きの変更は保留して報告 |
| ハイパーリンク | ワークブックモデルからモデル化して出力 |
| 印刷設定 / 改ページ、図形 / テーブル参照、リレーションシップ | モデル化していないものはバイト列のまま保持。モデル化した変更は保留して報告し、互換性のある保持済み末尾はそのまま出力する場合がある |
| 従来型ノート / スレッドコメント | 省略し、deferredFeatureCount で報告 |
| OOXML の描画（読み込んだ画像と挿入画像を含む） | 省略し、シートの描画先ごとに 1 件として報告。保持済みの互換性のある XLSB 描画パーツはそのまま出力する場合がある |
| モデル化したページ設定、余白、印刷オプション、ヘッダー / フッター、手動改ページ | 変更は出力せず報告。保持済みの互換性のある XLSB 末尾レコードはそのまま出力する場合がある |
| テーブルと構造化参照 | モデル化して出力（スタイル・フラグ・集計行・計算列・AutoFilter・並べ替え状態を持つ BrtBeginList、PtgList）。レコードで保持できないテーブルの設定は報告 |
| What-If データテーブル | 起点セルの値レコードの前に BrtTable として、常に計算するフラグ付きで出力 |
| スパークライングループ | XLSX と同様に列挙・編集でき、書き出される。参照をエンコードできないグループは書き出さず、報告 |
| テーブルスライサー | XLSB の再保存でも保持。XLSX 由来のものは書き出さず、報告 |
| カスタムのテーブル / ピボットテーブルスタイル | 書き出さず、報告 |
| 表現できないシート既定値 | 省略時に報告 |
| 非対応数式 | キャッシュ済みリテラルへ置き換える場合があり、件数を報告 |
保存後の deferredFeatureCount が 0 でなければ、XLSB の内容はモデルと異なります。どちらのコンテナも、シート ID をシートの位置で振り直さず、元のファイルのものを保持します。
印刷範囲と印刷タイトルは定義名として XLSB に出力され、上の保留対象のページ・印刷設定とは別です。ワークシート末尾の保持からコメントやピボットの保存を推測しないでください。これらが重要な場合は、入力ファイルを保持したうえで出力パッケージを確認してください。
保存時のコンテナ形式は明示的です。saveAs(format) / save_as(fmt) は WorkbookFormat を受け取って XLSB か XLSX かを選べます。saveWithDiagnostics(format) / save_with_diagnostics(fmt) も同じ形式指定を使い、パッケージ損失の一部を対象とするカウンターを返します。readDiagnostics() / read_diagnostics() では読み込み時に取得したカウンターを確認できます。CLI は -o パスの拡張子から出力形式を判断します（-o out.xlsb は MS-XLSB を書き出し、それ以外は OOXML を書き出します）。一方、読み込みは内容を調べて判定します。loadBytes() / Workbook.load() はどちらの形式も ZIP パッケージとして開き、通常は XLSX の xl/workbook.xml、XLSB の xl/workbook.bin とコンテンツタイプを確認します。ファイル名は判定に使いません。
下のパネルでは、1 つのワークブックを両方のコンテナに書き出し、生成したバイト列をファイル名なしでそのまま loadBytes() に戻しています。カウンターはその書き出しについて saveWithDiagnostics() が返した値です。すべて 0 のパネルは「報告対象の損失が起きなかった」という意味であり、すべての未対応機能が保持されたことを示すものではありません。重要な構造は出力パッケージも確認してください。
保存した XLSX・XLSB のすべての ZIP エントリーには、固定のタイムスタンプ 1980-01-01 00:00 を使います。同じワークブックモデルを変更せずに同じ形式で保存すると、同一のバイト列になるため、回帰テストでバイト単位の比較ができます。
同じワークブックを XLSX と XLSB で書き出す
1 つのワークブックを saveWithDiagnostics() で両方のコンテナに書き出し、生成したバイト列をそのまま loadBytes() に戻します。読み込みはファイル名ではなくバイト列の内容から形式を判定するため、拡張子のないバイト列でも正しく開きます。
本物の Formulon エンジン (WASM) がこのページ内で動作します。データは送信されません。
保持と評価の対応
| 機能 | 読み込み | 再計算 | 書き出し |
|---|---|---|---|
| セル内の数式 | 対応 | 対応 | 対応 |
| スタイル / 表示形式 | 対応 | 対象外 | 対応 |
| 定義名 | 対応 | 対応（参照として解決） | 対応 |
| テーブル | 対応 | 対応（参照として解決） | 両方のコンテナで対応。XLSB で保持できないテーブルの設定は報告 |
| 条件付き書式 | 対応 | 一部（対応する判定式） | 対応 |
| 入力規則 | 対応 | validateValue() / listInvalidCells() で明示的に確認。自動的な値の変更や強制はしない | 対応 |
| シート / ワークブック保護 | 対応 | メタデータのみ。セルロックは強制しない | 対応 |
| AutoFilter | 解析できる場合は型付き。XLSB から読み込んだものは不透明 | evaluateAutoFilter() で確認し、applyAutoFilter() で行の表示状態を変更して依存する SUBTOTAL / AGGREGATE 数式を再計算待ちにする。更新後の値を読む前に recalc() を呼ぶ | XLSX は対応。XLSB の型付き変更は保留して報告 |
| ハイパーリンク | モデル化 | 対象外 | モデル化したリンクを XLSX と XLSB に出力 |
| 印刷設定 / 改ページ | XLSX は型付き。XLSB から読み込んだ末尾は不透明 | 対象外 | XLSX は対応。XLSB のモデル化した変更は保留して報告し、互換性のある保持済み末尾はそのまま出力する場合があります |
| 図形参照 | 描画オブジェクトを列挙でき、画像 / グラフの対応範囲に従う | 対象外 | 対応範囲に応じて保持。XLSB は画像 / グラフの規則に従う |
| ピボットテーブル | レイアウト / 対応キャッシュ | pivotLayout() / GETPIVOTDATA で対応キャッシュを集計・取得。元シートからのキャッシュ更新はしない | XLSX は対応。XLSB は変更のない互換性のある保持済みパーツを出力。対応パーツがない場合は保留して報告し、保持済みパーツに対応するモデルを変更した場合は保存が失敗 |
| 画像 | XLSX では画像バイトとアンカーを読み取り・編集。XLSB の描画は不透明な場合がある | 対象外 | XLSX は対応。XLSB では OOXML の描画を省略して報告 |
| スレッドコメント | XLSX ではモデル化 | 対象外 | XLSX は対応。XLSB では省略して報告 |
| グラフ | 型付きの構造と系列データを読み取り、XLSX は作成・編集も可能。XLSB は読み取り専用 | 系列をセル値に対して解決。描画はしない | XLSX はキャッシュを更新。XLSB は描画の保持・省略規則に従う |
| 図形 / グループ | 描画オブジェクトを列挙でき、対応するパーツを保持 | 描画しない | 対応するパーツを保持。描画はしない |
| フォームコントロール | そのまま保持 | 対象外 | 対応 |
| VBA プロジェクト | そのまま保持 | 実行しない | 対応 |
VBA は保持するが実行はしない
VBA を含むワークブックは読み込み後に保存し直せますが、マクロは決して実行されません。マクロ側の状態に依存する計算は Excel と差分が出ます。
非対応
- 旧
.xls（BIFF）の読み書き - CSV の読み書きは未実装です。ホスト側で解析し、ワークブック API でセルへ書き込んでください。
- ライブ外部接続（Power Query / OLE DB / Web）
次に読むもの
- ライフサイクル ─ バイト列からワークブックモデルへの変換
- ワークブック操作 ─ シート / セル / 構造の編集
- フィルターと入力規則 ─ 型付き AutoFilter と入力規則の明示的な確認
- コメントと画像 ─ スレッドコメントとアンカー付き画像の操作
- 表示とレイアウト ─ 描画の境界と表示メタデータ
- 互換性 / ファイル形式サポート ─ 読み込み / 書き出し / 保持の対応表