跳到主要内容
版本: 23.11.1

API 参考

类​

类

描述

Accessibility

Accessibility 类提供了检查浏览器辅助功能树的方法。辅助功能树被诸如屏幕阅读器或开关等辅助技术所使用。

备注

辅助功能是一个非常特定于平台的东西。在不同的平台上，有不同的屏幕阅读器，它们可能有截然不同的输出。

Blink - Chrome 的渲染引擎 - 有一个“辅助功能树”的概念，然后将其转换为不同的平台特定的 API。辅助功能命名空间允许用户访问 Blink 辅助功能树。

当从 Blink AX 树转换为平台特定的 AX 树或由辅助技术本身转换时，大多数辅助功能树会被过滤掉。默认情况下，Puppeteer 尝试近似这种过滤，仅公开树的“有趣”节点。

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 Accessibility 类的子类。

Browser

Browser 表示一个浏览器实例，该实例要么

Browser 发出 各种事件，这些事件记录在 BrowserEvent 枚举中。

备注

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 Browser 类的子类。

BrowserContext

BrowserContext 表示 浏览器 中的各个用户上下文。

当 浏览器 启动时，它至少有一个默认的 浏览器上下文。其他可以使用 Browser.createBrowserContext() 创建。每个上下文都有隔离的存储空间（cookie/localStorage/等等）。

BrowserContext 发出 各种事件，这些事件记录在 BrowserContextEvent 枚举中。

如果一个 页面 打开另一个 页面，例如使用 window.open，则弹出窗口将属于父 页面的浏览器上下文。

备注

在 Chrome 中，所有非默认上下文都是隐身模式，如果您在启动浏览器时提供 --incognito 参数，则默认浏览器上下文可能是隐身模式。

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 BrowserContext 类的子类。

BrowserLauncher

描述一个启动器 - 一个能够创建和启动浏览器实例的类。

备注

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 BrowserLauncher 类的子类。

CDPSession

CDPSession 实例用于与原始 Chrome Devtools 协议进行通信。

备注

可以使用 CDPSession.send() 方法调用协议方法，可以使用 CDPSession.on 方法订阅协议事件。

有用的链接：DevTools 协议查看器 和 DevTools 协议入门。

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 CDPSession 类的子类。

Connection
ConsoleMessage

ConsoleMessage 对象由页面通过“console”事件分派。

备注

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 ConsoleMessage 类的子类。

Coverage

Coverage 类提供了收集页面使用的 JavaScript 和 CSS 部分信息的方法。

备注

要以 Istanbul 可消费的形式输出覆盖率，请参阅 puppeteer-to-istanbul。

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 Coverage 类的子类。

CSSCoverage
DeviceRequestPrompt

设备请求提示允许您响应页面通过类似 WebBluetooth 的 API 请求设备。

备注

DeviceRequestPrompt 实例通过 Page.waitForDevicePrompt() 方法返回。

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 DeviceRequestPrompt 类的子类。

DeviceRequestPromptDevice

请求提示中的设备。

备注

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 DeviceRequestPromptDevice 类的子类。

Dialog

Dialog 实例由 Page 通过 dialog 事件分派。

备注

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 Dialog 类的子类。

ElementHandle

ElementHandle 表示页面内的 DOM 元素。

备注

可以使用 Page.$() 方法创建 ElementHandles。

import puppeteer from 'puppeteer';

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

除非句柄被 释放，否则 ElementHandle 会阻止 DOM 元素被垃圾回收。当其原始框架导航时，ElementHandles 会自动释放。

ElementHandle 实例可以用作 Page.$eval() 和 Page.evaluate() 方法中的参数。

如果您正在使用 TypeScript，ElementHandle 会接受一个泛型参数，该参数表示句柄内部持有的元素的类型。例如，如果您有一个指向 <select> 元素的句柄，您可以将其类型设置为 ElementHandle<HTMLSelectElement>，您将获得一些更好的类型检查。

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 ElementHandle 类的子类。

EventEmitter

许多 Puppeteer 类都扩展的 EventEmitter 类。

备注

这允许您侦听 Puppeteer 类触发的事件并采取相应的行动。因此，您主要使用 on 和 off 来绑定和取消绑定到事件侦听器。

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 EventEmitter 类的子类。

ExtensionTransport

（实验性） 如果 Puppeteer 在扩展程序中运行，则实验性 ExtensionTransport 允许通过 chrome.debugger API 建立连接。由于 Chrome DevTools 协议对扩展程序有限制，因此传输实现了缺失的命令和事件。

备注

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 ExtensionTransport 类的子类。

FileChooser

文件选择器允许您对页面请求文件做出反应。

备注

FileChooser 实例通过 Page.waitForFileChooser() 方法返回。

在浏览器中，一次只能打开一个文件选择器。所有文件选择器都必须被接受或取消。如果不这样做，将阻止后续文件选择器出现。

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 FileChooser 类的子类。

Frame

表示 DOM 框架。

要理解框架，您可以将框架视为 <iframe> 元素。就像 iframe 一样，框架可以嵌套，并且当 JavaScript 在框架中执行时，JavaScript 不会影响执行 JavaScript 的环境框架内的框架。

备注

框架生命周期由父 页面 上分派的三个事件控制

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 Frame 类的子类。

HTTPRequest

表示页面发送的 HTTP 请求。

备注

每当页面发送请求时，例如请求网络资源时，Puppeteer 的 page 会发出以下事件

  • request：当页面发出请求时发出。

  • requestfinished - 当响应正文下载完毕并且请求完成时发出。

如果请求在某个时刻失败，则会发出 requestfailed 事件而不是 requestfinished 事件。

所有这些事件都提供一个 HTTPRequest 的实例，表示发生的请求

page.on('request', request => ...)

注意：HTTP 错误响应，如 404 或 503，从 HTTP 的角度来看仍然是成功的响应，因此请求将以 requestfinished 事件完成。

如果请求收到“重定向”响应，则请求成功完成并发出 requestfinished 事件，并且会向重定向的 URL 发出新请求。

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 HTTPRequest 类的子类。

HTTPResponse

HTTPResponse 类表示 Page 类接收的响应。

备注

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 HTTPResponse 类的子类。

JSCoverage

备注

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 JSCoverage 类的子类。

JSHandle

表示对 JavaScript 对象的引用。可以使用 Page.evaluateHandle() 创建实例。

除非句柄被有意 释放，否则句柄会阻止引用的 JavaScript 对象被垃圾回收。当其关联的框架导航离开或父上下文被销毁时，JSHandles 会自动释放。

句柄可以用作任何评估函数的参数，例如 Page.$eval()、Page.evaluate() 和 Page.evaluateHandle()。它们会被解析为它们引用的对象。

备注

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 JSHandle 类的子类。

键盘

键盘提供了一个用于管理虚拟键盘的 API。高级 API 是 Keyboard.type()，它接受原始字符并在页面上生成正确的 keydown、keypress/input 和 keyup 事件。

备注

对于更精细的控制，您可以使用 Keyboard.down()、Keyboard.up() 和 Keyboard.sendCharacter() 来手动触发事件，就像它们是从真实键盘生成的一样。

在 macOS 上，像 ⌘ A -> 全选这样的键盘快捷键不起作用。请参阅 #1313。

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 Keyboard 类的子类。

定位器

定位器描述了定位对象并对其执行操作的策略。如果由于对象未准备好执行操作而导致操作失败，则会重试整个操作。会自动检查成功操作的各种前提条件。

有关详细信息，请参阅 https://puppeteer.com.cn/guides/page-interactions#locators。

鼠标

鼠标类在相对于视口左上角的主框架 CSS 像素中操作。

备注

每个 page 对象都有自己的鼠标，可以通过 Page.mouse 访问。

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 Mouse 类的子类。

页面

页面提供了与浏览器中的单个选项卡或 扩展后台页面 进行交互的方法。

注意

一个浏览器实例可能具有多个页面实例。

备注

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 Page 类的子类。

ProtocolError

当协议发生错误时，会发出 ProtocolError。

Puppeteer

主要的 Puppeteer 类。

重要提示：如果您在 Node 环境中使用 Puppeteer，则在导入或 require puppeteer 时，您将获得 PuppeteerNode 的实例。该类扩展了 Puppeteer，因此具有下面记录的所有方法以及 PuppeteerNode 上定义的所有方法。

备注

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 Puppeteer 类的子类。

PuppeteerError

所有 Puppeteer 特定错误的基类

备注

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 PuppeteerError 类的子类。

PuppeteerNode

使用 Node 特定的行为扩展了主要的 Puppeteer 类，用于获取和下载浏览器。

如果您在 Node 环境中使用 Puppeteer，则在运行 require('puppeteer') （或等效的 ES import）时，将获得此类。

备注

最常用的方法是 launch，用于启动并连接到新的浏览器实例。

请参阅 主要的 Puppeteer 类，了解所有环境通用的方法，例如 Puppeteer.connect()。

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 PuppeteerNode 类的子类。

ScreenRecorder

备注

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 ScreenRecorder 类的子类。

SecurityDetails

SecurityDetails 类表示通过安全连接接收的响应的安全详细信息。

备注

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 SecurityDetails 类的子类。

目标

目标表示 CDP 目标。在 CDP 中，目标是可调试的，例如框架、页面或工作线程。

备注

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 Target 类的子类。

TimeoutError

当某些操作因超时而终止时，会发出 TimeoutError。

备注

示例操作为 page.waitForSelector 或 puppeteer.launch。

TouchError

当尝试移动或结束不存在的触摸时，会抛出 TouchError。

触摸屏

触摸屏类公开了触摸屏事件。

备注

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 Touchscreen 类的子类。

跟踪

跟踪类公开了跟踪审计接口。

备注

您可以使用 tracing.start 和 tracing.stop 来创建跟踪文件，该文件可以在 Chrome DevTools 或 时间轴查看器 中打开。

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 Tracing 类的子类。

UnsupportedOperation

如果当前使用的协议不支持某个方法，则 Puppeteer 会抛出此错误

WebWorker

此类表示 WebWorker。

备注

workercreated 和 workerdestroyed 事件在页面对象上发出，以指示工作线程的生命周期。

此类的构造函数被标记为内部函数。第三方代码不应直接调用构造函数，也不应创建扩展 WebWorker 类的子类。

枚举​

枚举

描述

BrowserContextEvent
BrowserEvent

一个 浏览器实例 可能发出的所有事件。

InterceptResolutionAction
LocatorEvent

定位器实例可能发出的所有事件。

PageEvent

页面实例可能发出的所有事件。

TargetType

函数​

函数

描述

connect(options)
convertCookiesPartitionKeyFromPuppeteerToCdp(partitionKey)
defaultArgs(options)
launch(options)
trimCache()

接口​

接口

描述

ActionOptions
AutofillData
BoundingBox
BoxModel
BrowserContextEvents
BrowserContextOptions
BrowserEvents
CDPSessionEvents
ChromeHeadlessShellSettings
ChromeSettings
ClickOptions
CommandOptions
CommonEventEmitter
Configuration

定义配置 Puppeteer 在安装和运行时行为的选项。

有关详细信息，请参阅各个属性。

ConnectionTransport
ConnectOptions

启动任何浏览器或连接到现有浏览器实例时可以传递的通用浏览器选项。

ConsoleMessageLocation
ContinueRequestOverrides
Cookie

表示 Cookie 对象。

CookieData

用于在浏览器级 Cookie API 中设置 Cookie 的 Cookie 参数对象。

CookieParam

用于在页面级 Cookie API 中设置 Cookie 的 Cookie 参数对象。

CookiePartitionKey

表示 Chrome 中的 Cookie 分区键。

CoverageEntry

CoverageEntry 类表示覆盖率报告的一个条目。

Credentials
CSSCoverageOptions

CSS 覆盖率的可配置选项集。

CustomQueryHandler
DebugInfo

（实验性）

DeleteCookiesRequest
Device
DownloadBehavior
ElementScreenshotOptions
FirefoxSettings
FrameAddScriptTagOptions
FrameAddStyleTagOptions
FrameEvents
FrameWaitForFunctionOptions
GeolocationOptions
GoToOptions
InterceptResolutionState
InternalNetworkConditions
JSCoverageEntry

JavaScript 的 CoverageEntry 类

JSCoverageOptions

JS 覆盖率的可配置选项集。

KeyboardTypeOptions
KeyDownOptions
LaunchOptions

启动任何浏览器时可以传递的通用启动选项。

LocatorEvents
LocatorScrollOptions
MediaFeature

要模拟的媒体功能。

Metrics
MouseClickOptions
MouseMoveOptions
MouseOptions
MouseWheelOptions
Moveable
NetworkConditions
NewDocumentScriptEvaluation
Offset
PageEvents

表示页面事件的回调函数接收的对象。

有关事件及其发出时间的更多详细信息，请参阅 PageEvent。

PDFMargin
PDFOptions

用于通过 Page.pdf() 配置 PDF 生成的有效选项。

Point
QueryOptions
RemoteAddress
ResponseForRequest

用于满足请求的必需响应数据。

ScreencastOptions

（实验性）

ScreenshotClip
ScreenshotOptions
SerializedAXNode

表示与可访问性相关的 Node 及其属性。

SnapshotOptions
SupportedWebDriverCapabilities

Puppeteer 本身未设置的 WebDriver BiDi 功能。

TouchHandle

TouchHandle 接口公开了操作已启动的触摸的方法

TracingOptions
Viewport
WaitForNetworkIdleOptions
WaitForOptions
WaitForSelectorOptions
WaitForTargetOptions
WaitTimeoutOptions

命名空间​

命名空间

描述

CDPSessionEvent

CDPSession 类发出的事件。

变量​

变量

描述

DEFAULT_INTERCEPT_RESOLUTION_PRIORITY

默认的协同请求拦截解析优先级

executablePath
KnownDevices

用于 Page.emulate() 的设备列表。

MouseButton

有效鼠标按钮的枚举。

PredefinedNetworkConditions

一个预定义的网络条件列表，用于 Page.emulateNetworkConditions()。

puppeteer

类型别名​

类型别名

描述

ActionResult
Awaitable
AwaitableIterable
AwaitablePredicate
AwaitedLocator
BrowserConnectOptions

Deprecated

请使用 ConnectOptions。

BrowserLaunchArgumentOptions

Deprecated

请使用 LaunchOptions。

CDPEvents
ChromeReleaseChannel
ConsoleMessageType

控制台消息支持的类型。

CookiePriority

表示 Cookie 的“优先级”状态：https://tools.ietf.org/html/draft-west-cookie-priority-00

CookieSameSite

表示 Cookie 的“SameSite”状态：https://tools.ietf.org/html/draft-west-first-party-cookies

CookieSourceScheme

表示最初设置 cookie 的来源方案。值为“Unset”允许协议客户端模拟该方案的旧版 cookie 范围。这是一个临时的功能，将来会被删除。

DownloadPolicy
ElementFor
ErrorCode
EvaluateFunc
EvaluateFuncWith
EventsWithWildcard
EventType
ExperimentsConfiguration

定义 Puppeteer 的实验选项。

有关详细信息，请参阅各个属性。

FlattenHandle
HandleFor
HandleOr
Handler
InnerParams
KeyInput

所有可以传递给接受用户输入函数的有效键，例如 keyboard.press

KeyPressOptions
LocatorClickOptions
LowerCasePaperFormat
Mapper
MouseButton
NodeFor
PaperFormat

打印 PDF 时所有有效的纸张格式类型。

备注

每种格式的大小如下：

  • Letter: 8.5 英寸 x 11 英寸

  • Legal: 8.5 英寸 x 14 英寸

  • Tabloid: 11 英寸 x 17 英寸

  • Ledger: 17 英寸 x 11 英寸

  • A0: 33.1102 英寸 x 46.811 英寸

  • A1: 23.3858 英寸 x 33.1102 英寸

  • A2: 16.5354 英寸 x 23.3858 英寸

  • A3: 11.6929 英寸 x 16.5354 英寸

  • A4: 8.2677 英寸 x 11.6929 英寸

  • A5: 5.8268 英寸 x 8.2677 英寸

  • A6: 4.1339 英寸 x 5.8268 英寸

Permission
Predicate
ProtocolLifeCycleEvent
ProtocolType
PuppeteerLaunchOptions

Deprecated

请使用 LaunchOptions。

PuppeteerLifeCycleEvent
PuppeteerNodeLaunchOptions

Deprecated

请使用 LaunchOptions。

Quad
ResourceType

渲染引擎感知的 HTTP 请求的资源类型。

SupportedBrowser

Puppeteer 支持的浏览器。

SupportedWebDriverCapability
TargetFilterCallback
VisibilityOption

是否等待元素 可见 或 隐藏。 null 表示禁用可见性检查。