如何在 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(基础)

Annotator 类加载文档并提供用于渲染和批注操作的方法。

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

### 步骤 2:配置预览选项(魔法所在)
`PreviewOptions` 类定义渲染参数,例如格式、分辨率以及是否包含批注。  
```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:生成预览(收获)
`GeneratePreview` 方法根据提供的选项处理文档,并返回已创建图像的文件路径。  
```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

相关教程