Aspose.PDF FOSS
TypeScriptでアノテーションを扱う方法

TypeScriptでアノテーションを扱う方法

このガイドでは、TypeScript 用の Aspose.PDF FOSS を使用して PDF アノテーションを追加、フラット化、検索する方法を示します。Page クラスは、アノテーションのサブタイプごとに 1 つの Add* メソッドを公開します — マークアップ（ハイライト、下線、取り消し線、波線）、シェイプ（四角形、円、線、多角形、インク）、テキスト（付箋、フリーテキスト）、リンク — それぞれが型付けされた Annotation ハンドルを返し、後で読み取りまたはフラット化できます。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 をインポートし、以下の手順で使用するアノテーションタイプのシグネチャには Page を使用します:

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

ステップ 3: マークアップ アノテーションを追加

Page.AddHighlight()、Page.AddUnderline()、Page.AddSquiggly()、および Page.AddStrikeOut() はすべて、quads 配列を受け取ります — ハイライトされたテキスト領域ごとに 8 数字のクアッド (x1,y1,x2,y2,x3,y3,x4,y4) が 1 つ — 加えて color とオプションの contents。ライブラリは、4 つのサブタイプすべてについて外観ストリーム (/AP) を自動的に生成します:

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

const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];

page.AddHighlight({
  quads: [72, 700, 300, 700, 72, 685, 300, 685],
  color: [1, 1, 0],
  contents: 'Yellow highlight',
});
page.AddUnderline({
  quads: [72, 660, 300, 660, 72, 645, 300, 645],
  color: [0, 0, 1],
});
page.AddStrikeOut({
  quads: [72, 620, 300, 620, 72, 605, 300, 605],
  color: [1, 0, 0],
});

doc.WriteTo('annotated.pdf');

ステップ 4: シェイプおよびインク アノテーションを追加

Page.AddSquare() と Page.AddCircle() はバウンディング rect と color（ストローク）およびオプションの fill を受け取ります。Page.AddLine() は 4 数字の line（x1,y1,x2,y2）とオプションの矢印端を受け取ります。Page.AddInk() は paths を受け取ります — ペンストロークごとにフラットなポイントペア配列の配列です:

page.AddSquare({ rect: [100, 500, 220, 560], color: [0.8, 0, 0], fill: [1, 1, 0.5], width: 2 });
page.AddCircle({ rect: [250, 500, 370, 560], color: [0, 0.5, 0], width: 2 });
page.AddLine({
  line: [100, 470, 370, 470],
  color: [0, 0, 0.7],
  width: 2,
  startEnding: 'OpenArrow',
  endEnding: 'ClosedArrow',
});
page.AddInk({
  paths: [[100, 400, 130, 430, 160, 390, 190, 420]],
  color: [0.6, 0, 0.6],
  width: 2,
});

ステップ 5: 付箋とフリーテキストを追加

Page.AddTextNote() はクリック可能なアイコンを配置し、コメントポップアップを開きます。Page.AddFreeText() はその rect 内にテキストを直接描画します:

page.AddTextNote({
  rect: [400, 700, 420, 720],
  icon: 'Note',
  author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

page.AddFreeText({
  rect: [400, 600, 550, 660],
  contents: 'FreeText sample',
  fontSize: 10,
  align: 'center',
  fill: [1, 1, 0.8],
  width: 1,
});

ステップ 6: アノテーションを静的コンテンツにフラット化

すべての Add* 呼び出しで返される注釈ハンドルは、注釈の外観をページのコンテンツストリームに組み込み、/Annots から削除する Flatten() メソッドを持っています。フラット化した後は、ビューアでクリックしたり編集したりできるものは何も残りません:

const note = page.AddFreeText({
  rect: [210, 535, 470, 590],
  contents: 'Sticky note — flattened into the page.',
  fontSize: 11,
  align: 'left',
});

note.Flatten(); // -> boolean; bakes the annotation, unwires itself from /Annots

ステップ 7: 注釈テキストを検索

Page.SearchAnnotationText() and Page.SearchAnnotations() は両方向で互いに排他的です: SearchAnnotationText() リテラル注釈メタデータと一致します（/Contents, /T, /Subj）、ただし SearchAnnotations() は以下に一致します rendered マークアップ注釈のテキスト（例えば FreeText:

const metadataHits = page.SearchAnnotationText('confidential');
for (const hit of metadataHits) {
  console.log(hit.key, hit.value); // e.g. 'Contents', 'confidential'
}

const renderedHits = page.SearchAnnotations('confidential');
console.log(renderedHits.length);

一般的な問題と対策

Page.AddHighlight() （または別のマークアップ手法）は誤った場所に描画されます。 quads は 8 要素のフラット配列です（x1,y1,x2,y2,x3,y3,x4,y4）、ではなく rect — 4つの数値からなる矩形を渡すと、退化した四角形または欠落した四角形が生成されます。ハイライトされたテキストの行ごとに四角形を1つ作成します。

フラット化された注釈は依然としてクリック可能です。 Flatten() は、呼び出し元が返すオブジェクトに対して呼び出さなければなりません Add* 呼び出し、そしてドキュメントは保存しなければなりません（doc.WriteTo() / doc.Save()）フラット化した後 — 変更はファイルが書き戻されるまでメモリ上にのみ存在します。

SearchAnnotationText() ページ上にテキストが表示されているにもかかわらず、ヒットが返されません。 注釈メタデータフィールドのみを検索します（/Contents, /T, /Subj） — 注釈自身の外観からレンダリングされた可視マークアップテキスト（例：a FreeText body) が見つかります SearchAnnotations() 代わりに、そして通常のページコンテンツは検索しません（使用 Page.GetText() or Page.Search() それを使用してください)。

注釈を検索するとき、編集マークは表示されません。 Page.AddRedact() 作成します RedactAnnotation, ここで取り上げたマークアップ/シェイプ/テキスト注釈とは別のサブタイプです — 以下をご参照ください Redaction ガイド。

よくある質問

Page がサポートする注釈サブタイプは何種類ありますか？

このライブラリは、マークアップ（ハイライト、下線、取り消し線、波線）、シェイプ（四角形、円、直線、ポリゴン、インク）、テキスト（付箋、フリーテキスト）、リンク、スタンプの外観を生成します — さらに、ファイル添付と削除注釈も生成され、これらはそれぞれのハウツーガイドで取り上げられています。

ページ上にすでに存在する注釈を読み取ることはできますか？

はい — Page.Annotations は既存の注釈を型付きハンドルの配列として返し、調査、編集、またはフラット化が可能です。また、Page.RemoveAnnotation(a) はそれを1つ削除します。

注釈をフラット化することと削除を適用することの違いは何ですか？

Flatten() 注釈の appearance ページに挿入し、アノテーションオブジェクトを削除しますが、その下にあるテキストや画像コンテンツはそのまま残ります。 ApplyRedactions() コンテンツストリームを破壊的に書き換えるため、対象となったコンテンツ自体がなくなります — 詳細は Redaction ガイドをご参照ください。

保存して再度開く際に、アノテーションは保持されますか？

はい — doc.WriteTo() / doc.Save() の前に追加されたアノテーションは PDF に書き込まれ、次の Document.Open() / Document.OpenFile() で正しく読み戻されます。

参照

 日本語