技術記事

DelphiでPDFへ出力するFlexbox、CSS Grid、脚注

2段組みの章の左段、最終行の1つ上の行に脚注参照が付いたとします。1行の注にはその段の足元に約14ポイント要りますが、残りは9ポイントしかありません。自明な帰結はどちらも誤りです。それでも注を描けば本文に重ね印刷され、注だけ送り出せば右段の下に、関係のないテキストの横に置かれます。ブラウザーがこの判断を迫られることはありません。Webページに下端がないからです。FlexboxとCSS Gridは同じ前提の下で設計されたため、レポートのHTMLが固定サイズのページに着地する瞬間から、両者には「ボックスの高さが尽きたら何が起こるか」という規則がそれぞれ必要になります

固定幅ボックスの中のflexダッシュボード行

PDF Library for Delphiは、display: flexやdisplay: inline-flexのスタイルを持つ要素を本物のflexコンテナとして扱うため、カードの行は行のまま保たれ、縦積みブロックに崩れません。描画はDrawHTMLTextBox(Left, Top, Width, Height, HTMLText)で行い、これはWideStringを返します。すべて収まれば空、収まらなければどこか別の場所に描くべき残りです

行方向では、各アイテムにbasisが与えられ、basisとアイテム間のギャップが合計され、行に残った分が配られます。正の空間はflex-growの通りに配り、負の空間はflex-shrinkにアイテムのbasisを掛けて取り戻します。これがCSSの規則であり、便利な副作用はすぐ後で示します。flex-wrapが設定されていると、次のbasisが入らなくなった時点でアイテムは新しい行へ移り、各行は自分の空きスペースを独自に分配します。justify-content、align-items、align-content、gap、そして-reverse方向指定は、その後、すでに測定済みのボックスを動かすだけです

PDF Library for Delphi の flex 行サイズ決定の図。測定ベースと grow ウェイト、行ごとの余剰空間の加重配分、移動のみの整列パスにより 2対1対1 のダッシュボード行を生成
Flex サイズ決定は、上限付きの 1 回の計測パスと、それに続く残りスペースの加重分配で構成されます。配置は計測済みボックスを移動するだけで、再計測を一切引き起こしません
uses
  SysUtils, PDFlibrary;

var
  Lib: TPDFlib;
  Html, Remainder: WideString;
begin
  Lib := TPDFlib.Create;
  try
    Lib.SetOrigin(1);          // 左上原点:Topはページの下向きに伸びる
    Lib.SetPageSize('A4');

    // パーセントbasisならgap込みで2:1:1の比率が厳密に保たれる
    Html :=
      '<div style="display:flex; gap:12px;">' +
      '<div style="flex:0 1 50%; background:#f4f6f8; padding:8px;">' +
        '<b>Revenue</b><br/>EUR 4,182,300</div>' +
      '<div style="flex:0 1 25%; background:#f4f6f8; padding:8px;">' +
        '<b>Margin</b><br/>18.4%</div>' +
      '<div style="flex:0 1 25%; background:#f4f6f8; padding:8px;">' +
        '<b>Backlog</b><br/>92 days</div>' +
      '</div>';

    Remainder := Lib.DrawHTMLTextBox(40, 40, 515, 120, Html);
    if Remainder <> '' then
      raise Exception.Create('Dashboard row needs more than 120 pt');

    Lib.SaveToFile('dashboard.pdf');
  finally
    Lib.Free;
  end;
end;

515ポイントのボックスで数字を追ってみます。12pxのギャップは9ポイントに換算され、2つのギャップで18です。basisの合計はちょうど515なので、その18ポイント分だけオーバーします。shrinkはbasisで重み付けされるため、50%のカードは9ポイント返し、25%のカードはそれぞれ4.5返して、248.5、124.25、124.25が残ります。比率は厳密に2:1:1のままで、コードはギャップを手で引く必要が一度もありません

同じflex: 1なのに幅が揃わないのはなぜか

basisがコンテンツの幅になっているからです。レンダラーはbasisをflex-basisから、flexショートハンド内の長さ(pt、px、em、%付きの値)から、あるいはwidthから取ります。どれも正の長さを生まないときは、測定したコンテンツ幅がbasisになります。素のflex: 1も、ブラウザーの慣用句であるflex: 1 1 0もそこに落ちます。単位なしの0は長さとして読まれないからです。等しいgrow係数は、等しくない開始幅の上に等しい空きスペースを足します

同じダッシュボードを全カードにflex: 1と書くと、7桁の数字でコンテンツが3つの中で最も広いRevenueカードが最初から広く始まり、成長後もその分だけ広いままです。残り空きスペースの3分の1を各カードが等しく受け取るからです。ツールバー、タグリスト、ボタンの行には、それがむしろ望む見た目のことが多い。ダッシュボードは違います。上下のテーブルと揃えるべきものには、growを0にした明示的なパーセントかポイントのbasisがふさわしく、私たちの推奨も、例がやっていることもまさにそれです。3枚のカードは中身の数字が何であれ、毎ページ248.5、124.25、124.25ポイントに着地します

列方向は同じ論理を縦軸で辿ります。basisはflex-basisかheightから、なければ測定したコンテンツの高さから来ます。空きスペースは、コンテナがheightを宣言しているときにだけ存在します。宣言がなければ、コンテナはアイテムとぴったり同じ高さになり、justify-contentに配るものがありません

グリッドのトラック、配置、スパン

display: gridでは、PDF Library for Delphiはgrid-template-columnsとgrid-template-rowsを、固定長、パーセンテージ、fr単位、repeat(n, track)、minmax(a, b)として読みます。固定トラックとギャップを利用可能な幅から引き、残りをfrの重みで分割します。minmax()トラックは第2引数でサイズが決まるため、minmax(120px, 1fr)は1frのように振る舞い、auto、min-content、max-contentの各トラックは空きスペースを1等分ずつ受け取ります

PDF Library for Delphi の図。許容されるグリッドトラック値、意図的な重なりを許す決定論的占有配置、行スパン項目がカバーする行にわたって平均した高さを返す動作
グリッドトラックは長さ、パーセンテージ、fr 単位、repeat、minmax を受け入れ、自動配置は占有マトリクスを決定論的に辿ります

配置は決定論的です。自動配置のアイテムはグリッドを行ごとに(grid-auto-flow: columnなら列ごとに)歩き、すでに占領されたセルをスキップします。行だけが指定されたアイテムはその行の空き列を探し、列だけが指定されたアイテムはその列を下って探します。両座標が指定されたアイテムは、別のアイテムの上であろうと、言われた場所そのものに行きます。カードの上にバッジを重ねるのはこの仕組みです

スパンにはひとつの習慣が必要です。レンダラーはスパンをスラッシュ以降の部分、たとえばgrid-row: 1 / span 2から、あるいはgrid-row-end: span 2とgrid-column-end: span 2から読みます。ブラウザーが値全体として受け付ける素のgrid-row: span 2は、これらの綴りには含まれないため、開始行とスラッシュは残してください

// 点検シート:固定のラベル列と、伸縮する2列
Html :=
  '<div style="display:grid; ' +
  'grid-template-columns:120pt repeat(2, 1fr); gap:6pt;">' +
  '<div style="grid-row:1 / span 2; background:#eef2ff;">' +
    'Site plan</div>' +
  '<div>Inspector</div>' +
  '<div>Date</div>' +
  '<div style="grid-column:2 / span 2;">Findings summary</div>' +
  '</div>';

Remainder := Lib.DrawHTMLTextBox(40, 180, 515, 260, Html);

この515ポイントのボックスでは、ラベル列が120ポイント、2つのギャップが12ポイント、各1fr列が191.5を受け取ります。Site planセルには行があり列がないため、列1に着地して行1と2を覆います。InspectorとDateが行1の残りを埋めます。summaryには列があり行がないため、配置は列2を下って探し、行1が占領済みと分かると、行2の両伸縮列にわたって落ち着きます

行の高さはコンテンツから来ます。スパンするアイテムは測定した高さを、覆う行に均等に割って還元し、各行はその中のアイテムが要求する最大の取り分を採るため、背の高いセルの余分な高さは、最初の行に押し付けられるのではなく、触れるすべての行に広がります。背の高いSite planセルは、最初の行だけを伸ばしてFindings summaryを隙間に浮かせる代わりに、両方の行を少し持ち上げます

コンテナはボックス間を分割されずに移動する

flexやgridのコンテナは、2つのボックスに跨って分割されることがありません。決してです。コンテナ全体が残りスペースに収まらないとき、コンテナとそれ以降のすべては返されるremainderに入ります。remainderは次のボックスや次のページにそのまま渡すものだから、カードの行は測定済みのジオメトリを保ったまま、次のフレームを冒頭から開けます。ページ3の下にKPIタイルの上半分、ページ4に下半分というのは、隙間よりひどいものです。この規則が取るトレードオフはそれです。例外は、空のボックス全体より背の高いコンテナで、これは問答無用でそのボックスの上端から描かれ、下端を走り抜けます。後のボックスがどれも大きくはならないからです

実務上の帰結は、ページに載せると決める前にコンテナの高さを知っておくべきということです。GetHTMLTextHeight(Width, HTMLText)は描画なしで測定します。flexもgridも込みでです

// GridHtml、Y、PageBottomはレポートコード側の変数
Needed := Lib.GetHTMLTextHeight(515, GridHtml);
if Y + Needed > PageBottom then
begin
  Lib.NewPage;
  Lib.SetPageSize('A4');
  Y := 40;
end;
Lib.DrawHTMLTextBox(40, Y, 515, Needed, GridHtml);
Y := Y + Needed + 12;

測定には意図的に上限があります。顧客がテンプレートを編集する状況では重要な話です。flexやgridのコンテナは直接の子を最初の256個まで取り、グリッド配置は64行の内側で働き、トラックリストは最大64トラック、repeat()の回数もそれに合わせて上限付きです。数百の子を持つflexコンテナは、ほとんどの場合、変装したデータテーブルであり、独自の列測定とrowspan対応を持つテーブル経路のほうが、いずれにせよ上手にレイアウトします

脚注はどうやって参照と一緒に保たれるのか

PDF Library for Delphiは、参照に出会った瞬間に各注を測定し、その高さを現在のボックスの本文予算から差し引きます。注は<aside style="float:footnote">、<aside role="doc-footnote">、あるいは<footnote>要素として書きます。参照は周囲のフォントサイズの3分の2の上付き数字になり、注テキストは10ポイントの行送りで8ポイントに組まれ、同じ番号が前に付きます

そこまでの本文に新しい注を足しても収まらない場合、マーカーとそれ以降のすべてが一緒にremainderへ移ります。注と参照はペアで旅します。冒頭のシナリオへの答えはこれです。参照の行とその注が次の段を冒頭から開けば、重ね印刷も、取り残された注も起こりません。上限付きのボックスでは、注エリアはボックス幅の4分の1の長さの薄いグレーの罫線の下、下端に固定されます。GetHTMLTextHeightのような上限なしの測定では、固定すべき下端がないため、注は本文の直後に続きます

PDF Library for Delphi の脚注改ページの図。注エリアはボックス下部の罫線下に確保され、入りきらない注はマーカーと共に継続列へ移動し、番号はページをまたいで連続を保つ
脚注スペースは本文の予算から確保されてからテキストが流し込まれ、番号は段やページをまたいでも維持されます

番号付けは、新しいHTML文字列ごとに1から始まります。次の番号はremainder文字列自身の内側に保存されるため、remainderを返された形のままで渡し戻す限り、DrawHTMLTextBoxの連鎖もDrawHTMLStoryも、段やページを跨いで1つの通し番号を保ちます。継続を自分のソーステキストから組み立て直すと、カウントは再起動します

Chapter :=
  '<p>The bearing stayed within tolerance for the full six hours' +
  '<aside style="float:footnote">Ambient temperature held at ' +
  '21 &deg;C throughout the run.</aside> of the load test.</p>' +
  MoreChapterHtml;                 // 章の残り

// 2段、ガター16pt、最大20ページ。ページ追加はストーリー自身が行う
Rest := Lib.DrawHTMLStory(40, 40, 515, 760, 2, 16, 20, Chapter);
Err := Lib.LastErrorCode;          // 1回だけ読む:読むとリセットされる

if Err = PDFLIB_ERROR_HTML_STORY_INVALID then
  // 不正な幾何:Columns 1..64、MaxPages 1..10000、ガターはWidth未満
else if Err = PDFLIB_ERROR_HTML_STORY then
  // 連続する2フレームが前進しなかった
else if Rest <> '' then
  // 20ページ消費済みでテキストが残っている:後でRestから続ける
  ;

DrawHTMLStory(Left, Top, Width, Height, Columns, Gutter, MaxPages, HTMLText)は現在のページから始まり、段を左から右へ埋め、テキストが尽きるかMaxPagesに達するまで、同じ寸法のページを追加していきます。3つの帰結を区別するために、返される文字列を確認する前にLastErrorCodeを読むのがよいのです。不正な引数は入力をそのまま返します。それは一見、ページを使い切ったストーリーと見分けがつきません

実コンテンツからレイアウトへ流し込む

多段の本文テキストについては、ハイフネーションとバランスした段組みで述べる段組みとハイフネーションの挙動が、各段の内側でのフローの見え方を決めます。マークアップが手書きテンプレートではなくデータから来るなら、flexとgridがページの上に並べる前に、データセットレポートエンジンがそれを生成する経路です。後でPDFから再び取り出すことになるコンテンツは、PDFからMarkdownとDOCXへのエクスポートを通ります

flex、grid、脚注を備えたHTMLレイアウトと、レポート生成、意味的エクスポートは、Delphi、C++Builder、Free Pascal向けの1つのライブラリに同梱されています。HTMLレンダラーと描画APIの残りはPDF Library for Delphiの製品ページに一覧があります