API 参考

类

类	说明
Accessibility	Accessibility 类提供了用于检查浏览器无障碍树的方法。无障碍树被辅助技术使用，例如屏幕阅读器或开关。备注：无障碍是一个非常依赖平台的概念。在不同的平台上，有不同的屏幕阅读器，它们的输出可能差异巨大。 Blink（Chrome 的渲染引擎）有一个「accessibility tree」（无障碍树）的概念，它会被转换为不同的平台特定 API。Accessibility 命名空间让用户可以访问 Blink 无障碍树。在从 Blink AX Tree 转换为平台特定的 AX-Tree 时，或者由辅助技术自身进行转换时，无障碍树的大部分内容都会被过滤掉。默认情况下，Puppeteer 会尝试近似模拟这种过滤，只暴露树中「有趣」的节点。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Accessibility` 类的子类。
Browser	Browser 表示一个浏览器实例，它可以是：通过 Puppeteer.connect() 连接，或 - 由 PuppeteerNode.launch() 启动。 Browser 会触发多种事件，这些事件记录在 BrowserEvent 枚举中。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Browser` 类的子类。
BrowserContext	BrowserContext 表示浏览器内的各个用户上下文。当浏览器启动时，它至少有一个默认的浏览器上下文。可以使用 Browser.createBrowserContext() 创建其他上下文。每个上下文都有隔离的存储（cookies/localStorage 等）。 BrowserContext 会触发多种事件，这些事件记录在 BrowserContextEvent 枚举中。如果页面打开另一个页面，例如使用 `window.open`，那么弹出的窗口将属于父页面的浏览器上下文。备注：在 Chrome 中，所有非默认上下文都是隐身模式，如果你在启动浏览器时提供了 `--incognito` 参数，默认浏览器上下文也可能是隐身模式。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `BrowserContext` 类的子类。
BrowserLauncher	描述了一个启动器——一个能够创建并启动浏览器实例的类。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `BrowserLauncher` 类的子类。
CDPSession	`CDPSession` 实例用于直接与原始 Chrome DevTools 协议进行通信。备注：可以使用 CDPSession.send() 方法调用协议方法，也可以使用 `CDPSession.on` 方法订阅协议事件。有用链接：DevTools 协议查看器和 DevTools 协议入门。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `CDPSession` 类的子类。
Connection	备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Connection` 类的子类。
ConnectionClosedError	如果底层协议连接已关闭，则抛出此错误。
ConsoleMessage	ConsoleMessage 对象由页面通过 'console' 事件分发。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `ConsoleMessage` 类的子类。
Coverage	Coverage 类提供了收集页面所使用的 JavaScript 和 CSS 部分信息的方法。备注：要以 Istanbul 可消费的形式输出覆盖率，请参阅 puppeteer-to-istanbul。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Coverage` 类的子类。
CSSCoverage
DeviceRequestPrompt	设备请求提示让你可以响应页面通过 WebBluetooth 等 API 发起的设备请求。备注： `DeviceRequestPrompt` 实例通过 Page.waitForDevicePrompt() 方法返回。
Dialog	Dialog 实例由 Page 通过 `dialog` 事件分发。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Dialog` 类的子类。
ElementHandle	ElementHandle 表示页面内的 DOM 元素。备注：可以使用 Page.$() 方法创建 ElementHandle。 `import puppeteer from 'puppeteer'; 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 元素被垃圾回收。当关联的框架被导航离开或父上下文被销毁时，ElementHandle 会被自动释放。 ElementHandle 实例可以用作 Page.$eval() 和 Page.evaluate() 方法的参数。如果你使用 TypeScript，ElementHandle 接受一个泛型参数，用于表示句柄所持有的元素类型。例如，如果你有一个指向 `<select>` 元素的句柄，你可以将其类型写为 `ElementHandle<HTMLSelectElement>`，这样就能获得更好的类型检查。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `ElementHandle` 类的子类。
EventEmitter	EventEmitter 类，许多 Puppeteer 类都继承自它。备注：这使你可以监听 Puppeteer 类触发的各种事件并作出相应处理。因此，你大多会使用 on 和 off 来绑定和解绑事件监听器。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `EventEmitter` 类的子类。
Extension	*(实验性)* Extension 表示浏览器中安装的浏览器扩展。它提供对扩展的 ID、名称和版本的访问，以及与扩展的后台工作线程和页面交互的方法。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Extension` 类的子类。
ExtensionTransport	*(实验性)* 实验性的 ExtensionTransport 允许在 Puppeteer 运行于扩展中时，通过 chrome.debugger API 建立连接。由于 Chrome DevTools 协议对扩展有限制，该 transport 实现了缺失的命令和事件。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `ExtensionTransport` 类的子类。
FileChooser	文件选择器让你可以响应页面发起的文件请求。备注： `FileChooser` 实例通过 Page.waitForFileChooser() 方法返回。在浏览器中，同一时间只能打开一个文件选择器。所有文件选择器都必须被接受或取消，否则后续的文件选择器将无法出现。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `FileChooser` 类的子类。
Frame	表示一个 DOM 框架。要理解框架，你可以把框架想象成 `<iframe>` 元素。与 iframe 一样，框架可以嵌套，当 JavaScript 在某个框架中执行时，该 JavaScript 不会影响其执行所在框架内部的框架。备注：框架的生命周期由三个事件控制，这些事件都在父页面上分发： PageEvent.FrameAttached - PageEvent.FrameNavigated - PageEvent.FrameDetached 此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `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 类表示由 Page 类接收到的响应。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `HTTPResponse` 类的子类。
JSCoverage	备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `JSCoverage` 类的子类。
JSHandle	表示对 JavaScript 对象的引用。可以使用 Page.evaluateHandle() 创建实例。除非句柄被有意释放，否则句柄会阻止所引用的 JavaScript 对象被垃圾回收。当关联的框架被导航离开或父上下文被销毁时，JSHandle 会被自动释放。句柄可以用作任何求值函数的参数，例如 Page.$eval()、Page.evaluate() 和 Page.evaluateHandle()。它们会被解析为其引用的对象。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `JSHandle` 类的子类。
Keyboard	Keyboard 提供了管理虚拟键盘的 API。高级 API 是 Keyboard.type()，它接收原始字符并在你的页面上生成相应的 keydown、keypress/input 和 keyup 事件。备注：如需更精细的控制，你可以使用 Keyboard.down()、Keyboard.up() 和 Keyboard.sendCharacter() 手动触发事件，就像这些事件是由真实键盘生成的一样。在 macOS 上，`⌘ A` -> 全选等键盘快捷键不起作用。请参阅 #1313。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Keyboard` 类的子类。
Locator	定位器描述了一种定位对象并对其执行操作的策略。如果由于对象尚未准备好而操作失败，整个操作会被重试。成功操作的各种前置条件会被自动检查。详情请参阅 https://pptr.dev/guides/page-interactions#locators。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Locator` 类的子类。
Mouse	Mouse 类以主框架的 CSS 像素为单位进行操作，坐标相对于视口的左上角。备注：每个 `page` 对象都有自己的 Mouse，可以通过 Page.mouse 访问。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Mouse` 类的子类。
Page	Page 提供了与浏览器中的单个标签页或扩展后台页面交互的方法。 ℹ️注意一个 Browser 实例可能包含多个 Page 实例。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Page` 类的子类。
ProtocolError	每当协议出现错误时，就会触发 ProtocolError。
Puppeteer	Puppeteer 的主类。重要提示：如果你在 Node 环境中使用 Puppeteer，那么当你 import 或 require `puppeteer` 时，你将获得一个 PuppeteerNode 实例。该类继承了 `Puppeteer`，因此拥有下面记录的所有方法，以及 PuppeteerNode 上定义的所有方法。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Puppeteer` 类的子类。
PuppeteerError	所有 Puppeteer 特定错误的基类备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `PuppeteerError` 类的子类。
PuppeteerNode	在主 Puppeteer 类的基础上扩展了 Node 特有的获取和下载浏览器的行为。如果你在 Node 环境中使用 Puppeteer，那么当你运行 `import puppeteer from 'puppeteer'` 时，你得到的就是这个类。备注：最常用的方法是 launch，它用于启动并连接到新的浏览器实例。主 Puppeteer 类中记录了所有环境通用的方法，例如 Puppeteer.connect()。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `PuppeteerNode` 类的子类。
Realm	备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Realm` 类的子类。
ScreenRecorder	备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `ScreenRecorder` 类的子类。
SecurityDetails	SecurityDetails 类表示通过安全连接接收到的响应的安全详细信息。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `SecurityDetails` 类的子类。
Target	Target 表示一个 CDP 目标。在 CDP 中，目标是可以被调试的东西，例如框架、页面或工作线程。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Target` 类的子类。
TimeoutError	每当某些操作因超时而终止时，就会触发 TimeoutError。备注：示例操作包括 page.waitForSelector 或 puppeteer.launch。
TouchError	当尝试移动或结束一个不存在的触摸时，会抛出 TouchError。
Touchscreen	Touchscreen 类暴露触摸屏事件。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Touchscreen` 类的子类。
Tracing	Tracing 类暴露追踪审计接口。备注：你可以使用 `tracing.start` 和 `tracing.stop` 创建追踪文件，该文件可以在 Chrome DevTools 或时间线查看器中打开。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `Tracing` 类的子类。
UnsupportedOperation	如果当前使用的协议不支持某个方法，Puppeteer 将抛出此错误
WebMCP	*(实验性)* 实验性的 WebMCP 类为 WebMCP API 提供 API。更多详情请参阅 WebMCP 指南。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `WebMCP` 类的子类。
WebMCPTool	表示页面上可用的已注册 WebMCP 工具。备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `WebMCPTool` 类的子类。
WebMCPToolCall	备注：此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `WebMCPToolCall` 类的子类。
WebWorker	此类表示一个 WebWorker。备注： `workercreated` 和 `workerdestroyed` 事件在页面对象上触发，用于表示工作线程的生命周期。此类的构造函数被标记为内部。第三方代码不应直接调用构造函数，也不应创建扩展 `WebWorker` 类的子类。

枚举

枚举	说明
AutofillAddressField	支持的自动填充地址字段名称。
BrowserContextEvent
BrowserEvent	浏览器实例可能触发的所有事件。
InterceptResolutionAction
LocatorEvent	定位器实例可能触发的所有事件。
PageEvent	页面实例可能触发的所有事件。
TargetType
WebWorkerEvent

函数

函数	说明
connect(options)
defaultArgs(options)
launch(options)
trimCache()

接口

接口	说明
ActionOptions
AddScreenParams
BluetoothEmulation	*(实验性)* 暴露蓝牙模拟能力。备注： Web Bluetooth 规范要求模拟适配器按顶级可导航单元进行隔离。然而，目前 Chromium 的蓝牙模拟实现与浏览器上下文绑定，而不是与页面绑定。这意味着，同一浏览器上下文中不同页面暴露的蓝牙模拟会相互干扰彼此的状态。
BluetoothManufacturerData	表示模拟蓝牙外设的制造商数据。
BoundingBox
BoxModel
BrowserContextEvents
BrowserContextOptions
BrowserEvents
CDPSessionEvents
ChromeHeadlessShellSettings
ChromeSettings
ClickOptions
CommandOptions
CommonEventEmitter
Configuration	定义用于配置 Puppeteer 在安装和运行期间行为的选项。更多信息请参阅各个属性。
ConnectionTransport
ConnectOptions	启动任何浏览器或连接到现有浏览器实例时可以传递的通用浏览器选项。
ConsoleMessageLocation
ContinueRequestOverrides
Cookie	表示一个 cookie 对象。
CookieData	用于在浏览器级别的 cookies API 中设置 cookie 的 cookie 参数对象。
CookieParam	用于在页面级别的 cookies API 中设置 cookie 的 cookie 参数对象。
CookiePartitionKey	表示 Chrome 中的 cookie 分区键。
CoverageEntry	CoverageEntry 类表示覆盖率报告中的一个条目。
Credentials
CSSCoverageOptions	CSS 覆盖率的一组可配置选项。
CustomQueryHandler
DebugInfo	*(实验性)*
DeleteCookiesRequest
Device
DeviceRequestPromptDevice	请求提示中的设备。
DownloadBehavior
ElementScreenshotOptions
ExtensionInstallOptions
FirefoxSettings
FrameAddScriptTagOptions
FrameAddStyleTagOptions
FrameEvents
FrameWaitForFunctionOptions
GeolocationOptions
GetPWAStateOptions	Browser.getPWAState() 的选项。
GoToOptions
HeapSnapshotOptions	Page.captureHeapSnapshot() 的选项。
InstallPWAOptions	Browser.installPWA() 的选项。
InterceptResolutionState
InternalNetworkConditions
Issue	Issue 接口表示一个 DevTools 问题。
JSCoverageEntry	用于 JavaScript 的 CoverageEntry 类
JSCoverageOptions	JS 覆盖率的一组可配置选项。
KeyboardTypeOptions
KeyDownOptions
LaunchOptions	启动任何浏览器时可以传递的通用启动选项。
LaunchPWAOptions	Browser.launchPWA() 的选项。
LocatorEvents
LocatorFillOptions
LocatorScrollOptions
MediaFeature	要模拟的媒体特性。
Metrics
MouseClickOptions
MouseMoveOptions
MouseOptions
MouseWheelOptions
Moveable
NetworkConditions
NewDocumentScriptEvaluation
Offset
PageEvents	表示页面事件的回调函数接收到的对象。有关这些事件及其触发时机的更多详情，请参阅 PageEvent。
PDFMargin
PDFOptions	通过 Page.pdf() 配置 PDF 生成的有效选项。
PermissionDescriptor_2
Point
PreconnectedPeripheral	要模拟的蓝牙外设。
PWAState	已安装 Web 应用的 OS 集成状态，由 Browser.getPWAState() 返回。
QueryOptions
ReloadOptions
RemoteAddress
ResponseForRequest	用于完成请求所需的响应数据。
ScreencastOptions	*(实验性)*
ScreenInfo
ScreenOrientation_2
ScreenshotClip
ScreenshotOptions
SerializedAXNode	表示一个节点及其与无障碍相关的属性。
SetContentWaitForOptions
SnapshotOptions
SupportedWebDriverCapabilities	不是由 Puppeteer 自身设置的 WebDriver BiDi 能力。
TouchHandle	TouchHandle 接口暴露了用于操作已启动触摸的方法
TracingOptions
UninstallPWAOptions	Browser.uninstallPWA() 的选项。
Viewport
WaitForNetworkIdleOptions
WaitForOptions
WaitForSelectorOptions
WaitForTargetOptions
WaitTimeoutOptions
WebMCPToolCallResult
WebMCPToolsAddedEvent
WebMCPToolsRemovedEvent
WebWorkerEvents
WindowBounds
WorkAreaInsets

命名空间

命名空间	说明
CDPSessionEvent	CDPSession 类触发的事件。

变量

变量	说明
asyncDisposeSymbol
DEBUG_PREFIXES	*(实验性)*
DEFAULT_INTERCEPT_RESOLUTION_PRIORITY	默认的协作式请求拦截解析优先级
disposeSymbol
executablePath
KnownDevices	用于与 Page.emulate() 配合使用的设备列表。
MouseButton	有效鼠标按钮的枚举。
PredefinedNetworkConditions	用于与 Page.emulateNetworkConditions() 配合使用的预定义网络条件列表。
puppeteer

类型别名

类型别名	说明
ActionResult
AdapterState	模拟的蓝牙适配器状态。
AutofillData
Awaitable
AwaitableIterable
AwaitablePredicate
AwaitedLocator
CDPEvents
ChromeReleaseChannel
ConsoleMessageType	控制台消息支持的类型。
CookiePriority	表示 cookie 的 'Priority' 状态：https://tools.ietf.org/html/draft-west-cookie-priority-00
CookieSameSite_2	表示 cookie 的 'SameSite' 状态：https://tools.ietf.org/html/draft-west-first-party-cookies
CookieSourceScheme	表示最初设置 cookie 的来源的源方案。值 "Unset" 允许协议客户端模拟该方案的旧版 cookie 作用域。这是一种临时能力，将来会被移除。
CreatePageOptions
DebugPrefix	*(实验性)*
DownloadPolicy
ElementFor
ErrorCode
EvaluateFunc
EvaluateFuncWith
EventsWithWildcard
EventType
ExperimentsConfiguration	定义 Puppeteer 的实验选项。更多信息请参阅各个属性。
FlattenHandle
HandleFor
HandleOr
Handler
ImageFormat
InnerParams
KeyInput	可以传递给接受用户输入的函数的所有有效按键，例如 keyboard.press
KeyPressOptions
LocatorClickOptions
Logger	*(实验性)* 一个日志器工厂函数，它接收调试通道前缀，并返回一个 LoggerFunction 用于输出该通道的日志；如果该通道的日志记录被禁用，则返回 `undefined`。
LoggerFunction	*(实验性)* 由 Puppeteer 调用来输出调试消息的函数。
LowerCasePaperFormat
Mapper
MouseButton
NodeFor
PaperFormat	打印 PDF 时所有有效的纸张格式类型。备注：每种格式的尺寸如下： `Letter`: 8.5in x 11in / 21.59cm x 27.94cm `Legal`: 8.5in x 14in / 21.59cm x 35.56cm `Tabloid`: 11in x 17in / 27.94cm x 43.18cm `Ledger`: 17in x 11in / 43.18cm x 27.94cm `A0`: 33.1102in x 46.811in / 84.1cm x 118.9cm `A1`: 23.3858in x 33.1102in / 59.4cm x 84.1cm `A2`: 16.5354in x 23.3858in / 42cm x 59.4cm `A3`: 11.6929in x 16.5354in / 29.7cm x 42cm `A4`: 8.2677in x 11.6929in / 21cm x 29.7cm `A5`: 5.8268in x 8.2677in / 14.8cm x 21cm `A6`: 4.1339in x 5.8268in / 10.5cm x 14.8cm
Permission	已废弃：推荐使用。
PermissionState_2
Predicate
ProtocolLifeCycleEvent
ProtocolType
PuppeteerLifeCycleEvent
PWADisplayMode	用户是更倾向于在独立窗口中打开已安装的 Web 应用，还是在浏览器标签页中打开。
Quad
ResourceType	渲染引擎所感知到的 HTTPRequest 的资源类型。
SupportedBrowser	Puppeteer 支持的浏览器。
SupportedWebDriverCapability
TargetFilterCallback
VideoFormat
VisibilityOption	是否等待元素可见或隐藏。传入 `null` 以禁用可见性检查。
WindowId
WindowState