Doconut の注釈は 2 方向で機能します。ユーザーがブラウザウィジェット上で描画しサーバーがページ単位で永続化するか、コードでプログラム的に作成して開いているセッションにロードするかです。いずれの場合もページ上に描画され、PDF/PNG エクスポート時に焼き込まれます。

注釈サポートは Annotation ライセンス機能で制御されます（アクティブな Temporary ライセンス下で自動的に付与されます）。

注釈 UI を有効にする

Annotation は Viewer のモジュールであり、単体のツールバーではありません。ページ全体に Viewer のリソース、Viewer ツールバー、Viewer のマウント、初期化済み objViewer を含める必要があり、そこに Annotation リボンがマウントされ同じインスタンスに添付されます。

ビューアのバンドルと同時に注釈バンドルを出力します — これらはライセンスで制御されるため、機能が利用可能なときだけタグが表示されます:

html

@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  // the embedded annotation ribbon
}))

マークアップ内で完全な Viewer 構成を可視化します:

html

<nav id="toolbar" aria-label="Document viewer controls">
    <!-- Viewer controls, including the button that opens Annotation -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

Annotation バンドルは annBarMount 内にリボンの DOM を生成します。ボタンやダイアログのマークアップをコピーする必要はありません。まず docViewer を初期化し、サーバーが Annotation のライセンスを確認したときだけリボンを作成します:

html

<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>

リボンからの保存はミドルウェア (AnnSave) を通じてデータを投稿し、ページ単位でドキュメントセッションに保存されます。読み込み (AnnLoad) は注釈があるページが描画されると自動的に行われます。4 つの onAnn* コールバックがリボンとビューアのライフサイクルを同期させます。

任意のホスト所有 Viewer ツールバーから開閉できます:

javascript

annBar.open();
annBar.close();

公開リボン API は次のとおりです:

メソッド	目的
`attach(objViewer)`	初期化済みビューアにリボンを接続します。1 回だけ必要です
`open()` / `close()`	注釈編集モードに入る／抜ける
`reset()`	リボンを閉じた非編集状態に戻します
`isOpen()` / `annotating()`	リボンの状態／ビューアの注釈編集状態を取得します
`reopenEditable()`	現在のページ注釈を編集可能オブジェクトとして再読み込みします
`updateActionState()`	ホスト側の変更後に保存/削除コントロールの有効性を更新します
`headerSlot()`	ホスト所有コントロール用のオプションヘッダー拡張スロットを取得します

onStatus, onToast, onLayout, onEditStart, onEditEnd はオプションのホストコールバックです。endpoints オブジェクトは追加で exportPdf, exportPng, imageUpload, imageList を提供できます。エンドポイントが設定されていないコントロールは非表示のままです。統合された Viewer、Search、Annotation の起動シーケンスについては、クイックスタートを参照してください。

注釈バンドルはブラウザの著作ツールを追加しますが、データ自体はトークンで識別されるサーバー側のドキュメントセッションに属します。ソースを再度開くと新しいセッションが作成されます。セッションの存続期間を超えて注釈を保持する必要がある場合は、XML またはエンコードされた注釈エンベロープをアプリケーション側で永続化してください。

C# で注釈を作成する

開いているセッションにバインドされたマネージャーを取得し、注釈を追加してロードします（型は using Doconut.Annotations;、Rectangle/Color は using System.Drawing;）:

csharp

app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // Bound to the open session's page dimensions
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // One stamp per page
    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));

    // Load into the session — the widget fetches them via AnnLoad and the
    // renderer burns them into image/PDF exports.
    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 は注釈が追加されたときにリクエストホストに対して解決され（焼き込み時に画像取得が行われるだけです）サーバーから到達可能である必要があります（例: `UseStaticFiles` で提供される `wwwroot` 配下のファイル）

AnnotationManager 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)。

注釈が焼き込まれたエクスポート

csharp

// PDF of all pages with annotations rendered onto them
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");
});

// Or a ZIP of per-page PNGs
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");
});

エクスポートは画面上のレンダリングと同じバーナーを使用するため、ユーザーが画面で見るものがファイルにそのまま含まれます。

永続化ワークフロー

ドキュメントを開き、トークンを取得します。
以前に保存した XML またはエンコードデータをそのトークンにロードします。
ウィジェットにセッション注釈を読み取り・編集させます。
アプリケーションが永続化を決定したときに GetAnnotationXML(token) で XML を取得します。
フラット化された成果物が必要な場合は PDF/PNG をエクスポートします。
ドキュメントセッションを閉じます。

不透明なビューアトークンを永続的な注釈識別子として使用しないでください。永続化した注釈データは自分のドキュメントおよびバージョン識別子と紐付けて管理します。

セキュリティとレンダリングに関する注意点

注釈リクエストはページリクエストと同じセッション/トークンのセキュリティを使用します。
相対的な ImageAnnotation の URL はリクエストホストから解決され、焼き込み時にサーバーが到達可能である必要があります。
ユーザー提供の画像 URL はサーバー側リクエスト偽装を防ぐために検証・制御してください。
エクスポートは画面上のページレンダリングと同じライセンス/カスタム透かしの判断を適用します。
大容量のフリーハンドペイロードや高解像度エクスポートはメモリ使用量を増加させます。実際のドキュメントとズーム値でテストしてください。

トラブルシューティング

症状	確認項目
Annotation リボンが表示されない	`Annotation` 機能と 4 つの注釈 CSS/スクリプトフラグ
保存コールバックがエラーを報告する	トークン/セッションの有効期限切れとミドルウェア `BasePath`
C# の注釈が表示されない	ページ番号は 1 から始まり、データがアクティブなトークンにロードされたか
画像注釈が画面には表示されるがエクスポートに含まれない	焼き込み時にサーバーが画像 URL に到達できるか
再オープンしたドキュメントに注釈がない	ビューアセッション外で XML/データを永続化し、新しいトークンにロードしたか