注釈

ビューアに注釈サポートを追加

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

注釈サポートは Annotation ライセンス機能によって制御されます(有効な Temporary ライセンスの下で自動的に付与されます)。

注釈 UI を有効化

注釈は Viewer のモジュールであり、スタンドアロンのツールバーではありません。完全なページには Viewer リソース、Viewer ツールバー、Viewer のマウント、そして初期化された objViewer が含まれる必要があります。その後、Annotation Ribbon がマウントされ、同じインスタンスに添付されます。

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

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  // 埋め込まれたアノテーションリボン
}))

マークアップ内で完全な Viewer 構成が見えるように保ちます:

html
<nav id="toolbar" aria-label="Document viewer controls">
    <!-- ビューアのコントロール、Annotation を開くボタンを含む -->
</nav>
<div id="annBarMount"></div>
<div id="divDocViewer"><div id="div_ctlDoc"></div></div>

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

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>

機能がない場合、ReferenceScripts は Ribbon のスクリプトを除外するため、サーバー側の if が保護されていない doconutAnnotationBar(...) 呼び出しがページを壊すのを防ぎます。

Ribbon からの保存はミドルウェア(AnnSave)を通じてデータを投稿し、ページごとのドキュメントセッションに保存します。ロード(AnnLoad)は注釈付きページがレンダリングされると自動的に行われます。4 つの onAnn* コールバックが Ribbon と Viewer のライフサイクルを同期させます。

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

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

公開されている Ribbon API は次のとおりです:

メソッド目的
attach(objViewer)初期化された Viewer に Ribbon を接続します;一度だけ必要です
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, and Properties は 名前で見つかるグローバル関数 です: イベントにビューアIDがプレフィックスされます。#div_ctlDoc のビューアの場合、IDは ctlDoc で、関数は ctlDoc_Created, ctlDoc_Changed, ctlDoc_Deleted, ctlDoc_Properties です。綴りミスや名前変更された関数は呼び出されません。

SaveAnnotations() は保存されたかどうかを返しません: 結果は onAnnSaved または onAnnSaveError を通じて届きます。戻り値を読むコードは「unsaved changes」フラグをクリアしません。

C# でアノテーションを作成

オープンセッションにバインドされたマネージャを取得し、アノテーションを追加し、ロードします(タイプには using Doconut.Annotations;、Rectangle/Color 用には using System.Drawing; を使用)。

csharp
app.MapPost("/api/annotations/load-sample", (string token, Viewer viewer) =>
{
    // 開いているセッションのページ寸法にバインドされます
    var manager = viewer.GetAnnotationManager(token);
    var pageCount = viewer.GetPageCount(token);

    // ページあたり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)。

TypeNotes
StampAnnotationフォントサイズ、枠線、色を持つテキストスタンプ;Opacity、Rotate をサポート
NoteAnnotationテキスト、背景色、フォントサイズ、TitleColor を持つ付箋ノート
RectangleAnnotation枠線と塗りつぶしの色、Title/ShowTitle
CircleAnnotation枠線と塗りつぶし、ShowBorder
EllipseAnnotation枠線と塗りつぶし、ShowBorder
TriangleAnnotation枠線の色、BackColor、ShowBorder
LineAnnotation幅と色を持つ直線
ArrowAnnotation矢印ヘッド付きの線;設定可能な Direction(タイプ ArrowDirection、コンパスポイント、デフォルト E)
FreehandAnnotationエンコードされた FreehandData ポイントからのフリーストローク
ImageAnnotationURL からの画像。相対 URL はアノテーションが追加されたときにリクエストホストに対して解決されます;サーバーは画像を焼き込み時にのみ取得します — 以下のエクスポート注記を参照してください

AnnotationManager API

MemberPurpose
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
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とエラーメッセージが赤で表示されます。

永続化ワークフロー

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

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

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

  • 注釈リクエストは、ページリクエストと同じセッション/トークンのセキュリティを使用します。
  • サーバー側リクエスト偽装を防ぐため、ユーザー提供の画像URLを検証・制御してください。
  • エクスポートは、画面上のページレンダリングと同じライセンス/カスタム透かしの決定を適用します。
  • 大きなフリーハンドペイロードや高解像度エクスポートはメモリ使用量を増加させます。実際的なドキュメントとズーム値でテストしてください。

トラブルシューティング

症状確認項目
注釈リボンが表示されないAnnotation の機能と4つの注釈CSS/スクリプトフラグ
保存コールバックがエラーを報告するトークン/セッションの期限切れとミドルウェア BasePath
ctlDoc_Created(または別のイベント関数)が実行されない関数名: viewer id + _ + event、グローバル関数として
C# の注釈が表示されないページ番号が1から始まり、データがアクティブなトークンにロードされている
画像注釈が画面上には表示されるがエクスポートに含まれない画像のホストがプライベートまたはループバックアドレスである — 上記参照
再度開いたドキュメントに注釈がないビューアセッション外でXML/データを永続化し、次に新しいトークンにロードしてください

このページは役に立ちましたか?