注釈

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

Doconut の注釈は 2 方向で機能します。ユーザーがブラウザウィジェットで描画し、サーバーがページごとに保存するか、またはコードで注釈を作成し、オープンセッションにロードします。いずれの場合もページに表示され、PDF や PNG エクスポートに焼き込むことができます。

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

注釈 UI を有効化

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

注釈ファイルは Viewer ファイルと一緒に出力します。これらはライセンスで制御されるため、機能が付与されたときにのみタグが表示されます。MVC 5 では、コントローラでタグを構築します(ビューには @inject がありません):

csharp
public class ViewerController : Controller
{
    public ActionResult Index()
    {
        var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
        ViewBag.ViewerCss = viewer.ReferenceCss(new CssConfig
        {
            IncludeViewerCss     = true,
            IncludeAnnotationCss = true    // jquery-ui.min.css + annotationBar.css
        });
        ViewBag.ViewerScripts = viewer.ReferenceScripts(new ScriptConfig
        {
            IncludeJQuery            = true,
            IncludeViewerScripts     = true,
            IncludeAnnotationScripts = true,  // jquery-ui, raphael.js, annotation.js
            IncludeAnnotationBar     = true   // 埋め込まれたアノテーションリボン
        });
        ViewBag.IsAnnotationEnabled = viewer.IsAnnotationEnabled;
        return View();
    }
}

マークアップ内に完全な 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 を生成します。ボタンやダイアログをコピーする必要はありません。まず docViewer を初期化し、サーバーが注釈がライセンスされていることを確認したときにのみ Ribbon を作成します:

html
@Html.Raw(ViewBag.ViewerCss)
@Html.Raw(ViewBag.ViewerScripts)
<script>
    var annBar = null;
    var currentToken = '';

    var objViewer = $('#div_ctlDoc').docViewer({
        BasePath: '/',
        ResPath:  'doconut-res/images',
        onAnnLoaded:    function () { if (annBar) annBar.handleAnnLoaded(); },
        onAnnSaved:     function () { if (annBar) annBar.handleAnnSaved(); },
        onAnnSaveError: function () { if (annBar) annBar.handleAnnSaveError(); },
        onAnnClosed:    function () { if (annBar) annBar.handleAnnClosed(); },
        onError:        function (message) { console.error('Viewer error:', message); }
    });

    @if ((bool)ViewBag.IsAnnotationEnabled)
    {
        <text>
    annBar = $('#annBarMount').doconutAnnotationBar({
        docId: 'ctlDoc',
        getRequestParams: function () { return { token: currentToken }; },
        onLayout: function () { requestAnimationFrame(function () { objViewer.Refit(); }); }
    });
    annBar.attach(objViewer);
        </text>
    }
</script>

機能がない場合、ReferenceScripts は Ribbon のスクリプトを除外するため、サーバー側の if が保護されていない doconutAnnotationBar(...) 呼び出しがページを壊すのを防ぎます。Web Forms では、同じガードを <% if (IsAnnotationEnabled) { %> … <% } %> として記述します。

Ribbon からの保存はデータを DocImage.axd(AnnSave)に投稿し、ページごとのドキュメントセッションに保存します。ロード(AnnLoad)は、注釈付きページがレンダリングされると自動的に行われます。

独自のツールバーから annBar.open() と annBar.close() を使用して Ribbon を開閉します。その公開 API:

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

onStatus、onToast、onLayout、onEditStart、および onEditEnd はオプションのホストコールバックです。endpoints オブジェクトは exportPdf、exportPng、imageUpload、imageList も提供できます;エンドポイントが設定されていないコントロールは非表示のままです。

コールバックの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 を通じて届きます。戻り値を読むコードは「未保存の変更」フラグをクリアしません。

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

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

csharp
// POST /Annotations/LoadSample?token=...
[HttpPost]
public ActionResult LoadSample(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<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));

    // セッションにロードします - ビューアが取得し、レンダラがそれらを組み込みます
    // image/PDF エクスポート.
    viewer.LoadAnnotationData(token, manager);
    return new HttpStatusCodeResult(200);
}

アノテーションタイプ

すべてのタイプは 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)エンコードされたアノテーションデータ — ウィジェットが消費するエンベロープ
GetAnnotationXml()XML 形式

Viewer はセッションに対するロードと読み取り操作をミラーします: LoadAnnotationData(token, manager) または LoadAnnotationData(token, encodedData)、LoadAnnotationXML(token, xml)、および GetAnnotationXML(token)。

アノテーションを焼き付けてエクスポート

csharp
// 注釈が描画されたすべてのページのPDF
public async Task<ActionResult> ExportPdf(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] pdf = await viewer.ExportAnnotationsToPdfAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return File(pdf, "application/pdf", "export.pdf");
}

// またはページごとのPNGを含むZIP
public async Task<ActionResult> ExportPngZip(string token)
{
    var viewer = Doconut.DoconutHost.Services.GetRequiredService<Viewer>();
    byte[] zip = await viewer.ExportAnnotationsToPngZipAsync(token, zoom: 100, ct: Response.ClientDisconnectedToken);
    return File(zip, "application/zip", "annotations-png.zip");
}

エクスポートは画面上のレンダリングと同じバーナーを使用し、同じライセンスとカスタム透かしの決定を行います。

イントラネットホストでの画像注釈が「画像がブロックされました」とエクスポートされる

ビューアとエクスポートは、ImageAnnotation の画像を異なる場所から取得します:

対象画像をダウンロードする側イントラネットまたは開発ホスト上
ブラウザ内のビューアユーザーのブラウザ画像が表示されます
ExportAnnotationsToPdfAsync / …PngZipAsyncサーバー赤い 「画像がブロックされました」 プレースホルダー

サーバーが画像を取得して埋め込もうとする際、プライベートネットワークに戻るアドレスは拒否されます: ループバック (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 またはデータを永続化し、次に新しいトークンにロードしてください

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