GroupDocs.Annotation không phụ thuộc vào giao diện người dùng. Nó đọc và ghi các đánh dấu trong tài liệu và không vẽ gì trên màn hình. Đối với một thư viện máy chủ, đây là cách chia tách đúng — và nó để lại một câu hỏi cho mọi người áp dụng nó: một người thực sự vẽ chú thích như thế nào?

Các câu trả lời thường gặp thường nặng nề: nhúng một trình xem thương mại, hoặc áp dụng bản demo Angular rồi cố gắng mở rộng nó. Có một cách nhẹ hơn. Hình ảnh các trang, một canvas và sáu endpoint — không có thành phần trình xem, không có framework front-end, không có bước xây dựng, không có CDN. Nó cũng chạy mà không cần truy cập mạng ra bên ngoài, điều này quan trọng hơn so với trước đây.

Mẫu code có trên GitHub: browser-annotation-ui-net — dotnet run và kéo một hộp trên trang.

Ý tưởng trong một đoạn

Kết xuất mỗi trang một lần dưới dạng PNG không có chú thích và lưu vào bộ nhớ đệm. Gửi danh sách chú thích tới trình duyệt dưới dạng dữ liệu. Canvas vẽ các đánh dấu lên trên hình ảnh. Thêm một bình luận sau đó chỉ là một lần ghi nhỏ vào tài liệu cộng với việc tải lại danh sách — không phải kết xuất lại trang — và các đánh dấu vẫn có thể chọn, nhấp và trả lời thay vì bị nhúng vào hình ảnh.

Các endpoint

Method Route Purpose
GET /api/documents/{name}/info số lượng trang và kích thước của mỗi trang, tính bằng điểm
GET /api/documents/{name}/pages/{n}/image PNG của trang n
GET /api/documents/{name}/annotations mỗi chú thích dưới dạng một hình chữ nhật trong đơn vị trang
POST /api/documents/{name}/annotations thêm một
PUT /api/documents/{name}/annotations/{id} thay đổi tin nhắn hoặc thêm một phản hồi
DELETE /api/documents/{name}/annotations/{id} xóa một

Mỗi lần ghi trả về danh sách đầy đủ, vì vậy trình duyệt không bao giờ phải suy đoán về những gì máy chủ hiện đang giữ.

Kết xuất

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

So sánh dấu thời gian của hình ảnh đã lưu trong bộ nhớ đệm với tài liệu và chỉ kết xuất lại khi tài liệu thực sự đã thay đổi.

Pixel vào, đơn vị trang ra

Canvas giữ hình chữ nhật của nó bằng pixel của hình ảnh và gửi kích thước của hình ảnh mà nó đã vẽ lên — không phải hệ số tỉ lệ:

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

Quyết định đó là yếu tố giữ cho giao diện người dùng đúng khi độ phân giải preview thay đổi, khi CSS phóng to/thu nhỏ hình ảnh, hoặc khi ai đó mở nó trên điện thoại. Máy chủ thực hiện các phép tính:

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 được đo từ góc trên‑trái của trang — cùng hướng mà trình duyệt đo — vì vậy một hộp được vẽ sẽ được ánh xạ với tỉ lệ mà không cần lật.

Gửi một hình dạng hình chữ nhật tới trình duyệt

Đánh dấu văn bản không chia sẻ nguồn gốc đó. HighlightAnnotation.Points và các thành phần liên quan của nó được đo từ góc dưới‑trái. Chuyển đổi trên máy chủ, để phần front‑end chỉ bao giờ thấy các hộp ở góc trên‑trái:

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

Thực hiện điều này và một phần tô sáng được thêm trong Word, trong Acrobat, hoặc bởi một đợt đánh giá tự động sẽ xuất hiện ở vị trí đúng trong UI của bạn mà JavaScript không cần biết gì về hình học PDF.

Ghi đổi tên tệp tạm

Annotator giữ nguồn mở và không thể lưu đè lên tệp mà nó đang đọc:

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

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

Áp dụng khóa per‑document quanh toàn bộ chuỗi thao tác. Hai yêu cầu đọc, thay đổi và ghi lại cùng một tệp đồng thời sẽ mất một trong các thay đổi.

Những gì thiết kế này không giải quyết

Nên nói thẳng, vì nó quyết định liệu bạn có thể phát hành nó như hiện tại hay không:

  • ID chú thích thay đổi sau khi ghi. Chúng được gán khi tài liệu được đọc, không được lưu trong tài liệu. Một UI tải lại danh sách sau mỗi thay đổi là ổn. Hệ thống đa người dùng nên lưu các chú thích trong bảng riêng và sử dụng nhập‑xuất để di chuyển chúng vào và ra khỏi tệp — đây cũng là cách bạn có được lịch sử audit và khả năng hiển thị theo người dùng.
  • Toàn bộ tài liệu được ghi lại sau mỗi thay đổi. Phù hợp cho hợp đồng 30 trang, không phù hợp cho kho lưu trữ 2.000 trang.
  • Không có xác thực. Mọi người gọi trong mẫu đều là “Reviewer”.

Chạy nó

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

Hoặc trong một container, với --network none nếu bạn muốn quan sát nó hoạt động mà không có bất kỳ lưu lượng ra nào:

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

Phiên bản hướng dẫn từng bước có trong tài liệu: Xây dựng UI chú thích cho ứng dụng web của bạn. Nếu bạn đã nhúng một trình xem PDF JavaScript, giữ nó để hiển thị và chỉ sử dụng các endpoint này cho việc lưu trữ — không có quy tắc hình học nào thay đổi.