如何在 .NET 使用 GroupDocs.Annotation 建立預覽

產生 如何建立預覽 體驗是現代以文件為中心的應用程式的基石。使用 .NET 版 GroupDocs.Annotation，您可以渲染 PDF 縮圖、產生安全的文件預覽串流，並在行動裝置上仍保持使用者介面流暢。在本指南中，您將了解為何預覽產生很重要、探索常見的實作情境，並取得將高品質預覽加入自家解決方案的路線圖。

快速回答

AnnotationApi 類別是 GroupDocs.Annotation 的核心元件，負責載入文件並建立預覽影像。GetPages 方法會以位元組陣列回傳已渲染的頁面影像。HideAnnotations 旗標會從渲染的影像中移除所有註解圖層。

  • 什麼是渲染 PDF 縮圖的最快方法？ 使用 AnnotationApi 載入 PDF，設定 DPI = 150，然後呼叫 GetPages —— 首頁會在 2 MB 檔案下於 200 ms 內以 PNG 形式回傳。
  • 我可以在預覽中隱藏所有註解嗎？ 可以 —— 在渲染之前使用 HideAnnotations 旗標，即可產生乾淨的視圖。
  • 預覽產生是執行緒安全的嗎？ API 為無狀態；您可以安全地平行執行多個預覽任務。
  • 在正式環境使用需要授權嗎？ 需要有效的 GroupDocs.Annotation 授權才能無限制產生預覽。
  • 支援哪些 .NET 版本？ .NET Framework 4.6+、.NET Core 3.1+、.NET 5/6/7。

什麼是文件預覽？

文件預覽是一種輕量級的視覺表示，通常為單張或多張影像，讓使用者在不下載完整文件的情況下快速瀏覽內容。它能提升使用者體驗、減少頻寬使用，並透過只顯示您決定渲染的部分，增加安全性。

為何使用安全的文件預覽？

安全的文件預覽可確保敏感的中繼資料、隱藏圖層或受限註解永不離開伺服器。GroupDocs.Annotation 會加密預覽串流，並剔除所有未明確允許的標記，讓您完整掌控最終使用者看到的內容。量化說明：此函式庫支援 30+ 檔案格式，在使用預設 DPI 150 時，能在標準 8 核心伺服器上於 2 秒內產生 500 頁 PDF 的預覽。

如何渲染 PDF 縮圖？

使用 AnnotationApi 載入 PDF，指定 150‑300 DPI 以獲得清晰文字，並請求首頁以 PNG 形式返回。此兩步驟方法會回傳位元組陣列，您可以直接串流至瀏覽器或寫入磁碟快取。使用較高 DPI（例如 300）可提升文字密集文件的可讀性，而較低 DPI（例如 72）則可減少縮圖格的檔案大小。

前置條件

  • .NET Framework 4.6+ 或 .NET Core 3.1+ 已安裝。
  • 有效的 GroupDocs.Annotation 授權（臨時授權可用於評估）。
  • 取得您欲預覽的 PDF、Word、Excel 或其他支援檔案的存取權限。

如何逐步建立預覽

要建立預覽，您需要安裝 GroupDocs.Annotation 套件、使用授權初始化 API、設定預覽選項、產生影像，並視需要快取結果。以下各節將以程式碼範例逐步說明每個步驟，展示如何隱藏註解、設定 DPI，以及有效處理大型檔案。

步驟 1：安裝 NuGet 套件

在專案的 Package Manager Console 中開啟，執行以下指令：

Install-Package GroupDocs.Annotation

步驟 2：初始化 API

建立 AnnotationApi 實例，傳入授權檔案路徑以及可選的設定（例如快取資料夾、記憶體限制）。

var config = new AnnotationConfig
{
    LicensePath = "GroupDocs.Annotation.lic",
    CacheFolder = Path.Combine(AppDomain.CurrentDomain.BaseDirectory, "Cache")
};
var annotationApi = new AnnotationApi(config);

步驟 3：產生無註解的預覽

將 HideAnnotations 旗標設為 true，選擇所需的 DPI，並請求所需的頁面。

var previewOptions = new PreviewOptions
{
    HideAnnotations = true,
    Dpi = 150,
    OutputFormat = PreviewOutputFormat.Png,
    PageNumbers = new[] { 1 }   // first page only for thumbnail
};

byte[] previewBytes = annotationApi.GetPreview("sample.pdf", previewOptions);
File.WriteAllBytes("sample_thumb.png", previewBytes);

GetPreview 呼叫會回傳位元組陣列，您可以直接傳送至 HTTP 回應、儲存於 CDN，或嵌入 UI 元件中。

步驟 4：快取與重複使用預覽

為避免重複產生相同的預覽，可使用來源檔案與預覽設定的雜湊值作為快取鍵來儲存影像。當來源文件變更時，透過比對時間戳記來使快取失效。

string cacheKey = $"{Path.GetFileNameWithoutExtension(filePath)}_{previewOptions.Dpi}_{previewOptions.HideAnnotations}";

步驟 5：有效處理大型文件

對於大於 100 MB 的檔案，請使用 using 區塊確保 AnnotationApi 及時釋放內部串流。若需多頁預覽，請分批處理頁面，於處理下一批前釋放當前批次。

常見實作情境

  • 文件管理系統 – 顯示縮圖格子以快速視覺導覽。
  • 協作平台 – 為審閱者渲染僅預覽的視圖，之後可依需求切換註解圖層。
  • 網站入口 – 為檔案連結提供滑鼠懸停預覽，減少完整下載需求。
  • 行動應用程式 – 產生低解析度 PNG（72 DPI），使每頁頻寬使用低於 50 KB。

疑難排解預覽產生

  • 大型 PDF 記憶體激增 – 確保在每個預覽批次後呼叫 Dispose() 於 AnnotationApi，並限制同時執行的預覽任務數量。
  • 縮圖文字模糊 – 提升 DPI 至 300 或改用 PNG 輸出格式；JPEG 壓縮會使細字元變得模糊。
  • Excel 預覽缺少圖像 – 在預覽選項中設定 LoadCharts = true，確保工作簿的圖表物件完整載入。
  • 回應時間緩慢 – 將預覽產生移至背景工作者（例如 Task.Run），在真實預覽完成前先回傳佔位圖像。

常見問與答

Q: 我可以為受密碼保護的文件產生預覽嗎？
A: 可以。於建立 AnnotationApi 實例時於 LoadOptions 中提供密碼；在成功解密後即會產生預覽。

Q: 此函式庫支援為非 PDF 格式（如 DOCX 或 XLSX）渲染預覽嗎？
A: 當然。GroupDocs.Annotation 可為超過 30 種不同格式渲染預覽，包括 DOCX、XLSX、PPTX 以及多種影像類型。

Q: 我如何確保預覽不會洩漏隱藏的中繼資料？
A: 在 PreviewOptions 中使用 HideMetadata 選項；API 會在渲染影像前剔除所有文件屬性。

Q: 將預覽端點公開是否安全？
A: 預覽串流於伺服器端產生，並可透過 HTTPS 傳送。結合基於 Token 的驗證，可將存取限制於授權使用者。

Q: 建議的快取過期政策是什麼？
A: 依來源文件版本的生命週期快取預覽。當文件的最後修改時間戳記變更時，讓快取影像失效並重新產生。

其他資源

最後更新： 2026-08-09
測試環境： GroupDocs.Annotation 23.10 for .NET
作者： GroupDocs

相關教學