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)](#pageselector-1)
  * [page. (selector)](#pageselector-1)  * [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]])](#pagewaitforselectororfunctionortimeout-options-args)
* [page.waitForFunction(pageFunction[, options[, …args]])](#pagewaitforfunctionpagefunction-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)](#frameselector-1)
  * [frame. (selector)](#frameselector-1)  * [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]])](#framewaitforselectororfunctionortimeout-options-args)
* [frame.waitForFunction(pageFunction[, options[, …args]])](#framewaitforfunctionpagefunction-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)](#elementhandleselector-1)
  * [elementHandle. (selector)](#elementhandleselector-1)  * [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