GroupDocs.Annotation 是與 UI 無關的。它在文件內讀寫標記,且不在螢幕上繪製任何內容。對於伺服器函式庫而言,這樣的分工是正確的——但它也為所有採用它的人留下了一個問題:實際上使用者如何繪製註解?

常見的解決方案都很笨重:嵌入商業檢視器,或採用 Angular 示範再試著擴充。還有更輕量的方案。頁面影像、畫布與六個端點——不需要檢視器元件、不需要前端框架、無建置步驟、也不需要 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 新增一個
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);

比較快取影像的時間戳記與文件的時間戳記,僅在文件實際變更時重新渲染。

輸入像素,輸出頁面單位

畫布以影像像素保存其矩形,並傳送它所繪製影像的尺寸——而不是比例因子:

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

這個決策確保了 UI 在預覽解析度變更、CSS 縮放影像,或在手機上開啟時仍保持正確。伺服器負責計算:

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

在整個流程前後使用每文件的鎖定。若同時有兩個請求讀取、變更並重新寫入同一檔案,將會遺失其中一次的變更。

此設計未解決的問題

值得直白說明,因為它決定了你是否能直接使用此設計:

  • Annotation ids 會在寫入後變更。 它們在讀取文件時分配,並未儲存在文件內。每次變更後重新載入清單的 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 檢視器,請保留其作為顯示用途,僅使用這些端點進行儲存——幾何規則不會改變。