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。
导出页面应当:
- 按约定读取当前筛选、排序后的完整导出数据。
- 关闭导出视图中的分页和虚拟化,并确保数据已经实际加载。
- 展开需要导出的明细,移除会裁切内容的固定高度和滚动容器。
- 设置打印样式,并在组件完成渲染后发出就绪信号。
下面的打印样式可以作为起点。类名需要由导出页面自行定义,并根据实际生成的 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 文件体积。
备注:内容仅供参考。
