使用 GroupDocs Viewer for Java 将 PDF 转换为 PNG

在本综合指南中，您将了解如何将 PDF 转换为 PNG，并保持每页的原始尺寸。保持原始页面大小对于法律文件、品牌一致的营销资产以及任何缩放都会破坏测量的技术图纸至关重要。我们将演示如何安装 GroupDocs.Viewer、配置渲染选项以及排除常见问题，以便您每次都能生成像素完美的 PNG 图像。

使用 GroupDocs.Viewer for Java 将 PDF 渲染为原始尺寸

快速答案

  • 哪个库可以在 Java 中将 PDF 转换为 PNG？ GroupDocs.Viewer for Java provides a straightforward API for convert pdf to png.
  • 如何保持原始页面尺寸？ Call setRenderOriginalPageSize(true) on the PdfOptions object.
  • 生产环境是否需要许可证？ Yes – a permanent or temporary GroupDocs license is required for non‑trial use.
  • 我可以渲染受密码保护的 PDF 吗？ Absolutely; supply the password when creating the Viewer instance.
  • 需要哪个 Java 版本？ JDK 8 or higher is fully supported.

什么是“以原始尺寸渲染 PDF”？

以原始尺寸渲染 PDF 是指在不进行任何缩放的情况下导出每页的精确尺寸。当您渲染 PDF 时，查看器可以将页面缩放以适应目标格式，或保持源文件中定义的精确尺寸。以原始尺寸渲染意味着每页都以像素完美的方式导出，这对于法律文件、档案材料以及任何不能妥协布局保真度的场景至关重要。

为什么要保留 PDF 页面尺寸？

保留原始 PDF 页面尺寸可确保在转换后视觉布局、精确测量和设计元素保持不变，这对于法律合规、品牌一致性以及图表或表单中的技术精度至关重要。它还能防止图形意外裁剪或失真，确保签名和水印在所有平台上都准确呈现。

前置条件

  • Java Development Kit (JDK)： 版本 8 或更高。
  • GroupDocs.Viewer for Java： 通过 Maven 添加库（见下文）。
  • IDE： IntelliJ IDEA、Eclipse 或任何兼容 Java 的编辑器。

设置 GroupDocs.Viewer for Java

Maven 配置

将官方 GroupDocs 仓库和 Viewer 依赖添加到您的 pom.xml 中。(请勿修改代码块——必须保持原样。)

<repositories>
   <repository>
      <id>groupdocs-repo</id>
      <name>GroupDocs Repository</name>
      <url>https://releases.groupdocs.com/viewer/java/</url>
   </repository>
</repositories>
<dependencies>
   <dependency>
      <groupId>com.groupdocs</groupId>
      <artifactId>groupdocs-viewer</artifactId>
      <version>25.2</version>
   </dependency>
</dependencies>

许可证获取

GroupDocs 提供三种授权选项：免费试用（无限页面，有限时间）、临时许可证（完整功能，最长 30 天）和永久购买（无限制的生产使用）。请选择与项目时间表相匹配的选项。

实施指南

步骤 1：初始化 GroupDocs.Viewer

Viewer 是 GroupDocs.Viewer 中的核心类，用于加载文档并提供渲染功能。创建一个 Viewer 实例并配置 PngViewOptions。PngViewOptions 定义将页面渲染为 PNG 图像的设置。关键调用 viewOptions.getPdfOptions().setRenderOriginalPageSize(true); 告诉引擎设置原始页面尺寸。

import com.groupdocs.viewer.Viewer;
import com.groupdocs.viewer.options.PngViewOptions;

import java.nio.file.Path;

public class RenderOriginalPageSize {
    public static void main(String[] args) {
        // Define output directory path for rendered pages
        Path outputDirectory = Path.of("YOUR_OUTPUT_DIRECTORY");
        
        // Format for the output page file paths
        String pageFilePathFormat = "page_{0}.png";
        Path pageFilePath = outputDirectory.resolve(pageFilePathFormat);
        
        // Initialize PngViewOptions with the path format
        PngViewOptions viewOptions = new PngViewOptions(pageFilePath.toString());
        
        // Set option to render original page size for PDF documents
        viewOptions.getPdfOptions().setRenderOriginalPageSize(true);
        
        // Create a Viewer instance for the source PDF document
        try (Viewer viewer = new Viewer("YOUR_DOCUMENT_DIRECTORY/SAMPLE_PDF")) {
            // Render the PDF using the specified options
            viewer.view(viewOptions);
        }
    }
}

关键行说明

  • 路径配置： 确定每个渲染的 PNG 保存的位置。
  • PngViewOptions： 选择 PNG 作为输出格式（经典的 pdf to png java 场景）。
  • 渲染原始页面尺寸： 确保不进行任何缩放，保留每个 PDF 页面精确的尺寸。

步骤 2：运行并验证

加载您的 PDF，调用渲染例程，然后检查生成的 PNG 文件。图像应与原始 PDF 页面尺寸像素对像素匹配。如果图像出现拉伸，请再次确认已使用 setRenderOriginalPageSize(true)，并且您使用的是最新的 GroupDocs.Viewer 版本。

故障排除与常见陷阱

  • 文件路径不正确： 确保 outputDirectory 和源 PDF 路径都是绝对路径或相对于项目的正确相对路径。
  • 缺少许可证： 没有有效许可证时，渲染可能会降级为限制页面数的试用模式。
  • 大 PDF 导致内存不足错误： 增加 JVM 堆内存（-Xmx2g 或更高）或启用页面懒加载。
  • 加密的 PDF： 在构造 Viewer 实例时提供密码，以避免 pdf rendering troubleshooting 错误。

实际使用案例

  1. 数字档案： 在不产生任何失真的情况下保存历史扫描件。
  2. 法律文档门户： 提供符合法院要求的 PDF，显示方式与提交时完全一致。
  3. 在线学习平台： 将教材转换为图像格式，同时保持布局完整。
  4. 发票自动化： 确保转换后项目明细和总额保持可读。

性能提示

  • 内存管理： 为大型文档分配足够的堆空间。
  • 懒加载： 在可能的情况下，仅渲染所需页面，而不是整个文件。
  • 缓存： 为频繁访问的 PDF 存储渲染后的 PNG，以避免重复处理。

常见问题

Q: 如何将 GroupDocs.Viewer 与 Spring Boot 集成？
A: 将 Viewer 注册为 Spring Bean，在需要的地方注入，并让 Spring 管理其生命周期以实现线程安全的复用。

Q: 我可以将 PDF 渲染为 PNG 之外的格式吗？
A: 可以——GroupDocs.Viewer 还支持 JPEG、SVG 和 PDF 转 HTML 的转换。

Q: 如果渲染过程因异常而失败，我该怎么办？
A: 检查堆栈跟踪以查找缺失的文件路径或授权问题，并确认 PDF 未损坏。

Q: 可渲染的 PDF 是否有大小限制？
A: 从技术上讲没有，但非常大的文件可能需要增加 JVM 内存，并且将其拆分为更小的部分会更有益。

Q: GroupDocs.Viewer 能处理受密码保护的 PDF 吗？
A: 当然——只需将密码传递给 Viewer 构造函数或通过 LoadOptions 对象即可。

资源

最后更新： 2026-06-25
测试环境： GroupDocs.Viewer 25.2 for Java
作者： GroupDocs

相关教程