如何在 C# 生成文件預覽時隱藏註釋

如果您需要分享文件預覽但想要 隱藏註釋,您來對地方了。本教學將示範如何使用 GroupDocs.Annotation for .NET 在 C# 中產生乾淨、無註釋的預覽,涵蓋從安裝到效能優化的全部內容。

快速答案

  • 產生預覽的主要類別是什麼? Annotator 類別。
  • 哪個選項可停用註釋? 在 PreviewOptions 中設定 RenderAnnotations = false。
  • 最低 .NET 版本? 建議使用 .NET 6;.NET Core 3.1 亦可使用。
  • 我可以預覽 PDF 和 Word 檔案嗎? 可以 — 支援超過 50 種格式。
  • 測試是否需要授權? 可取得臨時授權供免費試用。

什麼是隱藏註釋?

隱藏註釋 是在產生文件預覽圖像時抑制來源檔案中任何評論、標記或標註的過程。此技巧確保視覺輸出僅包含原始內容,適用於公開發佈、客戶簡報或任何需要隱藏內部備註的情境。

為何需要乾淨的文件預覽(以及如何取得)

當您與客戶、合作夥伴或公眾分享預覽時,內部評論可能顯得不專業,甚至洩漏機密策略。乾淨的預覽可將焦點放在內容上,保護您的工作流程。GroupDocs.Annotation 允許切換註釋渲染,讓您能從同一來源檔案產生帶註釋與不帶註釋的版本。

開始前您需要的項目

前置條件是什麼?

要開始使用,您需要在開發機器上安裝以下元件。事先準備好這些項目可確保程式碼不會在執行時發生錯誤,並且能在本機測試完整的預覽流程。

  • GroupDocs.Annotation for .NET 25.4.0 或更新版本(最新版本加入記憶體最佳化的預覽產生)。
  • Visual Studio 2022 或任何相容 .NET 的 IDE。
  • 有效的 GroupDocs 授權(臨時授權可免費評估)。

快速設定:將 GroupDocs.Annotation 加入您的專案

選項 1:NuGet 套件管理員主控台

Install-Package GroupDocs.Annotation -Version 25.4.0

選項 2:.NET CLI(我的個人偏好)

dotnet add package GroupDocs.Annotation --version 25.4.0

專業提示: 請在所有團隊成員之間保持套件版本一致,以避免細微的渲染差異。

使用簡短的健全性檢查驗證安裝:

using System.IO;
using GroupDocs.Annotation;

// This should compile without errors
using (Annotator annotator = new Annotator("path/to/document"))
{
    // You're good to go!
}

如何產生不含註釋的預覽?

使用 Annotator 載入文件,設定 PreviewOptions,然後呼叫 GeneratePreview。將 RenderAnnotations = false 設定為不渲染註釋,告訴引擎在輸出圖像中省略所有評論、標記與印章。

步驟 1:初始化您的 annotator(基礎)

The Annotator class loads a document and provides methods for rendering and annotation manipulation.

```csharp
using (Annotator annotator = new Annotator("path/to/your/document"))
{
    // All your preview generation happens within this scope
}

### 步驟 2:設定您的 preview options(魔法發生的地方)
The `PreviewOptions` class defines rendering parameters such as format, resolution, and whether annotations are included.  
```csharp
```csharp
// Define how each page should be handled during preview generation
PreviewOptions previewOptions = new PreviewOptions(pageNumber =>
{
    var pagePath = $"output_directory\\result{pageNumber}.png";
    return File.Create(pagePath);
});

// Set the output format for the preview as PNG
previewOptions.PreviewFormat = PreviewFormats.PNG;

// Specify which pages to include in the preview generation
previewOptions.PageNumbers = new int[] {1, 2, 3, 4, 5, 6};

// The key setting: disable rendering of annotations
previewOptions.RenderAnnotations = false;

### 步驟 3:產生預覽(成果)
The `GeneratePreview` method processes the document according to the supplied options and returns file paths for the created images.  
```csharp
```csharp
annotator.Document.GeneratePreview(previewOptions);

## 常見問題(以及如何解決)

### 問題 1:「找不到檔案」錯誤
**症狀:** 建立 `Annotator` 時拋出例外。  
**解決方案:** 使用絕對路徑或確認相對路徑正確。簡短的健全性檢查如下:
```csharp
string fullPath = Path.GetFullPath("your-document.pdf");
using (Annotator annotator = new Annotator(fullPath))

問題 2:預覽品質差

症狀: 輸出圖像模糊或像素化。
解決方案: 提高 PreviewOptions 中的 DPI 設定以改善清晰度:

previewOptions.Width = 1920;  // Higher resolution
previewOptions.Height = 1080;

問題 3:大型文件的記憶體問題

症狀: OutOfMemoryException 或處理速度明顯變慢。
解決方案: 分批處理頁面,而非一次載入整個檔案:

// Process 5 pages at a time instead of all at once
previewOptions.PageNumbers = new int[] {1, 2, 3, 4, 5};

真實案例(此情況實際重要)

法律文件共享

律師事務所可分發隱藏內部談判備註的合約預覽,保持與客戶的溝通專業。

學術出版

研究人員在經過一次同行評審後,可分享乾淨的手稿草稿,於提交期刊前移除審稿人評論。

商業報告

利害關係人可收到不含「請驗證此數字」或「會前更新」等備註的精緻報告,避免削弱信心。

文件存檔

合規團隊保存無註釋的副本以符合規範要求,同時保留原始帶註釋版本供內部參考。

效能最佳實踐

如何管理大型檔案的記憶體?

將頁面分成小批次處理,並及時釋放 Annotator。此方法可在超過 200 頁的文件上將峰值記憶體使用量降低最高 60 %。

// Good: Dispose properly
using (Annotator annotator = new Annotator(documentPath))
{
    // Generate preview
} // Automatically disposed here

// Avoid: Manual disposal (easy to forget)
Annotator annotator = new Annotator(documentPath);
// ... use annotator
annotator.Dispose(); // Easy to forget or skip due to exceptions

如何加速批次處理?

將 100 頁文件分成每組 10 頁,依序產生每組,並將結果寫入暫存資料夾。此技巧可在一般伺服器硬體上將總處理時間縮短約 30 %。

// Process in batches of 10 pages
for (int startPage = 1; startPage <= totalPages; startPage += 10)
{
    int endPage = Math.Min(startPage + 9, totalPages);
    var pageRange = Enumerable.Range(startPage, endPage - startPage + 1).ToArray();
    
    previewOptions.PageNumbers = pageRange;
    annotator.Document.GeneratePreview(previewOptions);
}

如何選擇最佳輸出格式?

  • PNG: 最佳視覺保真度;適合詳細圖表。
  • JPEG: 檔案較小;適用於文字密集且可接受輕微壓縮痕跡的文件。
  • WebP: 現代格式,壓縮效果佳;採用前請確認瀏覽器支援度。

進階設定選項

如何自訂檔案命名?

PreviewOptions 的 lambda 允許您在每個檔名中加入頁碼、時間戳記或自訂識別碼。

PreviewOptions previewOptions = new PreviewOptions(pageNumber =>
{
    string timestamp = DateTime.Now.ToString("yyyyMMdd_HHmmss");
    var pagePath = $"previews\\{timestamp}_page_{pageNumber:D3}.png";
    return File.Create(pagePath);
});

如何控制影像品質?

調整 PreviewOptions 中的 Width、Height 與 Resolution 屬性。較大的尺寸會提升品質,但會增加檔案大小。

previewOptions.Width = 2400;   // Higher resolution
previewOptions.Height = 3200;  // Maintains aspect ratio
previewOptions.PreviewFormat = PreviewFormats.PNG; // Best quality

如何僅處理特定頁面?

將 PageNumbers 集合設定為您需要的確切頁碼,可減少 I/O 並加速多百頁文件的產生。

// Only process odd pages (useful for double-sided documents)
var oddPages = Enumerable.Range(1, totalPages)
                        .Where(p => p % 2 == 1)
                        .ToArray();
previewOptions.PageNumbers = oddPages;

疑難排解指南

為何預覽產生會靜默失敗?

常見原因包括:

  1. 輸出目錄不存在或缺乏寫入權限。
  2. 受密碼保護的來源文件。
  3. 不支援的檔案格式。
  4. 系統記憶體不足。

為何註釋仍然顯示?

確保在呼叫 GeneratePreview 前,已在 PreviewOptions 實例上設定 RenderAnnotations = false。RenderAnnotations 屬性決定預覽渲染時是否繪製註釋層。

previewOptions.RenderAnnotations = false;  // Must be explicitly false
previewOptions.RenderComments = false;     // Also disable comments if needed

為何效能緩慢?

  • 測試時降低解析度。
  • 每批次處理較少頁面。
  • 確認使用最新的 GroupDocs.Annotation 版本(25.4.0 或更新),其中包含效能改進。

何時不宜使用此方法

  • 即時預覽: 對於即時、即時生成的預覽,客戶端渲染可能更快。
  • 互動文件: 表單或嵌入式腳本在渲染為靜態圖像時可能失去功能。
  • 可伸縮圖形: 若需向量輸出(例如 SVG),請考慮產生 PDF 頁面而非點陣圖像。

總結

使用 GroupDocs.Annotation for .NET 產生不含註釋的乾淨文件預覽相當簡單。請記得:

  1. 正確釋放 Annotator。
  2. 在 PreviewOptions 中設定 RenderAnnotations = false。
  3. 批次處理大型檔案以降低記憶體使用。
  4. 使用真實文件測試,微調 DPI 與格式選擇。

從簡單的測試檔案開始,試驗上述選項,即可擁有適合任何受眾的專業級、無註釋預覽。

常見問答

Q: 我可以預覽除 DOCX 之外的文件嗎?
A: 當然可以!GroupDocs.Annotation 支援超過 50 種格式,包括 PDF、PPTX、XLSX 以及常見影像類型。請參閱 文件說明 以取得完整清單。

Q: 我該如何處理受密碼保護的文件?
A: 使用包含密碼的 LoadOptions 物件初始化 Annotator。LoadOptions 類別允許您指定文件密碼及其他載入參數。

LoadOptions loadOptions = new LoadOptions { Password = "your-password" };
using (Annotator annotator = new Annotator("protected-doc.pdf", loadOptions))

Q: 我可以在 Web 應用程式中產生預覽嗎?
A: 可以。相同的程式碼可在 ASP.NET 中使用,但請將產生的圖像存放於暫存資料夾,並在回應後清除,以避免磁碟膨脹。

Q: 網頁顯示的最佳輸出格式是什麼?
A: PNG 提供最高品質,JPEG 載入較快,若目標瀏覽器支援,WebP 則提供最佳壓縮。PNG 是最安全的預設選擇。

Q: 我該如何有效處理極大型文件?
A: 將頁面分批處理(每批 5‑10 頁),監控記憶體使用,並可選擇顯示進度條以提升使用者體驗。

Q: 我可以自訂輸出影像品質嗎?
A: 可以——在 PreviewOptions 中調整 Width、Height 與 Resolution。較大的數值會提升品質,但也會增加檔案大小。

Q: 如果我需要同時擁有帶註釋與不帶註釋的版本該怎麼辦?
A: 產生兩次預覽——一次設定 RenderAnnotations = true,一次設定 false。將每組結果存放於不同目錄,以便檢索。

資源

最後更新: 2026-10-05
測試環境: GroupDocs.Annotation 25.4.0 for .NET
作者: GroupDocs

相關教學