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 查看器,请继续使用它进行显示,仅使用这些端点进行存储——几何规则不会改变。