Aspose.PDF FOSS for TypeScript の Core Document と Page API

はじめに

TypeScript 用 Aspose.PDF FOSS のすべての機能は、2 つのクラス、Document と Page を通じて実現されます。Document はページコレクションとドキュメントスコープのすべて（メタデータ、ブックマーク、ページラベル、保存/読み込み）を管理し、一方、doc.Pages の各 Page はそのページ単位でスコープされたすべて（コンテンツ、アノテーション、フォームフィールド）を管理します。これら 2 つのクラスに慣れれば、ライブラリの残りの機能—変換、アノテーション、フォーム、セキュリティ—は実質的に同じ 2 オブジェクト上の追加メソッドにすぎません。

この投稿は、introductory post がさりげなく言及したコア機能の一部を詳しく見ていきます：他のドキュメントから文書を組み立てること、何もない状態からページを作成すること、ナビゲーション用のブックマークツリーを追加すること、アクセシビリティのためにコンテンツにタグ付けすることの4つです。これら4つはすべて単純なメソッド呼び出しです — 別途インポートするモジュールは不要で、@asposefoss/pdf パッケージ自体以外の余分な依存関係もありません。

PDF パイプラインが「ファイルを開き、変更し、保存する」段階を超えると出てくる操作です：複数のソースからレポートを結合して 1 つのドキュメントにすること、テンプレートから始めるのではなくプログラムでページを生成すること、そして出力を単に見た目が正しいだけでなく、ナビゲート可能でアクセシブルにすることです。

含まれるもの

文書の組み立てと再編成

Document.Split() は文書をページ順に、ページごとに新しい単一ページの Document に分割します。Document.ExtractPages() は指定された 1 ベースのページ番号の集合を、新しい自己完結型の Document に、指定された順序でコピーします — 同じページを繰り返し含めることも可能です。ある文書のページは別の文書へもコピーできます：Document.Append() はソース文書のすべてのページをターゲットの末尾にコピーし、Document.InsertPage() は特定の 1 ベース位置に単一ページを文書間でコピーします。

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

const report = Document.OpenFile('report.pdf');

const parts = report.Split();                      // one Document per page
const chapter = report.ExtractPages([3, 4, 5]);     // subset (1-based, repeats allowed) as a new Document

const cover = Document.OpenFile('cover.pdf');
report.InsertPage(1, cover.Pages[0]);               // copy a single page across documents
report.Append(chapter);                             // copy chapter's pages onto report

report.WriteTo('assembled.pdf');

複数のドキュメントは、Document.Merge() を使用した単一の呼び出しでも 1 つに結合できます。Document.Merge() は、渡されたすべてのドキュメントの各ページのコピーから順に新しい Document を構築します。

ページをゼロから構築する

Document.New() は何もない状態からドキュメントを作成します。フォーマットが省略された場合はページ数 0、フォーマットが指定された場合はその PageFormat の空白ページが 1 枚作成されます。追加の空白ページは Document.AddPage() から取得でき、PageFormat（またはサイズをコピーする既存の Page）も受け付けます。テキストは Page.AddText() でページに描画され、PDF ユーザースペースの (x, y) 座標に配置されます。

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

const doc = Document.New(PageFormat.A4);          // one blank A4 page
doc.Pages[0].AddText('Hello', 72, 720, { fontSize: 14 });
doc.AddPage(PageFormat.A4.landscape());           // append more as you go
doc.WriteTo('scratch.pdf');

ブックマークとドキュメントナビゲーション

ドキュメントアウトライン（多くの PDF リーダーがページ横に表示するブックマークパネル）は Document.GetOutlines() で読み取られ、Document.SetOutlines() に全体的に置き換えられます。どちらも OutlineItem のツリーを扱います。各 OutlineItem は Title、Dest の宛先、オプションで入れ子エントリ用の Children を保持し、さらに Open（デフォルトで展開）や Bold といった表示ヒントを含みます。

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

const items: OutlineItem[] = [
  { Title: 'Introduction', Dest: { name: 'intro' } },
  {
    Title: 'Chapters',
    Open: true,
    Children: [
      { Title: 'Chapter 1', Dest: { name: 'ch1' } },
      { Title: 'Chapter 2', Dest: { name: 'ch2' } },
    ],
  },
];
doc.SetOutlines(items);

このように名前付けされた宛先（{ name: 'intro' }）は、ドキュメントの名前付き宛先テーブルを介して解決されます。Document.GetNamedDestinations() と Document.SetNamedDestination() は、ブックマークがページコンテンツに結び付かない宛先を指す必要がある場合に、直接このテーブルを管理します。

構造化テキストとアクセシビリティタグ付け

Document.GetStructTree() はドキュメントの論理構造ツリーを返します（ドキュメントにタグが付いていない場合は null）。Document.CreateStructTree() はツリーを構築し、ドキュメントに Tagged のマークを付けます。構造ツリーが存在すると、Page.GetStructuredText() はページのテキストを TextBlock 値として返します――位置情報が付与されたフラグメントがすでに行や段落のようなブロックにまとめられた形です――これは手動タグ付けパスの入力となります：ブロックを走査し、見出しか本文かを判定し、対応する要素をツリーに追加します。

function handTagPage(doc: Document, page: Page, heading: string): void {
  const root = doc.GetStructTree();
  if (!root) throw new Error('handTagPage: 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(heading) ? 'H2' : 'P');
    el.MarkContent(page, block.quad);
  }
}

タグ付けされた構造ツリーは、下流の機能が構築する基盤です。セマンティック HTML エクスポートは、単純なヒューリスティックレイアウトにフォールバックする代わりに、そこから再フローされ、Document.ValidatePdfUa() はタグ付けが存在することに依存する PDF/UA アクセシビリティ標準のサブセットに対して文書をチェックします。

クイックスタート

パッケージをインストールし、ドキュメントを開いて、そのページのサブセットを抽出して再結合し、結果を保存します：

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

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

const doc = Document.OpenFile('report.pdf');

const chapter = doc.ExtractPages([3, 4, 5]);   // subset (1-based, repeats allowed) as a new Document
const cover = Document.OpenFile('cover.pdf');

doc.InsertPage(1, cover.Pages[0]);             // copy a single page across documents
doc.Append(chapter);                           // copy chapter's pages onto doc

doc.WriteTo('assembled.pdf');

サポートされているフォーマット

オープンソースとライセンス

Aspose.PDF FOSS for TypeScript は MIT ライセンスの下でリリースされ、ソースは GitHub に公開されています。評価用の透かしや使用制限、別個のライセンスファイルは存在せず、ロイヤリティなしで商用製品にライブラリを使用できます。

このパッケージは現在バージョン 0.1.0 で、アクティブな初期開発段階を示しています。Node.js (>=22) が唯一のランタイム要件であり、パッケージは他のサードパーティ依存関係を持ちません。

入門

• はじめに
• 開発者ガイド
• KB 記事
• API Reference

関連リソース

• Aspose.PDF Enterprise Product Family
• Aspose.PDF — Enterprise Blog