アノテーション
ビューアにアノテーションサポートを追加
Doconut のアノテーションは 2 方向で機能します。ユーザーはブラウザウィジェット上で描画し、サーバーがページごとに永続化するか、またはコードでプログラム的に作成し、オープンセッションにロードします。いずれの場合もページ上に描画され、PDF/PNG エクスポートに焼き込むことができます。
アノテーションのサポートは Annotation ライセンス機能によって制御されます(アクティブな Temporary ライセンスの下で自動的に付与されます)。
アノテーション UI を有効にする
アノテーションは Viewer のモジュールであり、スタンドアロンのツールバーではありません。完全なページには Viewer リソース、Viewer ツールバー、Viewer のマウント、そして初期化された objViewer が含まれている必要があります。その後、Annotation Ribbon がマウントされ、同じインスタンスに添付されます。
アノテーションバンドルを Viewer バンドルと共に出力します — これらはライセンスで制御されるため、機能が利用可能なときだけタグが表示されます:
@Html.Raw(Viewer.ReferenceCss(new CssConfig
{
IncludeViewerCss = true,
IncludeAnnotationCss = true // jquery-ui.min.css + annotationBar.css
}))
@Html.Raw(Viewer.ReferenceScripts(new ScriptConfig
{
IncludeJQuery = true,
IncludeViewerScripts = true,
IncludeAnnotationScripts = true, // jquery-ui, raphael.js, annotation.js
IncludeAnnotationBar = true // 埋め込みアノテーションリボン
}))マークアップ内で完全な Viewer 構成が見えるように保ちます:
<nav id="toolbar" aria-label="Document viewer controls">
<!-- Viewer コントロール、Annotation を開くボタンを含む -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>Annotation バンドルは annBarMount 内に Ribbon の DOM を生成します;ボタンやダイアログのマークアップをコピーする必要はありません。まず docViewer を初期化し、サーバーがアノテーションがライセンスされていることを確認したときにのみ Ribbon を作成します:
<script>
let annBar = null;
let currentToken = '';
const objViewer = $('#div_ctlDoc').docViewer({
BasePath: 'doconut',
ResPath: 'doconut-res/images',
onAnnLoaded: () => annBar?.handleAnnLoaded(),
onAnnSaved: () => annBar?.handleAnnSaved(),
onAnnSaveError: () => annBar?.handleAnnSaveError(),
onAnnClosed: () => annBar?.handleAnnClosed(),
onError: (message) => console.error('Viewer error:', message)
});
@if (Viewer.IsAnnotationEnabled)
{
<text>
annBar = $('#annBarMount').doconutAnnotationBar({
docId: 'ctlDoc',
getRequestParams: () => ({ token: currentToken }),
onStatus: (message) => console.log(message),
onToast: (message, type) => console.log(type, message),
onLayout: () => requestAnimationFrame(() => objViewer.Refit())
});
annBar.attach(objViewer);
</text>
}
</script>機能がない場合、ReferenceScripts は Ribbon のスクリプトを除外するため、サーバー側の if が保護されていない doconutAnnotationBar(...) 呼び出しがページを壊すのを防ぎます。
Ribbon からの保存はミドルウェア (AnnSave) を通じてデータを投稿し、ページごとのドキュメントセッションに保存されます。ロード (AnnLoad) はアノテーション付きページがレンダリングされると自動的に行われます。4 つの onAnn* コールバックが Ribbon を Viewer のライフサイクルと同期させます。
任意のホスト所有 Viewer ツールバーから開閉できます:
annBar.open();
annBar.close();公開されている Ribbon API は次のとおりです:
| メソッド | 目的 |
|---|---|
attach(objViewer) | 初期化された Viewer に Ribbon を接続します;1 回だけ必要です |
open() / close() | アノテーション編集に入るまたは退出する |
reset() | Ribbon を閉じた編集状態でない状態に戻します |
isOpen() / annotating() | Ribbon の状態 / Viewer のアノテーション編集状態を取得します |
reopenEditable() | 現在のページのアノテーションを編集可能なオブジェクトとして再読み込みします |
updateActionState() | ホストの変更後に保存/削除コントロールの利用可能性を更新します |
headerSlot() | ホスト所有コントロール用のオプションヘッダー拡張スロットを取得します |
onStatus、onToast、onLayout、onEditStart、および onEditEnd はオプションのホストコールバックです。endpoints オブジェクトはさらに exportPdf、exportPng、imageUpload、imageList を提供できます;エンドポイントが設定されていないコントロールは非表示のままです。
統合された Viewer、Search、Annotation の起動シーケンスについては、クイックスタート を参照してください。
アノテーションバンドルはブラウザの作成ツールを追加しますが、データはトークンで識別されるサーバー側のドキュメントセッションに属したままです。ソースを再度開くと新しいセッションが作成されます;アノテーションをセッションの存続期間を超えて保持する必要がある場合は、XML またはエンコードされたアノテーションエンベロープをアプリケーションに永続化してください。
2つのコールバックの種類、2通りの配線
アノテーションコードは2つのコールバックスタイルを使用し、逆方向に配線された場合はそれぞれ黙って失敗します。
onAnnLoaded,onAnnSaved,onAnnSaveError,onAnnClosedはdocViewer({...})の オプション で、すべてのビューアコールバックと同様です。Created,Changed,Deleted, とPropertiesは 名前で見つかるグローバル関数 です: ビューアIDがイベント名にプレフィックスされます。#div_ctlDocのビューアの場合、IDはctlDocで、関数はctlDoc_Created、ctlDoc_Changed、ctlDoc_Deleted、ctlDoc_Propertiesです。綴りミスや名前変更された関数は呼び出されません。
SaveAnnotations() は保存されたかどうかを返しません: 結果は onAnnSaved または onAnnSaveError で届きます。戻り値を読むコードは「未保存の変更」フラグをクリアしません。
C#でアノテーションを構築する
オープンセッションにバインドされたマネージャを取得し、アノテーションを追加し、ロードします(タイプには using Doconut.Annotations;、Rectangle/Color 用には using System.Drawing; を使用)。
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
// 開いているセッションのページ寸法に合わせて
var manager = viewer.GetAnnotationManager(token);
var pageCount = viewer.GetPageCount(token);
// 1ページにつき1つのスタンプ
for (int page = 1; page <= pageCount; page++)
{
manager.Add(new StampAnnotation(page, new Rectangle(30, 20, 240, 90),
$"PAGE {page}", 28, 4, Color.Maroon)
{
Opacity = 60,
Rotate = -8
});
}
manager.Add(new NoteAnnotation(1, new Rectangle(420, 150, 220, 120),
"Loaded from C# code.", Color.FromArgb(255, 255, 255, 170), 14));
// セッションにロード — ウィジェットは AnnLoad を介してそれらを取得し、
// レンダラーはそれらを画像/PDF エクスポートに焼き込みます。
viewer.LoadAnnotationData(token, manager);
return Results.Ok();
});アノテーションタイプ
すべてのタイプは Doconut.Annotations にあり、BaseAnnotation を継承します(ページ番号 + バウンディング Rectangle)。
| タイプ | 備考 |
|---|---|
StampAnnotation | フォントサイズ、枠線、色を持つテキストスタンプ;Opacity、Rotate をサポート |
NoteAnnotation | テキスト、背景色、フォントサイズ、TitleColor を持つ付箋 |
RectangleAnnotation | 枠線+塗りつぶし色、Title/ShowTitle |
CircleAnnotation | 枠線+塗りつぶし、ShowBorder |
EllipseAnnotation | 枠線+塗りつぶし、ShowBorder |
TriangleAnnotation | 枠線色、BackColor、ShowBorder |
LineAnnotation | 幅と色を持つ直線 |
ArrowAnnotation | 矢じり付きの線;設定可能な Direction(タイプ ArrowDirection、コンパス方向、デフォルト E) |
FreehandAnnotation | エンコードされた FreehandData ポイントからのフリーストローク |
ImageAnnotation | URL からの画像。相対 URL はアノテーションが追加されるときにリクエストホストに対して解決されます;サーバは画像を焼き込み時にのみ取得します — 以下のエクスポート注記を参照してください |
アノテーションマネージャ API
| メンバー | 目的 |
|---|---|
Add(BaseAnnotation) | アノテーションをキューに入れる |
GetAnnotations() / GetAnnotations(int page) | マネージャが保持しているものを検査する |
ClearAnnotations() / ClearAnnotations(int page) | すべて削除 / ページ単位で削除 |
GetAnnotationData() / GetAnnotationData(int page) | エンコードされたアノテーションデータ文字列 — Base64 のワイヤーエンベロープ(ウィジェットが使用するもの) |
GetAnnotationXml() | XML 形式 |
Viewer はセッションに対するロード/読み取り操作をミラーします: LoadAnnotationData(token, manager) または LoadAnnotationData(token, encodedData)(GetAnnotationData() からの Base64 ワイヤーエンベロープ)、LoadAnnotationXML(token, xml)、GetAnnotationXML(token)。
アノテーションが焼き込まれた状態でエクスポート
// 注釈が描画されたすべてのページの PDF
app.MapGet("/api/annotations/export-pdf", async (string token, Viewer viewer) =>
{
byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100);
return Results.File(pdf, "application/pdf", "export.pdf");
});
// またはページごとの PNG の ZIP
app.MapGet("/api/annotations/export-png-zip", async (string token, Viewer viewer) =>
{
byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100);
return Results.File(zip, "application/zip", "annotations-png.zip");
});エクスポートは画面上のレンダリングと同じバーナーを使用するため、ユーザーが見るものはファイルに含まれるものと同じです — ただし、次に説明する画像アノテーションは除きます。
イントラネットホストでの画像注釈が「Image blocked」としてエクスポートされる
ビューアとエクスポートは、ImageAnnotation の画像を異なる場所から取得します。
| 対象 | 画像をダウンロードするのは誰か | イントラネットまたは開発ホスト上で |
|---|---|---|
| ブラウザ内のビューア | ユーザーのブラウザ | 画像が表示される |
ExportAnnotationsToPdfAsync / …PngZipAsync | サーバー | 赤い "Image blocked" プレースホルダー |
サーバーが画像を取得して埋め込む際、プライベートネットワークに戻るアドレスは拒否されます:ループバック(localhost、127.0.0.1)、0.0.0.0、リンクローカル(169.254.x.x)、プライベートレンジ 10.x、172.16–31.x、および 192.168.x、キャリアグレード NAT(100.64.0.0/10)、そして IPv6 のリンクローカルおよびユニークローカルアドレスです。これは、サーバーが細工された画像 URL を通じて内部システムにアクセスされるのを防ぎ、オフにするスイッチはありません。
相対画像 URL は現在のリクエストのホストに対して解決されるため、localhost 上、イントラネットサーバー上、またはプライベートアドレスで到達する任意のサイト上では、画像はビューアに表示され、エクスポートには代わりにプレースホルダーが含まれます。これはガードが機能しているのであって、レンダリング失敗ではありません。エクスポートに画像を含める必要がある場合は、パブリックアドレスを持つホストから提供し、絶対 URL を使用してください。解決できないホスト名も同様に拒否され、他のダウンロード失敗の場合は URL とエラーメッセージが赤で表示され、画像があるはずの場所に示されます。
永続化ワークフロー
- ドキュメントを開き、トークンを取得します。
- 以前に保存された XML またはエンコードされたデータをそのトークンにロードします。
- ウィジェットにセッション注釈を読み取り、編集させます。
GetAnnotationXML(token)を使用して XML を取得します(アプリケーションが永続化を決定したとき)。- フラット化された成果物が必要な場合は PDF/PNG をエクスポートします。
- ドキュメントセッションを閉じます。
不透明なビューアトークンを永続的な注釈識別子として使用しないでください。永続化された注釈データは、独自のドキュメントおよびバージョン識別子に関連付けてください。
セキュリティとレンダリングに関する注意点
- 注釈リクエストは、ページリクエストと同じセッション/トークンのセキュリティを使用します。
- サーバー側リクエスト偽装を防ぐため、ユーザー提供の画像 URL を検証・制御してください。
- エクスポートは、画面上のページレンダリングと同様のライセンス/カスタム透かしの決定を適用します。
- 大きなフリーハンドペイロードや高解像度エクスポートはメモリ使用量を増加させます。実際的なドキュメントとズーム値でテストしてください。
トラブルシューティング
| 症状 | 確認項目 |
|---|---|
| 注釈リボンが欠落している | Annotation 機能と4つの注釈 CSS/スクリプトフラグ |
| 保存コールバックがエラーを報告する | トークン/セッションの期限切れとミドルウェア BasePath |
ctlDoc_Created(または別のイベント関数)が実行されない | 関数名: viewer id + _ + event、グローバル関数として |
| C# 注釈が表示されない | ページ番号が1から始まり、データがアクティブなトークンにロードされている |
| 画像注釈が画面上には表示されるがエクスポートに含まれない | 画像のホストがプライベートまたはループバックアドレスである — 上記参照 |
| 再度開いたドキュメントに注釈がない | ビューアセッション外で XML/データを永続化し、次に新しいトークンにロードしてください |
このページは役に立ちましたか?