Puppeteer 頁面

class: Page v0.9.0

Page 提供操作一個 tab 頁或者 extension background page 的方法。一個 Browser 實例可以有多個 Page 實例。 下面的例子創(chuàng)建一個 Page 實例，導(dǎo)航到一個 url ，然后保存截圖：

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

Page會觸發(fā)多種事件（下面描述的），可以用 node原生的方法 來捕獲處理，比如 on,once 或者 removeListener。 下面的例子捕獲了一個 page 實例的 load 事件，打印了一句話：

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

可以用 removeListener 取消對事件的監(jiān)聽：

function logRequest(interceptedRequest) {
    console.log('A request was made:', interceptedRequest.url());
}
page.on('request', logRequest); // 一段時間后...page.removeListener('request', logRequest);

Events

• page.on('close')v0.9.0
• page.on('console')v0.9.0
• page.on('dialog')v0.9.0
• page.on('domcontentloaded')v0.9.0
• page.on('error')v0.9.0
• page.on('frameattached')v0.9.0
• page.on('framedetached')v0.9.0
• page.on('framenavigated')v0.9.0
• page.on('load')v0.9.0
• page.on('metrics')v0.9.0
• page.on('pageerror')v0.9.0
• page.on('request')v0.9.0
• page.on('requestfailed')v0.9.0
• page.on('requestfinished')v0.9.0
• page.on('response')v0.9.0
• page.on('workercreated')v0.9.0
• page.on('workerdestroyed')v0.9.0

Namespaces

• page.accessibilityv0.9.0
• page.coveragev0.9.0
• page.keyboardv0.9.0
• page.mousev0.9.0
• page.touchscreenv0.9.0
• page.tracingv0.9.0

• Methods
• page.$(selector)v0.9.0
• page.$$(selector)v0.9.0
• page.$$eval(selector, pageFunction[, ...args])v0.9.0
• page.$eval(selector, pageFunction[, ...args])v0.9.0
• page.$x(expression)v0.9.0
• page.addScriptTag(options)v0.9.0
• page.addStyleTag(options)v0.9.0
• page.authenticate(credentials)v0.9.0
• page.bringToFront()v0.9.0
• page.browser()v0.9.0
• page.click(selector[, options])v0.9.0
• page.close([options])v0.9.0
• page.content()v0.9.0
• page.cookies([...urls])v0.9.0
• page.deleteCookie(...cookies)v0.9.0
• page.emulate(options)v0.9.0
• page.emulateMedia(mediaType)v0.9.0
• page.evaluate(pageFunction[, ...args])v0.9.0
• page.evaluateHandle(pageFunction[, ...args])v0.9.0
• page.evaluateOnNewDocument(pageFunction[, ...args])v0.9.0
• page.exposeFunction(name, puppeteerFunction)v0.9.0
• page.focus(selector)v0.9.0
• page.frames()v0.9.0
• page.goBack([options])v0.9.0
• page.goForward([options])v0.9.0
• page.goto(url[, options])v0.9.0
• page.hover(selector)v0.9.0
• page.isClosed()v0.9.0
• page.mainFrame()v0.9.0
• page.metrics()v0.9.0
• page.pdf([options])v0.9.0
• page.queryObjects(prototypeHandle)v0.9.0
• page.reload([options])v0.9.0
• page.screenshot([options])v0.9.0
• page.select(selector, ...values)v0.9.0
• page.setBypassCSP(enabled)v0.9.0
• page.setCacheEnabled([enabled])v0.9.0
• page.setContent(html[, options])v0.9.0
• page.setCookie(...cookies)v0.9.0
• page.setDefaultNavigationTimeout(timeout)v0.9.0
• page.setExtraHTTPHeaders(headers)v0.9.0
• page.setGeolocation(options)v0.9.0
• page.setJavaScriptEnabled(enabled)v0.9.0
• page.setOfflineMode(enabled)v0.9.0
• page.setRequestInterception(value)v0.9.0
• page.setUserAgent(userAgent)v0.9.0
• page.setViewport(viewport)v0.9.0
• page.tap(selector)v0.9.0
• page.target()v0.9.0
• page.title()v0.9.0
• page.type(selector, text[, options])v0.9.0
• page.url()v0.9.0
• page.viewport()v0.9.0
• page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])v0.9.0
• page.waitForFunction(pageFunction[, options[, ...args]])v0.9.0
• page.waitForNavigation([options])v0.9.0
• page.waitForRequest(urlOrPredicate[, options])v0.9.0
• page.waitForResponse(urlOrPredicate[, options])v0.9.0
• page.waitForSelector(selector[, options])v0.9.0
• page.waitForXPath(xpath[, options])v0.9.0
• page.workers()v0.9.0-

NameSpaces

page.accessibilityv0.9.0 returns: <Accessibility>

page.coveragev0.9.0 returns: <Coverage>

page.keyboardv0.9.0 returns: <Keyboard>

page.mousev0.9.0 returns: <Mouse>

page.touchscreenv0.9.0 returns: <Touchscreen>

page.tracingv0.9.0 returns: <Tracing>

Events

page.on('close') v0.9.0 當(dāng)頁面關(guān)閉時觸發(fā)。

page.on('console') v0.9.0 <ConsoleMessage> 當(dāng)頁面js代碼調(diào)用了 console 的某個方法，比如 console.log，或者 console.dir 的時候觸發(fā)。（如果不監(jiān)聽這個事件，js源碼的console語句不會輸出）。當(dāng)頁面拋出一個錯誤或者經(jīng)過的時候也會觸發(fā)。 js源碼中傳給 console.log 的參數(shù)，會傳給 console 事件的監(jiān)聽器。 一個監(jiān)聽 console 事件的例子：

page.on('console', msg => {  for (let i = 0; i < msg.args().length; ++i)    
console.log(`${i}: ${msg.args()[i]}`); // 譯者注：這句話的效果是打印到你的代碼的控制臺});
page.evaluate(() => console.log('hello', 5, {foo: 'bar'})); 
// 這個代碼表示在頁面實例中執(zhí)行了console.log。如果沒有監(jiān)聽console事件，這里的輸出不會出現(xiàn)在你的控制臺

page.on('dialog') v0.9.0

<Dialog> 當(dāng)js對話框出現(xiàn)的時候觸發(fā)，比如alert, prompt, confirm 或者 beforeunload。Puppeteer可以通過Dialog's accept 或者 dismiss來響應(yīng)彈窗。

page.on('domcontentloaded') v0.9.0 當(dāng)頁面的 DOMContentLoaded事件被觸發(fā)時觸發(fā)。

page.on('error') v0.9.0 <Error> 當(dāng)頁面崩潰時觸發(fā)。 注意error 在 node 中有特殊的意義, 點擊 error events 查看詳情。

page.on('frameattached') v0.9.0 <Frame> 當(dāng) iframe 加載的時候觸發(fā)。

page.on('framedetached') v0.9.0 <Frame> 當(dāng) iframe 從頁面移除的時候觸發(fā)。

page.on('framenavigated') v0.9.0 <Frame> 當(dāng) iframe 導(dǎo)航到新的 url 時觸發(fā)。

page.on('load') v0.9.0 當(dāng)頁面的 load 事件被觸發(fā)時觸發(fā)。

page.on('metrics') v0.9.0 <Object> title <string> 傳給 console.timeStamp 方法的title參數(shù)。 metrics <Object> 包含度量對象的鍵值對，值是<number>類型 當(dāng)頁面js代碼調(diào)用了 console.timeStamp 方法時觸發(fā)。page.metrics 章節(jié)有描述所有的 metrics。

page.on('pageerror') v0.9.0 <Error> 異常信息 當(dāng)發(fā)生頁面js代碼沒有捕獲的異常時觸發(fā)。

page.on('request') v0.9.0 <Request> 當(dāng)頁面發(fā)送一個請求時觸發(fā)。參數(shù) request 對象是只讀的。 如果需要攔截并且改變請求，參考 page.setRequestInterception 章節(jié)。

page.on('requestfailed') v0.9.0 <Request> 當(dāng)頁面的請求失敗時觸發(fā)。比如某個請求超時了。

page.on('requestfinished') v0.9.0 <Request> 當(dāng)頁面的某個請求成功完成時觸發(fā)。

page.on('response') v0.9.0 <Response> 當(dāng)頁面的某個請求接收到對應(yīng)的 response 時觸發(fā)。

page.on('workercreated') v0.9.0 <Worker> 當(dāng)頁面生成相應(yīng)的 WebWorker 時觸發(fā)。

page.on('workerdestroyed') v0.9.0 <Worker> 當(dāng)頁面終止相應(yīng)的 WebWorker 時觸發(fā)。

Methods

page.$(selector)v0.9.0

selector <string> 選擇器 返回: <Promise<?ElementHandle>>

此方法在頁面內(nèi)執(zhí)行 document.querySelector。如果沒有元素匹配指定選擇器，返回值是 null。

page.mainFrame().$(selector) 的簡寫。

page.$$(selector)v0.9.0

selector <string> 選擇器 返回: <Promise<Array<ElementHandle>>>

此方法在頁面內(nèi)執(zhí)行 document.querySelector。如果沒有元素匹配指定選擇器，返回值是 null。 page.mainFrame().$(selector) 的簡寫。

page.$$(selector)v0.9.0

• selector <string> 選擇器
• 返回: <Promise<Array<ElementHandle>>>

此方法在頁面內(nèi)執(zhí)行 document.querySelectorAll。如果沒有元素匹配指定選擇器，返回值是 []。

page.mainFrame().$$(selector) 的簡寫。

page.$$eval(selector, pageFunction[, ...args])v0.9.0

• selector <string> 一個框架選擇器
• pageFunction <function> 在瀏覽器實例上下文中要執(zhí)行的方法
• ...args <...Serializable|JSHandle> 要傳給 pageFunction 的參數(shù)。（比如你的代碼里生成了一個變量，在頁面中執(zhí)行方法時需要用到，可以通過這個 args 傳進去）
• 返回: <Promise<Serializable>> Promise對象，完成后是 pageFunction 的返回值

此方法在頁面內(nèi)執(zhí)行 Array.from(document.querySelectorAll(selector))，然后把匹配到的元素數(shù)組作為第一個參數(shù)傳給 pageFunction。 如果 pageFunction 返回的是 Promise，那么此方法會等 promise 完成后返回其返回值。 示例:

const divsCounts = await page.$$eval('div', divs => divs.length);

page.$eval(selector, pageFunction[, ...args])v0.9.0

• selector <string> 選擇器 pageFunction <function> 在瀏覽器實例上下文中要執(zhí)行的方法
• ...args <...Serializable|JSHandle> 要傳給 pageFunction 的參數(shù)。（比如你的代碼里生成了一個變量，在頁面中執(zhí)行方法時需要用到，可以通過這個 args 傳進去）
• 返回: <Promise<Serializable>> Promise對象，完成后是 pageFunction 的返回值

此方法在頁面內(nèi)執(zhí)行 document.querySelector，然后把匹配到的元素作為第一個參數(shù)傳給 pageFunction。 如果 pageFunction 返回的是 Promise，那么此方法會等 promise 完成后返回其返回值。 示例:

const searchValue = await page.$eval('#search', el => el.value);
const preloadHref = await page.$eval('link[rel=preload]', el => el.href);
const html = await page.$eval('.main-container', e => e.outerHTML);

page.mainFrame().$eval(selector, pageFunction) 的簡寫。

page.$x(expression)v0.9.0 expression <string> XPath表達(dá)式，參考： evaluate. 返回: <Promise<Array<ElementHandle>>> 此方法解析指定的XPath表達(dá)式。 page.mainFrame().$x(expression) 的簡寫。

page.addScriptTag(options)v0.9.0

options <Object> url <string> 要添加的script的src path <string> 要注入frame的js文件路徑. 如果 path 是相對路徑, 那么相對 當(dāng)前路徑 解析。 content <string> 要注入頁面的js代碼（即content） type <string> 腳本類型。 如果要注入 ES6 module，值為'module'。點擊 script 查看詳情。 返回: <Promise<ElementHandle>> Promise對象，即注入完成的tag標(biāo)簽。當(dāng) script 的 onload 觸發(fā)或者代碼被注入到 frame。

注入一個指定src(url)或者代碼(content)的 script 標(biāo)簽到當(dāng)前頁面。 page.mainFrame().addScriptTag(options) 的簡寫。

page.addStyleTag(options)v0.9.0 options <Object> url <string> link標(biāo)簽的href屬性值 path <string> 樣式文件的路徑. 如果path 是相對路徑,那么相對 當(dāng)前路徑解析。 content <string> css代碼（即content） 返回: <Promise<ElementHandle>> Promise對象，即注入完成的tag標(biāo)簽。當(dāng)style的onload觸發(fā)或者代碼被注入到frame。 添加一個指定link(url)的 <link rel="stylesheet"> 標(biāo)簽。 或者添加一個指定代碼(content)的 <style type="text/css"> 標(biāo)簽。 page.mainFrame().addStyleTag(options) 的簡寫。

page.authenticate(credentials)v0.9.0

• credentials <?Object>
  • username <string>
  • password <string>
• 返回: <Promise> 為HTTP authentication 提供認(rèn)證憑據(jù) 。 傳 null 禁用認(rèn)證。

page.bringToFront()v0.9.0 returns: <Promise>

相當(dāng)于多個tab時，切換到某個tab。

page.browser()v0.9.0 returns: <Browser>

得到當(dāng)前 page 實例所屬的 browser 實例。

page.click(selector[, options])v0.9.0

• selector <string> 要點擊的元素的選擇器。 如果有多個匹配的元素, 點擊第一個。
• options <Object>
  • button <string> left, right, 或者 middle, 默認(rèn)是 left。
• clickCount <number> 默認(rèn)是 1. 查看 UIEvent.detail。
  • delay <number> mousedown 和 mouseup 之間停留的時間，單位是毫秒。默認(rèn)是0
• 返回: <Promise> Promise對象，匹配的元素被點擊。 如果沒有元素被點擊，Promise對象將被rejected。

此方法找到一個匹配 selector 選擇器的元素，如果需要會把此元素滾動到可視，然后通過 page.mouse 點擊它。 如果選擇器沒有匹配任何元素，此方法將會報錯。 要注意如果 click() 觸發(fā)了一個跳轉(zhuǎn)，會有一個獨立的 page.waitForNavigation() Promise對象需要等待。 正確的等待點擊后的跳轉(zhuǎn)是這樣的：

const [response] = await Promise.all([  page.waitForNavigation(waitOptions),  page.click(selector, clickOptions),]);
page.mainFrame().click(selector[, options]) 的簡寫。


page.close([options])v0.9.0
options <Object> 
runBeforeUnload <boolean> 默認(rèn) false. 是否執(zhí)行 before unload
返回: <Promise>
page.close() 在 beforeunload 處理之前默認(rèn)不執(zhí)行
注意 如果 runBeforeUnload 設(shè)置為true，可能會彈出一個 beforeunload 對話框。 這個對話框需要通過頁面的 'dialog' 事件手動處理。




page.content()v0.9.0
returns: <Promise<string>>