Screenshot PDF 工作原理：长网页如何生成连续截图
全页屏幕截图并不是瞬间拍摄的整个文档的照片。浏览器通常仅公开当前视口内的像素。因此，捕获长页面需要一个受控的序列：识别滚动的内容、对其进行测量、在其中移动、捕获可见切片并组装这些切片，而无需默默更改源页面。
本文记录了版本 0.0.13 中当前的 Screenshot PDF 扩展管道。它基于附带的捕获和编辑器代码，而不是基于理想化的图表。下面的边界很重要，因为可重复的限制比保证每个页面都可以完美捕获更有用。
1. 扩展从活动选项卡开始
Screenshot PDF 使用 Manifest V3 Chrome 扩展，从当前活动标签页开始工作。Chrome 内部页面（如 chrome://settings 和 Chrome Web Store）受浏览器限制，会在截图开始前被拒绝。普通公开页面、用户当前可见且已登录的页面以及许多 Web 应用界面通常可以截图，因为扩展运行在用户现有会话中。
这种访问并不意味着每个嵌入式表面都可用。跨源帧、受保护的视频、WebGL、虚拟化列表以及在正常页面流之外绘制的内容仍然需要不同的导出方法。 Chrome 在其 tabs.captureVisibleTab API 中记录了底层可见选项卡操作。
2. 找到真正的滚动容器
并非每个网站都会滚动文档正文。仪表板经常将可滚动区域放置在 div 内，而外部页面保持固定。该扩展首先检查常用的文档滚动元素。如果没有符合条件，它将检查常见内容容器并选择具有垂直溢出和最大有用区域的可见元素。
这个选择是必然的。即使用户可以看到更多内容，测量错误的元素也会产生在一个屏幕后停止的图像。实用的诊断是将用户移动的滚动条与 DevTools 中 scrollHeight 发生变化的元素进行比较。扩展会自动进行此选择，但嵌套或水平滚动应用程序可能仍需要分段捕获。
3. 移动前测量
截图数据会记录页面宽高、视口宽高和设备像素比。CSS 像素描述页面布局，而高 DPI 屏幕生成的 PNG 像素通常更密集。编辑器随后根据第一段截图计算实际像素比，让 CSS 坐标与图像坐标保持对齐。
当前的整页工作流程将明确的上限设置为 每次运行高度 15,000 个 CSS 像素。边界可防止无限制的提要无限期地消耗内存。如果页面较长，请捕获具有可见重叠的命名部分，或使用源服务的官方导出。不要将超出该边界的结果描述为完整的。
4. 一次捕获一个视口
扩展程序以视口高度的步长在页面中移动。每次请求滚动后，它都会读取实际的滚动位置，而不是假设页面完全按照请求移动。这可以保护最后的切片，浏览器可以将滚动位置固定在底部。
内容脚本先等待两个动画帧，滚动后再等待约 300 毫秒；后台流程还会在分段截图之间短暂停顿。这给普通布局留出了稳定时间，但不能保证所有延迟加载图片、动画或网络请求都已完成。对于媒体较多的页面，建议先手动滚动一遍，等占位内容加载完成后再开始截图。
Chrome 可能临时限制可见标签页的截图频率。当错误符合 Chrome 的频率限制特征时，Screenshot PDF 最多重试 3 次，每次间隔 1 秒；其他错误则直接报告，不会隐藏。这样可避免把持续的权限或渲染问题变成长时间无提示的重试循环。
5. 处理浮动界面元素
粘性页眉、Cookie 控件、聊天入口和浮动工具栏依附于视口，而不是文档中的固定位置。若它们在每段截图中都可见，就会在拼接结果里重复出现。Screenshot PDF 会记录浮动候选元素，在第一段中保留它们，后续分段则只改变可见性来隐藏，而不改写布局位置。
成功后以及失败路径内的可见性都会恢复。页面返回顶部，去除采集进度界面，清除扩展徽章。这种清理是正确性的一部分：当捕获失败时，工具不应使源页面在视觉上发生变化。
6. 将切片传递给编辑器
每个切片都有其实际的垂直位置。编辑器加载所有 PNG 切片，创建白色画布，并在根据 CSS 坐标、固有设备像素比和任何内存驱动的比例因子导出的位置绘制它们。有用的高度以最后捕获的视口结束，而不是自动信任可能已更改的早期页面测量值。
这种拼接方法非常适合稳定的垂直滚动布局。它无法重建在单个滚动状态下不存在的内容。当新行出现时，虚拟化表可能会卸载较早的行；实时仪表板可能会更改切片之间的值；自动旋转的组件可能会显示不同的框架。在这些情况下，请使用较小的部分或源本机导出。
7. 可重复的捕获记录
对于普通的个人文档，目视检查可能就足够了。对于支持证据、研究、设计审查或记录工作，请记录：
- 公共 URL 或经过身份验证的页面的非敏感描述；
- Chrome 和扩展版本；
- 视口大小、缩放和设备像素比；
- 预定的起点和终点；
- 内容是否已展开或预滚动；
- 页面是否超过15,000 CSS像素；
- 任何丢失的帧、嵌入的表面或实时值。
Screenshot PDF 提供一个公开的可复现截图测试页，其中包含粘性页眉、固定控件、延迟加载内容、表格、交替背景和末端标记。可用它区分通用截图问题与特定网站的布局问题。
这套流程不能证明什么
视觉上完整的屏幕截图并不能证明真实性、法律可接受性或未经修改的来源。它记录浏览器会话中渲染的像素。单独保留源 URL、访问时间和相关上下文。当源服务提供签名声明、结构化导出、发票或原生数字 PDF 时，请在屏幕截图旁边保留更强大的源。
当前的管道是故意限制的：测量、在实际位置捕获、仅重试已知的限制、恢复页面、本地组装，并要求用户检查输出。这些界限使得长页面捕获变得易于理解和可重复。