Puppeteer 页面

class: Page v0.9.0

Page 提供操作一个 tab 页或者 extension background page 的方法。一个 Browser 实例可以有多个 Page 实例。下面的例子创建一个 Page 实例，导航到一个 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会触发多种事件（下面描述的），可以用 node原生的方法来捕获处理，比如 on,once 或者 removeListener。下面的例子捕获了一个 page 实例的 load 事件，打印了一句话：

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

可以用 removeListener 取消对事件的监听：

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 当页面关闭时触发。

page.on('console') v0.9.0 <ConsoleMessage> 当页面js代码调用了 console 的某个方法，比如 console.log，或者 console.dir 的时候触发。（如果不监听这个事件，js源码的console语句不会输出）。当页面抛出一个错误或者经过的时候也会触发。 js源码中传给 console.log 的参数，会传给 console 事件的监听器。一个监听 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'})); 
// 这个代码表示在页面实例中执行了console.log。如果没有监听console事件，这里的输出不会出现在你的控制台

page.on('dialog') v0.9.0

<Dialog> 当js对话框出现的时候触发，比如alert, prompt, confirm 或者 beforeunload。Puppeteer可以通过Dialog's accept 或者 dismiss来响应弹窗。

page.on('domcontentloaded') v0.9.0 当页面的 DOMContentLoaded事件被触发时触发。

page.on('error') v0.9.0 <Error> 当页面崩溃时触发。注意error 在 node 中有特殊的意义, 点击 error events 查看详情。

page.on('frameattached') v0.9.0 <Frame> 当 iframe 加载的时候触发。

page.on('framedetached') v0.9.0 <Frame> 当 iframe 从页面移除的时候触发。

page.on('framenavigated') v0.9.0 <Frame> 当 iframe 导航到新的 url 时触发。

page.on('load') v0.9.0 当页面的 load 事件被触发时触发。

page.on('metrics') v0.9.0 <Object> title <string> 传给 console.timeStamp 方法的title参数。 metrics <Object> 包含度量对象的键值对，值是<number>类型当页面js代码调用了 console.timeStamp 方法时触发。page.metrics 章节有描述所有的 metrics。

page.on('pageerror') v0.9.0 <Error> 异常信息当发生页面js代码没有捕获的异常时触发。

page.on('request') v0.9.0 <Request> 当页面发送一个请求时触发。参数 request 对象是只读的。如果需要拦截并且改变请求，参考 page.setRequestInterception 章节。

page.on('requestfailed') v0.9.0 <Request> 当页面的请求失败时触发。比如某个请求超时了。

page.on('requestfinished') v0.9.0 <Request> 当页面的某个请求成功完成时触发。

page.on('response') v0.9.0 <Response> 当页面的某个请求接收到对应的 response 时触发。

page.on('workercreated') v0.9.0 <Worker> 当页面生成相应的 WebWorker 时触发。

page.on('workerdestroyed') v0.9.0 <Worker> 当页面终止相应的 WebWorker 时触发。

Methods

page.$(selector)v0.9.0

selector <string> 选择器返回: <Promise<?ElementHandle>>

此方法在页面内执行 document.querySelector。如果没有元素匹配指定选择器，返回值是 null。

page.mainFrame().$(selector) 的简写。

page.$$(selector)v0.9.0

selector <string> 选择器返回: <Promise<Array<ElementHandle>>>

此方法在页面内执行 document.querySelector。如果没有元素匹配指定选择器，返回值是 null。 page.mainFrame().$(selector) 的简写。

page.$$(selector)v0.9.0

selector <string> 选择器
返回: <Promise<Array<ElementHandle>>>

此方法在页面内执行 document.querySelectorAll。如果没有元素匹配指定选择器，返回值是 []。

page.mainFrame().$$(selector) 的简写。

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

selector <string> 一个框架选择器
pageFunction <function> 在浏览器实例上下文中要执行的方法
...args <...Serializable|JSHandle> 要传给 pageFunction 的参数。（比如你的代码里生成了一个变量，在页面中执行方法时需要用到，可以通过这个 args 传进去）
返回: <Promise<Serializable>> Promise对象，完成后是 pageFunction 的返回值

此方法在页面内执行 Array.from(document.querySelectorAll(selector))，然后把匹配到的元素数组作为第一个参数传给 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> 在浏览器实例上下文中要执行的方法
...args <...Serializable|JSHandle> 要传给 pageFunction 的参数。（比如你的代码里生成了一个变量，在页面中执行方法时需要用到，可以通过这个 args 传进去）
返回: <Promise<Serializable>> Promise对象，完成后是 pageFunction 的返回值

此方法在页面内执行 document.querySelector，然后把匹配到的元素作为第一个参数传给 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表达式，参考： evaluate. 返回: <Promise<Array<ElementHandle>>> 此方法解析指定的XPath表达式。 page.mainFrame().$x(expression) 的简写。

page.addScriptTag(options)v0.9.0

options <Object> url <string> 要添加的script的src path <string> 要注入frame的js文件路径. 如果 path 是相对路径, 那么相对当前路径解析。 content <string> 要注入页面的js代码（即content） type <string> 脚本类型。如果要注入 ES6 module，值为'module'。点击 script 查看详情。返回: <Promise<ElementHandle>> Promise对象，即注入完成的tag标签。当 script 的 onload 触发或者代码被注入到 frame。

注入一个指定src(url)或者代码(content)的 script 标签到当前页面。 page.mainFrame().addScriptTag(options) 的简写。

page.addStyleTag(options)v0.9.0 options <Object> url <string> link标签的href属性值 path <string> 样式文件的路径. 如果path 是相对路径,那么相对当前路径解析。 content <string> css代码（即content）返回: <Promise<ElementHandle>> Promise对象，即注入完成的tag标签。当style的onload触发或者代码被注入到frame。添加一个指定link(url)的 <link rel="stylesheet"> 标签。或者添加一个指定代码(content)的 <style type="text/css"> 标签。 page.mainFrame().addStyleTag(options) 的简写。

page.authenticate(credentials)v0.9.0

credentials <?Object>
- username <string>
- password <string>
返回: <Promise> 为HTTP authentication 提供认证凭据。传 null 禁用认证。

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

相当于多个tab时，切换到某个tab。

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

得到当前 page 实例所属的 browser 实例。

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

selector <string> 要点击的元素的选择器。如果有多个匹配的元素, 点击第一个。
options <Object>
- button <string> left, right, 或者 middle, 默认是 left。
clickCount <number> 默认是 1. 查看 UIEvent.detail。
- delay <number> mousedown 和 mouseup 之间停留的时间，单位是毫秒。默认是0
返回: <Promise> Promise对象，匹配的元素被点击。如果没有元素被点击，Promise对象将被rejected。

此方法找到一个匹配 selector 选择器的元素，如果需要会把此元素滚动到可视，然后通过 page.mouse 点击它。如果选择器没有匹配任何元素，此方法将会报错。要注意如果 click() 触发了一个跳转，会有一个独立的 page.waitForNavigation() Promise对象需要等待。正确的等待点击后的跳转是这样的：

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> 默认 false. 是否执行 before unload
返回: <Promise>
page.close() 在 beforeunload 处理之前默认不执行
注意 如果 runBeforeUnload 设置为true，可能会弹出一个 beforeunload 对话框。 这个对话框需要通过页面的 'dialog' 事件手动处理。




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