# raster-pdf

**Repository Path**: ppnt/raster-pdf

## Basic Information

- **Project Name**: raster-pdf
- **Description**: 本项目用于将 PDF 文件按页转换为图片文件，提供简单的图形界面，支持选择 PDF 文件、输出目录、图片格式、DPI 和页码范围。
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-28
- **Last Updated**: 2026-03-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# raster-pdf

一个基于 JavaFX 和 PDFBox 的 PDF 转图片桌面工具。

当前版本仅支持 **Java 1.8**。

## 1. Introduction

本项目用于将 PDF 文件按页转换为图片文件，提供简单的图形界面，支持选择 PDF 文件、输出目录、图片格式、DPI 和页码范围。

功能特性：

- 支持 PDF 按页导出为图片
- 支持图片格式：
  - png
  - jpg
- 支持设置 DPI
- 支持自定义页码范围
- 支持转换进度显示
- 支持日志输出
- 支持本地打包为原生应用

## 2. Environment

本项目 **仅支持 Java 1.8**。

请使用以下环境：

- JDK: `1.8`
- Maven: `3.6+` 或更高版本
- JavaFX: 使用 JDK 1.8 自带 JavaFX
- PDFBox: `2.0.24`

不支持：

- Java 11
- Java 17
- Java 21
- OpenJFX 独立模块化运行方式

## 3. Project Structure

```text
04_java-fx-pdf-to-image
├─ pom.xml
└─ src
   └─ main
      └─ java
         └─ com
            └─ litongjava
               └─ rasterpdf
                  ├─ ConversionOptions.java
                  ├─ PdfToImageService.java
                  └─ MainApp.java
````

## 4. Dependencies

### 4.1 Maven 配置

在 `pom.xml` 中添加以下配置：

```xml
<properties>
  <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
  <maven.compiler.release>1.8</maven.compiler.release>
  <pdfbox.version>2.0.24</pdfbox.version>
</properties>

<dependencies>
  <dependency>
    <groupId>org.apache.pdfbox</groupId>
    <artifactId>pdfbox</artifactId>
    <version>${pdfbox.version}</version>
  </dependency>
</dependencies>

<build>
  <plugins>
    <plugin>
      <groupId>com.zenjava</groupId>
      <artifactId>javafx-maven-plugin</artifactId>
      <version>8.8.3</version>
      <configuration>
        <mainClass>com.litongjava.rasterpdf.MainApp</mainClass>
        <vendor>litongjava</vendor>
        <bundleArguments>
          <installdirChooser>true</installdirChooser>
        </bundleArguments>
      </configuration>
    </plugin>
  </plugins>
</build>
```

## 5. Features

### 5.1 PDF 文件选择

可通过界面选择本地 PDF 文件。

### 5.2 输出目录选择

可自定义图片输出目录。

### 5.3 图片格式

支持以下输出格式：

* png
* jpg

说明：

* 输入 `jpeg` 时会自动规范化为 `jpg`

### 5.4 DPI 设置

支持手动输入 DPI，例如：

* 72
* 150
* 300

### 5.5 页码范围

支持以下格式：

* `all`
* `1`
* `1,3,5`
* `1-3`
* `1-3,5,8`

示例：

```text
all
1-3
2,4,6
1-3,5,8
```


## 7. Run

### 7.1 Windows 下设置 Java 1.8

```bat
set JAVA_HOME=D:\java\jdk-1.8_411
set PATH=%JAVA_HOME%\bin;%PATH%
```

### 7.2 启动项目

```bat
mvn clean javafx:run
```

## 8. Package

在 Windows 下执行：

```bat
set JAVA_HOME=D:\java\jdk-1.8_411
set PATH=%JAVA_HOME%\bin;%PATH%
mvn jfx:native
```

打包完成后，可在构建输出目录中找到生成的原生安装包或可执行文件。

## 9. Usage

启动应用后：

1. 点击 `选择PDF`
2. 选择需要转换的 PDF 文件
3. 点击 `选择目录`
4. 选择图片输出目录
5. 选择图片格式
6. 输入 DPI
7. 输入页码范围
8. 点击 `开始转换`

## 10. Page Range Rules

页码范围说明：

* 页码从 `1` 开始
* 支持单页
* 支持连续范围
* 支持多个片段组合

示例：

```text
all        -> 全部页面
1          -> 第 1 页
1-5        -> 第 1 到第 5 页
1,3,5      -> 第 1、3、5 页
1-3,6,8-10 -> 组合页码
```

## 11. Notes

### 11.1 仅支持 Java 1.8

这是本项目最重要的限制条件。

请不要使用以下版本运行或打包：

* Java 11
* Java 17
* Java 21

原因：

* 当前项目依赖 JDK 1.8 自带 JavaFX
* `javafx-maven-plugin 8.8.3` 主要适配 Java 8 生态
* 本项目未适配 OpenJFX 模块系统

### 11.2 关于 `@SuppressWarnings("restriction")`

代码中使用了：

```java
@SuppressWarnings("restriction")
```

这是为了避免某些 JavaFX 相关限制警告。在 Java 1.8 项目中可以接受。

### 11.3 图片输出命名规则

输出文件命名格式如下：

```text
原PDF文件名_page_001.png
原PDF文件名_page_002.png
原PDF文件名_page_003.png
```

## 12. Example

假设输入文件为：

```text
demo.pdf
```

输出格式为：

```text
png
```

则生成文件类似：

```text
demo_page_001.png
demo_page_002.png
demo_page_003.png
```

## 13. FAQ

### 13.1 启动失败，提示找不到 JavaFX

请确认当前使用的是 **JDK 1.8**，而不是 JRE，也不是 Java 11+。

### 13.2 打包失败

请确认：

* 已正确设置 `JAVA_HOME`
* `JAVA_HOME` 指向 JDK 1.8
* 系统中已安装打包所需环境
* 使用的是 `mvn jfx:native`

### 13.3 为什么不支持 Java 11+

因为当前工程是按 Java 1.8 的 JavaFX 运行方式编写和配置的，没有迁移到 OpenJFX 模块化方案。