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 檢視器,請保留其作為顯示用途,僅使用這些端點進行儲存——幾何規則不會改變。