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

首页

编程语言

热心网友

转载

2026-05-05

在日常办公与文档处理中，将多个PDF文件合并为一个的需求非常普遍。面对网络上众多的在线合并工具，用户常常面临广告干扰、文件大小或页数限制，以及最为关键的文件隐私安全顾虑。今天，我们将彻底解决这些痛点——使用Python和PyQt5，从零开始开发一款完全本地运行、无广告、无任何功能限制的PDF批量合并桌面工具。

免费影视、动漫、音乐、游戏、小说资源长期稳定更新！ 👉 点此立即查看 👈

一、为何选择自主开发PDF合并工具？

在动手编码之前，我们不妨先分析一下市面上常见的PDF合并解决方案及其局限性：

方案类型	主要缺点
在线网站（如 SmallPDF、iLovePDF）	存在文件上传限制，有数据泄露风险
专业软件（如 Adobe Acrobat）	价格昂贵，对于简单合并需求显得笨重
命令行脚本	操作门槛高，对普通用户不友好

通过对比，我们的开发目标变得非常明确：打造一个具备图形化界面、支持拖拽操作、且完全离线运行的轻量级PDF合并软件。

二、PDF合并工具的技术栈选择

为了实现上述目标，合理的技术选型是成功的基础。下表详细说明了我们选择各个库的原因：

核心需求	技术选型	选型理由
图形用户界面 (GUI)	PyQt5	成熟稳定，跨平台支持良好，UI控件丰富
PDF文件操作	PyPDF2	轻量高效，合并功能完善，纯Python实现
后台任务处理	QThread	与PyQt5无缝集成，防止界面卡顿

三、环境配置与依赖安装

工欲善其事，必先利其器。首先需要安装必要的Python库。打开终端或命令提示符，执行以下pip命令：

pip install PyQt5 PyPDF2

对于团队协作或项目部署，更推荐使用requirements.txt文件管理依赖：

pip install -r requirements.txt

四、PDF合并工具的整体架构设计

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

pdf_merger.py
├── MergeWorker — 后台合并线程（核心处理器）
├── DragDropListWidget — 支持拖拽的文件列表控件
└── PDFMergerApp — 主应用程序窗口（界面与逻辑控制器）

数据处理流程

工具的核心工作流程可以概括为以下几个步骤：

用户操作 → 添加PDF文件至列表 → 点击合并按钮

↓

启动后台MergeWorker线程

↓

逐个读取并追加PDF → 写入最终输出文件

↓

通过信号通知主线程 → 实时更新日志与进度

五、PDF合并工具核心代码解析

5.1 后台合并线程 — MergeWorker

为何必须使用多线程？因为PDF合并属于I/O密集型操作，若在主线程中执行，会导致图形界面冻结，用户体验极差。PyQt5的QThread配合信号（Signal）与槽（Slot）机制，是解决此问题的标准方案。

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_files = len(self.file_list)
        try:
            for index, file_path in enumerate(self.file_list, 1):
                self.log_signal.emit(f"[{index}/{total_files}] 正在处理: {os.path.basename(file_path)}")
                merger.append(file_path)
                self.progress_signal.emit(int(index / total_files * 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():
            file_paths = [url.toLocalFile() for url in event.mimeData().urls() if url.toLocalFile()]
            self.files_dropped.emit(file_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文件收集逻辑

为提升易用性，工具支持同时添加文件和文件夹，并自动递归扫描文件夹内的所有PDF：

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

文件去重添加

避免同一文件被重复添加，保持列表清晰：

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

列表顺序调整

通过“上移/下移”按钮调整合并顺序，核心是交换列表控件项及其底层数据：

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

六、界面样式美化

功能完备后，界面的美观度同样重要。使用Qt的样式表（QSS，语法类似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采用白色背景和圆角边框，呈现现代卡片式设计。
合并按钮使用主题蓝色，并设置了悬停和按下状态，增强交互感。
进度条使用从蓝到绿的渐变色，视觉上更具活力。
字体设置为Microsoft YaHei，确保中文显示清晰美观。

七、PDF合并工具使用教程

第一步：启动程序

python pdf_merger.py

第二步：添加PDF文件

提供三种添加方式，满足不同操作习惯：

直接拖拽：从Windows资源管理器或macOS Finder中，直接将PDF文件或文件夹拖入程序窗口。
添加文件：点击“添加文件”按钮，在对话框中选择多个PDF文件。
添加文件夹：点击“添加文件夹”按钮，选择目录，程序会自动扫描其中的所有PDF文件。

第三步：调整合并顺序

在列表中选择文件，使用“上移”、“下移”按钮调整位置。
或者，直接在列表内部通过拖拽来排序。

第四步：执行合并操作

点击 “开始合并” 按钮。
在弹出的对话框中，选择输出文件的保存位置和名称。
等待处理完成，日志区域会实时显示每个文件的处理进度。

八、常见问题与解决方案

1. 安装PyQt5失败或缓慢

由于网络原因，安装可能较慢。可以尝试使用国内镜像源加速安装过程：

# 使用清华大学镜像源
pip install PyQt5 -i https://pypi.tuna.tsinghua.edu.cn/simple

2. 合并时出现“PdfReadError”错误

此错误通常由PDF文件损坏或被加密导致。解决方法如下：

根据日志提示，排除有问题的PDF文件。
尝试使用其他工具（如Adobe Acrobat）先修复或解密该PDF。

3. 如何打包成独立的EXE可执行文件

若想分享给没有Python环境的同事使用，可以使用PyInstaller进行一键打包：

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

打包完成后，独立的EXE文件将生成在项目目录下的dist/文件夹中。

九、功能扩展与进阶思路

基础版本已能满足核心需求。如果你希望工具更加强大，可以参考以下扩展方向：

扩展方向	实现说明
支持加密PDF合并	在`append`前使用`PdfReader`并提供密码输入
选择页面范围合并	允许用户为每个PDF指定合并的起止页码
PDF页面预览	集成`pdf2image`库，生成文件缩略图
保存与加载任务配置	将文件列表和输出路径保存为项目文件，方便下次使用
多语言国际化	利用Qt的i18n机制，支持中英文界面切换
软件打包与分发	使用PyInstaller或Nuitka生成更小的单文件可执行程序