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 像素描述頁面佈局；捕獲的 PNG 像素在高 DPI 顯示器上可能會更密集。編輯器隨後從第一個捕獲的切片中導出固有像素比，以便 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 時，請在螢幕截圖旁保留更強大的來源。

目前的管道是故意限制的：測量、在實際位置捕獲、僅重試已知的限制、恢復頁面、本地組裝，並要求用戶檢查輸出。這些界限使得長頁面捕獲變得易於理解和可重複。