stitched-full-page-capture

拼接式整页截图

概述

使用滚动稳定后的视口截图，而不要依赖一次性浏览器 fullPage 截图。对于 Framer 页面和其他带有延迟加载或滚动动画的网站，这一点尤为重要，因为 MP4 可能看起来正常，但长截图却大部分为空白。

核心工作流

1. 打开真实页面 URL，而不是市场缩略图、封面图片、混剪页面或资源 URL。
2. 从顶部滚动到底部一次，让延迟加载的媒体和显示区域完成挂载。
3. 返回顶部。
4. 按视口大小或略有重叠的步幅向下滚动。
5. 每次停止滚动后等待约 2 秒。
6. 截取稳定后的视口。
7. 将视口截图垂直拼接为一张整页图片。
8. 从拼接后的图片裁切各个区域，而不是从浏览器原生 fullPage 截图中裁切。
9. 将拼接后的图片与代表性静帧、MP4 和动画帧进行验证。

如果整页候选图片包含空白、灰色或白色条带、可见内容极少、缺少延迟加载的区域、内容列异常狭窄，或与滚动视频明显不符，请予以拒绝。

脚本

对于每日 UI 灵感文章，如果此技能目录中提供了辅助脚本，请使用它：

node <skills-root>/stitched-full-page-capture/scripts/stitch_full_page_capture.mjs \
  --manifest articles/YYYY-MM-DD-ui-inspiration-capture/manifest.json

该脚本会：

• 读取 items[].pageUrl、fullPageImage 和 sectionImages；
• 在 Playwright Chromium 中打开每个实时页面；
• 通过滚动一次预加载延迟内容；
• 截取稳定后的视口片段；
• 将片段拼接到 fullPageImage；
• 从拼接后的图片重新生成每个已有的区域裁切图；
• 更新 manifest.json，写入 fullPageCaptureMethod: "stitchedViewportScreenshots"、视口、步幅、片段数量和修正后的裁切坐标。

实用选项：

--item 4              # repair only item 4, 1-based
--viewport 1440x1100 # default
--step 950           # default; use less than viewport height for overlap
--wait 2000          # ms to wait after each scroll stop
--quality 3          # ffmpeg JPEG quality, lower is better

验证

截图或修复后：

• 至少检查之前明显有问题的页面。
• 确认 sips -g pixelWidth -g pixelHeight full-page/*.jpg 报告的宽高尺寸符合预期。
• 确认整页图片并非大部分为空白，且包含页面下方的内容。
• 确认区域裁切坐标连续，并且终点与整页图片的高度一致。
• 运行项目的常规检查，例如：

git diff --check -- articles/YYYY-MM-DD-ui-inspiration-capture/content.md articles/YYYY-MM-DD-ui-inspiration-capture/manifest.json
node scripts/check-ui-inspiration-duplicates.mjs articles/YYYY-MM-DD-ui-inspiration-capture/manifest.json
for f in articles/YYYY-MM-DD-ui-inspiration-capture/videos/*.mp4; do ffprobe -v error "$f" >/dev/null; done

说明

• 滚动视频可以证明页面在实际滚动时能够正常渲染，但不能替代整页静态截图证据。
• 原生 fullPage 截图仍可保存为对比候选，但除非视觉效果与拼接截图一致，否则不要将其作为事实依据。
• 对于每日 UI 文章，请更新清单，并且只提交已修复文章的资源和元数据。