頁面類別

Page 提供方法與瀏覽器中的單個標籤頁或擴充功能背景頁面互動。

注意

一個 Browser 實例可能有多個 Page 實例。

簽名

export declare abstract class Page extends EventEmitter<PageEvents>

擴展： EventEmitter<PageEvents>

備註

此類別的建構函式標記為內部。第三方程式碼不應直接呼叫建構函式或建立擴展 Page 類別的子類別。

範例 1

此範例會建立一個頁面，將其導覽至 URL，然後儲存螢幕截圖

import puppeteer from 'puppeteer';

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await page.screenshot({path: 'screenshot.png'});
  await browser.close();
})();

Page 類別繼承自 Puppeteer 的 EventEmitter 類別，並將發出各種事件，這些事件記錄在 PageEvent 列舉中。

範例 2

此範例會記錄單個頁面 load 事件的訊息

page.once('load', () => console.log('Page loaded!'));

若要取消訂閱事件，請使用 EventEmitter.off() 方法

function logRequest(interceptedRequest) {
  console.log('A request was made:', interceptedRequest.url());
}
page.on('request', logRequest);
// Sometime later...
page.off('request', logRequest);

屬性

屬性	修飾詞	類型	描述
accessibility	唯讀	Accessibility	Accessibility 類別提供方法來檢查瀏覽器的可存取性樹狀結構。可存取性樹狀結構供輔助技術使用，例如螢幕閱讀器或切換器。 備註 可存取性是非常特定於平台的事物。在不同的平台上，有不同的螢幕閱讀器可能會有截然不同的輸出。 Blink - Chrome 的渲染引擎 - 有「可存取性樹狀結構」的概念，然後將其轉譯為不同的平台特定 API。Accessibility 命名空間讓使用者可以存取 Blink Accessibility Tree。 從 Blink AX Tree 轉換為平台特定 AX-Tree 或由輔助技術本身轉換時，大部分可存取性樹狀結構都會被篩選掉。預設情況下，Puppeteer 會嘗試近似此篩選，僅公開樹狀結構中「有趣」的節點。 此類別的建構函式標記為內部。第三方程式碼不應直接呼叫建構函式或建立擴展 Accessibility 類別的子類別。
coverage	唯讀	Coverage	Coverage 類別提供方法來收集有關頁面使用的 JavaScript 和 CSS 部分的資訊。 備註 若要以可供Istanbul 取用的形式輸出涵蓋範圍，請參閱 puppeteer-to-istanbul。 此類別的建構函式標記為內部。第三方程式碼不應直接呼叫建構函式或建立擴展 Coverage 類別的子類別。
keyboard	唯讀	Keyboard	Keyboard 提供用於管理虛擬鍵盤的 API。高階 API 是 Keyboard.type()，它會接收原始字元，並在您的頁面上產生正確的 keydown、keypress/input 和 keyup 事件。 備註 若要更精細的控制，您可以使用 Keyboard.down()、Keyboard.up() 和 Keyboard.sendCharacter() 來手動觸發事件，就像它們是從真實鍵盤產生的一樣。 在 macOS 上，鍵盤快速鍵（例如 ⌘ A -> 全選）不起作用。請參閱#1313。 此類別的建構函式標記為內部。第三方程式碼不應直接呼叫建構函式或建立擴展 Keyboard 類別的子類別。
mouse	唯讀	Mouse	Mouse 類別在相對於視窗左上角的 Main-Frame CSS 像素中運作。 備註 每個 page 物件都有自己的 Mouse，可透過 Page.mouse 存取。 此類別的建構函式標記為內部。第三方程式碼不應直接呼叫建構函式或建立擴展 Mouse 類別的子類別。
touchscreen	唯讀	Touchscreen	Touchscreen 類別會公開觸控螢幕事件。
tracing	唯讀	Tracing	Tracing 類別會公開追蹤稽核介面。 備註 您可以使用 tracing.start 和 tracing.stop 來建立追蹤檔，該檔案可以在 Chrome DevTools 或 時間軸檢視器中開啟。 此類別的建構函式標記為內部。第三方程式碼不應直接呼叫建構函式或建立擴展 Tracing 類別的子類別。

方法

方法	修飾詞	描述
$(selector)		尋找第一個符合選取器的元素。如果沒有元素符合選取器，則傳回值會解析為 null。 備註 Page.mainFrame().$(selector) 的捷徑。
$$(selector, options)		在頁面上尋找符合選取器的元素。如果沒有元素符合選取器，則傳回值會解析為 []。 備註 Page.mainFrame().$$(selector) 的捷徑。
$$eval(selector, pageFunction, args)		此方法會傳回所有符合選取器的元素，並將產生的陣列作為第一個引數傳遞給 pageFunction。 備註 如果 pageFunction 傳回 promise，則 $$eval 會等待 promise 解析，然後傳回其值。
$eval(selector, pageFunction, args)		此方法會在頁面中尋找第一個符合選取器的元素，並將結果作為第一個引數傳遞給 pageFunction。 備註 如果找不到符合 selector 的元素，則此方法會擲回錯誤。 如果 pageFunction 傳回 promise，則 $eval 會等待 promise 解析，然後傳回其值。
addScriptTag(options)		使用所需的 URL 或內容將 <script> 標籤新增至頁面。 備註 page.mainFrame().addScriptTag(options) 的捷徑。
addStyleTag(options)		使用所需的 URL 將 <link rel="stylesheet"> 標籤新增至頁面，或使用內容新增 <style type="text/css"> 標籤。 page.mainFrame().addStyleTag(options) 的捷徑。
addStyleTag(options)
authenticate(credentials)		提供 HTTP 驗證的憑證。 注意 會在幕後開啟請求攔截以實作驗證。這可能會影響效能。 備註 若要停用驗證，請傳遞 null。
bringToFront()		將頁面移至前景（啟用索引標籤）。
browser()		取得頁面所屬的瀏覽器。
browserContext()		取得頁面所屬的瀏覽器內容。
click(selector, options)		此方法會擷取具有 selector 的元素，並在需要時將其捲動至檢視區，然後使用 Page.mouse 在元素中心點擊。如果沒有符合 selector 的元素，則此方法會擲回錯誤。 備註 請記住，如果 click() 觸發導覽事件，並且有要解析的獨立 page.waitForNavigation() promise，您可能會遇到產生意外結果的競爭條件。點擊並等待導覽的正確模式如下 const [response] = await Promise.all([ page.waitForNavigation(waitOptions), page.click(selector, clickOptions), ]); page.mainFrame().click(selector[, options]) 的捷徑。
close(options)
content()		頁面的完整 HTML 內容，包括 DOCTYPE。
cookies(urls)	已過時	如果未指定 URL，則此方法會傳回目前頁面 URL 的 cookie。如果指定 URL，則只會傳回那些 URL 的 cookie。 已過時 頁面層級 cookie API 已過時。請改用 Browser.cookies() 或 BrowserContext.cookies()。
createCDPSession()		建立附加至頁面的 Chrome Devtools Protocol 會話。
createPDFStream(options)		使用 print CSS 媒體類型產生頁面的 PDF。 備註 若要使用 screen 媒體類型產生 PDF，請在呼叫 page.pdf() 之前呼叫 `page.emulateMediaType('screen')`。 依預設，page.pdf() 會產生具有修改列印顏色的 PDF。使用 `-webkit-print-color-adjust` 屬性來強制轉譯精確色彩。
deleteCookie(cookies)	已過時	已過時 頁面層級的 Cookie API 已被棄用。請改用 Browser.deleteCookie() 或 BrowserContext.deleteCookie()。
emulate(device)		模擬指定裝置的指標和使用者代理程式。 為了輔助模擬，Puppeteer 提供了一個已知裝置列表，可透過 KnownDevices 取得。 備註 此方法是呼叫兩個方法的捷徑：Page.setUserAgent() 和 Page.setViewport()。 此方法會調整頁面大小。許多網站不希望手機改變大小，因此您應該在導覽到頁面之前進行模擬。
emulateCPUThrottling(factor)		啟用 CPU 節流以模擬慢速 CPU。
emulateIdleState(overrides)		模擬閒置狀態。如果沒有設定任何引數，則會清除閒置狀態模擬。
emulateMediaFeatures(features)
emulateMediaType(type)
emulateNetworkConditions(networkConditions)		這不會影響 WebSockets 和 WebRTC PeerConnections (請參閱 https://crbug.com/563644)。若要將頁面設定為離線，您可以使用 Page.setOfflineMode()。 可以透過匯入 PredefinedNetworkConditions 來使用預定義的網路條件列表。
emulateTimezone(timezoneId)
emulateVisionDeficiency(type)		在頁面上模擬給定的視力缺陷。
evaluate(pageFunction, args)		在頁面的內容中評估一個函式，並傳回結果。 如果傳遞給 page.evaluate 的函式傳回 Promise，則該函式將等待 Promise 解析並傳回其值。
evaluateHandle(pageFunction, args)		備註 page.evaluate 和 page.evaluateHandle 之間的唯一區別在於，evaluateHandle 將傳回包裝在頁面內物件中的值。 如果傳遞給 page.evaluateHandle 的函式傳回 Promise，則該函式將等待 Promise 解析並傳回其值。 您可以傳遞字串而不是函式（雖然建議使用函式，因為它們更容易偵錯並與 TypeScript 搭配使用）
evaluateOnNewDocument(pageFunction, args)		新增一個函式，該函式將在下列情況之一中被呼叫 每當頁面被導覽時 每當附加或導覽子框架時。在這種情況下，函式會在新附加框架的內容中被呼叫。 函式會在文件建立後但在執行任何指令碼之前被呼叫。這對於修改 JavaScript 環境很有用，例如，播種 Math.random。
exposeFunction(name, pptrFunction)		此方法會在頁面的 window 物件上新增一個名為 name 的函式。當被呼叫時，該函式會在 node.js 中執行 puppeteerFunction，並傳回一個 Promise，該 Promise 會解析為 puppeteerFunction 的傳回值。 如果 puppeteerFunction 傳回 Promise，則會等待它。 注意 透過 page.exposeFunction 安裝的函式會在導覽中存留。
focus(selector)		此方法會擷取具有 selector 的元素並將其聚焦。如果沒有符合 selector 的元素，則該方法會擲回錯誤。 備註 page.mainFrame().focus(selector) 的捷徑。
frames()		附加到頁面的所有框架的陣列。
getDefaultNavigationTimeout()		最大導覽時間（以毫秒為單位）。
getDefaultTimeout()		最大時間（以毫秒為單位）。
goBack(options)		此方法會導覽至歷史記錄中的前一個頁面。
goForward(options)		此方法會導覽至歷史記錄中的下一個頁面。
goto(url, options)		將框架或頁面導覽至給定的 url。 備註 導覽至 about:blank 或導覽至具有不同雜湊的相同 URL 將會成功並傳回 null。 警告 無頭殼模式不支援導覽至 PDF 文件。請參閱上游問題。 在無頭殼中，當遠端伺服器傳回任何有效的 HTTP 狀態碼（包括 404「找不到」和 500「內部伺服器錯誤」）時，此方法不會擲回錯誤。可以透過呼叫 HTTPResponse.status() 來擷取此類回應的狀態碼。
hover(selector)		此方法會擷取具有 selector 的元素，根據需要將其捲動到檢視區中，然後使用 Page.mouse 將滑鼠游標暫留在元素的中心上方。如果沒有符合 selector 的元素，則該方法會擲回錯誤。 備註 page.mainFrame().hover(selector) 的捷徑。
isClosed()		表示頁面已關閉。
isDragInterceptionEnabled()	已過時	如果正在攔截拖曳事件，則為 true，否則為 false。 已過時 我們不再支援攔截拖曳酬載。請使用 ElementHandle 上新的拖曳 API 來拖曳（或只使用 Page.mouse）。
isJavaScriptEnabled()		如果頁面已啟用 JavaScript，則為 true，否則為 false。
isServiceWorkerBypassed()		如果正在繞過 Service Worker，則為 true，否則為 false。
locator(selector)		為提供的選取器建立定位器。請參閱 Locator 以了解詳細資訊和支援的動作。
locator(func)		為提供的函式建立定位器。請參閱 Locator 以了解詳細資訊和支援的動作。
mainFrame()		頁面的主框架。
metrics()		包含以鍵/值組形式呈現的指標物件。 備註 所有時間戳記都採用單調時間：自過去任意點起單調遞增的時間（以秒為單位）。
pdf(options)		使用 print CSS 媒體類型產生頁面的 PDF。 備註 若要使用 screen 媒體類型產生 PDF，請在呼叫 page.pdf() 之前呼叫 `page.emulateMediaType('screen')`。 依預設，page.pdf() 會產生具有修改列印顏色的 PDF。使用 `-webkit-print-color-adjust` 屬性來強制轉譯精確色彩。
queryObjects(prototypeHandle)		此方法會迭代 JavaScript 堆積並尋找具有給定原型物件的所有物件。
reload(options)		重新載入頁面。
removeExposedFunction(name)		此方法會從頁面的 window 物件中移除先前透過 $Page.exposeFunction() 新增的函式（名為 name）。
removeScriptToEvaluateOnNewDocument(identifier)		移除透過 Page.evaluateOnNewDocument 插入到頁面的指令碼。
screencast(options)		(實驗性) 擷取此 頁面的螢幕錄影。 備註 所有錄製內容都將使用 WebM 格式，並使用 VP9 影片編解碼器。FPS 為 30。 您的系統上必須安裝 ffmpeg。
screenshot(options)		擷取此 頁面的螢幕快照。 備註 在 BrowserContext 中擷取螢幕快照時，下列方法會自動等待螢幕快照完成，以防止干擾螢幕快照程序：BrowserContext.newPage()、Browser.newPage()、Page.close()。 呼叫 Page.bringToFront() 不會等待現有的螢幕快照作業。
screenshot(options)
select(selector, values)		一旦選取了所有提供的選項，就會觸發 change 和 input 事件。如果沒有符合 selector 的 <select> 元素，則該方法會擲回錯誤。 備註 page.mainFrame().select() 的捷徑
setBypassCSP(enabled)		切換繞過頁面的內容安全性原則。 備註 注意：CSP 繞過發生在 CSP 初始化時，而不是評估時。通常，這表示應在導覽至網域之前呼叫 page.setBypassCSP。
setBypassServiceWorker(bypass)		切換是否忽略每個要求的 Service Worker。
setCacheEnabled(enabled)		根據啟用狀態，切換是否忽略每個要求的快取。預設情況下，會啟用快取。
setContent(html, options)		設定頁面的內容。
setCookie(cookies)	已過時	已過時 頁面層級的 Cookie API 已被棄用。請改用 Browser.setCookie() 或 BrowserContext.setCookie()。
setDefaultNavigationTimeout(timeout)		此設定將變更以下方法和相關捷徑的預設最大導覽時間 page.goBack(options) page.goForward(options) page.goto(url,options) page.reload(options) page.setContent(html,options) page.waitForNavigation(options)
setDefaultTimeout(timeout)
setDragInterception(enabled)	已過時	已過時 我們不再支援攔截拖曳酬載。請使用 ElementHandle 上新的拖曳 API 來拖曳（或只使用 Page.mouse）。
setExtraHTTPHeaders(headers)		額外的 HTTP 標頭將會與頁面起始的每個要求一起傳送。 提示 所有 HTTP 標頭名稱都為小寫。（HTTP 標頭不區分大小寫，因此這不應影響您的伺服器程式碼。） 注意 page.setExtraHTTPHeaders 不保證外送要求中標頭的順序。
setGeolocation(options)		設定頁面的地理位置。 備註 請考慮使用 BrowserContext.overridePermissions() 來授與頁面讀取其地理位置的權限。
setJavaScriptEnabled(enabled)		備註 注意：變更此值不會影響已執行的指令碼。它會在下次導覽時完全生效。
setOfflineMode(enabled)		將網路連線設定為離線。 它不會變更 Page.emulateNetworkConditions() 中使用的參數
setRequestInterception(value)		啟用要求攔截會啟用 HTTPRequest.abort()、HTTPRequest.continue() 和 HTTPRequest.respond() 方法。這提供了修改頁面發出的網路要求的功能。 一旦啟用要求攔截，除非繼續、回應或中止每個要求；或使用瀏覽器快取完成，否則每個要求都會停滯。 請參閱 要求攔截指南以了解更多詳細資訊。
setUserAgent(userAgent, userAgentMetadata)
setViewport(viewport)		page.setViewport 會調整頁面大小。許多網站不希望手機改變大小，因此您應該在導覽至頁面之前設定檢視區。 在單一瀏覽器中有多個頁面的情況下，每個頁面都可以有自己的檢視區大小。將檢視區設定為 null 會將檢視區重設為其預設值。 備註 注意：在某些情況下，設定 viewport 會重新載入頁面，以便設定 isMobile 或 hasTouch 屬性。
tap(selector)		此方法會取得符合 selector 的元素，如果需要，會將其滾動到可見範圍，然後使用 Page.touchscreen 在元素的中心點擊。如果沒有任何元素符合 selector，此方法會拋出錯誤。 備註 是 page.mainFrame().tap(selector) 的快捷方式。
target()	已過時	此頁面從哪個目標建立的。 已過時 直接使用 Page.createCDPSession()。
title()		頁面的標題。 備註 是 page.mainFrame().title() 的快捷方式。
type(selector, text, options)		針對文字中的每個字元發送一個 keydown、keypress/input 和 keyup 事件。 若要按下特殊按鍵，例如 Control 或 ArrowDown，請使用 Keyboard.press()。
url()		頁面的 URL。 備註 是 page.mainFrame().url() 的快捷方式。
viewport()		返回當前頁面的 viewport 設定，而不檢查實際的頁面 viewport。 這可能是上次使用 Page.setViewport() 設定的 viewport，或是透過 ConnectOptions.defaultViewport 設定的預設 viewport。
waitForDevicePrompt(options)		此方法通常與觸發來自 API（例如 WebBluetooth）裝置請求的動作搭配使用。 注意 必須在提出裝置請求之前呼叫此方法。它不會返回目前作用中的裝置提示。
waitForFileChooser(options)		此方法通常與觸發檔案選擇的動作搭配使用。 注意 必須在啟動檔案選擇器之前呼叫此方法。它不會返回目前作用中的檔案選擇器。 注意 目前不支援攔截透過 DOM API（例如 window.showOpenFilePicker）觸發的檔案對話方塊。 備註 在「有頭」瀏覽器中，此方法會導致原生檔案選擇器對話方塊 不顯示 給使用者。
waitForFrame(urlOrPredicate, options)		等待符合指定條件的框架出現。
waitForFunction(pageFunction, options, args)		等待提供的函式 pageFunction 在頁面內容中求值時返回 truthy 值。
waitForNavigation(options)		等待頁面導航到新的 URL 或重新載入。當您執行會間接導致頁面導航的程式碼時，此方法很有用。 備註 使用 History API 變更 URL 會被視為導航。
waitForNetworkIdle(options)		等待網路閒置。
waitForRequest(urlOrPredicate, options)		備註 可選的等待參數有： timeout：最大等待時間（以毫秒為單位），預設值為 30 秒，傳遞 0 以停用逾時。可以使用 Page.setDefaultTimeout() 方法變更預設值。
waitForResponse(urlOrPredicate, options)		備註 可選參數有： timeout：最大等待時間（以毫秒為單位），預設值為 30 秒，傳遞 0 以停用逾時。可以使用 Page.setDefaultTimeout() 方法變更預設值。
waitForSelector(selector, options)		等待 selector 出現在頁面中。如果在呼叫此方法時 selector 已經存在，此方法會立即返回。如果等待 timeout 毫秒後 selector 沒有出現，函式會拋出錯誤。 備註 引數 options 中的可選參數為： visible：布林值，等待元素出現在 DOM 中且可見，即不具有 display: none 或 visibility: hidden CSS 屬性。預設值為 false。 hidden：等待在 DOM 中找不到元素或元素被隱藏，即具有 display: none 或 visibility: hidden CSS 屬性。預設值為 false。 timeout：最大等待時間（以毫秒為單位）。預設值為 30000（30 秒）。傳遞 0 以停用逾時。可以使用 Page.setDefaultTimeout() 方法變更預設值。
workers()		所有與頁面相關聯的專用 WebWorkers。 備註 這不包含 ServiceWorkers。