技術記事

Delphiにおける宣言的PDFレイアウトとタグ付き出力

4ページ目の下段で始まり5ページ目の上段で終わる段落は、読んでいる人にとっては1つの段落です。タグ付きPDFでは、その段落は2つのコンテンツストリームにまたがり、各ページがマークコンテンツ列を独立して採番するため、構造ツリーには1つのP要素が必要になります。その/K配列は、たとえば4ページ目のMCID 7と5ページ目のMCID 3を指します。座標コードでページを描いてからタグ付けを後付けすると、アクセシビリティチェッカーのタグツリーには、本来1つであるはずの段落が2つ並び、さらに継続中のテーブルのデータ内に列見出しのセットが繰り返し現れるのが定番の光景になります

座標アプローチには、さらに早く顔を出すもう1つのコストがあります。レポートの最初のバージョンは動きます。しかしやがて、顧客住所が3行に伸び、ローカライズされた見出しが折り返し、テーブルに40行増え、それ以降のすべてのy座標がずれます。改ページチェックはビジネスロジックのあちこちに散らばり、xとyしか知らないコードは、2年後にアクセシビリティ要件が降ってきたとき、段落がどこから始まるのか見当もつきません

DelphiでHotPDFレイアウトツリーを組み立てる

HotPDFは、HPDFLayoutDOMユニットの宣言的なレイアウトツリーでこの2つの問題に応えます。THPDFDOMDocumentがセクションを保持し、各THPDFDOMSectionはページサイズ、マージン、任意のヘッダーとフッター、そしてテキスト、見出し、スペーサー、リスト、画像、コンテナ、テーブルを追加していくBodyスタックを持ちます。ツリーの中にy座標を運ぶ要素は1つもありません。THPDFDOMRendererがツリーを測定して改ページを決め、各ページにヘッダーとフッターを描きます。GenerateStructureの既定値はTrueなので、描画と並行して構造ツリーも書き出されます

ツリー内の所有権は厳格です。ドキュメントはセクションを所有し、セクションは本文・ヘッダー・フッターを所有し、スタック、コンテナ、テーブルはそれぞれの子を所有します。そのためSection.Body.Add(Table)と書いた時点で、テーブルは丸ごと引き渡されます。2つの親に取り付いたコンポーネントは、異なる制約の下で2回測定され、解体時には2回解放されてしまいます。署名欄のような繰り返し登場する部品は、Clone、SetHeaderClone / SetFooterClone、あるいはRegisterComponentで登録したファクトリから調達します。登録後はCreateComponent('signature')を呼ぶたびに新しいインスタンスが返ってきます

HotPDF 宣言型レイアウトドキュメントの所有ツリー。セクション、ヘッダー、フッター、テーブル行がそれぞれちょうど 1 つの所有者を持つ
レイアウトツリーのすべてのノードには所有者がちょうど 1 人います。そのためヘルパーは共有参照ではなく新しいインスタンスを返し、繰り返し現れる部品は登録されたファクトリーから、呼び出しごとに新しいコンポーネントとして得られます
uses
  SysUtils, HPDFDoc, HPDFLayoutDOM;

type
  TAssetRow = record                    // 独自のデータ型
    Name, ServiceDate, Status: WideString;
  end;

function BuildMaintenanceReport(const Assets: array of TAssetRow): THPDFDOMDocument;
var
  Doc: THPDFDOMDocument;
  Section: THPDFDOMSection;
  Heading: THPDFDOMText;
  Table: THPDFDOMTable;
  Row: THPDFDOMTableRow;
  I: Integer;
begin
  Doc := THPDFDOMDocument.Create;       // GenerateStructure = True、Language = 'en-US'
  try
    Section := Doc.AddSection;          // 既定はA4縦置き、マージン36 pt
    Section.MarginLeft := 56;
    Section.MarginRight := 56;
    Section.Style.FontName := 'Helvetica';
    Section.Style.FontSize := 10;
    Section.Style.LineHeight := 13;
    Section.Body.Style.Spacing := 6;    // 本文の子要素どうしの間隔
    Section.Footer := THPDFDOMText.Create('Plant maintenance - internal');

    Heading := Section.Body.AddHeading('Annual maintenance report', 1);
    Heading.Style.FontSize := 18;
    Heading.Style.LineHeight := 22;     // LineHeightはFontSizeに追従しない
    Section.Body.AddText('Every asset inspected during the reporting ' +
      'period is listed below, grouped by site.');

    Table := THPDFDOMTable.Create('assets');  // RepeatHeadersは既定でTrue
    Table.AddColumn(3);                 // ポイント幅ではなく重み
    Table.AddColumn(1);
    Table.AddColumn(1);
    Row := Table.AddRow(18, True);      // ヘッダー行は必ず先頭
    Row[0].Text := 'Asset';
    Row[1].Text := 'Last service';
    Row[2].Text := 'Status';
    for I := 0 to High(Assets) do
    begin
      Row := Table.AddRow(16);
      Row[0].Text := Assets[I].Name;
      Row[1].Text := Assets[I].ServiceDate;
      Row[2].Text := Assets[I].Status;
    end;
    Section.Body.Add(Table);            // この行からテーブルは本文の所有物
    Result := Doc;
  except
    Doc.Free;
    raise;
  end;
end;

このリストには、人がひっかかりやすい既定値が2つあります。LineHeightは、スタイルのチェーンのどこでも設定されなければ、FontSizeが何であれ12ポイントに解決されます。そのため独自のLineHeightを持たない18 ptの見出しは12 ptの行間になり、次の見出しと重なります。また、テーブル行の高さはAddRowに渡した高さそのものです。セルのテキストは1行で押し出されるので、行の高さは選んだフォントに合わせて設定してください

Render自体がドキュメントを開き、閉じる

THPDFDOMRenderer.Render(Doc, Pdf)は、ターゲットに対してBeginDocを呼び、全セクションを描画し、戻る前にEndDocを呼びます。自分でBeginDoc / EndDocのペアを囲み込んではいけません。ドキュメント開始前に設定しておくべきものは、すべて先にTHotPDFインスタンスへ設定します。FileName、Title、そして出力にPDF/UAを名乗らせるならPDFUAComplianceです。構造生成が有効なとき、RenderはEnableTaggedPDFも有効にし、空のままにしてあればDoc.LanguageをPdf.Langへコピーします

var
  Doc: THPDFDOMDocument;
  Pdf: THotPDF;
  Renderer: THPDFDOMRenderer;
  Stats: THPDFDOMRenderStatistics;
begin
  Doc := BuildMaintenanceReport(Assets);
  Pdf := THotPDF.Create(nil);
  Renderer := THPDFDOMRenderer.Create;
  try
    Pdf.FileName := 'maintenance-report.pdf';
    Pdf.Title := 'Annual maintenance report';
    Pdf.PDFUACompliance := True;        // 図の代替テキストチェックも同時に有効になる
    // ここにBeginDoc / EndDocは書かない。開閉はRenderが行う
    Stats := Renderer.Render(Doc, Pdf);

    Writeln(Format('%d page(s), %d placement(s), %d split(s)',
      [Stats.PageCount, Stats.PlacementCount, Stats.SplitCount]));
    Writeln(Format('structure elements=%d marked content=%d artifacts=%d',
      [Stats.StructureElementCount, Stats.MarkedContentCount,
       Stats.ArtifactCount]));
    Writeln(Format('header draws=%d footer draws=%d deepest chain=%d',
      [Stats.HeaderDrawCount, Stats.FooterDrawCount,
       Stats.MaximumContinuationDepth]));
  finally
    Renderer.Free;
    Doc.Free;
    Pdf.Free;
  end;
end;

統計レコードは実行のたびにログへ出してください。例外を1つも投げないテンプレートの退行が、ここに顔を出します。テンプレート変更の後にSplitCountが跳ね上がるのは、たいてい、どれかのコンポーネントが以前は収まっていたスペースより高く測定され始めた合図です。MaximumContinuationDepthがじわじわ上昇するのは、1ページあたりに運ぶコンテンツが少なすぎるSplitを持つコンポーネントを指しています。ArtifactCountはページのヘッダーとフッター、テーブルの既定の0.5 pt枠といった装飾罫線、繰り返されるヘッダー行を合わせて数えるので、手計算の目標値ではなく同じテンプレートの実行間で比較します

長いテーブルはどうやって毎ページ自己コピーせずにページ分割するのか?

レンダラーが分割するのは、ページ境界にまたがった部分だけです。ツリーのページ分割を素朴に実装すると、収まらなかったものをクローンして次のページへ運びます。1万行のテーブルでは、残りの行をページごとにクローンすることになり、線形の仕事が2乗の仕事に変わります。HotPDFは本文の子要素をインデックスでたどり、セクションや本文全体をクローンしません。ページ境界をまたぐネストされたスタックやコンテナは、影響を受けた部分木だけをクローンし、重量級の2つの葉型はコピーの代わりにカーソルを持ちます

継続中の段落は、元テキストへの参照と、まだ担っていない文字範囲の組み合わせであり、その幅で計算済みの改行位置を再利用します。継続中のテーブルは、元テーブルへの参照と、まだ配置していない行スライスの組み合わせです。300行の段落は、1回に分割されようが5回に分割されようがコストは変わりません

HotPDF における、サブツリー全体クローンによる 2 次的な改ページコストと、狭いページ境界分割によるフラットな線形コストを対比する棒グラフ
またがったページごとに未配置のサブツリー全体を複製すると、追加の行が二次時間の仕事になります。狭い分割なら、長文は文字範囲カーソルを、テーブルは行スライスカーソルを担えます

配置そのものは公開ルーチンのTHotPDF.PlaceLayoutElementを通ります。このルーチンは要素を残り本文高さに対して測定し、収まるなら丸ごと描き、収まらなければSplitを求め、配置した側を再測定して描き、残りをオーバーフローオブジェクトとして返します。レンダラーはそれを新しいページへ運びます。Measureが描画を行ってはいけないのは重要で、1回の配置のために何度も走ることがあります。DOMレンダラーは、そのルーチンの上にページ装飾、子要素間の間隔、新規ページの判断を積み上げます

なぜヘッダー行1つでレンダリング全体が止まり得るのか?

テーブルヘッダーの繰り返しには2つの規則が伴い、どちらもレポートがデータのないページを生み出すのを防ぐために存在します。ヘッダー行は行の先頭の連なりでなければなりません。本文行の後でAddRow(Height, True)を呼ぶと、"Table header rows must precede body rows"というEInvalidOpExceptionが上がります。さらにテーブルの最初の分割は、すべてのヘッダー行と少なくとも1つの本文行を収めなければなりません。ヘッダーをページの下段に取り残すことになるテーブルは、代わりに次のページへ移動します

2つ目の規則には厳しい決まりがあります。ヘッダー行に本文行を1行足しても空のページにすら収まらない場合、そのテーブルを始められるページはどこにもなく、Renderがコンポーネントパス付きで"Layout component ... cannot fit an empty body page"を上げます。パスの例はSections[0]/Body/Items[2]/assetsです。これこそ望ましい挙動です。次のページならもっと広いはずだとページを追加し続けるレイアウトエンジンは、1個の巨大すぎるヘッダーを、ディスクを食い潰すループに変えてしまいます

カスタムコンポーネントも同じ保護を受けます。THPDFDOMComponentを継承してClone、Measure、Draw、Splitを実装すれば、レンダラーは本文の子ごとに何個の継続が生まれたかを数えます。THPDFDOMRenderer.MaximumContinuationDepth(既定で100,000)を超えると、レンダリングは"exceeded the continuation depth limit"で止まります。同等の末尾を返し続けて前に進まないSplitは、ディスクが満杯になるまで走るのではなく、コンポーネントパス付きで失敗します

継続ページではヘッダー行が/Artifactのマークコンテンツ列の中に再描画され、構造ツリーは元のTRを1回だけ保持します。そのためテキスト抽出がデータ行の間に重複したヘッダー行を挿入することはなく、支援技術もテーブルの途中でもう一度列見出しを読み上げることはありません。各ヘッダーセルは/Scope /Column属性付きのTHとしてタグ付けされます

1つの論理段落、複数のページ断片

分割された段落は1つのP構造要素のままです。見えている断片ごとに、そのページ上で新しいマークコンテンツ列が開き、HotPDFはマークコンテンツ参照ディクショナリ<< /Type /MCR /Pg page /MCID n >>をその要素の/K配列へ追加し、そのMCIDをページのParentTreeエントリに、同じ要素を指す形で登録します。これはISO 32000-1 §14.7.4が、ページにまたがって散らばるコンテンツ項目について説明している構成そのものです。ページ上は2つに見えても、タグツリーのビューでは1つの段落として見えるのはこのおかげです

継続によるコピーが、自分で作るクローンと違う振る舞いをするのは、意味的アイデンティティがあるからです。Cloneの呼び出しは「新しい論理コンテンツ」を意味し、その結果は描画されるとき新しい構造要素を得ます。一方、ページ分割中に作られるコピーは、継続元のコンポーネントのアイデンティティを引き継ぎます。3ページにまたがって分割されたスタックでもDivは1つのまま、2ページに分かれたリストでもLは1つのままです。ページのヘッダーとフッターは別ルートを通り、毎ページ/Artifact << /Type /Pagination /Subtype /Header >>(または/Footer)として包まれ、構造ツリーには決して入りません

HotPDF の図。1 つのタグ付き段落が単一 PDF 構造要素として保持され、その 2 つのページ断片は別々の marked-content 識別子を持ち、再描画されたヘッダーはアーティファクトとしてタグ付け
1 つの段落の断片は、K 配列に集められた Pg と MCID のペアを通じて 1 つの構造要素を共有します。続きのページに再描画されるヘッダーは、コンテンツではなくアーティファクトとして一緒に運ばれます

ツリーがレンダリングされている最中にチェックされる構造規則

GenerateStructureを有効にすると、レンダラーはPDF/UA検証が後で拒否するはずの構造を受け付けません。最初の見出しはH1でなければならず、以降の見出しはレベルを飛ばせません。したがってH1の直後にH3を置くと"Semantic heading levels cannot skip an intermediate level"が上がります。LIにはLの親が、LblとLBodyにはLIの親が、TRにはテーブルか行グループが、TH / TDにはTRの親が必要です。ターゲットにPDFUAComplianceが設定されている場合、代替テキストのないFigureも拒否されます。どの違反も、例外でRenderを止めます

var
  List: THPDFDOMList;
  Bmp: TBitmap;                         // Vcl.Graphics
begin
  Section.Body.AddHeading('Findings', 2);     // 先にH1があるのでH2は妥当

  List := THPDFDOMList.Create('Decimal');     // Lとしてタグ付け、ListNumbering /Decimal
  List.AddItem('1.', 'Replace the intake filter on pump P-14');
  List.AddItem('2.', 'Re-torque the flange bolts on line 3');
  Section.Body.Add(List);                     // AddItemがLI、Lbl、LBodyを組み立てる

  Bmp := TBitmap.Create;
  try
    Bmp.LoadFromFile('site-plan.bmp');
    // 画像はグラフィックをコピーする。空の代替テキストはPDFUACompliance下で失敗する
    Section.Body.Add(THPDFDOMImage.Create(Bmp, 240, 160,
      'Site plan of plant 3 with the inspected pumps circled'));
  finally
    Bmp.Free;
  end;
end;

これらの規則をチェックするのは、レンダリング中が適切です。理由はタイミングです。ファイルの書き出し後に代替テキストの欠落を報告するバリデーターは、1万通の明細書バッチの再生成が必要だと告げるだけです。一方Render中の例外は、原因となったレコードがまだスコープ内にあるうちに、違反した規則を名指しします。正式な適合性チェックはそれでもパイプラインに属しますが、Renderが返った後もドキュメントのオブジェクトは読めるままなので、すぐそこで実行できます。PDF/A、PDF/X、PDF/UAの検証がそのステップを扱い、構造の順序とテキスト抽出は、タグツリーが抽出ツールの読み戻しをどう導くかを示します

手描画を続けるべきとき

ツリーは、直接APIと同じTHPDFPageオブジェクトの上に描きます。RenderがBeginDocからEndDocまでドキュメントを所有するため、署名画像のような手動配置のアートワークはツリーの中に置くのが正解です。カスタムコンポーネントのDrawはページとその境界を受け取るので、そこで通常のページメソッドを呼べます。ページのクローズはAddPageとEndDocの管轄のままなので、THotPDFインスタンスにImmediateFlushLayoutを設定しておけば、完成したページは描画の進行に合わせて書き出され、レンダラーは完成済みページを保持しません。メモリ消費は開いた継続、フォントリソース、ドキュメントのオブジェクトグラフ次第です

DOMのテキストコンポーネントは、1文字あたり平均0.55 × フォントサイズという概算で行を折り、各行に解決済みのLineHeightを与えます。測定は安価で、どのマシンでも同じ結果になり、データ駆動のレポートには十分です。オールキャップス、ボールド連続、CJKのような幅広グリフを含むテキストは概算より広くなるので、そういう列幅には余裕を残し、一番長い実文字列で一度レイアウトを試してください。正確なグリフメトリクス、1行内でのフォント混在、両端揃えの段落を含む組版ページは、直接テキストAPIのほうが向いています。テキストの行揃えがその道筋を解説し、悩みがテーブルのページ分割だけなら、PDFでのテーブル生成のほうが小さな変更で済みます

レイアウトツリー、そのレンダラー、ここで説明したタグ付け、直接描画APIは、DelphiおよびC++Builder向けの1つのコンポーネントにすべて同梱されています。エディションと完全な機能一覧は、HotPDF Delphi PDFコンポーネントページに掲載されています