Annotations

注釈

このページでは、PDF注釈の作成、読み取り、検索、フラッティングについて説明します。Page は、注釈サブタイプごとに 1 つの Add*() メソッドを公開し、各メソッドはライブ Annotation ハンドルを返します。Annotation 基底クラスとそのサブタイプ(TextAnnotation、StampAnnotation、MarkupAnnotation、その他)では、注釈のプロパティを読み取りおよび編集できるように公開します。


マークアップ、ノート、リンク注釈の作成

4 つのテキストマークアップメソッド — Page.AddHighlight()、Page.AddUnderline()、Page.AddSquiggly()、Page.AddStrikeOut() — は、quads 配列(/QuadPoints)を受け取り、MarkupAnnotation を返します。Page.AddLink() は URI または内部アクションを持つクリック可能な領域を作成し、Page.AddTextNote() はポップアップで contents テキストを表示する付箋アイコンを追加し、TextAnnotation を返します。

page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' });
page.AddUnderline({ quads, color: [0, 0, 1] });
page.AddStrikeOut({ quads, color: [1, 0, 0] });

page.AddLink({
  rect: [100, 700, 220, 716],
  action: { type: 'uri', uri: 'https://example.com' },
  border: 0,
});

page.AddTextNote({
  rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
  contents: 'This is a sticky-note annotation.',
});

Page は、形状およびフリーハンドメソッド — AddSquare()、AddCircle()、AddLine()、AddPolygon()、AddPolyline()、AddInk()、AddFreeText()、AddCaret()、および AddStamp() — も公開し、各メソッドはそのサブタイプに対応する注釈ハンドルを返し、/AP の外観を自動的に生成します。


注釈の読み取りと一覧表示

page.Annotations は、ページ上のすべての Annotation の配列です。サブタイプに関わらず、すべての注釈は Subtype、Rect、Color、Contents、Name、Layer、ModDate、Flags、Print、Hidden、および Opacity を公開します。サブタイプは StampAnnotation.StampName や MarkupAnnotation.QuadPoints など独自のフィールドを追加します。

const freeText = page.Annotations.find((a) => a.Subtype === 'FreeText');
if (freeText) {
  freeText.Contents = 'Updated note text';
}

注釈テキストの検索

Page.SearchAnnotationText() and Page.SearchAnnotations() 意図的に分離しています。 SearchAnnotationText() テキスト内の注釈で一致を見つけます carries 描画するのではなく — ノートの /Contents、その作者(/T)、またはその対象(/Subj) — そして返します AnnotationTextMatch[] ({ annot, key, value, text }). SearchAnnotations() テキスト内の注釈で一致を見つけます draws、例えば a FreeText’s の可視単語を取得し、返します AnnotationMatch[] ({ annot, text, quads }).

// A sticky note's /Contents text — found by SearchAnnotationText, not SearchAnnotations.
const textHits = page.SearchAnnotationText('body secret');
console.log(textHits[0].key, textHits[0].value); // 'Contents' 'body secret'

// A FreeText's rendered words — found by SearchAnnotations, not SearchAnnotationText.
const drawnHits = page.SearchAnnotations('bravo');

注釈のフラット化

Annotation.Flatten() は、注釈の /AP 表示をページのコンテンツストリームの /Rect に直接組み込み、/Annots からは削除します。その結果は永続的な静的コンテンツとなり、閲覧者がクリックしたり編集したり非表示にできる個別の注釈はもう存在しません。

const note = page.AddTextNote({
  rect: [72, 660, 92, 680], icon: 'Comment', contents: 'Reviewed and approved.',
});
note.Flatten();

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

  • Flatten() は、Add*() 呼び出しが直接返すオブジェクトに対して呼び出してください — 後で page.Annotations を再読込して取得した注釈は別のオブジェクト参照になります。
  • SearchAnnotationText() と SearchAnnotations() は異なるテキストを対象とします:フレーズがノートに入力されたものかページに描かれたものかに関わらず検索したい場合は、両方実行してください。
  • 4つのマークアップ手法(AddHighlight, AddUnderline, AddSquiggly, AddStrikeOut)は、/AP の表示を自動的に生成します — 手動でコンテンツストリームを描画する必要はありません。
  • 暗号化は往復しても残ります: Document.Save() の前に encrypt オプションで追加されたアノテーションは、ドキュメントを再度開いて復号化した後でも有効です。

よくある問題

問題原因修正
page.Annotations.find() は、あなたが追加したばかりのアノテーションに対して undefined を返しますアノテーションが追加される前に取得された古い配列を検索していますAdd*() 呼び出しの後で page.Annotations を再読込するか、呼び出しが返したハンドルを直接使用してください
SearchAnnotationText() はページ上の可視テキストに対して何も見つけませんテキストはアノテーションによって描画されます(例: FreeText の本文)、/Contents に保持されているわけではありません。SearchAnnotations() を代わりに使用してください — 描画されたテキストと一致します。
アノテーションは Flatten() 後もまだ編集可能に見えます。Flatten() は、Add*() が返したハンドルではなく、コピーに対して呼び出されました。作成メソッドが直接返すオブジェクトに対して Flatten() を呼び出してください。

FAQ

SearchAnnotationText と SearchAnnotations の違いは何ですか?

SearchAnnotationText() テキストとアノテーションが一致します。 carries — /Contents, /T (author)、または /Subj — たとえば付箋の本文のように。 SearchAnnotations() テキストと注釈が一致する draws ページ上で、例えば FreeTextの可視単語。二者は互いに排他的です:一方での一致は他方には現れません。

アノテーションを永続的で非インタラクティブにするにはどうすればよいですか?

作成した Add*() メソッドが返す Annotation ハンドルに対して Flatten() を呼び出します。これにより外観がページのコンテンツストリームに焼き込まれ、/Annots から削除されます。

サポートされているアノテーションのサブタイプはどれですか?

Page は、テキストマークアップ(AddHighlight、AddUnderline、AddSquiggly、AddStrikeOut)や、ノートとコールアウト(AddTextNote、AddFreeText、AddCaret)、リンク(AddLink)、シェイプ(AddSquare、AddCircle、AddLine、AddPolygon、AddPolyline)、フリーハンドインク(AddInk)、スタンプ(AddStamp)、ファイル添付(AddFileAttachment)の作成メソッドを提供します。

ページ上に既にあるすべてのアノテーションを一覧表示するにはどうすればよいですか?

page.Annotations を読み取ります。これは Annotation ハンドルの配列です。各ハンドルは Subtype、Rect、Color、Contents とその他の共通プロパティを提供するので、標準的な配列メソッドでフィルタリングしたり検査したりできます。


API Reference の概要

クラス/メソッド説明
Annotation任意の注釈に対するベースハンドル; Subtype、Rect、Color、Contents、Name、Flags、Print、Hidden、Opacity を公開します
Annotation.Flatten()注釈の外観を静的なページコンテンツに焼き込む
TextAnnotationA /Text スティッキーノートハンドル; Icon、Open、Author を追加
StampAnnotationA /Stamp ゴムスタンプハンドル; StampName を追加
MarkupAnnotationA テキストマークアップハンドル (Highlight/Underline/StrikeOut/Squiggly); MarkupType、QuadPoints を追加
Page.AddHighlight() / Page.AddUnderline() / Page.AddStrikeOut() / Page.AddSquiggly()/QuadPoints にテキストマークアップ注釈を作成
Page.AddTextNote()付箋アノテーションを作成する
Page.AddLink()URI または内部アクションを使用したクリック可能なリンクを作成する
Page.Annotationsページ上のすべての Annotation を配列として
Page.SearchAnnotationText()アノテーションが保持するテキストを検索する (/Contents, /T, /Subj)
Page.SearchAnnotations()ページ上の注釈が描くテキストを検索する

参照

 日本語