weixin_34021089
weixin_34021089

Puppeteer v1.5.0 中文翻译

最近用到了 Puppeteer 这个库，既然用到了这个东西，顺便也就把它的 API给看了一遍，为了加深印象，在看的同时也就顺便翻译了一下，不过这API文档的内容量还是蛮大的，花费了好些时间才看完，有些地方不知道怎么翻译比较好，所以也就没翻译，有的地方可能官方说得不怎么详细，我也加了一点主观意见。

Table of Contents
  • Overview
  • Environment Variables
  • class: Puppeteer
    • puppeteer.connect(options)
    • puppeteer.createBrowserFetcher([options])
    • puppeteer.defaultArgs()
    • puppeteer.executablePath()
    • puppeteer.launch([options])
  • class: BrowserFetcher
    • browserFetcher.canDownload(revision)
    • browserFetcher.download(revision[, progressCallback])
    • browserFetcher.localRevisions()
    • browserFetcher.platform()
    • browserFetcher.remove(revision)
    • browserFetcher.revisionInfo(revision)
  • class: Browser
    • event: 'disconnected'
    • event: 'targetchanged'
    • event: 'targetcreated'
    • event: 'targetdestroyed'
    • browser.browserContexts()
    • browser.close()
    • browser.createIncognitoBrowserContext()
    • browser.disconnect()
    • browser.newPage()
    • browser.pages()
    • browser.process()
    • browser.targets()
    • browser.userAgent()
    • browser.version()
    • browser.wsEndpoint()
  • class: BrowserContext
    • event: 'targetchanged'
    • event: 'targetcreated'
    • event: 'targetdestroyed'
    • browserContext.browser()
    • browserContext.close()
    • browserContext.isIncognito()
    • browserContext.newPage()
    • browserContext.targets()
  • class: Page
    • event: 'close'
    • event: 'console'
    • event: 'dialog'
    • event: 'domcontentloaded'
    • event: 'error'
    • event: 'frameattached'
    • event: 'framedetached'
    • event: 'framenavigated'
    • event: 'load'
    • event: 'metrics'
    • event: 'pageerror'
    • event: 'request'
    • event: 'requestfailed'
    • event: 'requestfinished'
    • event: 'response'
    • event: 'workercreated'
    • event: 'workerdestroyed'
    • page.$(selector)
    • page.$$(selector)
    • page.$$eval(selector, pageFunction[, ...args])
    • page.$eval(selector, pageFunction[, ...args])
    • page.$x(expression)
    • page.addScriptTag(options)
    • page.addStyleTag(options)
    • page.authenticate(credentials)
    • page.bringToFront()
    • page.browser()
    • page.click(selector[, options])
    • page.close(options)
    • page.content()
    • page.cookies(...urls)
    • page.coverage
    • page.deleteCookie(...cookies)
    • page.emulate(options)
    • page.emulateMedia(mediaType)
    • page.evaluate(pageFunction, ...args)
    • page.evaluateHandle(pageFunction, ...args)
    • page.evaluateOnNewDocument(pageFunction, ...args)
    • page.exposeFunction(name, puppeteerFunction)
    • page.focus(selector)
    • page.frames()
    • page.goBack(options)
    • page.goForward(options)
    • page.goto(url, options)
    • page.hover(selector)
    • page.isClosed()
    • page.keyboard
    • page.mainFrame()
    • page.metrics()
    • page.mouse
    • page.pdf(options)
    • page.queryObjects(prototypeHandle)
    • page.reload(options)
    • page.screenshot([options])
    • page.select(selector, ...values)
    • page.setBypassCSP(enabled)
    • page.setCacheEnabled(enabled)
    • page.setContent(html)
    • page.setCookie(...cookies)
    • page.setDefaultNavigationTimeout(timeout)
    • page.setExtraHTTPHeaders(headers)
    • page.setJavaScriptEnabled(enabled)
    • page.setOfflineMode(enabled)
    • page.setRequestInterception(value)
    • page.setUserAgent(userAgent)
    • page.setViewport(viewport)
    • page.tap(selector)
    • page.target()
    • page.title()
    • page.touchscreen
    • page.tracing
    • page.type(selector, text[, options])
    • page.url()
    • page.viewport()
    • page.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])
    • page.waitForFunction(pageFunction[, options[, ...args]])
    • page.waitForNavigation(options)
    • page.waitForSelector(selector[, options])
    • page.waitForXPath(xpath[, options])
    • page.workers()
  • class: Worker
    • worker.evaluate(pageFunction, ...args)
    • worker.evaluateHandle(pageFunction, ...args)
    • worker.executionContext()
    • worker.url()
  • class: Keyboard
    • keyboard.down(key[, options])
    • keyboard.press(key[, options])
    • keyboard.sendCharacter(char)
    • keyboard.type(text, options)
    • keyboard.up(key)
  • class: Mouse
    • mouse.click(x, y, [options])
    • mouse.down([options])
    • mouse.move(x, y, [options])
    • mouse.up([options])
  • class: Touchscreen
    • touchscreen.tap(x, y)
  • class: Tracing
    • tracing.start(options)
    • tracing.stop()
  • class: Dialog
    • dialog.accept([promptText])
    • dialog.defaultValue()
    • dialog.dismiss()
    • dialog.message()
    • dialog.type()
  • class: ConsoleMessage
    • consoleMessage.args()
    • consoleMessage.text()
    • consoleMessage.type()
  • class: Frame
    • frame.$(selector)
    • frame.$$(selector)
    • frame.$$eval(selector, pageFunction[, ...args])
    • frame.$eval(selector, pageFunction[, ...args])
    • frame.$x(expression)
    • frame.addScriptTag(options)
    • frame.addStyleTag(options)
    • frame.childFrames()
    • frame.click(selector[, options])
    • frame.content()
    • frame.evaluate(pageFunction, ...args)
    • frame.evaluateHandle(pageFunction, ...args)
    • frame.executionContext()
    • frame.focus(selector)
    • frame.hover(selector)
    • frame.isDetached()
    • frame.name()
    • frame.parentFrame()
    • frame.select(selector, ...values)
    • frame.setContent(html)
    • frame.tap(selector)
    • frame.title()
    • frame.type(selector, text[, options])
    • frame.url()
    • frame.waitFor(selectorOrFunctionOrTimeout[, options[, ...args]])
    • frame.waitForFunction(pageFunction[, options[, ...args]])
    • frame.waitForSelector(selector[, options])
    • frame.waitForXPath(xpath[, options])
  • class: ExecutionContext
    • executionContext.evaluate(pageFunction, ...args)
    • executionContext.evaluateHandle(pageFunction, ...args)
    • executionContext.frame()
    • executionContext.queryObjects(prototypeHandle)
  • class: JSHandle
    • jsHandle.asElement()
    • jsHandle.dispose()
    • jsHandle.executionContext()
    • jsHandle.getProperties()
    • jsHandle.getProperty(propertyName)
    • jsHandle.jsonValue()
  • class: ElementHandle
    • elementHandle.$(selector)
    • elementHandle.$$(selector)
    • elementHandle.$$eval(selector, pageFunction, ...args)
    • elementHandle.$eval(selector, pageFunction, ...args)
    • elementHandle.$x(expression)
    • elementHandle.asElement()
    • elementHandle.boundingBox()
    • elementHandle.boxModel()
    • elementHandle.click([options])
    • elementHandle.contentFrame()
    • elementHandle.dispose()
    • elementHandle.executionContext()
    • elementHandle.focus()
    • elementHandle.getProperties()
    • elementHandle.getProperty(propertyName)
    • elementHandle.hover()
    • elementHandle.jsonValue()
    • elementHandle.press(key[, options])
    • elementHandle.screenshot([options])
    • elementHandle.tap()
    • elementHandle.toString()
    • elementHandle.type(text[, options])
    • elementHandle.uploadFile(...filePaths)
  • class: Request
    • request.abort([errorCode])
    • request.continue([overrides])
    • request.failure()
    • request.frame()
    • request.headers()
    • request.isNavigationRequest()
    • request.method()
    • request.postData()
    • request.redirectChain()
    • request.resourceType()
    • request.respond(response)
    • request.response()
    • request.url()
  • class: Response
    • response.buffer()
    • response.fromCache()
    • response.fromServiceWorker()
    • response.headers()
    • response.json()
    • response.ok()
    • response.request()
    • response.securityDetails()
    • response.status()
    • response.text()
    • response.url()
  • class: SecurityDetails
    • securityDetails.issuer()
    • securityDetails.protocol()
    • securityDetails.subjectName()
    • securityDetails.validFrom()
    • securityDetails.validTo()
  • class: Target
    • target.browser()
    • target.browserContext()
    • target.createCDPSession()
    • target.opener()
    • target.page()
    • target.type()
    • target.url()
  • class: CDPSession
    • cdpSession.detach()
    • cdpSession.send(method[, params])
  • class: Coverage
    • coverage.startCSSCoverage(options)
    • coverage.startJSCoverage(options)
    • coverage.stopCSSCoverage()
    • coverage.stopJSCoverage()

Overview

Puppeteer是一个通过 DevTools Protocol 来控制 Chromium 或者 Chrome的 Node库，并提供了一些高级API。

这些API层级分明，并能提现出浏览器的自身结构。

NOTE 在下面这个图例中，浅色实体代表的结构尚未在 Puppeteer中实现。

  • Puppeteer 使用 DevTools Protocol与浏览器进行通信。
  • Browser 浏览器实例可以包含多个浏览器上下文。
  • BrowserContext 用于保持浏览器session，一个浏览器上下文可以包含多个页面。
  • Page 一个Page最起码包含一个frame，即 main frame，允许存在其他的 frame，这些frame可以用 [iframe]创建。
  • Frame 一个 Frame最起码有一个 Javascript执行上下文环境，即默认的执行上下文环境。Frame允许存在额外附加的上下文环境
  • Worker 存在唯一的上下文环境，并可与 WebWorkers相互协作。

(图例来源: link)

Environment Variables

Puppeteer 需要明确的 environment variables 来协助其完成一系列操作，如果 Puppeteer没有在打钱执行环境中发现这些环境变量，那么将会直接从 npm config搜寻（忽略大小写）。

  • HTTP_PROXY, HTTPS_PROXY, NO_PROXY - 定义了 HTTP proxy的相关配置，常用于下载或启动 Chromium。
  • PUPPETEER_SKIP_CHROMIUM_DOWNLOAD - 用于指示 Puppeteer不要在安装的过程中下载 Chromium安装包。
  • PUPPETEER_DOWNLOAD_HOST - 用于覆写下载 Chromium安装包的地址url。
  • PUPPETEER_CHROMIUM_REVISION - 在安装阶段，用于明确指示 Puppeteer下载安装哪个版本的 Chromium。

class: Puppeteer

Puppeteer模块提供了一个用于启动一个Chromium实例的方法。 下面的代码展示了一种使用 Puppeteer来启动 Chromium实例的典型例子：

const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
  const page = await browser.newPage();
  await page.goto('https://www.google.com');
  // other actions...
  await browser.close();
});
复制代码
puppeteer.connect(options)
  • options
    • browserWSEndpoint a browser websocket endpoint to connect to.
    • ignoreHTTPSErrors 在导航阶段是否忽略 HTTPS错误，默认为 false.
    • slowMo 通过改变此值来减缓 Puppeteer的操作速度，单位是毫秒，当你想知道具体发生了什么情况的时候，此参数将会比较有用。
  • returns: >：以 Promise的形式返回了一个 Browser实例对象。

    • 此方法将会为 Puppeteer 附加上一个 Chromium 实例。

    puppeteer.createBrowserFetcher([options])
    • options
      • host 下载链接的host，默认为 https://storage.googleapis.com。
      • path 下载链接的 path路径，默认为 /.local-chromium, 这里的root指的是是 puppeteer包的根目录.
      • platform 可能的选项有： mac, win32, win64, linux。默认是当前的环境平台。
    • returns:
      • puppeteer.defaultArgs()
      • returns: > The default flags that Chromium will be launched with.
      puppeteer.executablePath()
      • returns: Puppeteer将会在此路径中搜寻 Chromium包， 如果在 PUPPETEER_SKIP_CHROMIUM_DOWNLOAD阶段 Chromium包被跳过下载，那么此包也有可能是不存在的。
      puppeteer.launch([options])
      • options 启动浏览器时的配置，可能存在如下字段:
        • ignoreHTTPSErrors 是否忽略在导航阶段 HTTPS引发的错误，默认为false。
        • headless 是否以一种 headless mode的模式来启动浏览器。 只要devtools 选项不为true，那么此选项的默认值就是 true
        • executablePath Chromium 或 Chrome 的运行路径而不是安装路径。 如果 executablePath 是一个相对目录, 那么它应该是相对于 current working directory。
        • slowMo 通过改变此值来减缓 Puppeteer的操作速度，单位是毫秒，当你想知道具体发生了什么情况的时候，此参数将会比较有用。
        • args > 传递给浏览器实例的额外参数，这些参数的可选列表可见与此。
        • ignoreDefaultArgs 将会使 puppeteer.defaultArgs()失效。 属于比较危险的选项，需要小心使用。默认为 false。
        • handleSIGINT 程序终止信号，通过按下 Ctrl-C 来关闭浏览器进程，默认为 true。
        • handleSIGTERM 程序结束信号，当接收到程序结束信号时，关闭浏览器进程，默认为 true。
        • handleSIGHUP 程序挂起信号，当接收到程序挂起信号时，关闭浏览器进程，默认为 true。
        • timeout 等待浏览器实例启动的超时时间，单位为 ms，默认是30000 (30秒)，设置为 0标识禁用此选项。
        • dumpio 是否将浏览器的输入、输出流连通到控制台的 process.stdout和 process.stderr上。 默认为 false.
        • userDataDir User Data Directory所在路径。
        • env 明确指示浏览器实例可用的环境变量，默认为 process.env。
        • devtools 是否为每个标签页自动打开 DevTools面板，如果为 true, 那么 headless选项将被设置为 false。
        • pipe 通过一个 pipe 而不是 WebSocket来链接浏览器实例，默认为 false。
        • returns: > 一个返回 浏览器实例的 Promise.

          • 此方法根据给定的参数来启动一个浏览器实例，此浏览器实例将会在其 node.js主进程关闭时被销毁。

          NOTE Puppeteer 也可以直接用于控制 Chrome浏览器, 不过，只有当其控制的 Chrome浏览器的版本和其本身绑定的 Chromium版本一致时才能最大程度地发挥作用，如果版本不一致，可能无法正常运行， 特别是当你使用了 executablePath 选项的时候。

          如果你更想使用 Google Chrome (而不是Chromium) 的话, a Chrome Canary or Dev Channel build is suggested.

          在上面的 puppeteer.launch([options]) 选项中, 所有提及到 Chromium 的地方同样适用于 Chrome。

          你可以在这篇文章中找到 Chromium 与 Chrome之间的不同之处， 这篇文章 则介绍了一些在 Linux平台上的差异。

          class: BrowserFetcher

          BrowserFetcher 能够下载和管理不同版本的 Chromium。

          BrowserFetcher 的方法可以接收一个 版本号字符串，此版本号指定精确的 Chromium版本，例如 "533271"，版本号列表可以在 omahaproxy.appspot.com获取。

          下面这里例子展示了如何通过 BrowserFetcher来下载一个特定版本的 Chromium，以及使用 Puppeteer来启动这个 Chromium。

          const browserFetcher = puppeteer.createBrowserFetcher();
const revisionInfo = await browserFetcher.download('533271');
const browser = await puppeteer.launch({executablePath: revisionInfo.executablePath})
复制代码

          NOTE BrowserFetcher无法与其他使用相同下载目录的 BrowserFetcher实例同时运行。

          browserFetcher.canDownload(revision)
          • revision 检查是否可用版本的版本号。
          • returns: > 如果目标版本的浏览器可以从目标 host上下载下来，则返回 true。

          此方法通过发起一个 HEAD request来检查目标版本是否可用。

          browserFetcher.download(revision[, progressCallback])
          • revision 需要下载的浏览器的版本号.
          • progressCallback 此函数方法存在两个参数:
            • downloadedBytes 已经下载了多少字节
            • totalBytes 一共有多少字节.
          • returns: > 当目标版本的浏览器正在被下载和提取的时候，返回一个 Promise 对象，此对象包含目标版本浏览器的一些信息。
            • revision the revision the info was created from
            • folderPath 提取所下载的浏览器包的目录
            • executablePath 目标版本的浏览器的运行目录
            • url 目标版本的浏览器的下载url
            • local 目标版本的浏览器是否可在本地磁盘上获取

          此方法通过发起一个 GET请求来从目标 host下载指定版本的浏览器。

          browserFetcher.localRevisions()
          • returns: >> 本地磁盘可获取到的所有版本浏览器的列表。
          browserFetcher.platform()
          • returns: 返回 mac, linux, win32、 win64 中的其中一个。
          browserFetcher.remove(revision)
          • revision 需要删除的版本。如果指定的版本的浏览器并没有被下载下来，此方法将会抛出错误（此错误可用 catch捕获）。
          • returns: 当指定版本的浏览器被删除后返回一个 Promise。
          browserFetcher.revisionInfo(revision)

          • revision 希望获取相关信息的浏览器的版本号。

          • returns:

            • revision 信息来源的版本号
            • folderPath 提取所下载的浏览器包的目录
            • executablePath 目标版本的浏览器的运行目录
            • url 目标版本的浏览器的下载url
            • local 目标版本的浏览器是否可在本地磁盘上获取

            class: Browser

            • extends: EventEmitter

            当 Puppeteer 连接上一个 Chromium实例的时候，将会puppeteer.launch 或者 puppeteer.connect方法产生一个 Browser。

            下面是一个使用 Browser 来创建一个 Page的例子 :

            const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
  const page = await browser.newPage();
  await page.goto('https://example.com');
  await browser.close();
});
复制代码

            下面是一个使用 Browser 来断开连接和重连的例子：

            const puppeteer = require('puppeteer');

puppeteer.launch().then(async browser => {
  // Store the endpoint to be able to reconnect to Chromium
  const browserWSEndpoint = browser.wsEndpoint();
  // Disconnect puppeteer from Chromium
  browser.disconnect();

  // Use the endpoint to reestablish a connection
  const browser2 = await puppeteer.connect({browserWSEndpoint});
  // Close Chromium
  await browser2.close();
});
复制代码
            event: 'disconnected'

            当 Puppeteer被从 Chromium实例上断开时被触发，包括如下几种情形：

            • Chromium 被关闭或崩溃
            • The browser.disconnect 方法被调用
            event: 'targetchanged'

            当目标 url改变时触发。

            NOTE 包括在匿名浏览器上下文中目标URL改变。

            event: 'targetcreated'

            当目标被创建时触发, 例如，当一个新页面通过 window.open 或者 browser.newPage被打开时。

            NOTE 包括在匿名浏览器上下文中目标的创建。

            event: 'targetdestroyed'

            目标被销毁时触发, 例如，当一个页面关闭时。

            NOTE 包括在匿名浏览器上下文中目标的销毁。

            browser.browserContexts()
            • returns: >

            返回一个包含所有已经被打开的浏览器上下文的数组。 在一个最新被创建的浏览器中，将会返回一个唯一的BrowserContext的实例。

            browser.close()
            • returns:

            关闭 Chromium以及它所有的页面（如果存在被打开的页面的话）。Browser 对象将会被销毁，并且不再可用。

            browser.createIncognitoBrowserContext()
            • returns: >

            创建一个新的匿名浏览器上下文，这个匿名浏览器上下文不会与其他浏览器上下文共享 cookies/cache。

            const browser = await puppeteer.launch();
// Create a new incognito browser context.
const context = await browser.createIncognitoBrowserContext();
// Create a new page in a pristine context.
const page = await context.newPage();
// Do stuff
await page.goto('https://example.com');
复制代码
            browser.disconnect()

            Disconnects Puppeteer from the browser, but leaves the Chromium process running. After calling disconnect, the Browser object is considered disposed and cannot be used anymore.

            断开 Puppeteer与 浏览器之间的连接，不过 Chromium进程依旧继续运行。当调用了disconnect方法之后，Browser 对象将会被销毁，并且不再可用。

            browser.newPage()
            • returns: >

            返回一个新的 Page Promise对象，Page将在一个默认的浏览器上下文中创建。

            browser.pages()
            • returns: >> resolve一个包含所有打开页面的数组，不可见的页面，例如 "background_page", 将不会包含在此数组中，你可以使用 target.page()方法来获取到（不可见页面）。
            browser.process()
            • returns: 开启一个浏览器主进程的子进程。如果浏览器实例是使用 puppeteer.connect 方法创建，那么将会返回 null。
            browser.targets()
            • returns: >

            An array of all active targets inside the Browser. In case of multiple browser contexts, the method will return an array with all the targets in all browser contexts.

            返回Browser实例中包含的所有的有效targets的一个数组，由于可能存在多个浏览器上下文，所以此方法将会返回一个由所有浏览器上下文中的所有 targets梭组成的数组。

            browser.userAgent()
            • returns: > resolve 浏览器的user agent.

            NOTE 可以使用 page.setUserAgent来改变浏览器的 user agent。

            browser.version()
            • returns: > 对于 headless Chromium来说，将返回一个类似于 HeadlessChrome/61.0.3153.0的字符串。 对于non-headless 浏览器来说, 将返回一个类似于 Chrome/61.0.3153.0的字符串。

            NOTE 此方法返回的字符串格式可能会在将来的版本中发生变化。

            browser.wsEndpoint()
            • returns: 浏览器 websoket 的url。

            此方法返回的 浏览器 websoket端口字符串格式如：ws://${host}:${port}/devtools/browser/，此字符串可作为puppeteer.connect方法的一个参数传入。

            You can find the webSocketDebuggerUrl from http://${host}:${port}/json/version. Learn more about the devtools protocol and the browser endpoint.

            class: BrowserContext

            • extends: EventEmitter

            BrowserContexts提供了一种操作多个独立浏览器session的方法。当启动一个浏览器的时候，将会同时产生一个BrowserContext，并且在这个 BrowserContext中，browser.newPage() 方法将会创建一个新页面。

            如果使用例如 window.open的方法创建了另外的页面， the popup 将隶属于父页面的浏览器上下文。

            Puppeteer允许通过 browser.createIncognitoBrowserContext() 方法来创建匿名浏览器上下文，匿名浏览器上下文不会向磁盘中记录任何浏览的内容。

            // 创建匿名浏览器上下文
const context = await browser.createIncognitoBrowserContext();
// 在上下文中创建页面
const page = await context.newPage();
// ... do stuff with page ...
await page.goto('https://example.com');
// Dispose context once it's no longer needed.
await context.close();
复制代码
            event: 'targetchanged'

            当浏览器上下文中的某个target url改变时触发。

            event: 'targetcreated'

            当浏览器上下文中创建了一个新target时触发，例如，当使用 window.open 或 browserContext.newPage方法创建一个新页面的时候。

            event: 'targetdestroyed'

            当浏览器上下文中的某个target 被销毁时触发，例如当一个页面被关闭时。

            browserContext.browser()
            • returns:

            浏览器上下文归属的浏览器实例。

            browserContext.close()
            • returns:

            关闭浏览器上下文。所有属于此浏览器上下文的target都将会一同销毁。

            NOTE 只有匿名浏览器上下文可以被关闭(也就是只有通过 createIncognitoBrowserContext方法创建的匿名浏览器才可以使用此方法)。

            browserContext.isIncognito()
            • returns: 返回 BrowserContext 是否是匿名的。 浏览器的默认上下文是非匿名的。

            NOTE 浏览器的默认浏览器上下文是不可关闭的。

            browserContext.newPage()
            • returns: >

            在浏览器上下文中创建新页面。

            browserContext.targets()
            • returns: >

            浏览器上下文中的所有有效target（例如Page页面）组成的一个数组。

            class: Page

            • extends: EventEmitter

            Page提供了一些能让你操作 Chromium中标签页的方法。一个 Browser实例中可能包含多个 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();
});
复制代码

            使用 Node模块EventEmitter的一些方法，我们能够控制 Page类触发的一些事件，例如 on once 或者 removeListener等。

            下面的例子展示了如何监听页面的 load事件。

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

            使用 removeListener方法来移除监听事件：

            function logRequest(interceptedRequest) {
  console.log('A request was made:', interceptedRequest.url());
}
page.on('request', logRequest);
// Sometime later...
page.removeListener('request', logRequest);
复制代码
            event: 'close'

            当页面关闭的时候触发。

            event: 'console'

            当页面上的Javascript脚本调用一些类似于 console.log 或 console.dir的 console API时触发，除此之外，如果页面上的脚本抛出错误或者警告同样也会触发。

            The arguments passed into console.log appear as arguments on the event handler.

            下面是一个监听 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'}));
复制代码
            event: 'dialog'

            当页面上弹出 JavaScript对话框的时候触发，例如 alert, prompt, confirm 或者 beforeunload。Puppeteer能够通过 Dialog的 accept 或者 dismiss 方法来对此事件作出回应。

            event: 'domcontentloaded'

            当 JavaScript 的DOMContentLoaded 事件被触发时触发。

            event: 'error'

            当页面崩溃时触发。

            NOTE error 事件在 Node中具有特殊的含义，具体细节参见 error events 。

            event: 'frameattached'

            当一个 frame 被附加到主页面上时触发。

            event: 'framedetached'

            当一个 frame 从主页面上分离(删除)时触发。

            event: 'framenavigated'

            当一个 frame 的url被定向到一个新的url上时触发。

            event: 'load'

            当 JavaScript 的load 事件被触发时触发。

            event: 'metrics'
              • title console.timeStamp 的 title
              • metrics Object containing metrics as key/value pairs. The values of metrics are of type.一个包含 metrics key/value对的对象。metrics的值为 number类型。

                当页面上的JavaScript脚本调用 cnosole.timeStamp时触发。metrics的可选列表可见 page.metrics。

                event: 'pageerror'
                • The exception message

                当页面上出现未捕获的异常时触发。

                event: 'request'

                当页面上发起一个请求的时候触发。request对象是只读的，如果你想拦截并改造请求，参照 page.setRequestInterception。

                event: 'requestfailed'

                当请求失败时触发，例如，请求超时。

                event: 'requestfinished'

                当请求完成时触发。

                event: 'response'

                当页面收到请求的响应时触发。

                event: 'workercreated'

                当页面上产生一个新的 WebWorker线程时触发。

                event: 'workerdestroyed'

                当页面上有 WebWorker线程结束时触发。

                page.$(selector)
                • selector 选择器
                • returns: >

                此方法在页面上使用了 document.querySelector。如果选择器没有匹配到元素，将会返回 null。

                page.mainFrame().$(selector)的快捷方法。

                page.$$(selector)
                • selector 选择器
                • returns: >>

                此方法在页面上使用了 document.querySelectorAll。如果选择器没有匹配到元素，将会返回 []。

                page.mainFrame().$$(selector)的快捷方法。

                page.$$eval(selector, pageFunction[, ...args])
                • selector 选择器
                • pageFunction 将在浏览器上下文中执行的函数
                • ...args <...Serializable|JSHandle> 传递给 pageFunction的额外参数
                • returns: > pageFunction返回的结果。

                此方法在页面上使用了 Array.from(document.querySelectorAll(selector))，并将获取到的结果当做 pageFunction的第一个参数传递进去。

                如果 pageFunction返回的结果是一个 Promise，则page.$$eval将会等到前者 resolve回一个结果后，才会继续返回自己的值。

                例子:

                const divsCounts = await page.$$eval('div', divs => divs.length);
复制代码
                page.$eval(selector, pageFunction[, ...args])
                • selector 选择器
                • pageFunction 将在浏览器上下文中执行的函数
                • ...args <...Serializable|JSHandle> 传递给 pageFunction的额外参数
                • returns: > pageFunction返回的结果。

                此方法在页面上使用了 document.querySelector，并将获取到的结果当做 pageFunction的第一个参数传递进去。如果选择器没有匹配到元素，则将抛出一个错误。

                如果 pageFunction返回的结果是一个 Promise，则page.$eval将会等到前者 resolve回一个结果后，才会继续返回自己的值。

                例子:

                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)
                • expression Expression to evaluate.
                • returns: >>

                根据给定的 Xpath表达式获取 DOM元素。

                page.mainFrame().$x(expression)的快捷方法。

                page.addScriptTag(options)
                • options
                  • url 将要被添加的 script 的url.
                  • path 将要被添加的JavaScript文件的路径. 如果 path 是相对路径, 则其是相对于 current working directory。
                  • content 将要被添加的JavaScript脚本的内容。
                  • type 脚本类型. 如果是 'module' ，则将导入的是JS的 ES6模块。更多参见 script。
                • returns: > 当script脚本加载完毕，或者脚本内容已经注入到页面上时，将会返回所添加的script标签元素。

                  • 向页面中增加指定 url或者 脚本内容的 script标签。

                  page.mainFrame().addScriptTag(options)的快捷方法。

                  page.addStyleTag(options)
                  • options
                    • url 将要被添加的 style 的url
                    • path 将要被添加的 CSS文件的路径. 如果 path 是相对路径, 则其是相对于 current working directory。
                    • content 将要被添加的CSS脚本的内容。
                  • returns: >当style加载完毕，或者style内容已经注入到页面上时，将会返回所添加的style标签元素。

                    • 向页面中添加一个 带有指定 url的标签，或者一个带有内容的