はじめに
introductory post は注釈を簡単に取り上げています：ハイライト、下線、付箋、スタンプで、Page.AddHighlight()、Page.AddUnderline() などの方法で追加されます。これは Page が実際にサポートする機能のごく一部です — このライブラリの注釈ギャラリーはマークアップ、フリーハンド形状、実際のナビゲーションやフォーム送信アクションを持つリンク、検索をカバーしており、すべて Page から直接利用できます。
この記事では、その概要の残りの部分を解説します：形状およびフリーハンド注釈の方法、Link 注釈のアクションが実際に何ができるか、そして検索対象のテキストが注釈の外観にあるか /Contents コメントにあるかによって、注釈内容を検索する2つの異なる方法です。
すべての注釈メソッドは、作成した注釈にスコープされた型付きハンドルを返し、ページ上のすべての注釈はその後 page.Annotations を介して読み取ることができます。
含まれるもの
マークアップ注釈
Page.AddHighlight()、Page.AddUnderline()、Page.AddSquiggly()、および Page.AddStrikeOut() はすべて同じ形状のオプションを受け取ります — テキスト領域を示す四つの点のセットとオプションの色 — そして4つすべてが MarkupAnnotation を返します。四つの点は通常、テキスト検索または既知のテキスト矩形から導出されます。
const markup = (body: [number, number, number, number], sample: string,
add: (quads: number[]) => void): void => {
const yMid = (body[1] + body[3]) / 2 - 6;
const textRect: [number, number, number, number] = [body[0] + 4, yMid, body[2] - 4, yMid + 16];
page.AddText(sample, textRect[0], textRect[1], { fontSize: 12 });
add(rectToQuads(textRect));
};
markup(cardBody, 'Highlight this phrase', (quads) =>
page.AddHighlight({ quads, color: [1, 1, 0], contents: 'Yellow highlight' }));
markup(cardBody, 'Underline this phrase', (quads) =>
page.AddUnderline({ quads, color: [0, 0, 1] }));
markup(cardBody, 'Squiggle this phrase', (quads) =>
page.AddSquiggly({ quads, color: [1, 0.5, 0] }));
markup(cardBody, 'Strike this phrase out', (quads) =>
page.AddStrikeOut({ quads, color: [1, 0, 0] }));
ノートと独立テキスト
Page.AddTextNote() は、クリックするとコメントポップアップを開くクラシックな付箋アイコンを追加し、TextAnnotation を返します。Page.AddFreeText() は代わりに、ページ上に枠付きのボックス内にテキストを直接描画し、独自のフォントサイズ、配置、塗りつぶし色を持ちます — 何も開かずに表示されるべきコールアウトに便利です。
page.AddTextNote({
rect: [x, y, x + 20, y + 20], icon: 'Note', author: 'Reviewer',
contents: 'This is a sticky-note annotation.',
});
page.AddFreeText({
rect: [220, 60, 520, 96],
contents: 'FreeText sample', fontSize: 10, align: 'center',
fill: [1, 1, 0.8], width: 1,
});
図形とフリーハンドインク
Page.AddSquare() と Page.AddCircle() は、枠付きの矩形または楕円を描画し、各々オプションで内部塗りつぶしを設定できます。Page.AddLine() は二点間に直線を描き、各端点で独立して選択可能な矢じりスタイル（startEnding/endEnding、例: 'OpenArrow'/'ClosedArrow'）を適用します。Page.AddPolygon() と Page.AddPolyline() は、座標のフラットリストから閉じた形状と開いた多点形状を描画し、Page.AddInk() は一点リストの paths として1本以上のフリーハンドペンストロークを記録します。
page.AddSquare({ rect: [50, 400, 130, 435], color: [0.8, 0, 0], fill: [1, 1, 0.5], width: 2 });
page.AddCircle({ rect: [150, 400, 230, 435], color: [0, 0.5, 0], width: 2 });
page.AddLine({
line: [260, 417, 420, 417],
color: [0, 0, 0.7], width: 2,
startEnding: 'OpenArrow', endEnding: 'ClosedArrow',
});
const stroke: number[] = [];
[-8, 6, -4, 10, -2, 8, -6].forEach((dy, i) => stroke.push(440 + i * 12, 417 + dy));
page.AddInk({ paths: [stroke], color: [0.6, 0, 0.6], width: 2 });
リンクとそのアクション
Page.AddLink() は、クリック時の挙動を決定する action を持つ LinkAnnotation を返します：{ type: 'uri', uri: '...' } は外部URLを開き、{ type: 'goto', page: N } は同一文書内のページへジャンプし、{ type: 'submit', url: '...', format: 'html' } は現在のフォームフィールド値をエンドポイントに送信します。範囲外の goto ページ番号や不正なアクションオブジェクトは、作成時に拒否され、黙って受け入れられることはありません。
const uriLink = page.AddLink({
rect: [10, 10, 100, 30], action: { type: 'uri', uri: 'https://example.com' },
});
const gotoLink = page.AddLink({
rect: [10, 40, 100, 60], action: { type: 'goto', page: 2 },
});
const submitLink = page.AddLink({
rect: [10, 70, 100, 90],
action: { type: 'submit', url: 'https://example.com/post', format: 'html' },
});
// page.AddLink({ rect: [...], action: { type: 'goto', page: 99 } }) throws RangeError
// when 99 is out of range for the document.
注釈コンテンツの検索
二つの異なるメソッドがアノテーションテキストを検索し、意図的に分離されています： Page.SearchAnnotations() アノテーション自身の外観にあるテキストを検索する 描画する — a の可視ラベル FreeText 例としてスタンプなど — しかし Page.SearchAnnotationText() アノテーションに含まれるテキストを検索する /Contents エントリ、たとえば付箋メモのコメント本文など。片方で一致しても、もう片方で一致するとは限らない。
page.SearchAnnotations('bravo'); // finds it if the annotation's drawn appearance contains it
page.SearchAnnotationText('bravo'); // finds it if the annotation's /Contents comment contains it
必要なくなったアノテーションは、Page.RemoveAnnotation() を直接使用して削除できます。アノテーションハンドルまたはその基になる辞書のいずれかを渡してください。
クイックスタート
パッケージをインストールし、既存のページにハイライト、リンク、付箋を追加します:
git clone https://github.com/aspose-pdf-foss/Aspose.PDF-FOSS-for-TypeScript.git
cd Aspose.PDF-FOSS-for-TypeScript
npm install
npm run buildimport { Document } from '@asposefoss/pdf';
const doc = Document.OpenFile('input.pdf');
const page = doc.Pages[0];
page.AddHighlight({ quads: [72, 700, 300, 700, 72, 715, 300, 715], color: [1, 1, 0] });
page.AddLink({
rect: [72, 670, 200, 690], action: { type: 'uri', uri: 'https://example.com' },
});
page.AddTextNote({
rect: [320, 670, 340, 690], icon: 'Note', author: 'Reviewer',
contents: 'Please double-check this figure.',
});
doc.WriteTo('annotated.pdf');
サポートされているフォーマット
| 形式 | 拡張 | 読み取り | 書き込み |
|---|---|---|---|
| ✓ | ✓ | ||
| Markdown | MD | ✓ | ✓ |
| SVG | SVG | ✓ | ✓ |
| TIFF | TIFF | ✓ | ✓ |
| DOCX | DOCX | — | ✓ |
| HTML | HTML | — | ✓ |
| PNG | PNG | — | ✓ |
| EPUB | EPUB | — | ✓ |
オープンソースとライセンス
Aspose.PDF FOSS for TypeScript は MIT ライセンスの下でリリースされており、ソースは GitHub に公開されています。評価用の透かしや使用制限、別途管理するライセンスファイルはありません。また、ロイヤリティなしで商用製品にライブラリを使用できます。
このパッケージは現在バージョン 0.1.0 で、アクティブな初期開発段階を示しています。Node.js (>=22) が唯一のランタイム要件で、他のサードパーティ依存はありません。
