注釈とフォーム

Aspose.PDF FOSS for .NET は、PDF アノテーションとインタラクティブな AcroForm フィールドへの完全な読み書きアクセスを提供します。アノテーションの主要エントリーポイントは Page.Annotations（AnnotationCollection）で、フォームフィールドは Document.Form を通じてアクセスします。両方のサブシステムは完全にメモリ内で動作し、ライセンスキーは不要です。

注釈の追加

AnnotationCollection は、すべての標準アノテーション種別に対して型付きヘルパーメソッドを公開します。
各メソッドは、ページ上のアノテーション位置を定義する Rectangle と、タイプ固有のパラメーターを受け取ります。

using var doc = Document.Open(pdfBytes);
var page = doc.Pages[1];

// Text (sticky-note) annotation
page.Annotations.AddTextAnnotation(
    new Rectangle(72, 720, 200, 740),
    contents: "Review this paragraph",
    title: "Editor",
    open: true);

// Highlight annotation
page.Annotations.AddHighlightAnnotation(
    new Rectangle(72, 680, 300, 700),
    quadPoints: null,
    color: new double[] { 1, 1, 0 });

// Free-text annotation (rendered directly on the page)
page.Annotations.AddFreeTextAnnotation(
    new Rectangle(72, 640, 350, 660),
    contents: "Inline note",
    fontName: "Helvetica",
    fontSize: 10,
    color: new double[] { 0, 0, 0 });

using var ms = new MemoryStream();
doc.Save(ms);

リンク注釈とアクション

リンクはクリック可能な矩形とPdfActionを組み合わせます。ライブラリは URI、GoTo、JavaScript、Named、Launch アクションをサポートします。

using var doc = Document.Open(pdfBytes);
var page = doc.Pages[1];

// URI link
var uriAction = PdfAction.CreateUri("https://aspose.com");
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 700, 200, 720), uriAction);

// GoTo link (jump to page 3)
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 660, 200, 680),
    destinationPage: 3,
    destRect: new Rectangle(0, 0, 612, 792));

// JavaScript link
var jsAction = PdfAction.CreateJavaScript("app.alert('Hello');");
page.Annotations.AddLinkAnnotation(
    new Rectangle(50, 620, 200, 640), jsAction);

doc.Save("links.pdf");

保存されたPDFを開いた後にリンクを読み戻すには、アノテーションを LinkAnnotation にキャストし、その Uri プロパティを調べるか、PdfAction.Create を介してアクション辞書を解決します。

マークアップとシェイプ注釈

Markup annotations（ハイライト、下線、取り消し線）は既存のテキストにマークを付けます。Shape annotations（四角形、円、線、インク）はページ上にジオメトリを描画します。

var page = doc.Pages[1];

// Underline
page.Annotations.AddUnderlineAnnotation(
    new Rectangle(72, 600, 300, 620),
    quadPoints: null,
    color: new double[] { 1, 0, 0 });

// Square
page.Annotations.AddSquareAnnotation(
    new Rectangle(72, 540, 200, 580),
    borderColor: new double[] { 0, 0, 1 },
    fillColor: null,
    lineWidth: 1.5);

// Line
page.Annotations.AddLineAnnotation(
    new Rectangle(72, 500, 300, 520),
    x1: 72, y1: 510, x2: 300, y2: 510,
    color: new double[] { 0, 0.5, 0 },
    lineWidth: 2);

// Ink (freehand)
page.Annotations.AddInkAnnotation(
    new Rectangle(72, 440, 200, 480),
    inkPaths: new[] { new double[] { 80, 450, 120, 470, 160, 450 } },
    color: new double[] { 0.5, 0, 0.5 },
    lineWidth: 1);

スタンプ注釈

スタンプ注釈は、ページ上に画像または事前定義されたアイコンをオーバーレイします。

var stamp = new StampAnnotation(doc);
// Configure stamp properties, then add to page
page.Annotations.Add(stamp);

アノテーションのフラット化

任意の注釈に対して Flatten() を呼び出し、視覚的外観をページコンテンツストリームに焼き付け、インタラクティブ注釈リストから削除します。

foreach (var annot in doc.Pages[1].Annotations)
{
    annot.Flatten();
}

AnnotationSelector を使用したビジターパターン

AnnotationSelector はビジターパターンを実装しているため、手動でキャストせずにタイプでアノテーションをフィルタリングできます。

var selector = new AnnotationSelector();
doc.Pages[1].Accept(selector);

// selector.Selected now contains all annotations on page 1
foreach (var annot in selector.Selected)
{
    // Process each annotation by type
}

コンストラクタに型付きアノテーションインスタンスを渡して、その型のみでフィルタリングします:

var linkFilter = new AnnotationSelector(new LinkAnnotation(page, Rectangle.Empty));
page.Accept(linkFilter);
// linkFilter.Selected contains only LinkAnnotation instances

インタラクティブフォームフィールド

Document.Form を介して AcroForm フィールドにアクセスします。Form クラスはフィールドレベルの読み取り/書き込み操作を公開し、JSON エクスポートをサポートします。

using var doc = Document.Open(pdfBytes);

// Enumerate all fields
foreach (var field in doc.Form.Fields)
{
    Console.WriteLine($"{field.FullName}: {field.Value}");
}

FieldサブクラスにはTextBoxField、CheckboxField、RadioButtonField、ComboBoxField、ListBoxField、ChoiceField、およびSignatureFieldが含まれます。

JSONへのフォームデータのエクスポート

WidgetAnnotation は、フィールドデータをストリームまたはファイルパスにシリアライズするための ExportToJson オーバーロードを提供します。オプションの ExportFieldsToJsonOptions パラメーターは出力書式を制御します。

using var doc = Document.Open(pdfBytes);
var widget = (WidgetAnnotation)doc.Pages[1].Annotations[1];

using var jsonStream = new MemoryStream();
widget.ExportToJson(jsonStream);

ヒントとベストプラクティス

常に PDF ユーザースペース単位 (1/72 インチ) で明示的な Rectangle 座標を指定してください。
最大の柔軟性を得るために AddLinkAnnotation と PdfAction を使用してください — URI、GoTo、JavaScript、Named アクションがすべてサポートされています。
アノテーションを非インタラクティブビューアでも表示させたい場合は、PDF を配布する前に Flatten() を呼び出してください。
ページアノテーションを反復処理するのではなく、Document.Form.Fields を介してフォームフィールドにアクセスしてください — フォームコレクションはページ間のフィールドグルーピングを処理します。
特にカスタムアクションの場合、アノテーションの往復忠実度を確認するためにドキュメントを保存して再度開いてください。

一般的な問題

問題	原因	対策
保存後に注釈が表示されない	矩形の面積がゼロであるか、ページ境界の外にあります	座標がページ内に収まっていることを確認してください `MediaBox`
`LinkAnnotation.Uri` が null を返す	リンクが URI アクションではなく GoTo または JavaScript アクションを使用しています	`PdfAction.Create` を使用してアクション辞書を解決し、`ActionType` を確認してください
フォームフィールドの値が空文字列です	フィールドは存在しますが `/V` エントリがありません	処理前に `field.Value` が null でないことを確認してください
`Flatten()` が例外をスローします	注釈に `/P`（ページ）参照がありません	`Page.Annotations` を介して注釈が追加されたことを確認してください

よくある質問

PDFページにハイパーリンクを追加するにはどうすればよいですか？

page.Annotations.AddLinkAnnotation(rect, PdfAction.CreateUri(url)) を使用して、指定された矩形にクリック可能な URI リンクを作成します。

既存のPDFからフォームフィールドの値を読み取ることはできますか？

はい。Document.Openでドキュメントを開き、次にDocument.Form.Fieldsを反復し、各FieldのValueプロパティを読み取ります。

ライブラリがサポートするアノテーションタイプは何ですか？

このライブラリはテキスト、フリーテキスト、リンク、ハイライト、下線、取り消し線、四角形、円、線、インク、スタンプ、キャレット、ファイル添付、サウンド、ポリゴン、ポリライン、ウィジェット、透かし、そして3Dアノテーションをサポートしています。すべてのタイプはAnnotationCollectionヘルパーメソッドまたは直接構築で利用できます。

注釈をタイプでフィルタリングするにはどうすればよいですか？

AnnotationSelector を型付きテンプレート注釈と共に使用します。page.Accept(selector) を呼び出し
selector.Selected を検査して一致する注釈を確認します。

特定の注釈だけをフラット化できますか？

はい。コレクション全体を反復処理するのではなく、個々の Annotation インスタンスに対して Flatten() を呼び出してください。

API リファレンス概要

Class / Method	Description
`AnnotationCollection`	各`Page`の型付きコレクション; すべてのアノテーションタイプに対する`Add*`ヘルパーを提供します
`AnnotationCollection.AddTextAnnotation`	付箋アノテーションを追加
`AnnotationCollection.AddLinkAnnotation`	URI、ページ先、またはカスタムアクションを持つリンクを追加
`AnnotationCollection.AddHighlightAnnotation`	テキストハイライトアノテーションを追加
`AnnotationCollection.AddInkAnnotation`	フリーハンド描画アノテーションを追加
`AnnotationCollection.AddSquareAnnotation`	矩形シェイプアノテーションを追加
`AnnotationCollection.AddCircleAnnotation`	楕円シェイプアノテーションを追加
`AnnotationCollection.AddLineAnnotation`	線アノテーションを追加
`Annotation.Flatten`	アノテーションの外観をページコンテンツに焼き付ける
`Annotation.Accept`	型付き`AnnotationSelector.Visit`オーバーロードにディスパッチ
`AnnotationSelector`	タイプ別にアノテーションを収集するビジター
`LinkAnnotation`	URIまたはアクションを保持するアノテーションサブクラス
`TextAnnotation`	付箋アノテーション
`InkAnnotation`	ストロークパスを持つフリーハンド描画アノテーション
`StampAnnotation`	画像またはアイコンオーバーレイアノテーション
`WidgetAnnotation.ExportToJson`	フォームフィールドデータをJSONにシリアライズ
`Form`	AcroFormファサード; フィールドを列挙および操作
`Field`	フォームフィールドの基底クラス（`TextBoxField`、`CheckboxField`など）
`CheckboxField`	チェックボックスフォームフィールド
`TextBoxField`	単一/複数行テキスト入力フィールド
`ComboBoxField`	ドロップダウン選択フィールド
`RadioButtonField`	ラジオボタングループフィールド
`AnnotationType`	アノテーション種別の列挙
`PdfAction.CreateUri`	URIリンクアクションのファクトリ
`PdfAction.CreateJavaScript`	JavaScriptアクションのファクトリ

参照

Aspose.PDF for .NET エンタープライズ製品

注釈とフォーム