GroupDocs.Annotation 是与 UI 无关的。它读取和写入文档中的标记,但不在屏幕上绘制任何内容。对于服务器库来说,这种划分是正确的——但它给所有采用它的人留下了一个问题:实际如何让用户绘制标注?

常见的答案都很笨重:嵌入商业查看器,或采用 Angular 示例然后尝试扩展它。有一种更轻量的方案。页面图像、一个 canvas 和六个端点——无需查看器组件、前端框架、构建步骤,也不需要 CDN。它甚至可以在完全没有外部网络访问的情况下运行,这一点比以前更重要。

示例在 GitHub 上: 浏览器注释 UI .NET — dotnet run 并在页面上拖动一个框。

一个段落概述

将每页渲染一次为 PNG 不带标注并缓存。将标注列表作为数据发送到浏览器。canvas 在图像上方绘制标记。添加评论时,只需向文档写入一次并重新加载列表——而不是重新渲染页面——标记仍然可以被选中、点击并回复,而不是被烘焙进图片。

端点

方法 路由 用途
GET /api/documents/{name}/info 页面数量以及每页的尺寸(单位:点)
GET /api/documents/{name}/pages/{n}/image 第 n 页的 PNG
GET /api/documents/{name}/annotations 将每个标注作为页面单位的矩形返回
POST /api/documents/{name}/annotations 添加一个标注
PUT /api/documents/{name}/annotations/{id} 修改消息或追加回复
DELETE /api/documents/{name}/annotations/{id} 删除一个标注

每次写入都会返回完整列表,因此浏览器永远不需要推断服务器当前持有什么。

渲染

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

将缓存图像的时间戳与文档的时间戳进行比较,仅在文档实际更改时重新渲染。

像素输入,页面单位输出

canvas 使用图像像素保存矩形,并发送它绘制的图像尺寸——而不是比例因子:

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 中添加的高亮,还是通过自动审阅批次 添加的高亮,都会出现在 UI 的正确位置,而 JavaScript 并不需要了解 PDF 几何。

写入时使用交换文件

annotator 会保持源文件打开,无法直接覆盖正在读取的文件:

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

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

在整个过程前后对每个文档加锁。两个同时读取、修改并重写同一文件的请求会导致其中一次修改丢失。

此设计未解决的问题

直言不讳地说明,因为这决定了你是否可以按原样交付:

  • 标注 ID 在写入后会改变。 它们在读取文档时分配,而不是存储在文档中。每次更改后重新加载列表的 UI 没问题。多用户系统应将标注保存在自己的表中,并使用导入/导出在文件内外移动标注——这也是获取审计日志和按用户可见性的方式。
  • 每次更改都会重写整个文档。 对于 30 页的合同来说可以接受,但对 2,000 页的档案来说就不合适。
  • 没有身份验证。 示例中的每个调用者都是 “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

分步版本位于文档中: 为您的 Web 应用构建标注 UI。
如果您已经嵌入了 JavaScript PDF 查看器,请继续使用它进行显示,仅使用这些端点进行存储——几何规则不会改变。