技術記事

Delphi で PDF のブックマークと注釈アクションを読み取る

上流工程から PDF のフォルダを引き継ぎ、「どのブックマークが外部 URL に飛ぶか、どれが JavaScript を実行するか、内部ジャンプは実際にはどこに着地するか教えてほしい」という依頼を受けたとします。一見単純な仕事です。ところが API リファレンスを開いてみると、ライブラリはそうしたアクションをすべて作成できるのに、読み戻す手段は何も用意していないことに気付きます。この非対称性は PDF ツールリングの至るところにあります。https://example.com を開くブックマークの書き込みは 1 行で済みますが、既存のブックマークに「何をするのか、ターゲットはどこか」と尋ねるには、/A、/S、/Dest と、ほとんどの人が最初の 1 回で正しく扱えないフィットタイプのバリエーション群を、生のオブジェクトツリーで手作業たどることになりがちです

PDF Library for Delphi は Delphi と C++Builder 向けのネイティブ Object Pascal PDF ライブラリで、書き込み側のセッターに加えて、v3.77.0 から利用できる少数の型付きイントロスペクション呼び出しを提供しています。これらはアクションの種類、アクションのペイロード、移動先のジオメトリを、掘り起こすための生の TPDFObject ではなくプレーンなレコードとして報告します。本記事では、これらの呼び出しが ISO 32000-1 のアクションと移動先のモデルにどう対応するか、そして手書き実装が静かに誤動作する 3 つの具体的な罠を解説します

アクションの読み取りが書き込みより難しい理由

PDF のアクションはサブタイプを示す /S キーを持つ辞書です。GoTo、GoToR、URI、Launch、Named、JavaScript、そしてめったに出会わない長い尾続きがあります(ISO 32000-1 §12.6.4)。面倒なのは、ペイロードがサブタイプごとに異なるキーに入っており、「ターゲットをくれ」という一律のスロットが存在しないことです。URI アクションはアドレスを /URI に保持します。GoToR や Launch アクションはファイル指定を /F に保持します。JavaScript アクションはスクリプトを /JS に保持し、文字列の場合もストリームの場合もあります。GoTo アクションはそれ自身のペイロードをまったく持ちません。ターゲットは移動先で、/D にぶら下がっており、別途解決する必要があります

書き込むときは種類を最初から知っているので、これらは問題になりません。読み取るときは、まず /S で分岐し、次に適切なキーへ手を伸ばし、そのうえで「このアクションが指すもの」という同じ論理概念が 3 つの互換性のない形でエンコードされている事実も処理しなければなりません。この分岐こそ、型付きゲッターが吸収してくれる部分です。GetOutlineActionInfo と GetAnnotActionInfo はどちらも TPDFlibActionInfo レコードを返します:

type
  TPDFlibActionKind = (akNone, akGoTo, akGoToR, akURI,
                       akLaunch, akNamed, akJavaScript);

  TPDFlibActionInfo = record
    Kind: TPDFlibActionKind;
    URI: AnsiString;          // akURI 用に設定される
    JavaScript: WideString;   // akJavaScript 用に設定される
    FileName: AnsiString;     // akGoToR / akLaunch 用に設定される
    OpenInNewWindow: Boolean; // akGoToR / akLaunch
  end;

レコードは Kind によって、どのフィールドが意味を持つかを教えてくれます。Kind が akURI なら URI を読み、残りは無視します。akGoTo ならペイロードフィールドはどれも当てはまらず、次の移動先へ進みます。移動先は別の呼び出しで、後ほど扱います。akNone は、ブックマークや注釈にアクションがまったくないときの正直な答えであり、意味を推測しなければならないゼロではありません

アウトラインツリーをたどってブックマークを見つける

ブックマークをイントロスペクトするには、まずそのハンドルが必要です。PDF Library for Delphi はアウトラインノードを整数 ID で識別し、FindOutlineByTitle が表示テキストでノードを特定します。検索の及ぶ範囲は明示的に制御できます:

type
  TPDFlibOutlineSearchDepth =
    (osdSiblingsOnly, osdChildrenOnly, osdFullSubTree);

function FindOutlineByTitle(const Title: WideString;
  StartOutlineID: Integer;
  Depth: TPDFlibOutlineSearchDepth): Integer;

Depth 引数は立ち止まる価値のある部分です。osdSiblingsOnly は開始ノードと同じレベルの兄弟チェーンを走査して止まります。兄弟ブックマークは見つけますが、兄弟の子へは決して降りません。osdChildrenOnly は 1 つ下のレベル、開始ノードの直接の子を見ます。osdFullSubTree は枝全体を再帰します。間違えた場合の症状はエラーではなく静かな取りこぼしです。2 レベル深いところにあるタイトルを兄弟限定で検索すると、単に 0 が返り、ブックマークはずっとそこにあったのに存在しないと結論してしまいます。文書ルートから検索するには開始 ID に GetFirstOutline を渡します

var
  Lib: TPDFlib;
  FoundID: Integer;
begin
  Lib := TPDFlib.Create;
  try
    if Lib.LoadFromFile('report.pdf', '') = 1 then
    begin
      // ルートからツリー全体を検索し、入れ子のブックマークを探す。
      FoundID := Lib.FindOutlineByTitle('Appendix B',
        Lib.GetFirstOutline, osdFullSubTree);
      if FoundID <> 0 then
        // FoundID はこの後のアクション取得、
        // 移動先取得の各ゲッターに渡せるハンドルです。
        ;
    end;
  finally
    Lib.Free;
  end;
end;

マッチングはタイトル文字列の完全一致で、WideString として比較されます。大文字小文字を区別し、保存されている Unicode テキストをそのまま扱います。ソースの PDF がばらばらのプロデューサーから来ているなら、検索するタイトルは文書が保存したのと同じ形に正規化してください。そうしないと、実在しない取りこぼしを追い回すことになります

ブックマークのアクションとターゲットを解決する

ハンドルが手元にあれば、GetOutlineActionInfo が型付きの見方を提供します。パターンは、呼び出し、Kind による分岐、その種類が設定するフィールドの読み取り、です

var
  Info: TPDFlibActionInfo;
begin
  Info := Lib.GetOutlineActionInfo(FoundID);
  case Info.Kind of
    akURI:
      Writeln('Opens URL: ', Info.URI);
    akGoToR, akLaunch:
      Writeln('Opens file: ', Info.FileName,
        ' (new window: ', Info.OpenInNewWindow, ')');
    akJavaScript:
      Writeln('Runs script: ', string(Info.JavaScript));
    akGoTo:
      Writeln('Jumps within this document');  // 移動先は下記を参照
    akNamed:
      Writeln('Named action (NextPage, Print, etc.)');
    akNone:
      Writeln('Bookmark has no action');
  end;
end;

ここに最初の本物の罠があります。古いゲッター GetActionURL が存在し、URI アクションを読むのにそれへ手を伸ばすのが見た目上の典型的な誤りです。GetActionURL は /F キーを通してファイル指定を解決します。GoToR と Launch にとってはそれが正しいのです。ターゲットが本当にファイルだからです。しかし URI アクションにはまったく違うキーが正解になります。URI アクションのアドレスは、アクション自身の /URI キーに置かれたプレーンな文字列であり、ファイル指定ではありません。URI アクションをファイル指定の経路に通すと、空の結果か無意味な結果が返ります。型付きゲッターはこの判断を内部で処理します。akURI では /URI を直接読み、ファイル指定リゾルバを呼ぶのは akGoToR と akLaunch だけです。手書き実装が曖昧にしがちな区別が、まさにここです

移動先のフィットタイプと背後にあるジオメトリ

akGoTo アクションは「この文書内で移動する」ことを意味しますが、どこへ、どのように については何も語りません。それが移動先の仕事で、移動先は人が思うより繊細です。PDF の移動先は単なるページ番号ではありません。ページと、ビューアがそのページをどう枠取るべきかを示す「フィット」仕様の組み合わせです(ISO 32000-1 §12.3.2.2)。GetOutlineDestinationInfo はこれをレコードで返します:

type
  TPDFlibDestinationKind = (dkNone, dkXYZ, dkFit, dkFitH,
    dkFitV, dkFitR, dkFitB, dkFitBH, dkFitBV);

  TPDFlibDestinationInfo = record
    Kind: TPDFlibDestinationKind;
    Page: Integer;   // 1 起点。未解決のときは 0
    Left, Top, Right, Bottom, Zoom: Double;
  end;

8 つのフィット種別は、それぞれ異なる枠取りの問いに答えます。dkXYZ は特定の点を明示的なズームで左上に置くので、Left、Top、Zoom を使います。dkFit はページ全体をウィンドウに収め、座標を無視します。dkFitH と dkFitV はページ幅か高さを、単一の意味のある座標(上端または左端)で合わせます。dkFitR が興味深い種別です。指定された矩形を合わせるので、4 つの端すべてが意味を持ちます。dkFitB* 系は同じことを、ページ全体ではなく可視コンテンツのバウンディングボックス基準で行います。種類ごとにどのフィールドが生きているかを知っていることが、移動先を正しく読むことと、たまたまゼロになっているガラクタ座標を印字することの分かれ目です

入れ子のアウトライン ツリーを表示する PDF リーダーのブックマーク ナビゲーション パネル
このナビゲーション パネルの各ブックマークはアクションに解決され、内部ジャンプの場合は固有のフィット タイプと座標を持つ移動先に解決されます

実装の内部では、この対応関係が信頼できる理由を説明する、意図的なアラインメントに支えられています。内部の GetDestType は 8 つのフィット種別に対して 1 から 8 の整数を、正確に XYZ/Fit/FitH/FitV/FitR/FitB/FitBH/FitBV の順で返します。TPDFlibDestinationKind はその序数が 1 対 1 で並ぶよう宣言されています。dkXYZ は序数 1、dkFitBV は序数 8、dkNone はゼロの位置です。したがって変換は範囲ガード付きの直接的な序数キャストであり、列挙型が育っても同期を外れることがあるルックアップテーブルではありません。小さな細部ですが、素朴に実装すると、誰かが列挙を並べ替えた最初の時点でオフバイワンのバグになる類のものです

var
  Dest: TPDFlibDestinationInfo;
begin
  Dest := Lib.GetOutlineDestinationInfo(FoundID);
  if Dest.Page = 0 then
    Exit;  // 移動先が解決できなかった
  case Dest.Kind of
    dkXYZ:
      Writeln(Format('Page %d at (%.0f, %.0f), zoom %.2f',
        [Dest.Page, Dest.Left, Dest.Top, Dest.Zoom]));
    dkFitR:
      Writeln(Format('Page %d, rect L%.0f T%.0f R%.0f B%.0f',
        [Dest.Page, Dest.Left, Dest.Top, Dest.Right, Dest.Bottom]));
    dkFit, dkFitB:
      Writeln(Format('Page %d, fit whole page', [Dest.Page]));
  else
    Writeln(Format('Page %d, fit kind %d',
      [Dest.Page, Ord(Dest.Kind)]));
  end;
end;

Page がゼロなのは、移動先が解決しなかった合図です。多くの場合、アクションが移動先を運んでいないか、名前付き移動先が見つからなかったためです。座標を信用する前に必ず確認してください。あわせて知っておくべきなのは、GetOutlineDestinationInfo が移動先のありうる両方の場所を調べることです。ブックマークの /Dest 直下と、埋め込まれた GoTo アクションの /D の中です。プロデューサーがどちらの形を使ったかを知っている必要はありません

注釈アクションと SelectPage の罠

リンク注釈はブックマークとまったく同じようにアクションを運び、GetAnnotActionInfo は同じ TPDFlibActionInfo レコードを、同じ「種別が先、ペイロードが後」のパターンで返します。ただしアウトラインにはないステートフルな注意点があり、これが 3 つ目の罠です

注釈はページに属します。PDF Library for Delphi は現在ページの注釈を、そのページを選択した後にだけ有効になる状態で公開します。SelectPage(N) を先に呼ばずに GetAnnotActionInfo を呼ぶと、注釈ハンドルはゼロで、呼び出しは akNone を返します。そのページに操作可能な注釈がないと誤って結論してしまうのです。修正は 1 行ですが、ページをループしていると忘れやすいものです:

var
  P: Integer;
  Info: TPDFlibActionInfo;
begin
  for P := 1 to Lib.PageCount do
  begin
    Lib.SelectPage(P);   // 注釈に触れる前に必須
    // GetAnnotActionID(1) <> 0 が確実な「アクションを持つ」
    // 判定。CheckPageAnnots はブール風のフラグを返すだけで
    // 数ではないため、ここでは弱いシグナルです。
    if Lib.GetAnnotActionID(1) <> 0 then
    begin
      Info := Lib.GetAnnotActionInfo(1);
      if Info.Kind = akURI then
        Writeln(Format('Page %d link -> %s', [P, Info.URI]));
    end;
  end;
end;

このループには意図的な点が 2 つあります。第 1 に、SelectPage(P) が毎回の反復で注釈アクセスの前に来ています。ページごとの注釈状態は引き継がれません。第 2 に、存在テストは CheckPageAnnots ではなく GetAnnotActionID(1) <> 0 を使っています。後者はプレゼンスを数ではなくブール風のフラグで報告するため、「最初の注釈が存在し、読めるアクションを運んでいるか」という問いには、非ゼロのアクション ID の方が精密な聞き方です。もう 1 つ付言すると、注釈の JavaScript アクションのスクリプトは /JS から直接読まれます。スクリプトがストリームで保存されていればデコードし、文字列ならそのまま読みます。よくある 2 つのエンコーディングのどちらでも生き残ります

読み取り側イントロスペクションの位置づけ

これらのゲッターは意図的に狭い用途に絞られています。ライブラリの既存の整数ハンドル方式のアクション層と移動先層の上に築かれた純粋な読み取りであり、書き込み経路には触れず、同時に編集中の文書へリスクを追加しません。ファイルの中身を報告するだけで、ポリシーに対する検証も何の書き換えもしません。逆の目的、つまり最初からこれらのアクションを運ぶブックマークやリンク注釈を作りたい場合は、書き込み側の仕事で、Delphi でのインタラクティブフォームアクションと JavaScript の解説が作成の手順を扱っています。ナビゲーショングラフではなく可視コンテンツや構造コンテンツを PDF から取り出したい場合は、PDF Library for Delphi でのテキスト、画像、フォントの抽出を参照してください

心得ておくべき正直な境界があります。イントロスペクションは、プロデューサーが実際に書き込んだものしか見えません。ジェネレーターがアクションを不正な形で書き出したブックマークや、定義されていない名前付きターゲットを指す移動先は、例外ではなく akNone やゼロページとして現れます。信頼できないファイルを監査する読み取り API としては正しい挙動ですが、その分、コードではこうしたゼロ結果を「存在しないか未解決である」と扱うべきであり、入力の整形済みを保証するものとしては扱わないでください。ここで示した型付きのアクションと移動先のイントロスペクションは、Delphi と C++Builder 向けネイティブ PDF ライブラリ PDF Library for Delphi の一部です