Skip to main content
Version: 23.8.0

API 参考

¥API Reference

类​

¥Classes

类

描述

无障碍

Accessibility 类提供了检查浏览器的辅助功能树的方法。可访问性树由 屏幕阅读器 或 switches 等辅助技术使用。

评论：

可访问性是一个非常特定于平台的东西。在不同的平台上，有不同的屏幕阅读器，可能会产生截然不同的输出。

Blink - Chrome's rendering engine - 有一个 "可达性树" 的概念，然后将其转换为不同平台特定的 API。Accessibility 命名空间使用户可以访问 Blink Accessibility Tree。

当从 Blink AX 树转换为特定于平台的 AX 树或通过辅助技术本身时，大多数可访问性树都会被过滤掉。默认情况下，Puppeteer 尝试近似此过滤，仅公开树的 "interesting" 节点。

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

Browser

Browser 代表一个浏览器实例，它是：

Browser emits 各种事件记录在 BrowserEvent 枚举中。

评论：

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

BrowserContext

BrowserContext 代表 browser 中的各个用户上下文。

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

BrowserContext emits 各种事件记录在 BrowserContextEvent 枚举中。

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

评论：

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

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

BrowserLauncher

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

评论：

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

CDPSession

CDPSession 实例用于讨论原始 Chrome Devtools 协议。

评论：

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

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

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

联系
ConsoleMessage

ConsoleMessage 对象通过 'console' 事件按页面调度。

评论：

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

覆盖范围

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

评论：

要以 伊斯坦布尔 可以使用的形式输出覆盖范围，请参阅 puppeteer-to-istanbul。

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

CSSCoverage
DeviceRequestPrompt

设备请求提示可让你通过 WebBluetooth 等 API 响应请求设备的页面。

评论：

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

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

DeviceRequestPromptDevice

设备处于请求提示状态。

评论：

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

对话

对话框实例由 页 通过 dialog 事件调度。

评论：

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

ElementHandle

ElementHandle 表示页内 DOM 元素。

评论：

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

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 元素被垃圾回收，除非句柄是 disposed。当其原始框架被导航时，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 类的子类。

框架

代表一个 DOM 框架。

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

评论：

框架生命周期由三个事件控制，这些事件都在父 page 上调度：

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

HTTPRequest

表示页面发送的 HTTP 请求。

评论：

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

  • request：当页面发送请求时触发。

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

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

所有这些事件都提供代表发生的请求的 HTTPRequest 实例：

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

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

如果请求收到 'redirect' 响应，则该请求已成功完成并发生 requestfinished 事件，并向重定向的 url 发送新请求。

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

HTTPResponse

HTTPResponse 类表示 页 类接收到的响应。

评论：

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

JSCoverage

评论：

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

JSHandle

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

句柄可防止引用的 JavaScript 对象被垃圾回收，除非句柄特意为 disposed。当 JSHandles 关联的框架被导航离开或父上下文被破坏时，JSHandles 会被自动处置。

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

评论：

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

键盘

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

评论：

为了更好地控制，你可以使用 Keyboard.down()、Keyboard.up() 和 Keyboard.sendCharacter() 手动触发事件，就像它们是从真正的键盘生成的一样。

在 macOS 上，诸如 ⌘ A -> 全选之类的键盘快捷键不起作用。参见 #1313。

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

定位器

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

详情请参阅 https://pptr.nodejs.cn/guides/page-interactions#locators。

Mouse

Mouse 类在相对于视口左上角的主框架 CSS 像素中运行。

评论：

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

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

页

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

注意

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

评论：

此类的构造函数被标记为内部构造函数。第三方代码不应直接调用构造函数或创建扩展 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 类公开触摸屏事件。

评论：

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

追踪

Tracing 类公开跟踪审计接口。

评论：

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

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

UnsupportedOperation

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

WebWorker

该类代表 WebWorker。

评论：

事件 workercreated 和 workerdestroyed 在页面对象上触发，以向工作线程生命周期发送信号。

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

枚举​

¥Enumerations

枚举

描述

BrowserContextEvent
BrowserEvent

浏览器实例 可能触发的所有事件。

InterceptResolutionAction
LocatorEvent

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

PageEvent

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

TargetType

函数​

¥Functions

函数

描述

connect(options)
defaultArgs(options)
executablePath(channel)
launch(options)
trimCache()

接口​

¥Interfaces

界面

描述

ActionOptions
AutofillData
BoundingBox
BoxModel
BrowserConnectOptions

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

BrowserContextEvents
BrowserContextOptions
BrowserEvents
BrowserLaunchArgumentOptions

仅适用于 Chrome 的启动器选项。

CDPSessionEvents
ChromeHeadlessShellSettings
ChromeSettings
ClickOptions
CommandOptions
CommonEventEmitter
配置

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

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

ConnectionTransport
ConnectOptions
ConsoleMessageLocation
ContinueRequestOverrides
Cookie

代表一个 cookie 对象。

CookieParam

Cookie 参数对象

CoverageEntry

CoverageEntry 类代表覆盖率报告的一项。

证书
CSSCoverageOptions

CSS 覆盖范围的一组可配置选项。

CustomQueryHandler
DebugInfo

（实验性）

DeleteCookiesRequest
设备
ElementScreenshotOptions
FirefoxSettings
FrameAddScriptTagOptions
FrameAddStyleTagOptions
FrameEvents
FrameWaitForFunctionOptions
GeolocationOptions
GoToOptions
InterceptResolutionState
InternalNetworkConditions
JSCoverageEntry

JavaScript 的 CoverageEntry 类

JSCoverageOptions

JS 覆盖率的一组可配置选项。

KeyboardTypeOptions
KeyDownOptions
LaunchOptions

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

LocatorEvents
LocatorScrollOptions
MediaFeature

要模拟的媒体功能。

指标
MouseClickOptions
MouseMoveOptions
MouseOptions
MouseWheelOptions
Moveable
NetworkConditions
NewDocumentScriptEvaluation
抵消
PageEvents

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

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

PDFMargin
PDFOptions

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

Point
PuppeteerLaunchOptions
QueryOptions
RemoteAddress
ResponseForRequest

满足请求所需的响应数据。

ScreencastOptions

（实验性）

ScreenshotClip
ScreenshotOptions
SerializedAXNode

表示一个节点及其与可访问性相关的属性。

SnapshotOptions
SupportedWebDriverCapabilities

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

TouchHandle

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

TracingOptions
视口
WaitForNetworkIdleOptions
WaitForOptions
WaitForSelectorOptions
WaitForTargetOptions
WaitTimeoutOptions

命名空间​

¥Namespaces

命名空间

描述

CDPSessionEvent

CDPSession 类触发的事件。

变量​

¥Variables

多变的

描述

DEFAULT_INTERCEPT_RESOLUTION_PRIORITY

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

KnownDevices

与 Page.emulate() 一起使用的设备列表。

MouseButton

有效鼠标按钮的枚举。

PredefinedNetworkConditions

与 Page.emulateNetworkConditions() 一起使用的预定义网络条件列表。

puppeteer

类型别名​

¥Type Aliases

类型别名

描述

ActionResult
等待的
AwaitableIterable
AwaitablePredicate
AwaitedLocator
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 的源的源方案。值 "取消设置" 允许协议客户端模拟该方案的旧 cookie 范围。这是暂时的能力，将来会被删除。

ElementFor
ErrorCode
EvaluateFunc
EvaluateFuncWith
EventsWithWildcard
EventType
ExperimentsConfiguration

定义 Puppeteer 的实验选项。

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

FlattenHandle
HandleFor
HandleOr
处理程序
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.1102in x 46.811in

  • A1：23.3858in x 33.1102in

  • A2：16.5354in x 23.3858in

  • A3：11.6929in x 16.5354in

  • A4：8.2677in x 11.6929in

  • A5：5.8268in x 8.2677in

  • A6：4.1339in x 5.8268in

Permission
Predicate
ProtocolLifeCycleEvent
ProtocolType
PuppeteerLifeCycleEvent
PuppeteerNodeLaunchOptions

公开工具类型，使用户能够定义可传递给 puppeteer.launch 的选项，而无需列出所有类型的集合。

Quad
ResourceType

渲染引擎感知到的 HTTPRequest 的资源类型。

SupportedBrowser

Puppeteer 支持的浏览器。

SupportedWebDriverCapability
TargetFilterCallback
VisibilityOption

是否等待元素为 visible 或 hidden。null 禁用可见性检查。