PyQt5 QWebEngineView集成PDF.js如何编程切换PDF页面

问题梳理 #

• 技术栈：PyQt5 + QWebEngineView 加载Mozilla 官方PDF.js 实现文档预览
• 已完成能力：PDF 基础加载渲染
• 待实现需求：
  • 加载PDF时直接指定初始展示页码
  • PDF加载完成后，无需重载文档即可动态切换展示页码
• 已遇报错：直接调用runJavaScript()执行翻页逻辑时，分别触发Cannot set property of undefined、Object is NoneType 运行错误

现有加载逻辑代码如下：

def load_file(self, file, page=0) -> None:
        url = QtCore.QUrl().fromLocalFile(os.path.abspath("./pdfjs/web/viewer.html"))
        query = QtCore.QUrlQuery()
        query.addQueryItem("file", os.path.normpath(os.path.abspath(file)))
        url.setQuery(query)
        self.pdf_view.load(url)

注：self.pdf_view为QWebEngineView实例对象，目前已验证URL锚点方式可实现初始页码指定，但未找到无重载动态翻页的实现方式。

具体实现 #

1. 加载时指定初始页码 #

直接通过URL锚点传参即可，注意PDF.js页码从1开始计数，传入0会默认 fallback 到第1页。修改后的加载代码：

import os
from PyQt5 import QtCore

def load_file(self, file, page=1) -> None:
    viewer_local_path = os.path.abspath("./pdfjs/web/viewer.html")
    url = QtCore.QUrl.fromLocalFile(viewer_local_path)
    query = QtCore.QUrlQuery()
    query.addQueryItem("file", os.path.normpath(os.path.abspath(file)))
    url.setQuery(query)
    # 拼接页码锚点
    url.setFragment(f"page={page}")
    self.pdf_view.load(url)

2. 无重载动态切换页码 #

之前调用JS报错核心原因有两个：

• 执行JS时机过早：PDF.js的viewer实例、PDF文档对象未完成初始化，访问属性自然返回undefined
• 调用对象不存在：load()方法调用后立刻取self.pdf_view.page()时，QWebEnginePage还未创建完成，返回None触发NoneType错误

实现步骤：

• 第一步：绑定QWebEngineView的loadFinished信号，等页面DOM加载完成后注入PDF.js初始化监听
• 第二步：翻页前先判断PDF.js实例、文档对象是否就绪，未就绪则延迟重试，就绪后直接调用官方API赋值翻页

代码实现：

# 窗口初始化阶段执行一次即可，不要重复绑定
self.pdf_view.loadFinished.connect(self._pdf_viewer_ready_init)

def _pdf_viewer_ready_init(self, load_success):
    if not load_success:
        return
    # 注入JS监听PDF.js初始化完成状态
    init_listen_js = """
    if (window.PDFViewerApplication) {
        window._pyqt_pdf_viewer_ready = true;
    } else {
        document.addEventListener('webviewerloaded', () => {
            window._pyqt_pdf_viewer_ready = true;
        });
    }
    """
    self.pdf_view.page().runJavaScript(init_listen_js)

def jump_to_page(self, target_page):
    # 校验状态后执行翻页
    flip_js = """
    (function() {
        if (window._pyqt_pdf_viewer_ready && PDFViewerApplication.pdfDocument) {
            PDFViewerApplication.page = %d;
            return true;
        }
        return false;
    })();
    """ % target_page

    def check_ready(res):
        if not res:
            # 未就绪则100ms后重试，避免阻塞主线程
            QtCore.QTimer.singleShot(100, lambda: self.jump_to_page(target_page))
    
    self.pdf_view.page().runJavaScript(flip_js, check_ready)

注意：不要通过修改页码输入框DOM值的方式实现翻页，该方式仅修改UI展示，不会触发PDF实际渲染跳转，必须调用PDFViewerApplication.page属性赋值，这是PDF.js官方支持的翻页接口，不会出现渲染错位、页码不同步问题。

常见报错排查 #

• 触发Cannot set property of undefined：检查PDF.js版本，确认全局PDFViewerApplication对象存在；确认执行JS时PDF文档已经加载完成，不要在viewer刚打开时就调用翻页
• 触发Object is NoneType：确认调用runJavaScript时已经收到loadFinished信号，QWebEnginePage对象已完成创建，不要在调用load()后立刻执行JS逻辑

内容的提问来源于stack exchange，提问作者Nikolas