Qt C++使用QTextDocument打印PDF时如何实现各内容单独分页

QTextDocument默认按内容流连续排版、填充完当前页剩余空间后自动分页，要实现每个独立内容块单独占一页，核心是在每个内容块前插入强制分页标记，同时需要修正原代码中的排版参数错误。

原代码存在的问题 #

你当前代码里的doc.setTextWidth(0.5)写法有误：该接口参数为文档布局的宽度值（单位为逻辑像素），传入0.5会导致文档宽度几乎为0，内容排版完全错乱。另外设置0边距打印时，多数家用打印机和PDF阅读器会自动裁切边缘内容，建议保留适当边距。

实现代码 #

如果你是通过QTextCursor逐段向QTextDocument填充内容，可以在每段独立内容（除第一段外）前插入带分页属性的块，参考代码如下：

QPrinter printer(QPrinter::HighResolution);
printer.setOutputFormat(QPrinter::PdfFormat);
printer.setPaperSize(QPrinter::A4);
printer.setOrientation(QPrinter::Landscape);
printer.setOutputFileName(ui->lE_Save->text() + ".pdf");

// 初始化文档排版参数，匹配打印机尺寸
doc.setDocumentMargin(20); // 保留20单位边距，避免内容被裁切
qreal printableWidth = printer.pageRect(QPrinter::DevicePixel).width();
doc.setTextWidth(printableWidth); // 文档宽度和打印机可打印宽度一致

QTextCursor cursor(&doc);
// 遍历所有独立内容块，contentBlocks为存储你所有独立内容的列表，可根据实际存储结构调整
for (int i = 0; i < contentBlocks.size(); ++i) {
    if (i != 0) {
        // 非首个内容块前插入强制分页
        QTextBlockFormat pageBreakFmt;
        pageBreakFmt.setPageBreakPolicy(QTextFormat::PageBreak_AlwaysBefore);
        cursor.insertBlock(pageBreakFmt);
    }
    // 写入当前块内容，纯文本用insertText，富文本用insertHtml
    cursor.insertHtml(contentBlocks[i]);
}

doc.print(&printer);

已填充内容的文档分页处理 #

如果你已经把所有内容提前写入doc，不需要重新构建内容，可以直接遍历文档块，给每个独立内容的起始块设置分页属性：

QTextBlock currentBlock = doc.firstBlock();
int blockIndex = 0;
while (currentBlock.isValid()) {
    // isIndependentBlockStart为你自己实现的判断逻辑，识别当前块是否是独立内容的起始位置
    if (blockIndex != 0 && isIndependentBlockStart(currentBlock)) {
        QTextBlockFormat blockFmt = currentBlock.blockFormat();
        blockFmt.setPageBreakPolicy(QTextFormat::PageBreak_AlwaysBefore);
        currentBlock.setBlockFormat(blockFmt);
    }
    currentBlock = currentBlock.next();
    blockIndex++;
}
// 分页属性设置完成后再调用print即可

避坑提示 #

• 不要用插入大量空行的方式手动凑分页，不同打印分辨率、页边距下空行的渲染高度不固定，很容易出现分页错位。
• 如果内容块包含表格、嵌入图片等元素，分页属性必须设置在块级格式上，不要把分页符插入到元素内部，否则会导致元素被强制拆分、渲染异常。
• 不需要手动计算页面高度插入分页符，Qt的打印引擎会自动根据设置的分页规则完成页面拆分。

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