Python结合PyQt5开发一个PDF批量合并工具

日常工作中，需要把多个PDF文件合并成一个的场景并不少见。面对网上的在线工具，我们常常会纠结：要么被广告干扰，要么有页数限制，更让人担心的是文件隐私问题。今天，我们就来动手解决这个痛点——用Python和PyQt5，从零打造一款完全本地运行、无广告、无任何限制的PDF批量合并工具。

一、为什么要自己做？

在动手之前，不妨先看看市面上的主流方案，它们大致可以分为三类：

这么一看，我们的目标就很明确了：打造一个拥有图形界面、支持拖拽操作、且完全在本地运行的轻量级工具。

二、技术选型

要实现这个目标，技术栈的选择至关重要。下面这张表清晰地展示了我们的选择与理由：

三、安装依赖

万事开头先装包。打开你的命令行，执行以下命令即可：

pip install PyQt5 PyPDF2

当然，更规范的做法是使用 requirements.txt 文件：

pip install -r requirements.txt

四、整体架构设计

整个程序的核心逻辑可以清晰地划分为3个模块：

pdf_merger.py

├── MergeWorker — 后台合并线程

├── DragDropListWidget — 支持拖拽的文件列表控件

└── PDFMergerApp — 主窗口（界面 + 业务逻辑）

数据流

整个工具的工作流程，可以概括为以下几步：

用户操作 → 添加文件到列表 → 点击合并

↓

启动 MergeWorker 线程

↓

逐个 append PDF → 写入输出文件

↓

信号通知主线程 → 更新日志和进度条

五、核心代码详解

5.1 后台合并线程 — MergeWorker

为什么一定要用线程？道理很简单：PDF合并是典型的IO密集型操作，如果放在主线程里执行，整个界面就会“卡死”，用户体验极差。PyQt5的QThread配合信号（Signal）机制，正是解决这个问题的利器。

class MergeWorker(QThread):
    log_signal = pyqtSignal(str)        # 日志消息
    progress_signal = pyqtSignal(int)   # 进度百分比
    finished_signal = pyqtSignal(bool, str)  # 完成状态

    def __init__(self, file_list, output_path):
        super().__init__()
        self.file_list = file_list
        self.output_path = output_path

    def run(self):
        merger = PdfMerger()
        total = len(self.file_list)
        try:
            for idx, fpath in enumerate(self.file_list, 1):
                self.log_signal.emit(f"[{idx}/{total}] 正在添加: {os.path.basename(fpath)}")
                merger.append(fpath)
                self.progress_signal.emit(int(idx / total * 100))

            merger.write(self.output_path)
            merger.close()
            self.finished_signal.emit(True, self.output_path)
        except Exception as e:
            self.finished_signal.emit(False, str(e))

关键点：

• 定义了三个信号：日志、进度、完成状态
• run() 方法在子线程执行，通过信号回传到主线程更新 UI
• 使用 try/except 捕获异常，合并失败不会崩溃

5.2 拖拽列表控件 — DragDropListWidget

PyQt5自带的QListWidget默认不支持从系统文件管理器拖入文件，这显然不够方便。我们需要通过重写几个关键事件来实现这个功能。

class DragDropListWidget(QListWidget):
    files_dropped = pyqtSignal(list)  # 拖入的路径列表

    def __init__(self, parent=None):
        super().__init__(parent)
        self.setAcceptDrops(True)
        self.setDragDropMode(QAbstractItemView.InternalMove)

    def dragEnterEvent(self, event):
        if event.mimeData().hasUrls():
            event.acceptProposedAction()
        else:
            super().dragEnterEvent(event)

    def dropEvent(self, event):
        if event.mimeData().hasUrls():
            paths = [url.toLocalFile() for url in event.mimeData().urls() if url.toLocalFile()]
            self.files_dropped.emit(paths)
            event.acceptProposedAction()
        else:
            super().dropEvent(event)

关键点：

• setAcceptDrops(True) 允许接受外部拖拽
• setDragDropMode(InternalMove) 同时支持列表内部拖拽排序
• dragEnterEvent 判断拖入的是否为文件 URL
• dropEvent 提取本地路径，发射自定义信号

5.3 主窗口 — PDFMergerApp

主窗口负责整个界面的布局和核心业务逻辑的串联。其核心布局结构如下：

QMainWindow

└── QVBoxLayout (根布局)

├── QLabel (标题)

├── QLabel (副标题)

├── QSplitter (垂直分割)

│ ├── QGroupBox — 文件列表区

│ │ ├── DragDropListWidget

│ │ └── QHBoxLayout — 按钮行

│ └── QGroupBox — 日志区

│ └── QTextEdit

├── QProgressBar (进度条)

└── QPushButton (合并按钮)

文件收集逻辑

为了提升易用性，我们支持同时传入文件和文件夹路径，并自动递归收集所有PDF文件：

def _collect_pdfs(self, paths):
    pdfs = []
    for p in paths:
        if os.path.isfile(p) and p.lower().endswith(".pdf"):
            pdfs.append(p)
        elif os.path.isdir(p):
            for root, _, files in os.walk(p):
                for f in sorted(files):
                    if f.lower().endswith(".pdf"):
                        pdfs.append(os.path.join(root, f))
    return pdfs

去重添加

避免同一个文件被重复添加，保证列表的整洁：

def _add_to_list(self, new_files):
    added = 0
    for f in new_files:
        if f not in self.pdf_files:
            self.pdf_files.append(f)
            self.file_list_widget.addItem(f)
            added += 1

列表排序

通过“上移/下移”按钮调整顺序，其核心是交换列表项及其对应的数据：

def _move_up(self):
    row = self.file_list_widget.currentRow()
    if row > 0:
        item = self.file_list_widget.takeItem(row)
        self.file_list_widget.insertItem(row - 1, item)
        self.file_list_widget.setCurrentRow(row - 1)
        self.pdf_files[row], self.pdf_files[row - 1] = (
            self.pdf_files[row - 1], self.pdf_files[row]
        )

六、样式美化

功能完备了，界面美观也不能落下。使用Qt的StyleSheet（语法类似CSS），可以轻松统一控件风格：

QMainWindow {
    background-color: #f5f7fa;
}
QGroupBox {
    border: 1px solid #dcdfe6;
    border-radius: 8px;
    background-color: #ffffff;
}
#mergeBtn {
    background-color: #3498db;
    color: white;
    font-size: 15px;
    font-weight: bold;
    border-radius: 8px;
}
QProgressBar::chunk {
    background: qlineargradient(x1:0, y1:0, x2:1, y2:0,
        stop:0 #3498db, stop:1 #2ecc71);
    border-radius: 5px;
}

美化要点：

• QGroupBox 使用白色背景 + 圆角，呈现卡片效果
• 合并按钮使用蓝色主题色，hover 和 pressed 有层次感
• 进度条渐变色（蓝 → 绿），视觉上更有活力
• 字体使用 Microsoft YaHei，中文显示清晰美观

七、使用流程

第一步：启动程序

python pdf_merger.py

第二步：添加文件

三种方式任选，总有一款适合你：

• 拖拽：直接从文件资源管理器拖入 PDF 文件或文件夹
• 添加文件：点击按钮，在文件选择对话框中多选 PDF
• 添加目录：点击按钮，选择一个文件夹，自动扫描其中所有 PDF

第三步：调整顺序

• 选中某个文件，用 ⬆/⬇ 按钮调整位置
• 或者直接在列表中拖拽排序

第四步：点击合并

• 点击 “? 开始合并”
• 选择保存位置和文件名
• 等待完成，日志区实时显示处理进度

八、可能遇到的问题与解决

1. 安装 PyQt5 失败

网络问题可能导致安装缓慢或失败，可以尝试使用国内镜像源加速：

# 尝试使用国内镜像
pip install PyQt5 -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 合并时报错 “PdfReadError”

这通常是因为PDF文件本身已损坏或被加密。解决方法也很直接：

• 排除问题文件（可在日志中看到是哪个文件报错）
• 使用其他工具先修复或解密该 PDF

3. 打包为 EXE

想分发给没有Python环境的同事使用？用PyInstaller一键打包即可：

pip install pyinstaller
pyinstaller --onefile --windowed --name "PDF合并工具" pdf_merger.py

打包后的独立EXE文件会生成在 dist/ 目录下。

九、进阶扩展思路

如果你觉得这个基础版本已经满足需求，那当然很好。但如果你想把它打磨得更强大，下面这些扩展方向或许能给你带来灵感：

十、完整项目结构

整个项目的文件结构非常清晰，一目了然：

19-批量PDF合并工具/

├── pdf_merger.py # 主程序源码

├── requirements.txt # 依赖清单

├── README.md # 项目说明

└── blog.md # 本篇开发博客

总结

回顾一下，我们通过这篇文章，从零实现了一个功能完整的PDF批量合并工具：

• PyPDF2 负责 PDF 的读取与合并
• PyQt5 构建了美观的图形界面
• QThread 保证了合并过程中界面不冻结
• 拖拽功能 让操作更加便捷
• QSS 样式 让界面更加美观

整个项目只有一个Python文件，代码约300行，结构简洁，逻辑清晰。希望这个小工具能切实提升你的工作效率，也希望这篇教程能为你打开一扇窗，看到用PyQt5进行桌面应用开发的便捷与乐趣。