class: Browser

3.1.0

3.1.0

• extends: EventEmitter

当 Puppeteer 通过 puppeteer.launch 或puppeteer.connect 连接到 Chromium 实例时，将会创建一个浏览器。

使用 [Browser] 创建 [Page] 的例子：

const puppeteer = require('puppeteer');

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

与 [Browser] 断开连接并重新连接的例子：

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  // 存储节点以便能够重新连接到 Chromium
  const browserWSEndpoint = browser.wsEndpoint();
  // 从 Chromium 断开 puppeteer
  browser.disconnect();

  // 使用节点重新建立连接
  const browser2 = await puppeteer.connect({browserWSEndpoint});
  // 关闭 Chromium
  await browser2.close();
})();

event: 'disconnected'

当 Puppeteer 与 Chromium 实例断开连接时触发。比如下面两种情况：

• Chromium is closed or crashed
• The browser.disconnect method was called

event: 'targetchanged'

• <[Target]>

当目标网址更改时触发。

NOTE 这包括隐身浏览器上下文中的目标网址更改。

event: 'targetcreated'

• <[Target]>

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

NOTE 这包括在隐身浏览器上下文中的目标创建。

event: 'targetdestroyed'

• <[Target]>

在目标销毁时触发，比如页面被关闭时。

NOTE 这也包括隐身浏览器上下文中的目标破坏时。

browser.browserContexts()

• returns: <[Array]<[BrowserContext]>>

返回一个所有打开的浏览器上下文的数组。在新创建的浏览器中，这将返回
[BrowserContext] 的单个实例。

browser.close()

• returns: <[Promise]>

关闭 Chromium 及其所有页面(如果已打开)。 [Browser] 对象本身被认为是已销毁，所以无法再使用。

browser.createIncognitoBrowserContext()

• returns: <[Promise]<[BrowserContext]>>

创建一个新的隐身浏览器上下文。这不会与其他浏览器上下文共享 cookie/缓存。

(async () => {
  const browser = await puppeteer.launch();
  // 创建一个新的隐身浏览器上下文
  const context = await browser.createIncognitoBrowserContext();
  // 在原始上下文中创建一个新页面
  const page = await context.newPage();
  // Do stuff
  await page.goto('https://example.com');
})();

browser.defaultBrowserContext()

• returns: <[BrowserContext]>

返回默认浏览器的上下文。默认浏览器的上下文无法被关闭。

browser.disconnect()

断开 Puppeteer 与浏览器的连接，但保持 Chromium 进程运行。调用 disconnect后，[Browser] 对象被视为已销毁，无法再使用。

browser.isConnected()

• returns: <[boolean]>

浏览器已连接。

browser.newPage()

• returns: <[Promise]<[Page]>>

承诺解析为新的 [Page] 对象。 [Page] 是在默认浏览器上下文中创建的。

browser.pages()

• returns: <[Promise]<[Array]<[Page]>>> 它解析为所有打开的页面的数组。不包括不可见的页面，例如“ background_page”，将不在此处列出。可以使用 target.page() 找到它们。

浏览器中所有页面的数组。如果有多个浏览器上下文，该方法将返回一个数组，其中包含所有浏览器上下文中的所有页面。

browser.process()

• returns: <?[ChildProcess]> 生成的浏览器进程。如果使用 puppeteer.connect 方法创建了浏览器实例，则返回null。

browser.target()

• returns: <[Target]>

与浏览器关联的目标。

browser.targets()

• returns: <[Array]<[Target]>>

浏览器内所有活动目标的数组。如果有多个浏览器上下文，该方法将返回一个数组，其中包含所有浏览器上下文中的所有目标。

browser.userAgent()

• returns: <[Promise]<[string]>> 它解析为浏览器的原始用户代理

NOTE 页面可以使用 page.setUserAgent 覆盖浏览器用户代理

browser.version()

• returns: <[Promise]<[string]>> 对于无头浏览器, 类似于 HeadlessChrome/61.0.3153.0。对于有头浏览器, 类似于 Chrome/61.0.3153.0。

NOTE browser.version() 的格式可能会随着 Chromium 的未来版本而改变。

browser.waitForTarget(predicate[, options])

• predicate <[function]([Target]):[boolean]> A function to be run for every target
• options <[Object]>
  • timeout <[number]> 最大等待时间，以毫秒为单位。传递0以禁用超时。默认为30秒。
• returns: <[Promise]<[Target]>> 解析为找到的第一个与 predicate 函数匹配的目标。

这将在所有浏览器上下文中搜索目标。

查找通过 window.open 打开的页面的目标的例子：

await page.evaluate(() => window.open('https://www.example.com/'));
const newWindowTarget = await browser.waitForTarget(target => target.url() === 'https://www.example.com/');

browser.wsEndpoint()

• returns: <[string]> Browser websocket url.

浏览器 websocket 端点，可以用作以下参数
puppeteer.connect。格式为ws:/// $ {host}：$ {port} / devtools / browser / <id>

可以从 http:/// $ {host}：$ {port} / json / version 找到 webSocketDebuggerUrl。详细了解 devtools协议 和 浏览器端点。

返回所有打开的浏览器上下文的数组。在新创建的浏览器中，这将返回
[BrowserContext] 的单个实例。

本译文仅用于学习和交流目的，转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议，如果我们的工作有侵犯到您的权益，请及时联系我们。

原文地址：https://learnku.com/docs/puppeteer/3.1.0...

译文地址：https://learnku.com/docs/puppeteer/3.1.0...