Aspose.PDF FOSS
TypeScript
TypeScriptでPDF構造を扱う方法

TypeScriptでPDF構造を扱う方法

このガイドでは、Aspose.PDF FOSS for TypeScript を使用して PDF ファイル内に文書ナビゲーションと論理構造を構築する方法を示します。ページ上のクリック可能な目次、文書レベルのブックマークアウトライン、名前付きデスティネーション、アクセシビリティ用のタグ付けされた構造ツリーが含まれます。Node.js 22 以降が必要です。

ステップバイステップガイド

ステップ 1: パッケージをインストールする 

git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run build

パッケージがインストールされたら、新しい TypeScript ファイルで Document クラスをインポートしてインストールを確認してください — この行はエラーなく解決されるはずです：

import { Document } from '@asposefoss/pdf';

ステップ 2: 必要なクラスをインポートする

ファイルを開くには Document をインポートし、ステップ4で作成されたブックマークエントリには OutlineItem を使用します:

import { Document, OutlineItem } from '@asposefoss/pdf';

ステップ3: 目次を追加

Page.AddTOC() は { title, page } エントリの配列、境界 rect、およびスタイルオプションを受け取り、点線リーダーと対象ページへのクリック可能なリンクを描画します:

const page = doc.Pages[0];

page.AddTOC(
  [
    { title: '1.  Introduction', page: 2 },
    { title: '2.  Methodology', page: 5 },
    { title: '3.  Results', page: 9 },
  ],
  [72, 160, 400, 600],
  { font: 'Helvetica', fontSize: 13, color: [0.1, 0.1, 0.15], rowGap: 18 },
);

ステップ4: ブックマークを追加

Document.SetOutlines() はドキュメントのブックマークパネルを OutlineItem オブジェクトの配列に置き換えます。各項目は Dest（ページ先）やスタイリング（Color、Bold）を持ち、折りたたみ可能なツリー用のネストされた Children を含めることができます:

const items: OutlineItem[] = [
  { Title: 'Sales', Dest: { name: 'section.sales' }, Open: true, Color: [0.1, 0.4, 0.1] },
  { Title: 'Appendix', Dest: { name: 'section.appendix' } },
];

doc.SetOutlines(items);

ステップ5: アウトラインと名前付きデスティネーションを読み取る

Document.GetOutlines() は現在のブックマークツリーを返します。Document.GetNamedDestinations() はドキュメントに登録されたすべての名前付きデスティネーションを返します — これにより、すべてのアウトラインターゲットと目次リンクが実際に実在するページに解決されるかを検証するのに役立ちます:

const destNames = new Set(doc.GetNamedDestinations().map((d) => d.name));

const walk = (nodes: OutlineItem[]): void => {
  for (const item of nodes) {
    if (item.Dest && 'name' in item.Dest) {
      console.log(destNames.has(item.Dest.name), item.Title);
    }
    if (item.Children) walk(item.Children);
  }
};
walk(doc.GetOutlines());

ステップ6: タグ付き構造ツリーを構築

Document.GetStructTree() は既存の構造ツリーを返します（ドキュメントがタグ付けされていない場合は null）。StructTreeRoot.Append(tag) は 'H2' や 'P' のような子要素を追加し、StructElement を返し、StructElement.MarkContent(page, quad) はその要素を説明するページコンテンツと関連付けます：

function tagPage(doc: Document, page: Page, headingText: string): void {
  const root = doc.GetStructTree();
  if (!root) throw new Error('tagPage: the document is not tagged yet');

  for (const block of page.GetStructuredText()) {
    const text = block.text.trim();
    if (text.length === 0) continue;
    const el = root.Append(text.startsWith(headingText) ? 'H2' : 'P');
    el.MarkContent(page, block.quad);
  }
}

一般的な問題と対策

Document.GetStructTree() returns null. ドキュメントはまだタグ付けされていません — 呼び出す Document.CreateStructTree() (または Document.AutoTag()) 手動で要素を作成する前に StructTreeRoot.Append() / StructElement.MarkContent().

アウトライン項目が正しいページにジャンプしません。 OutlineItem.Dest 実際に存在する宛先を指定しなければなりません — クロスチェック item.Dest.name against Document.GetNamedDestinations() ステップ5に示されているように、保存する前に。

Page.AddTOC() エントリが間違ったページを指しています。 page 各目次エントリにおいて、対象ページ自身のページ番号です — それと照合してください page.Number 実際のターゲット上で Page, 想定された配列インデックスではなく。

ブックマークは後の Document.SetOutlines() 呼び出し。 SetOutlines() ブックマークツリー全体を置き換えます — 現在のツリーを次のように読み取ります Document.GetOutlines() まず配列を変更し、ブックマークを置き換えるのではなく追加する場合は、配列全体を返します。

よくある質問

ブックマークはすでに展開された状態で開くことができますか？

はい — Open: true を OutlineItem に設定すると、そのノードの子がデフォルトでブックマークパネルに表示されます。

ブックマークと名前付きデスティネーションの違いは何ですか？

ブックマーク（OutlineItem）はナビゲーションパネルに表示されるエントリです。名前付きデスティネーション（Document.GetNamedDestinations() / SetNamedDestination()）は、ブックマーク、目次エントリ、またはリンク注釈が名前で指すことのできる、内部で再利用可能なページターゲットです。

ドキュメントにタグ付けすると見た目が変わりますか？

いいえ — 構造ツリー（StructTreeRoot, StructElement）は、読順と意味論を記述する並行的な論理層であり、ページの可視コンテンツは変更しません。

ブックマークを入れ子にできますか？

はい — Children を OutlineItem に設定し、さらに OutlineItem オブジェクトの配列にすることで、折りたたみ可能な多層ツリーを構築できます。

参照

 日本語