簡(jiǎn)介面向需要在Qt應(yīng)用中集成PDF預(yù)覽能力的開(kāi)發(fā)者這套示例直接采用QPrintPreviewWidget配合QPrinter、QPainter完成PDF渲染全程未引入任何第三方庫(kù)同時(shí)支持放大、縮小視圖操作簡(jiǎn)單直觀。壓縮包共24個(gè)文件、約3.93MB主要包含2個(gè)cpp源文件、1個(gè)h頭文件、1個(gè)pro工程文件、1個(gè)ui界面定義與1個(gè)qrc資源腳本并附有LICENSE、README說(shuō)明以及15張jpg和1張png效果截圖方便在Qt Creator中打開(kāi)工程直接構(gòu)建并通過(guò)截圖對(duì)照理解界面交互。已有6798人學(xué)習(xí)該資源適合Qt進(jìn)階開(kāi)發(fā)者學(xué)習(xí)打印框架與文檔渲染場(chǎng)景。通過(guò)源碼可深入理解QPrintPreviewWidget與QPainter協(xié)作繪制PDF頁(yè)面的核心流程掌握利用QPrinter設(shè)置輸出頁(yè)面、結(jié)合預(yù)覽控件實(shí)現(xiàn)縮放交互的典型用法也可將其中頁(yè)面繪制、縮放手勢(shì)或工具欄邏輯移植到現(xiàn)有項(xiàng)目快速實(shí)現(xiàn)輕量級(jí)PDF預(yù)覽避免接入重型第三方庫(kù)。1. 想給項(xiàng)目加 PDF 預(yù)覽QPrintPreviewWidget 是繞不開(kāi)的那條路接到一個(gè)內(nèi)部工具的需求給一套報(bào)表程序加上 PDF 預(yù)覽和打印能力。界面不用花哨能翻頁(yè)、能縮放、能直接送打印機(jī)就行。第一反應(yīng)是找個(gè)現(xiàn)成控件翻了一圈發(fā)現(xiàn) Qt 里其實(shí)有一個(gè)專(zhuān)門(mén)干這個(gè)的現(xiàn)成控件就是 QPrintPreviewWidget——標(biāo)題里的 Qt-Pdf預(yù)覽示例-采用QPrintPreviewWidget 說(shuō)的也是它。但這里有個(gè)反直覺(jué)的點(diǎn)直接 new 一個(gè) QPrintPreviewWidget 是顯示不出 PDF 的它預(yù)覽的是打印機(jī)要畫(huà)的內(nèi)容你得把 PDF 頁(yè)面當(dāng)成“打印內(nèi)容”畫(huà)進(jìn)去它才真正工作。這篇文章就圍繞這條主線展開(kāi)原理怎么銜接、最小代碼怎么寫(xiě)、參數(shù)怎么調(diào)、以及那些不跑一遍根本發(fā)現(xiàn)不了的坑。適合正在做桌面工具、想在程序里塞進(jìn)輕量 PDF 預(yù)覽的開(kāi)發(fā)者也適合打印排版邏輯需要統(tǒng)一預(yù)覽和輸出效果的人。2. 為什么是 QPrintPreviewWidget它預(yù)覽的是繪圖結(jié)果不只是 PDF2.1 預(yù)覽控件和打印機(jī)共用同一個(gè)繪制坐標(biāo)系先想清楚一個(gè)本質(zhì)問(wèn)題QPrintPreviewWidget 到底是拿來(lái)預(yù)覽什么的?？搭?lèi)名也看得出它是“打印預(yù)覽控件”不是“PDF 預(yù)覽控件”。它的職責(zé)是把一次 QPainter 繪制過(guò)程模擬到屏幕上讓你在點(diǎn)打印之前就看到打印機(jī)會(huì)畫(huà)出來(lái)什么。這套繪制的目標(biāo)對(duì)象是 QPrinter也就是一臺(tái)虛擬打印機(jī)頁(yè)面大小、分辨率、方向都由 QPrinter 的參數(shù)決定。所以 PDF 預(yù)覽這件事的完整鏈路是先有一個(gè) QPdfDocument 負(fù)責(zé)解析 PDF 文件再把 PDF 的每一頁(yè)渲染成一張 QImage最后在 QPrintPreviewWidget 的繪制回調(diào)里用 QPainter 把這張圖片畫(huà)到“虛擬打印機(jī)”上。屏幕顯示和真正打印走的是同一套繪制代碼這就是為什么用 QPrintPreviewWidget 而不是直接用 QLabel 貼圖——你調(diào)的是打印狀態(tài)機(jī)不是單純顯示。這個(gè)設(shè)計(jì)帶來(lái)的第一個(gè)好處是你不需要維護(hù)兩套布局代碼。預(yù)覽時(shí) QPrintPreviewWidget 會(huì)按 QPrinter 的頁(yè)面尺寸模擬分頁(yè)效果打印時(shí) QPrinter 也按同樣的尺寸出紙兩個(gè)環(huán)節(jié)不會(huì)出現(xiàn)“預(yù)覽是對(duì)的打印出來(lái)全亂”的問(wèn)題。第二個(gè)好處是預(yù)覽控件自帶了頁(yè)數(shù)導(dǎo)航、縮放、翻頁(yè)交互省去自己造的輪子。2.2 為什么不用 QPdfView也不用自繪控件很多人第一反應(yīng)是用 QPdfView它是 Qt 里直接對(duì)標(biāo) PDF 瀏覽的控件能滾動(dòng)、能選文字體驗(yàn)也接近閱讀器。但 QPdfView 的設(shè)計(jì)目標(biāo)是“讀文檔”不是“打文檔”。你真要打印時(shí)還是得自己把 PDF 頁(yè)面按 QPrinter 的要求重新排版一遍等于預(yù)覽一套邏輯、打印另一套邏輯。而且 QPdfView 的顯示密度和打印機(jī)分辨率不是一回事預(yù)覽適配得好不代表打出來(lái)清晰。自繪控件這條路也有自己處理滾輪縮放、頁(yè)碼顯示、DPI 換算做出來(lái)確實(shí)很靈活但工作量和邊界情況都多尤其是高分屏和多頁(yè)布局要自己調(diào)的地方非常碎。QPrintPreviewWidget 的定位正好在中間它不負(fù)責(zé)解析 PDF也不負(fù)責(zé)像素級(jí)渲染但它把“打印機(jī)頁(yè)面模擬”這層做得足夠完整PDF 解析交給 QPdfDocument像素渲染交給 Qt 自己的光柵引擎各管一段接縫清楚。Poppler 這條路線也是常見(jiàn)選擇特別是要解析復(fù)雜 PDF 標(biāo)注、表單這類(lèi)高級(jí)特性時(shí)Poppler 的能力比 Qt PDF 模塊更全。但對(duì)大多數(shù)內(nèi)部工具來(lái)說(shuō)Poppler 引入的構(gòu)建依賴(lài)和許可證核驗(yàn)成本都不低QPrintPreviewWidget 配合 Qt PDF 模塊能在幾小時(shí)內(nèi)跑通全流程。選型判斷就一條只要你的 PDF 來(lái)源可控、不需要復(fù)雜交互式表單這條路最省。2.3 paintRequested 回調(diào)里到底發(fā)生了什么QPrintPreviewWidget 的工作方式是向外發(fā)一個(gè) paintRequested 信號(hào)參數(shù)是一個(gè) QPrinter 指針。這個(gè)信號(hào)什么時(shí)候觸發(fā)控件初始化時(shí)、你點(diǎn)翻頁(yè)時(shí)、點(diǎn)縮放時(shí)、調(diào)用 updatePreview() 時(shí)都會(huì)觸發(fā)。你要做的就是連上這個(gè)信號(hào)然后在這個(gè)回調(diào)里把當(dāng)前 PDF 頁(yè)畫(huà)到傳進(jìn)來(lái)的 QPrinter 上。繪制時(shí)的邏輯要點(diǎn)如下先設(shè)置 QPrinter 的頁(yè)面大小和分辨率再?gòu)?QPdfDocument 里取出當(dāng)前頁(yè)的渲染結(jié)果最后用 QPainter 把圖片按頁(yè)面矩形畫(huà)進(jìn)去。QPainter 可以綁定 QPrinter也可以綁定 QPrintPreviewWidget 內(nèi)部的預(yù)覽引擎兩者的繪制代碼完全一致這是這套方案的核心優(yōu)勢(shì)。這里有一個(gè)容易想歪的地方QPrinter 的單位是像素嗎不是。QPrinter 的坐標(biāo)系單位受分辨率影響分辨率就是每英寸點(diǎn)數(shù)你在 300 DPI 下畫(huà) 100 像素物理上就是一英寸的三分之一。QPdfDocument 渲染出的 QImage 有自己的像素尺寸你要做的是把它按比例縮放到 QPrinter 的頁(yè)面矩形里而不是直接 drawImage 原圖。2.4 初始化和信號(hào)連接的骨架代碼先看一個(gè)不含業(yè)務(wù)邏輯的最小連接后面再補(bǔ)充完整示例#include QApplication #include QPrintPreviewWidget #include QPrinter #include QPdfDocument int main(int argc, char *argv[]) { QApplication app(argc, argv); QPrinter printer(QPrinter::HighResolution); printer.setPageSize(QPageSize(QPageSize::A4)); printer.setResolution(300); QPrintPreviewWidget preview(printer); QPdfDocument pdfDoc; // 這里先只連信號(hào)加載和繪制邏輯在完整示例里展開(kāi) QObject::connect(preview, QPrintPreviewWidget::paintRequested, [](QPrinter *p) { // 后續(xù)章節(jié)會(huì)填真正的繪制代碼 }); preview.resize(900, 700); preview.show(); return app.exec(); }這段代碼先把 QPrinter 以高分辨率模式建出來(lái)設(shè)置 A4 紙和 300 DPI。QPrintPreviewWidget 構(gòu)造時(shí)接收 QPrinter 的地址之后回調(diào)里拿到的也是同一個(gè)打印機(jī)對(duì)象參數(shù)改動(dòng)會(huì)直接反映到預(yù)覽布局上。要注意 setResolution 必須在構(gòu)造之后、預(yù)覽刷新之前設(shè)置否則預(yù)覽顯示和實(shí)際打印的分辨率可能不一致后面的坑里會(huì)細(xì)說(shuō)。3. 最小可用示例讓 PDF 在預(yù)覽控件里正常分頁(yè)顯示3.1 需要的模塊與工程配置把方案落進(jìn) CMake 工程時(shí)除了 Qt Widgets還要引入 Qt PDF 模塊。Qt PDF 模塊提供的 QPdfDocument 負(fù)責(zé)解析和渲染QPrintPreviewWidget 則在 Qt PrintSupport 模塊里。常見(jiàn)的工程配置寫(xiě)法如下find_package(Qt6 REQUIRED COMPONENTS Widgets PrintSupport Pdf) add_executable(pdfpreview main.cpp) target_link_libraries(pdfpreview PRIVATE Qt6::Widgets Qt6::PrintSupport Qt6::Pdf )如果用的是 Qt 5Pdf 模塊也存在于對(duì)應(yīng)的組件列表中組件名保持一致。一個(gè)常見(jiàn)的工程配置錯(cuò)誤是只鏈接了 PrintSupport 忘了 Pdf結(jié)果 QPdfDocument 的 include 和符號(hào)都找不到編譯報(bào)錯(cuò)指向不明先查這里往往能定位。3.2 加載 PDF 文件和組裝預(yù)覽窗口設(shè)計(jì)一個(gè)簡(jiǎn)單的窗口結(jié)構(gòu)一個(gè) QPrintPreviewWidget 作為主體一個(gè) QLineEdit 輸文件名一個(gè)按鈕觸發(fā)加載和刷新。PDF 文檔對(duì)象用成員變量持有避免在回調(diào)里重復(fù)打開(kāi)文件。具體代碼如下#include QMainWindow #include QPrintPreviewWidget #include QPushButton #include QLineEdit #include QVBoxLayout #include QPrinter #include QPdfDocument #include QPainter class PdfPreviewWindow : public QMainWindow { public: PdfPreviewWindow() { setWindowTitle(PDF Preview via QPrintPreviewWidget); resize(960, 700); m_printer new QPrinter(QPrinter::HighResolution); m_printer-setPageSize(QPageSize(QPageSize::A4)); m_printer-setResolution(300); m_preview new QPrintPreviewWidget(m_printer, this); m_preview-setZoomFactor(1.0); m_preview-setPreviewMode(QPrintPreviewWidget::SinglePage); auto *input new QLineEdit(this); auto *openBtn new QPushButton(打開(kāi)PDF, this); auto *topLayout new QHBoxLayout(); topLayout-addWidget(input); topLayout-addWidget(openBtn); auto *mainLayout new QVBoxLayout(); mainLayout-addLayout(topLayout); mainLayout-addWidget(m_preview); auto *central new QWidget(this); central-setLayout(mainLayout); setCentralWidget(central); connect(openBtn, QPushButton::clicked, this, [this, input]() { if (m_doc.load(input-text().trimmed()) QPdfError::None) { m_preview-updatePreview(); } }); connect(m_preview, QPrintPreviewWidget::paintRequested, this, PdfPreviewWindow::renderPdfPage); } private: void renderPdfPage(QPrinter *printer) { // 完整繪制邏輯在 3.3 節(jié)展開(kāi) } QPrinter *m_printer nullptr; QPrintPreviewWidget *m_preview nullptr; QPdfDocument m_doc; };窗口里用了簡(jiǎn)單的頂層布局放文件路徑輸入和打開(kāi)按鈕下方放預(yù)覽控件。加載 PDF 用的是 QPdfDocument::load傳入文件路徑如果返回 QPdfError::None 就代表解析成功隨后調(diào)用 updatePreview() 觸發(fā)一次重繪。第 1 次接觸 QPrintPreviewWidget 的人常忘記 updatePreview 這一步結(jié)果控件空在那里沒(méi)有任何反饋這是個(gè)容易忽略的細(xì)節(jié)。參數(shù)說(shuō)明里值得留意的是 setPreviewMode。SinglePage 模式下預(yù)覽控件一次只顯示當(dāng)前一頁(yè)配合下方的翻頁(yè)交互最直觀FacingPages 適合雙面對(duì)開(kāi)排版AllPages 會(huì)把全部頁(yè)面攤開(kāi)顯示類(lèi)似打印排版視圖。對(duì)大多數(shù)文檔預(yù)覽場(chǎng)景SinglePage 是默認(rèn)首選。3.3 在 paintRequested 里繪制 PDF 頁(yè)面的核心邏輯這是整個(gè)示例的核心?；卣{(diào)里要完成三件事計(jì)算當(dāng)前頁(yè)面號(hào)的渲染圖、按頁(yè)面矩形繪制到打印機(jī)坐標(biāo)系、處理翻頁(yè)時(shí)的頁(yè)號(hào)推進(jìn)。完整代碼void PdfPreviewWindow::renderPdfPage(QPrinter *printer) { QPainter painter(printer); painter.setRenderHint(QPainter::Antialiasing, true); // 頁(yè)號(hào)保護(hù)預(yù)覽控件內(nèi)部維護(hù)當(dāng)前頁(yè)這里與它的頁(yè)碼同步 int pageIndex qBound(0, m_preview-currentPage(), m_doc.pageCount() - 1); if (pageIndex 0) { painter.drawText(100, 100, 無(wú)法渲染沒(méi)有有效頁(yè)); return; } // 按物理頁(yè)面尺寸計(jì)算目標(biāo)矩形QPrinter 的邏輯單位是 1/分辨率 英寸 QRectF targetRect(0, 0, printer-width(), printer-height()); // 渲染當(dāng)前頁(yè)尺寸按打印機(jī)當(dāng)前分辨率計(jì)算 QSize pageSize printer-pageLayout().paintRectPixels( printer-resolution(), printer-pageLayout().fullRect()); QSize reqSize pageSize; // 向量渲染時(shí)直接采用 1:1 像素 QPdfDocumentRenderOptions opts; opts.setRenderFlags(QPdfDocumentRenderOptions::RenderOptimizedForLcd); QImage pageImage m_doc.render(pageIndex, reqSize, opts); if (pageImage.isNull()) { painter.drawText(100, 100, 當(dāng)前頁(yè)渲染失敗); return; } // 畫(huà)到目標(biāo)矩形里保持縱橫比 QImage scaled pageImage.scaled(targetRect.size().toSize(), Qt::KeepAspectRatio, Qt::SmoothTransformation); QRectF centered QRectF(targetRect.topLeft(), scaled.size().toSizeF()); centered.moveCenter(targetRect.center()); painter.drawImage(centered.topLeft(), scaled); }這段代碼先算了目標(biāo)矩形來(lái)源是打印機(jī)的寬高——注意這寬高不是像素而是當(dāng)前分辨率下的“邏輯像素”300 DPI 下 A4 紙的寬約 2480高約 3508。QPdfDocument::render 的第二個(gè)參數(shù)就是輸出的像素尺寸這里直接用與打印機(jī)一致的像素尺寸避免縮放損失。render 返回的 QImage 是按頁(yè)面旋轉(zhuǎn)方向處理過(guò)的結(jié)果直接縮放繪制即可。Highlight 區(qū)域的繪制用的是比例縮放加居中這樣 PDF 寬高比和打印紙不一致時(shí)兩側(cè)留白而不是拉伸變形。注意這個(gè)實(shí)現(xiàn)里沒(méi)有處理多頁(yè)循環(huán)因?yàn)?QPrintPreviewWidget 的 SinglePage 模式下每次繪制回調(diào)只畫(huà)當(dāng)前頁(yè)打印時(shí)才需要遍歷全部頁(yè)這部分在下一節(jié)補(bǔ)上。3.4 多頁(yè)打印打印循環(huán)與預(yù)覽的差別預(yù)覽控件走的是“每次畫(huà)一頁(yè)”的路徑但 QPrinter 真正打印時(shí)需要在一個(gè)連續(xù)繪制會(huì)話里輸出所有頁(yè)用 newPage() 推進(jìn)紙張。常見(jiàn)的錯(cuò)誤是把打印循環(huán)直接套用預(yù)覽回調(diào)導(dǎo)致打印出來(lái)只有第一頁(yè)。正確的打印函數(shù)獨(dú)立實(shí)現(xiàn)void PdfPreviewWindow::printDocument() { QPrinter printer(QPrinter::HighResolution); printer.setPageSize(QPageSize(QPageSize::A4)); printer.setResolution(300); QPrintDialog dialog(printer, this); if (dialog.exec() ! QDialog::Accepted) return; QPainter painter; if (!painter.begin(printer)) { return; // 打印機(jī)初始化失敗時(shí)直接退出避免后續(xù)崩潰 } painter.setRenderHint(QPainter::Antialiasing, true); for (int page 0; page m_doc.pageCount(); page) { QPdfDocumentRenderOptions opts; QSize pageSize printer.pageLayout().paintRectPixels( printer.resolution(), false); QImage img m_doc.render(page, pageSize, opts); if (!img.isNull()) { painter.drawImage(0, 0, img); } if (page ! m_doc.pageCount() - 1) { printer.newPage(); // 非最后一頁(yè)才換紙 } } painter.end(); }代碼里 pageLayout().paintRectPixels 在 Qt 5.15 及以上可用作用是拿到頁(yè)面可繪制區(qū)域的實(shí)際像素矩形啃到渲染尺寸與打印紙匹配。最后一頁(yè)不調(diào)用 newPage防止輸出空白頁(yè)尾頁(yè)這是一處實(shí)操易忘的細(xì)節(jié)。打印循環(huán)里不再做縮放居中因?yàn)?PDF 頁(yè)面本來(lái)就是 A4 或可由 QPdfDocument 按要求縮放直接鋪滿頁(yè)面最穩(wěn)妥。預(yù)覽與打印共用的協(xié)調(diào)點(diǎn)在于兩者都在同一個(gè)分辨率300 DPI下渲染頁(yè)面預(yù)覽看到的頁(yè)邊距、內(nèi)容占比和打印輸出一致。如果預(yù)覽用 150 DPI 打印用 300 DPI文字會(huì)顯得“預(yù)覽剛好打印偏小”這是后文要重點(diǎn)說(shuō)的坑。4. 預(yù)覽參數(shù)與打印參數(shù)分辨率、頁(yè)邊距、縮放模式的五組必調(diào)參數(shù)4.1 分辨率決定預(yù)覽清晰度與打印質(zhì)量的根因QPrinter 的 setResolution 直接影響兩個(gè)環(huán)節(jié)預(yù)覽渲染用的 QImage 尺寸和打印輸出的物理點(diǎn)密度。分辨率設(shè)低了PDF 渲染出的圖片像素少預(yù)覽窗口一放大就有鋸齒打印出來(lái)字體明顯發(fā)虛設(shè)高了內(nèi)存占用和渲染耗時(shí)會(huì)上升頁(yè)面多的時(shí)候速度體感很差。一般我會(huì)按兩個(gè)場(chǎng)景分開(kāi)設(shè)預(yù)覽時(shí)用 150200 DPI 左右打印時(shí)用 300 DPI 甚至更高。不要在 QPrintPreviewWidget 構(gòu)造時(shí)傳一個(gè)高分辨率打印機(jī)然后在回調(diào)里又要求低分辨率渲染否則預(yù)覽和打印的顏色、密度對(duì)不上。如果一定只用一個(gè)打印機(jī)對(duì)象統(tǒng)一的取值以打印需求為準(zhǔn)——因?yàn)榇蛴≥敵鍪遣豢赡娴念A(yù)覽模糊還能忍打印糊了沒(méi)法交代。具體參數(shù)上普通文字文檔 300 DPI 是性價(jià)比最高的檔位矢量圖形和表格線條也會(huì)清晰。600 DPI 留給帶有小字號(hào)注腳或者精細(xì)工程圖的文檔再往上就主要消耗 CPU 和內(nèi)存觀感差異已經(jīng)不大。預(yù)覽控件的顯示縮放和分辨率是兩個(gè)維度分辨率負(fù)責(zé)“渲染原圖質(zhì)量”zoomFactor 負(fù)責(zé)“顯示放大倍率”不要混為一談。4.2 頁(yè)面大小與方向打印機(jī)紙張和 PDF 頁(yè)面不一致時(shí)PDF 頁(yè)面大小與打印機(jī)紙型不總是一致。常見(jiàn)的情況PDF 是按 Letter 排版的打印機(jī)默認(rèn) A4結(jié)果打印出來(lái)四周被裁掉一塊或者留出很大的空白。QPrintPreviewWidget 預(yù)覽時(shí)用的是 QPrinter 當(dāng)前設(shè)置的紙張大小如果 PDF 是 Letter渲染圖片按 KeepAspectRatio 縮放居中預(yù)覽看著正常但打印時(shí)會(huì)按打印機(jī)的物理紙槽走可能裁切。規(guī)避思路加載 PDF 后讀取文檔第一頁(yè)的頁(yè)面尺寸嘗試據(jù)此設(shè)置 QPrinter 的頁(yè)面。QPdfDocument 的 pagePointSize 方法可以拿到頁(yè)面尺寸的 point 值再換算成 QPageSize 設(shè)置給打印機(jī)。代碼寫(xiě)法如下QSizeF pdfPageSize m_doc.pagePointSize(0); // 返回的是 point QPageSize pageSize(pdfPageSize, QPageSize::Point); m_printer-setPageSize(pageSize);這里單位是 point1 point 等于 1/72 英寸。這樣設(shè)置后打印機(jī)紙張會(huì)跟隨 PDF 實(shí)際尺寸減少裁切。方向上同理如果第一頁(yè)是橫向而默認(rèn)縱向需要判斷寬高比后調(diào)用 setPageOrientation 調(diào)整否則頁(yè)面旋轉(zhuǎn) 90 度是常見(jiàn)事故。4.3 頁(yè)邊距寧可在預(yù)覽里縮不要在打印里摳QPrinter 的頁(yè)邊距有兩個(gè)來(lái)源一個(gè)來(lái)自打印機(jī)的不可打印區(qū)域也就是硬件物理邊距另一個(gè)來(lái)自 QPageLayout 的 margins 設(shè)置屬于軟件層內(nèi)容邊距。預(yù)覽控件顯示的是前者約束下的物理紙張如果你的頁(yè)碼或者表格線剛好畫(huà)在硬件邊距內(nèi)預(yù)覽里看著沒(méi)問(wèn)題打印出來(lái)會(huì)被裁掉或噴到紙外。解決方案有兩個(gè)方向。第一是接受硬件邊距把所有內(nèi)容繪制限定在 paintableRect 內(nèi)適合成品打印。第二是設(shè)置頁(yè)邊距為 0QPrinter 會(huì)自動(dòng)把內(nèi)容盡量居中在物理可打印區(qū)域內(nèi)適合需要最大化利用紙張的場(chǎng)景。如果你設(shè)計(jì)時(shí)已經(jīng)預(yù)留了固定出血邊距就用 QPageLayout::setMargins 指定毫米值QMarginsF margins(10.0, 10.0, 10.0, 10.0); // 單位毫米 m_printer-setPageMargins(margins, QPageLayout::Millimeter);建議直接在預(yù)覽階段就套用最終打印的邊距參數(shù)這樣預(yù)覽看到的白邊就是打印出來(lái)的白邊。不要預(yù)覽時(shí)用零邊距打印時(shí)又加上 20 毫米互相抵消的后果是內(nèi)容位置不可預(yù)期。4.4 縮放模式、頁(yè)序與翻頁(yè)細(xì)節(jié)QPrintPreviewWidget 提供的 look 相關(guān)接口里有幾個(gè)高頻使用項(xiàng)。setZoomFactor 設(shè)置的是顯示縮放倍率1.0 代表 100% 按物理尺寸顯示大于 1 放大小于 1 縮小。fitToWidth 和 fitInView 是按頁(yè)面寬度或整個(gè)頁(yè)面適配窗口的自動(dòng)模式更適合第一次打開(kāi)文檔時(shí)使用兩者都會(huì)覆蓋手動(dòng)設(shè)置的 zoomFactor。預(yù)覽控件自帶 setCurrentPage 方法控制當(dāng)前顯示頁(yè)connect 它的 pageChanged 信號(hào)可以在翻頁(yè)時(shí)同步你的狀態(tài)欄或者工具欄。另外一個(gè)不太顯眼的接口是 setEnabled 和 updatePreview 的組合加載新文檔后必須先 setCurrentPage(0) 再 updatePreview否則控件可能停留在上一份文檔的尾頁(yè)附近出現(xiàn)示意上的錯(cuò)位感。頁(yè)序問(wèn)題主要影響打印環(huán)節(jié)。某些打印驅(qū)動(dòng)支持“逆序打印”如果你的循環(huán)是從第 0 頁(yè)到最后一頁(yè)配合打印驅(qū)動(dòng)自帶的逆序選項(xiàng)就會(huì)導(dǎo)致硬編碼順序和驅(qū)動(dòng)順序疊加出錯(cuò)。一般建議代碼里保持自然頁(yè)序把逆序交給打印對(duì)話框設(shè)置不要兩頭都管。4.5 五組常用參數(shù)的速查表與推薦配置下面這張表匯總了這套預(yù)覽方案最常改動(dòng)的參數(shù)及落地取值方便直接對(duì)照設(shè)置參數(shù)項(xiàng)接口位置預(yù)覽場(chǎng)景建議打印場(chǎng)景建議渲染 DPIQPrinter::setResolution150~200300 起精細(xì)圖 600頁(yè)面大小QPrinter::setPageSize跟隨 PDF 首頁(yè)尺寸與紙槽一致頁(yè)邊距QPageLayout::setMargins與打印一致按成品需求設(shè)顯示縮放QPrintPreviewWidget::setZoomFactor1.0 或 fitToWidth不參與打印預(yù)覽頁(yè)序QPrintPreviewWidget::setCurrentPage自然頁(yè)序循環(huán)按自然頁(yè)序這套配置里唯一要?jiǎng)幽X筋的是 DPI 和頁(yè)邊距兩組。DPI 影響渲染圖片的像素總量不建議盲目拉高預(yù)覽里 200 DPI 配合 fitToWidth 在普通屏幕上已經(jīng)足夠銳利打印時(shí) 300 DPI 能覆蓋絕大多數(shù)辦公場(chǎng)景。頁(yè)邊距則要盡早固定因?yàn)樗苯佑绊懪虐孀鴺?biāo)中途改動(dòng)會(huì)牽連所有頁(yè)面元素的位置計(jì)算。5. 六條踩坑記錄空白頁(yè)面、雙屏縮放、資源釋放這些毛病怎么查5.1 預(yù)覽控件一片空白但直接打印卻有內(nèi)容現(xiàn)象QPrintPreviewWidget 窗口正常顯示但頁(yè)面區(qū)域完全空白工具欄的頁(yè)數(shù)信息也是對(duì)的。原因有兩個(gè)高頻來(lái)源一是打開(kāi) PDF 后沒(méi)有調(diào)用 updatePreview()控件根本不知道文檔已經(jīng)變化二是 paintRequested 回調(diào)里 QPdfDocument::render 的請(qǐng)求尺寸傳了空值返回的 QImage 是空的。解決先確認(rèn) load 返回成功隨后強(qiáng)制調(diào)用 updatePreview()。如果還空白在回調(diào)里對(duì) render 結(jié)果判空并打印調(diào)試信息。另外檢查回調(diào)綁定的 QPrinter 是不是構(gòu)造預(yù)覽控件時(shí)傳入的那一個(gè)如果連接信號(hào)時(shí)用了別的打印機(jī)對(duì)象繪制坐標(biāo)系不匹配也會(huì)導(dǎo)致輸出位置錯(cuò)亂。5.2 預(yù)覽很清晰打印出來(lái)的文字卻發(fā)虛現(xiàn)象同一份 PDF 在預(yù)覽窗口里看起來(lái)銳利無(wú)瑕送到打印機(jī)后文字邊緣模糊像低分辨率放大。原因預(yù)覽和打印用了同一個(gè) QPrinter 對(duì)象加載 PDF 渲染時(shí)按預(yù)覽窗口 DPI 計(jì)算尺寸真正打印時(shí)沒(méi)有重新設(shè)置 QPrinter 的分辨率導(dǎo)致輸出圖形的點(diǎn)陣密度不足。解決把預(yù)覽用打印機(jī)和打印用打印機(jī)分開(kāi)。預(yù)覽用一個(gè)獨(dú)立的 QPrinter 調(diào) 200 DPI 顯示打印時(shí)在 printDocument() 里新建 QPrinter 并設(shè) 300 DPI分別驅(qū)動(dòng)渲染。如果項(xiàng)目代碼里確實(shí)只想用一個(gè)打印機(jī)就必須在打印前重新 setResolution 并重新 render 頁(yè)面不要復(fù)用之前緩存的 QImage。5.3 高分屏上頁(yè)面邊緣出現(xiàn) 1 像素白線現(xiàn)象在 2K 或 Retina 屏上預(yù)覽 PDF 時(shí)頁(yè)面邊緣偶爾出現(xiàn)細(xì)白線截圖放大后能看到是渲染圖沒(méi)有完全覆蓋目標(biāo)矩形。原因QImage 縮放時(shí)尺寸取整目標(biāo)矩形是浮點(diǎn)值但 drawImage 用的是整數(shù)坐標(biāo)縮放后差 1 像素沒(méi)有填充。解決繪制前計(jì)算目標(biāo)矩形后再做一次取整處理保證 drawImage 的目標(biāo)區(qū)域與原圖寬高比誤差小于 1 像素。最簡(jiǎn)單的方法是 scaled 后用 QRectF 顯式對(duì)齊QSizeF targetSizeF targetRect.size(); QSize targetSize QSize(qRound(targetSizeF.width()), qRound(targetSizeF.height())); QImage scaled pageImage.scaled(targetSize, Qt::KeepAspectRatio, Qt::SmoothTransformation); painter.drawImage(targetRect.x(), targetRect.y(), scaled);5.4 大 PDF 文件反復(fù)翻頁(yè)時(shí)內(nèi)存持續(xù)上漲現(xiàn)象打開(kāi)一份幾百頁(yè)的掃描版 PDF連續(xù)翻頁(yè)半小時(shí)后程序內(nèi)存占用從三百兆漲到接近一個(gè) G。原因每翻一頁(yè)都在渲染一張全尺寸 QImage翻過(guò)的頁(yè)沒(méi)有主動(dòng)釋放連 Qt 自己的圖片緩存也沒(méi)有清理。解決分兩塊處理。第一是渲染前檢查 pageImage 是否仍然引用舊數(shù)據(jù)直接在循環(huán)里用局部變量承接 render 結(jié)果出作用域就釋放第二是借助 QPdfDocument 自帶的頁(yè)面緩存控制設(shè)置 document 的 DocumentRender 參數(shù)限制緩存頁(yè)數(shù)避免無(wú)限增長(zhǎng)。翻頁(yè)極多且圖片巨大的文檔建議直接降預(yù)覽分辨率到 150 DPI肉眼差別有限但內(nèi)存減半。5.5 文件名帶中文或空格怎么也打不開(kāi)現(xiàn)象同一個(gè) PDF 文件路徑改成純英文就正常改成中文路徑就加載失敗。原因是 Qt 在部分平臺(tái)或編碼環(huán)境下對(duì)本地文件名解析依賴(lài)系統(tǒng)代碼頁(yè)中文路徑落入非 UTF-8 語(yǔ)義時(shí) QPdfDocument 讀不到文件。解決先確認(rèn)文件確實(shí)存在再用 QFile::exists 快速排除路徑拼寫(xiě)問(wèn)題。穩(wěn)定做法是把路徑轉(zhuǎn)為標(biāo)準(zhǔn)路徑后傳入QString filePath input-text().trimmed(); QFileInfo info(filePath); if (!info.exists()) return; QString canonicalPath info.canonicalFilePath(); m_doc.load(canonicalPath); // 使用規(guī)范化絕對(duì)路徑canonicalFilePath 返回的是絕對(duì)路徑而且消除了路徑里的相對(duì)段和符號(hào)鏈接干擾能有效減少編碼引起的加載失敗。5.6 雙面打印時(shí)偶數(shù)頁(yè)缺失或順序顛倒現(xiàn)象啟用打印對(duì)話框里的雙面打印后輸出結(jié)果出現(xiàn)奇數(shù)頁(yè)和偶數(shù)頁(yè)混排原本的第 2 頁(yè)跑到第 7 頁(yè)的位置。原因很多打印機(jī)驅(qū)動(dòng)只負(fù)責(zé)物理翻面不負(fù)責(zé)頁(yè)碼順序重排需要應(yīng)用程序在打印循環(huán)里按雙面規(guī)則輸出或者關(guān)閉驅(qū)動(dòng)側(cè)的頁(yè)序處理。解決簡(jiǎn)單方案是在打印對(duì)話框里關(guān)閉自動(dòng)雙面保持代碼輸出自然頁(yè)序。如果必須支持驅(qū)動(dòng)雙面就在循環(huán)里先輸出全部奇數(shù)頁(yè)再輸出全部偶數(shù)頁(yè)并把驅(qū)動(dòng)端的逆序關(guān)閉。更可控的方案是自己在代碼里組織雙面打印for (int odd 0; odd m_doc.pageCount(); odd 2) { // 先打印奇數(shù)頁(yè)再打印對(duì)應(yīng)的偶數(shù)頁(yè) }這塊沒(méi)有絕對(duì)通用的版本不同驅(qū)動(dòng)的行為差異很大建議在目標(biāo)打印機(jī)上實(shí)際打一份三頁(yè)的測(cè)試文檔驗(yàn)證。6. 進(jìn)階滾動(dòng)連續(xù)預(yù)覽、縮略圖導(dǎo)航與驗(yàn)證方法6.1 用 QScrollArea 包裝 QPrintPreviewWidget 實(shí)現(xiàn)連續(xù)瀏覽SinglePage 模式翻頁(yè)適合閱讀單頁(yè)文檔但面對(duì)多頁(yè) PDF用戶會(huì)更習(xí)慣滾動(dòng)瀏覽的體驗(yàn)。把 QPrintPreviewWidget 放進(jìn) QScrollArea 只是第一步重點(diǎn)在尺寸同步預(yù)覽控件的高度應(yīng)隨當(dāng)前頁(yè)數(shù)和縮放系數(shù)更新否則滾動(dòng)范圍始終只有一屏。常見(jiàn)做法是監(jiān)聽(tīng) zoomFactorChanged 和文檔加載完成信號(hào)重設(shè) preview 的 minimumHeight 為所有頁(yè)面高度之和示例代碼如下connect(preview, QPrintPreviewWidget::zoomFactorChanged, this, [this](qreal factor) { int totalHeight m_doc.pageCount() * preview-height() * factor; preview-setMinimumHeight(totalHeight); });6.2 縮略圖導(dǎo)航與當(dāng)前頁(yè)高亮多頁(yè)文檔沒(méi)有縮略圖導(dǎo)航翻頁(yè)效率很低。可以用 QListWidget 配合 QPdfDocument 的縮略渲染為每一頁(yè)生成小尺寸預(yù)覽圖點(diǎn)擊后同步 QPrintPreviewWidget 的 currentPage用列表選中的高亮作為當(dāng)前頁(yè)指示。優(yōu)點(diǎn)是不需要引入額外控件庫(kù)幾十行就能實(shí)現(xiàn)一個(gè)可用的導(dǎo)航欄代價(jià)是縮略圖需要額外渲染一次文檔頁(yè)數(shù)多時(shí)建議用 120px 寬度渲染并緩存到內(nèi)存里避免每次點(diǎn)擊重新生成。6.3 驗(yàn)證效果用“渲染對(duì)比”代替肉眼抽查預(yù)覽界面做得再舒服最終交付的是打印輸出驗(yàn)證環(huán)節(jié)不能省。我的習(xí)慣是先把 PDF 頁(yè)導(dǎo)出為 PNG 參考圖再用同一套渲染函數(shù)把頁(yè)面畫(huà)到 QPrinter 上最后對(duì)比打印輸出或再次渲染的結(jié)果。由于代碼里預(yù)覽和打印共用 renderPdfPage 的繪制邏輯這份對(duì)比能直接發(fā)現(xiàn) DPI 不一致、邊距偏差這類(lèi)問(wèn)題。另一個(gè)驗(yàn)證手段是生成 PDF 后檢查頁(yè)數(shù)循環(huán)里最后一頁(yè)不調(diào)用 newPage 的寫(xiě)法在空文檔或者尾頁(yè)為空白頁(yè)時(shí)最容易漏掉打印前先打印一行日志記錄 pageCount比事后翻紙快得多。這套方案做到現(xiàn)在最大的教訓(xùn)是“先定分辨率再定邊距”順序反了后面所有排版的坐標(biāo)都要返工。文檔預(yù)覽在內(nèi)部工具里不算核心功能但做砸了會(huì)直接拖累主流程的信任度。希望這篇記錄下來(lái)的做法能幫你少走幾段彎路希望幫到你。本文還有配套的精品資源點(diǎn)擊獲取