PAYATHON 2026

Blazor PDF 导出如何选择 QuestPDF、PuppeteerSharp 与不同渲染方案?

数据阿明

建议按页面的验收标准选择导出方式:第一类页面如果需要长期维护并严格控制分页,适合用 QuestPDF 单独建立报表布局;第二类页面可以优先用 PuppeteerSharp 渲染现有 HTML/CSS 并打印为 PDF,视觉效果仍不满足要求时再采用截图转 PDF。

如果当前最希望减少布局重写,可以先用 PuppeteerSharp 验证两类页面。Chromium 打印普通 HTML 文本时,通常可以保留可选择的文字,无需将整页变成图片。最终能否满足分页和文件体积要求,仍取决于页面结构、字体、图片及数据规模。

先明确“DataGrid 不能被截断”的含义

这里有两种不同的要求:

  • 整个 DataGrid 必须放在同一页:前提是它能装进一页的可打印区域。
  • DataGrid 可以跨页,但不能裁掉内容或随意拆开一行:适合较长的表格,通常需要按行分页并重复表头。

如果表格比整页还高,又不允许缩小、拆分或改变纸张尺寸,任何库都无法让它完整地留在一页。

CSS 的 break-inside: avoid 用于避免内部断页,但无法解决内容超过单页容量的问题,也不能保证所有复杂布局都按预期分页。相关规则见 CSS Fragmentation 规范。

第一类页面:严格分页时选择 QuestPDF

QuestPDF 适合以数据和文档结构为中心的导出:先读取业务数据,再用 C# 定义章节、表格、页眉和页脚。它不会直接把现有 Radzen 组件转换为 PDF,因此需要维护一套单独的文档布局。

数据查询、筛选条件、排序和格式化逻辑可以复用,以减少业务规则重复;页面布局与 PDF 布局仍需分别实现。

分页时可以这样处理:

  • 允许长表格跨页并重复表头。QuestPDF 的表格表头支持跨页重复,见表头与表尾文档。
  • 对确定能放进一页的小区块,可以使用 ShowEntire() 保持完整。
  • 不要把任意长度的整个表格都包进 ShowEntire()。内容超过单页容量时可能触发 DocumentLayoutException,见 ShowEntire 文档。

文件体积小也不能只靠选库保证。保留真实文本、控制字体资源和图片分辨率,通常比把整张报表栅格化更符合这类需求。

复用现有布局时,先建立专用导出页面

如果第一类页面希望继续使用 HTML/CSS,可以建立专用导出路由,保留必要的组件或改用语义化 HTML 表格,再由 PuppeteerSharp 打印。

首先要保证数据完整。Radzen DataGrid 启用虚拟化时,DOM 中只渲染可见行;服务端分页也可能只加载当前页。浏览器打印无法自动补齐没有加载或没有渲染的数据。相关行为见 Radzen DataGrid API。

导出页面应当:

  1. 按约定读取当前筛选、排序后的完整导出数据。
  2. 关闭导出视图中的分页和虚拟化,并确保数据已经实际加载。
  3. 展开需要导出的明细,移除会裁切内容的固定高度和滚动容器。
  4. 设置打印样式,并在组件完成渲染后发出就绪信号。

下面的打印样式可以作为起点。类名需要由导出页面自行定义,并根据实际生成的 DOM 调整;它们不是 Radzen 内置类名。

@page {
  size: A4;
  margin: 12mm;
}

@media print {
  .export-scroll-container {
    height: auto !important;
    max-height: none !important;
    overflow: visible !important;
  }

  .export-table thead {
    display: table-header-group;
  }

  .export-table tr {
    break-inside: avoid;
    page-break-inside: avoid;
  }

  /* 仅用于确认能放进一页的小区块 */
  .export-keep-together {
    break-inside: avoid;
    page-break-inside: avoid;
  }
}

不要给所有长表格统一设置“整表不分页”。应检查超高行、合并单元格、嵌套表格和固定列等结构的实际打印结果。

PuppeteerSharp 导出示例

以下代码假设已经创建 page,并且 exportUrl 指向可访问的导出页面。data-pdf-ready="true" 是应用自行定义的就绪标记,必须在数据、组件和所需图片准备完成后设置。

using PuppeteerSharp;

await page.GoToAsync(exportUrl);

await page.WaitForFunctionAsync(
    "() => document.documentElement.dataset.pdfReady === 'true'");

await page.EvaluateFunctionAsync(
    "() => document.fonts.ready.then(() => true)");

await page.PdfAsync("report.pdf", new PdfOptions
{
    PrintBackground = true,
    PreferCSSPageSize = true
});

PrintBackground 用于打印背景图形,PreferCSSPageSize 让 CSS 中的 @page 尺寸优先,见 PdfOptions 文档。纸张尺寸和边距只是示例,需要按实际内容调整。

Blazor 页面导航完成后,异步数据和组件可能还未渲染完成。使用明确的就绪信号比固定等待几秒更可靠。

第二类页面:先直接打印,再考虑截图

对于阀门外观这类依赖复杂 HTML/CSS 的页面,可以优先让 Chromium 渲染现有页面,避免在 QuestPDF 中重新实现视觉布局。

PdfAsync 默认使用 print 媒体样式。如果希望沿用屏幕样式,可以在导出前调用:

await page.EmulateMediaTypeAsync(
    PuppeteerSharp.Media.MediaType.Screen);

该行为见 PuppeteerSharp Page 文档。使用 screen 样式后仍然存在纸张分页,不能保证 PDF 与网页逐像素一致。还需要固定视口宽度、字体、主题和页面状态,并明确宽表格如何适配纸张。

如果直接打印仍然改变了关键布局,可以用 Chromium 对目标元素截图,再将图片按比例嵌入 PDF。PuppeteerSharp 提供元素级截图能力,见 ElementHandle 文档。如果项目已经使用 QuestPDF,也可以由它负责把截图放进 PDF。

截图方案有一些取舍:文字不再天然可选择;放大后的清晰度取决于截图分辨率;提高分辨率可能增加文件体积。对于超长内容,应明确选择单页缩放、自定义纸张尺寸或按设计区块分页,避免机械切图破坏图形结构。

如何决定是否使用两套工具?

主要条件 建议
第一类页面要求稳定、可预测的文档分页 QuestPDF,接受单独维护报表布局
两类页面都希望尽量复用现有 HTML/CSS 先验证 PuppeteerSharp,加专用导出视图
第二类页面直接打印达不到视觉要求 Chromium 截图,再嵌入 PDF
第一类要求严格分页,第二类要求高度还原网页 QuestPDF 与 PuppeteerSharp 分工

结合目前给出的约束,采用混合方案是合理的。如果重写成本是当前的主要障碍,可以先用 PuppeteerSharp 验证最复杂的页面,再决定第一类页面是否值得迁移到 QuestPDF。

验收时,使用包含最长表格、超高行、复杂图形和真实字体的样例,检查是否漏行、分页是否合理、文字能否选择,以及文件体积是否满足目标。还应分别评估运行 Chromium 所需的部署资源和生成的 PDF 文件体积。

备注:内容仅供参考。