Lightdash 数据应用中基于 html-to-image + jspdf 的客户端 PDF 导出实战指南

Lightdash 数据应用中基于 html-to-image + jspdf 的客户端 PDF 导出实战指南

【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash

本文讲解 Lightdash 数据应用（Data App）中"客户端 PDF 下载"的标准实现：如何用预置的html-to-image与jspdf两个库，把浏览器里的 React 报表页面逐页光栅化并合成为可下载的 PDF 文件。适用于 PDF Report 模板、报表/打印/文档形态的应用，以及任何用户要求"下载 PDF"的场景。读完本文，你将掌握从.pdf-page页面容器设计、图片加载、A4 多页拼接到导出状态管理的完整方案。

背景：为什么数据应用需要一份"客户端 PDF 导出"规范

Lightdash 的数据应用（Data App）是 AI 生成、运行在沙箱 iframe 中的交互式 React 应用，用户通过一句话描述需求，编码代理（coding agent）在隔离沙箱内编写应用源码，最终由 Lightdash 构建并在沙箱 iframe 中提供访问。所有运行中的应用查询都经由 Lightdash 语义层执行，权限由 Lightdash 而非应用自身强制。docs/data-apps/CONTEXT.md 中对数据应用的产品形态做了明确定义：模板（Template）是数据应用生成的初始风格，包括 Dashboard（仪表盘）、Slide show（幻灯片）、PDF report（PDF 报表）和 Custom（自定义）四种。

其中PDF report 模板的核心产物就是一份可下载的 PDF 报表。对这类应用而言，"导出 PDF"不是可选功能，而是报表形态的组成部分——这正是 pdf-downloads.md 这份参考文档存在的意义：它被编码代理在搭建任何报表/可打印/文档形态应用时强制执行，作为沙箱内 PDF 生成的唯一标准路径。

与"后端导出"不同，这套方案强调客户端生成：不把数据行序列化到 iframe 之外，也不依赖服务器渲染。它与你可能已经熟悉的 后端数据下载（downloadResults） 分工明确——后者通过 Lightdash 的导出管线生成真实 CSV/XLSX 文件；而 PDF 报表要保留的是版式而非数据行，因此采用 DOM 快照的方式。

为什么是 html-to-image + jspdf：沙箱约束下的必然选择

模板在 package.json 中预置了完整的依赖集，其中html-to-image版本为1.11.13，jspdf版本为4.2.1。使用它们有两条硬性规则：

• 不要从 CDN 加载 PDF 库，也不要请求安装新包。数据应用沙箱内禁用安装（npm install/pnpm add会失败），模板的依赖集是固定的，所有第三方库都已预装。规范明确要求直接使用这两个预置包。
• 浏览器端的光栅化必须是"就地"的。预览 iframe 以sandbox="allow-scripts"（不含allow-same-origin）运行，因此 iframe 的 origin 是不透明的（opaque）。两个不透明 origin 永远不会同源，这会破坏所有"内部创建一个隐藏 iframe 再读取iframe.contentDocument"的 DOM-to-image 库——例如 html2canvas（把整页克隆进嵌套 iframe）和 modern-screenshot（创建沙箱 iframe 计算默认样式）都会抛出跨域错误。

这一点在 screenshotHandler.js 的注释中有清晰的论证：html-to-image不采用嵌套 iframe 的技巧，而是直接遍历实时 DOM，把computedStyle.cssText复制到克隆节点上，再用 SVG<foreignObject>包裹。没有嵌套 iframe 访问，也就没有跨域查询。这意味着同样的光栅化方案既用于 iframe 内截图能力（toBlob），也用于 PDF 导出（toPng），两者共享同一个沙箱兼容性根基。

核心原则：PDF 导出是"图像化"的

文档明确了 PDF 导出的本质定位：

PDF downloads are image-based: they preserve the visible report exactly, but the exported text is not selectable/searchable.

即：PDF 由每个页面区域的 PNG 位图拼接而成，忠实还原可见报表，但导出文本不可选中、不可检索。由此推导出两条重要规则：

1. window.print()只能作为次要的打印动作。报表工具栏中的主按钮必须是"Download PDF"并直接保存文件，而不是触发浏览器打印对话框。
2. 报表图表必须显示数值标签（value labels）。因为导出后的页面无法悬停，所有依赖 tooltip 才能读取的数值都会丢失。规范的配套约定（见 skill.md）要求：当图表的输出将被静态阅读（导出或打印到 PDF）时，用 Recharts 的<LabelList>把数值直接画在图上，并搭配formatter保持与坐标轴/tooltip 一致的格式。标签是叠加的，不替代交互。

页面容器设计：.pdf-page 的稳定 DOM 结构

规范要求把 PDF 的每一页（或每个 section）渲染在稳定的 DOM 容器中，通常命名为.pdf-page，并赋予固定的可打印尺寸或宽高比。这一设计服务于两个目标：

• 可预测的分页：downloadPdfFromPages通过querySelectorAll('.pdf-page')收集所有页面元素，每个.pdf-page对应 PDF 中的一页（A4）。
• 避免滚动容器陷阱：规范明确要求不要捕获含有隐藏内容的滚动容器（scroll container），而是捕获已经包含完整待导出内容的、页面尺寸的元素。如果对带滚动条的容器做快照，只会得到可视区域的局部内容，超出部分会丢失。

<div ref={reportRef}>{/* .pdf-page report sections */}</div>

组件内部通过reportRef.current.querySelectorAll<HTMLElement>('.pdf-page')收集页面；当找不到任何.pdf-page时，优雅降级为把整个reportRef容器当作单页导出（pages.length > 0 ? pages : [reportRef.current]）。

从页面到 PDF：downloadPdfFromPages 的完整实现

以下是文档给出的核心导出函数，它承担了"逐页 PNG 化 + A4 缩放 + 多页拼接 + 文件保存"的全部工作：

import { Button } from '@/components/ui/button'; import { toPng } from 'html-to-image'; import { jsPDF } from 'jspdf'; import { Download, Loader2 } from 'lucide-react'; import { useRef, useState } from 'react'; async function imageLoaded(src: string) { const image = new Image(); image.src = src; await new Promise<void>((resolve, reject) => { image.onload = () => resolve(); image.onerror = reject; }); return image; } async function downloadPdfFromPages( pages: HTMLElement[], filename = 'report.pdf', ) { const pdf = new jsPDF({ orientation: 'portrait', unit: 'pt', format: 'a4' }); const pageWidth = pdf.internal.pageSize.getWidth(); const pageHeight = pdf.internal.pageSize.getHeight(); for (let index = 0; index < pages.length; index += 1) { if (index > 0) pdf.addPage(); const dataUrl = await toPng(pages[index], { cacheBust: true, pixelRatio: 2, backgroundColor: '#ffffff', }); const image = await imageLoaded(dataUrl); const scale = Math.min(pageWidth / image.width, pageHeight / image.height); const width = image.width * scale; const height = image.height * scale; pdf.addImage(dataUrl, 'PNG', (pageWidth - width) / 2, 0, width, height); } pdf.save(filename.endsWith('.pdf') ? filename : `${filename}.pdf`); }

逐段拆解这段代码的技术细节：

环节	代码	说明
PDF 文档初始化	new jsPDF({ orientation: 'portrait', unit: 'pt', format: 'a4' })	纵向 A4，单位使用 pt（点）。pt 是 jsPDF 内部逻辑坐标系的标准单位，与 A4 的 595×842 pt 尺寸天然对齐
页面尺寸读取	pdf.internal.pageSize.getWidth()/getHeight()	从 jsPDF 内部 pageSize 读取当前页面宽高，避免硬编码魔数
多页切换	if (index > 0) pdf.addPage()	第一页使用初始页，后续页面显式新增
DOM 光栅化	toPng(pages[index], { cacheBust: true, pixelRatio: 2, backgroundColor: '#ffffff' })	cacheBust: true给资源 URL 加时间戳防缓存；pixelRatio: 2以 2 倍分辨率渲染，保证打印清晰度；显式白底防止透明背景在部分 PDF 阅读器中显示异常
图片解码	imageLoaded(dataUrl)	用Image对象预加载 dataURL，onload/onerror承诺化，确保位图尺寸真实可用
等比缩放	Math.min(pageWidth / image.width, pageHeight / image.height)	取宽高两个方向缩放比的较小值，保证页面完整落进 A4 且不变形
水平居中	(pageWidth - width) / 2	x 坐标为居中偏移，y 固定为 0（顶部对齐）
保存文件	pdf.save(...)	自动补.pdf后缀，容错用户传入report或report.pdf两种文件名

报表组件的导出状态机：isExportingPdf

规范要求在报表的工具栏/页头中提供 Download PDF 按钮，并配套完整的异步状态管理：

• 用isExportingPdf状态跟踪导出过程；
• 在报表数据加载中或PDF 生成运行中时禁用按钮；
• 显示 spinner（Loader2的animate-spin）或 "Exporting..." 文案，直到 promise 落定。

文档给出的完整组件实现：

export function PdfReport() { const reportRef = useRef<HTMLDivElement | null>(null); const [isExportingPdf, setIsExportingPdf] = useState(false); async function exportPdf() { if (!reportRef.current) return; setIsExportingPdf(true); try { const pages = Array.from( reportRef.current.querySelectorAll<HTMLElement>('.pdf-page'), ); await downloadPdfFromPages( pages.length > 0 ? pages : [reportRef.current], 'executive-report.pdf', ); } finally { setIsExportingPdf(false); } } return ( <> <Button disabled={isExportingPdf} onClick={exportPdf}> {isExportingPdf ? ( <Loader2 className="mr-2 h-4 w-4 animate-spin" /> ) : ( <Download className="mr-2 h-4 w-4" /> )} {isExportingPdf ? 'Exporting...' : 'Download PDF'} </Button> <div ref={reportRef}>{/* .pdf-page report sections */}</div> </> ); }

这段代码体现了两个容易忽略的工程要点：

1. finally保证状态复位：无论toPng、imageLoaded还是pdf.save抛出什么异常，isExportingPdf都会复位为false，按钮不会永久卡在禁用态。这与模板对 loading 状态的整体要求一致——skill.md 规定所有用户触发的异步数据动作（导出、底层数据获取、drilldown 查询、refetch）都必须展示等待状态并保持周边 UI 稳定。
2. 空状态守卫：if (!reportRef.current) return;防止 ref 尚未挂载时执行导出。这是防御性编程的底线，也解释了为什么按钮的disabled通常还应与查询的loading状态联动（报表数据未加载完成时不应当导出空白页）。

导出按钮是报表的"必备件"而非可选件

文档用加粗口吻强调了这条规范：

Every PDF or printable report app includes a visible Download PDF button — the app is incomplete without one, on first generation and after every edit.

即：任何 PDF/可打印报表应用都必须包含可见的 Download PDF 按钮——首次生成要有，每次迭代编辑之后也要保持。具体到数据应用的生命周期（见 docs/data-apps/CONTEXT.md 对"迭代"的定义：用户用新提示词给现有应用追加新版本，编码代理基于当前源码做定向修改），这条规则的含义是：

• 编辑轮次中删除 Download PDF 按钮属于回归缺陷（regression），必须避免；
• 无论用户请求的措辞如何——PDF Report 启动模板、带 "printable"/"document"/"report to share" 字样的请求、还是已经渲染.pdf-page区块的应用——只要应用是报表形态，导出按钮就是标配。

该规范的约束力在基准测试中也有体现：sandboxes/data-apps/benchmark/prompts.json为不同提示词预设了mustRead/mustNotRead引用清单，pdf-downloads.md正是编码代理在报表场景下必须读取的参考文档之一。

五项实现规则清单

文档将散落在代码中的约束归纳为五条可执行的规则，编写报表应用时应逐条自查：

1. 稳定页面容器：每个 PDF 页或 section 渲染在固定尺寸/宽高比的 DOM 容器（如.pdf-page）中。
2. 按钮常驻：报表工具栏/页头必须有 Download PDF 按钮。
3. 导出状态追踪：维护isExportingPdf，在数据加载或导出进行中禁用按钮，显示 spinner 或 "Exporting..." 直至 promise 落定。
4. 静态可读性：PDF 报表中的图表必须带数值标签，因为导出页面无法悬停。
5. 不截滚动容器：避免捕获含隐藏内容的滚动容器，只捕获包含完整待导出内容的页面尺寸元素。

组合进真实数据应用：与查询管线的协作模式

PDF 导出不会孤立存在，它总是与数据应用的数据获取管线协作。以 skill.md 定义的 SDK 模式为例，报表应用的典型结构是：

1. 用query('orders').metrics(['total_revenue', 'order_count'])这类语义层查询（模块作用域定义、不可变、带.label()）获取数据；
2. 通过useLightdash(query)拿到data、loading、error，把数据渲染进.pdf-page区块；
3. loading状态同时驱动两处 UI：数据区的 spinner，以及 Download PDF 按钮的disabled（数据未就绪时禁止导出）；
4. 点击按钮后，exportPdf()按本文展示的流程逐页光栅化并保存文件。

一个可参考的落地要点是：图表的数值标签与 PDF 导出是配套需求。模板约定在正常情况下不默认开数值标签（避免杂乱），但当图表输出会被静态阅读时（导出/打印到 PDF），必须用<LabelList>叠加标签并让格式与坐标轴一致。也就是说，isExportingPdf只是导出过程的"门闩"，而页面内容本身的静态可读性才是 PDF 质量的决定因素。

与替代方案的边界

理解这套方案，还需要明确它与数据应用内其他导出能力的边界：

能力	机制	适用场景
客户端 PDF（本文）	html-to-image光栅化 +jspdf拼接位图	报表版式保留、多页文档、可分享的 PDF 文件
后端数据下载（downloadResults）	Lightdash 后端导出管线生成 CSV/XLSX	导出查询结果数据行，支持格式化/原始值与行范围选择
底层数据下载（downloadUnderlyingData）	后端导出聚合指标背后的原始行	指标值下钻到明细行后导出
Google Sheets（exportToSheets）	OAuth + Sheets 目的地写入	用户要求"Open in Google Sheets"时

规范对此有明确判断：当用户在报表场景要求导出结果行而非版式时，应使用downloadResults()；而当应用对data做了本地转换、分组或分页、且用户要求导出"当前可见表格"时，应使用客户端 CSV/复制辅助函数而非后端导出。PDF 导出始终保留给"文档形态"的输出。

小结

在 Lightdash 数据应用沙箱的约束下，客户端 PDF 导出是一条已被验证的标准路径：html-to-image绕过沙箱的跨域限制就地光栅化 DOM，jspdf以 A4 页面为单位拼接位图并保存文件。实现上只需守住三个要点——稳定的.pdf-page页面容器、常驻的 Download PDF 按钮、严格的isExportingPdf状态管理——就能交付一份完整、可分享、忠实还原报表版式的 PDF 文件。后续每次迭代编辑，都请让导出按钮保持可用：它是报表应用的形态的一部分，而不是可以随手删除的附加功能。

【免费下载链接】lightdashAgentic BI. Analytics at the speed of code ⚡️项目地址: https://gitcode.com/GitHub_Trending/li/lightdash