GroupDocs.Annotation は UI に依存しません。ドキュメント内のマークアップを読み書きし、画面に何も描画しません。サーバーライブラリとしては適切な分割であり、これを採用するすべての人に一つの質問が残ります:実際にユーザーはどのようにアノテーションを描くのでしょうか?

一般的な回答は重いです:商用ビューアを埋め込むか、Angular デモを採用してそれを拡張しようとするか。もっと軽い方法があります。ページ画像、キャンバス、そして 6 つのエンドポイント — ビューアコンポーネントなし、フロントエンドフレームワークなし、ビルドステップなし、CDN なし。さらに、全く外部ネットワークアクセスがなくても動作し、以前よりも重要です。

サンプルは GitHub にあります: browser-annotation-ui-net — dotnet run してページ上でボックスをドラッグしてください。

アイデアを一文で

各ページを一度だけ PNG(アノテーションなし)としてレンダリングし、キャッシュします。アノテーションリストをデータとしてブラウザに送ります。キャンバスが画像の上にマークアップを描画します。コメントを追加することは、ドキュメントへの小さな書き込みとリストのリロードに過ぎず、ページの再レンダリングは行われません。そして、マークアップは画像に埋め込まれるのではなく、選択可能・クリック可能・回答可能なままです。

エンドポイント

メソッド ルート 目的
GET /api/documents/{name}/info ページ数と各ページのサイズ(ポイント単位)
GET /api/documents/{name}/pages/{n}/image ページ n の PNG
GET /api/documents/{name}/annotations 各アノテーションをページ単位の矩形として取得
POST /api/documents/{name}/annotations 1 件追加
PUT /api/documents/{name}/annotations/{id} メッセージを変更または返信を追加
DELETE /api/documents/{name}/annotations/{id} 1 件削除

各書き込みは完全なリストを返すため、ブラウザはサーバーが現在保持しているものについて推測する必要がありません。

レンダリング

PreviewOptions previewOptions = new(page => File.Create(CachePath(name, page)))
{
    PreviewFormat = PreviewFormats.PNG,
    PageNumbers = new[] { pageNumber },   // 1-based
    RenderAnnotations = false,            // the canvas draws the markup
    Resolution = 144
};

annotator.Document.GeneratePreview(previewOptions);

キャッシュされた画像のタイムスタンプをドキュメントのものと比較し、ドキュメントが実際に変更されたときだけ再レンダリングします。

ピクセル入力、ページ単位出力

キャンバスは矩形を画像ピクセル単位で保持し、描画した画像のサイズを送信します — スケール係数ではありません:

body: JSON.stringify({
    page: currentPage,
    x, y, width, height,
    imageWidth: img.clientWidth,
    imageHeight: img.clientHeight,
    message: window.prompt('Comment'),
    user: 'Reviewer'
})

この決定一つが、プレビュー解像度が変わったとき、CSS が画像をスケーリングしたとき、またはスマートフォンで開いたときに UI を正しく保つ要因です。サーバーが計算を行います:

double scaleX = page.Width / request.ImageWidth;
double scaleY = page.Height / request.ImageHeight;

annotator.Add(new AreaAnnotation
{
    PageNumber = page.PageNumber - 1,     // PageInfo is 1-based, annotations are 0-based
    Box = new Rectangle(
        (float)(request.X * scaleX), (float)(request.Y * scaleY),
        (float)(request.Width * scaleX), (float)(request.Height * scaleY)),
    BackgroundColor = 0xFFE699,
    PenColor = 0xE08C00,
    Opacity = 0.35,
    Message = request.Message,
    User = new User { Id = 1, Name = request.User, Role = Role.Editor }
});

AreaAnnotation.Box はページの左上隅から測定されます — ブラウザが測定する方向と同じです — したがって描画されたボックスはスケールのみでマッピングされ、反転はありません。

矩形の形状をブラウザに送信

テキストマークアップはその原点を共有しません。HighlightAnnotation.Points とその関連は 左下 隅から測定されます。サーバー側で変換し、フロントエンドでは常に左上のボックスだけが見えるようにします:

x = minX;
y = page.Height - maxY;      // flip to top-left
width = maxX - minX;
height = maxY - minY;

これを行うと、Word や Acrobat、あるいは automated review pass で追加されたハイライトが、PDF のジオメトリについて JavaScript が何も知らなくても、UI の正しい位置に表示されます。

書き込み時にスワップファイルを使用

アノテータはソースを開いたままにし、読み込んでいるファイルに上書き保存できません:

using (Annotator annotator = new Annotator(path))
{
    annotator.Add(annotation);
    annotator.Save(path + ".tmp");
}

File.Move(path + ".tmp", path, overwrite: true);
InvalidatePreviewCache(name);

全シーケンスをドキュメント単位のロックで囲んでください。同時に同じファイルを読み取り、変更し、書き換える二つのリクエストは、変更の一方を失います。

この設計が解決しないこと

率直に述べる価値があります。なぜなら、現状のまま提供できるかどうかを決めるからです:

  • Annotation ids change after a write. They are assigned while the document is read, not stored in it. A UI that reloads the list after every change is fine. A multi-user system should keep annotations in its own table and use import and export to move them in and out of the file — which is also how you get an audit trail and per-user visibility.
  • The whole document is rewritten on every change. Fine for a 30-page contract, wrong for a 2,000-page archive.
  • 認証はありません。 サンプル内のすべての呼び出し元は「Reviewer」です。

実行方法

git clone https://github.com/groupdocs-annotation/browser-annotation-ui-net.git
cd browser-annotation-ui-net
dotnet run --project src/AnnotationUi

またはコンテナ内で、外部への通信を全く行わない様子を確認したい場合は --network none を付けて実行します:

docker build -t annotation-ui .
docker run --rm -p 8080:8080 annotation-ui

ステップバイステップのバージョンはドキュメントにあります: Build an annotation UI for your web app。すでに JavaScript PDF ビューアを埋め込んでいる場合は、表示用にそれを保持し、これらのエンドポイントはストレージ用にのみ使用してください — ジオメトリに関するルールは変わりません。