xl3 が保持するもの、保持しないもの
xl3 が自分のテンプレートに合うかは、結局ひとつに集約されます。ワークブックは そのまま出てくるのか? このページが機能ごとに答えます。
以下はすべて仕様上の決定であり、特定の実装のたまたまの挙動ではありません。 先送り と書かれた項目は意図的に先送りしたもので、そのことが ADR に記録されて います。「誰も確認していない」とは違います。
3 つの判定
| 判定 | 意味 |
|---|---|
| 保持 | テンプレートとまったく同じものが出力されます。適合するすべての実装がそうしなければなりません。 |
| 保持、範囲は拡張しない | 機能そのものは残りますが、範囲はテンプレートが与えた座標のままです。@repeat がシートを 1 行から 50 行に増やしても、範囲はその 1 行しか覆いません。各項目にテンプレート側での対処法があります。 |
| 先送り | XTL 0.1 は何も保証しません。残ることもあれば失われることもあり、適合する 2 つの実装が違う挙動をしても構いません。1.1 より前にこれを前提にしないでください。 |
レイアウトと書式
| 機能 | 判定 | 備考 |
|---|---|---|
| セル書式 — フォント、塗りつぶし、罫線、配置 | 保持 | |
| 数値・日付の表示形式 | 保持 | @repeat で増えた行すべてが引き継ぎます。最初の行だけではありません — 繰り返しブロック内の書式 を参照。 |
| 行の高さ、列の幅 | 保持 | |
| 結合セル | 保持 | テンプレート側とソースのデータ行、どちらも (ADR-0033、ADR-0035)。 |
| 画像とそのアンカー | 保持 | @repeat が上に行を挿入してもアンカーはずれません。画像はヘッダ・フッタ・サイドなど、ブロックの外に置いてください。 |
| ウィンドウ枠の固定・分割 | 保持 | |
| セルのコメント | 保持 | {{ [列] }} のセルに付いたコメントは、レンダー後のセルにそのまま残ります。 |
| シート保護、セル単位のロック・非表示フラグ | 保持 | エンジンが書いたセルは、合成した既定値ではなくテンプレートセルのロック状態を引き継ぎます。 |
| ワークブックのプロパティ — テーマ、ドキュメントプロパティ | 保持 | フィクスチャ 120-workbook-properties-preserved。 |
| 静的セルのネイティブ Excel 数式 | 保持 | xl3 が生成していない数式はそのまま通します (ADR-0046)。Excel が開いたときに計算できるものはこちらに寄せてください — Cookbook 16 を参照。 |
範囲を持つルール
残りますが、範囲はテンプレートが指定した位置に留まります。エンジンがルールを黙って 広げ、言及されていない行まで覆うことはしません — 自動で広がる条件付き書式は 、作者が 意図的に除外したフッタ行にまで滲み出しかねません。
| 機能 | 判定 | テンプレート側での対処 |
|---|---|---|
| 条件付き書式 | 保持、範囲は拡張しない | テンプレートでルールを列全体 ($A:$A) に掛けておく。実測: 1 行のブロックが 3 行に増えても、ルールは A2:A2 に留まります。 |
| データの入力規則 (ドロップダウン、制約) | 保持、範囲は拡張しない | 同じ対処。実測: B2 に設定した入力規則は、拡張後も B2 だけに残ります。 |
| 名前の定義 | 保持、範囲は拡張しない | ブック スコープ・シート スコープとも残りますが、拡張された領域に向けて参照が張り替えられることはありません。 |
| 印刷範囲、印刷タイトル | 保持、範囲は拡張しない | 印刷範囲を列全体 ($A:$Z) か、繰り返すヘッダ行 ($1:$1) に設定する。 |
1.1 へ先送りしたもの
4 つの機能は 1.0 では意図的に実装依存のままにしています (ADR-0076)。計画を立てられる ようリファレンス実装の現在の挙動を載せますが、どれも約束ではありません — それが 先送りの意味です。
| 機能 | リファレンス実装の現状 |
|---|---|
| ピボットテーブル | 通りません。作成も保持もできません。 |
| スパークライン | 同様に通りません。 |
| 構造化テーブル (ListObject) | テーブル自体は残りますが、ref は拡張されません。@repeat の行にまたがって作ったテーブルは、元々覆っていた行しか覆い続けません。テンプレート側で ref を列全体に広げておいてください。 |
| 改ページ | 失われます。 概念的には「印刷範囲」の隣に見えますが、そこには含まれません。変換後にホスト側で設定してください。 |
| グラフ | 実装依存 (ADR-0036 項目 3)。リファレンス実装は ExcelJS で読み書きしており、そのグラフ対応は不完全です — グラフが残ることを前提にしないでください。 |
意図的に取り除くもの
| 機能 | 挙動 |
|---|---|
| マクロ (VBA、XLM) | 常に除去されます。 .xlsm の入力はマクロを取り除いた XLSX として受け付け、警告を出します。マクロは実行されず、1.x の間にホストやテンプレートが元に戻す手段はありません。SECURITY.md を参照。 |
繰り返しブロック内の書式
範囲とセル単位の書式は逆方向に振る舞います。この違いでつまずく人が多いところです。
テンプレートで A2:A2 に固定された範囲は、10 行が出力されても A2:A2 のままです。
一方その 10 行はすべて A2 の表示形式とセル書式を持ちます — エンジンが書いたセルは
テンプレートセルの書式を取り、最初の行だけでなくすべての行がそうなります。
後半のほうが聞こえより重要です。2..N 行目で書式が落ちるのは静かなデータ損失です。
最初の行だけ 1,234.50 で残りが 1234.5 の列は書式のうっかりミスに見え、実際の
ミスと区別できません。data-loss タグの付いたフィクスチャ 9 件が、この退行を防ぐ
ために存在します。
サイズの上限
| 上限 | 値 |
|---|---|
| メモリ | 規模が大きくなると出力セルあたり約 2.2 KB、これに約 130 MB の下限が加わります。200 万セルならピーク RSS でおよそ 4.2 GB。 |
| 1 回の変換あたりのセル数 | 約 200 万まで通しで検証済み。2 GB のホストには約 50 万が収まります。それより大きなジョブが動くと仮定する前に、セルあたり 2.2 KB でホストを見積もってください。 |
| セル文字列の長 さ | xl3 は渡されたものをそのまま書きます。Excel は 32,767 文字を超えるセルを読み込み時に拒否しますが、xl3 は事前検証しません — 出力を Excel で開く必要があるなら、渡す前に長さを確認してください (ADR-0032)。 |
利用可能なメモリを超えると、xl3 のエラーではなくホストレベルの out-of-memory として
現れます — xl3 では捕まえられません。長時間の変換は AbortSignal を受け取ります。
どこまで機械的に検証されているか
一部です。そしてどの部分かを知っておく価値があります。
123-feature-preservationは、名前の定義とセルのコメントがレンダーを経て残るかを Stage 1 のセル値比較で確認します。170-data-loss-numfmt-preserved-across-expansionは Stage 2 で、表示形式が@repeatの展開を越えて保たれるかを確認します — 上で述べた落とし穴です。- 上の表のすべての行に対する Stage 2 の正規化比較は、ADR-0006 の canonicalizer 対応を待っている状態です。
つまりフィクスチャが裏付けていない行は、機械的に検証されたものではなく仕様上の約束 です。すべての実装が同じ適合性コーパスを走らせるので、検証されている ものはどこでも検証されます。ただしコーパスはまだこの表の全体 を覆っていません。この ページは、そうでないふりをするよりそう書くことを選びます。
これらの決定が置かれている場所
このページは規範文書を平たい言葉に置き換えたものです。食い違ったら向こうが正です。
spec/evaluation.md§ Styles and Workbook Structure — 規範的なルール- ADR-0036 — 9 機能の保持マトリクスと、各項目を「保持して拡張まで」ではなく「そのまま保持」にした理由
- ADR-0076 — ピボット / スパークライン / ListObject / 改ページを 1.1 へ先送りした決定と実測値
- ADR-0046 — 静的セルのネイティブ Excel 数式
- ADR-0032 — 文字列長などの周辺的な上限
- ADR-0022 — Excel バージョン互換性
- SECURITY.md — マクロ / ネットワーク / ファイルシステムに関する立場