Page 类

accessibility

readonly

Accessibility

Accessibility 类提供了检查浏览器无障碍树的方法。无障碍树被辅助技术使用，例如屏幕阅读器或开关控制。

备注：

无障碍是一个高度依赖平台的问题。在不同的平台上，有不同的屏幕阅读器，它们的输出可能差异巨大。

Blink（Chrome 的渲染引擎）有一个"无障碍树"的概念，它会被转换为不同平台特定的 API。Accessibility 命名空间使用户能够访问 Blink 无障碍树。

在从 Blink AX 树转换为平台特定的 AX 树时，或者由辅助技术本身处理时，无障碍树的大部分内容会被过滤掉。默认情况下，Puppeteer 会尝试近似这种过滤，只暴露树中"有趣"的节点。

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

bluetooth

readonly

BluetoothEmulation

公开蓝牙仿真能力。

备注：

Web Bluetooth 规范要求仿真适配器应按顶层可导航单元（top-level navigable）隔离。然而，目前 Chromium 的蓝牙仿真实现与浏览器上下文绑定，而不是与页面绑定。这意味着从同一浏览器上下文的不同页面暴露的蓝牙仿真会相互干扰各自的状态。

coverage

readonly

Coverage

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

备注：

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

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

keyboard

readonly

Keyboard

Keyboard 提供了管理虚拟键盘的 API。高级 API 是 Keyboard.type()，它接收原始字符并在你的页面上生成相应的 keydown、keypress/input 和 keyup 事件。

备注：

如需更精细的控制，你可以使用 Keyboard.down()、Keyboard.up() 和 Keyboard.sendCharacter() 手动触发事件，就像这些事件是由真实键盘生成的一样。

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

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

mouse

readonly

Mouse

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

备注：

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

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

touchscreen

readonly

Touchscreen

Touchscreen 类公开触摸屏事件。

tracing

readonly

Tracing

Tracing 类公开了追踪审查接口。

备注：

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

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

webmcp

readonly

WebMCP

（实验性） 面向 WebMCP 的实验性 API。需要 Chrome 151 及以上版本，并启用 --enable-features=WebMCP 标志。

[asyncDisposeSymbol]()

[disposeSymbol]()

$(selector)

查找与选择器匹配的第一个元素。如果没有元素与选择器匹配，返回值将解析为 null。

备注：

是 Page.mainFrame().$(selector) 的快捷方式。

$$(selector, options)

查找页面上与选择器匹配的元素。如果没有元素与选择器匹配，返回值将解析为 []。

备注：

是 Page.mainFrame().$$(selector) 的快捷方式。

$$eval(selector, pageFunction, args)

此方法返回与选择器匹配的所有元素，并将结果数组作为第一个参数传递给 pageFunction。

备注：

如果 pageFunction 返回 promise，$$eval 将等待 promise 解析，然后返回其值。

$eval(selector, pageFunction, args)

此方法查找页面内与选择器匹配的第一个元素，并将结果作为第一个参数传递给 pageFunction。

备注：

如果找不到与 selector 匹配的元素，该方法将抛出错误。

如果 pageFunction 返回 promise，$eval 将等待 promise 解析，然后返回其值。

addScriptTag(options)

将带有所需 URL 或内容的 <script> 标签添加到页面中。

备注：

是 page.mainFrame().addScriptTag(options) 的快捷方式。

addStyleTag(options)

将带有所需 URL 的 <link rel="stylesheet"> 标签或带有内容的 <style type="text/css"> 标签添加到页面中。

是 page.mainFrame().addStyleTag(options) 的快捷方式。

addStyleTag(options)

authenticate(credentials)

为 HTTP authentication 提供凭据。

备注：

要禁用认证，请传入 null。

bringToFront()

将页面带到前台（激活标签页）。

browser()

获取该页面所属的浏览器。

browserContext()

获取该页面所属的浏览器上下文。

captureHeapSnapshot(options)

捕获 JavaScript 堆的快照并将其写入文件。

click(selector, options)

此方法获取与 selector 匹配的元素，在需要时将其滚动到视图中，然后使用 Page.mouse 点击元素的中心。如果没有与 selector 匹配的元素，该方法会抛出错误。

备注：

请注意，如果 click() 触发了导航事件，并且还有一个独立的 page.waitForNavigation() promise 待解析，你可能会遇到竞态条件，产生意外结果。点击并等待导航的正确模式如下：

const [response] = await Promise.all([
  page.waitForNavigation(waitOptions),
  page.click(selector, clickOptions),
]);

是 page.mainFrame().click(selector[, options]) 的快捷方式。

close(options)

content()

页面的完整 HTML 内容，包括 DOCTYPE。

cookies(urls)

deprecated

如果未指定 URL，此方法返回当前页面 URL 的 Cookie。如果指定了 URL，则只返回这些 URL 的 Cookie。

已废弃：

页面级 Cookie API 已废弃。请改用 Browser.cookies() 或 BrowserContext.cookies()。

createCDPSession()

创建附加到该页面的 Chrome DevTools 协议会话。

createPDFStream(options)

使用 print CSS 媒体类型生成页面的 PDF。

备注：

要使用 screen 媒体类型生成 PDF，请在调用 page.pdf() 之前调用 `page.emulateMediaType('screen')`。

默认情况下，page.pdf() 生成的 PDF 会为打印修改颜色。请使用 `-webkit-print-color-adjust` 属性强制渲染精确的颜色。

deleteCookie(cookies)

deprecated

已废弃：

页面级 Cookie API 已废弃。请改用 Browser.deleteCookie()、BrowserContext.deleteCookie()、Browser.deleteMatchingCookies() 或 BrowserContext.deleteMatchingCookies()。

emulate(device)

模拟给定设备的指标和用户代理。

为辅助模拟，Puppeteer 提供了一份已知设备列表，可通过 KnownDevices 获取。

备注：

此方法是调用两个方法的快捷方式：Page.setUserAgent() 和 Page.setViewport()。

此方法会调整页面大小。许多网站并不期望手机改变尺寸，因此你应该在导航到页面之前进行模拟。

emulateCPUThrottling(factor)

启用 CPU 节流以模拟慢速 CPU。

emulateFocusedPage(enabled)

模拟页面的焦点状态。

emulateIdleState(overrides)

模拟空闲状态。如果未设置任何参数，则清除空闲状态模拟。

emulateLocale(locale)

emulateMediaFeatures(features)

emulateMediaType(type)

emulateNetworkConditions(networkConditions)

这不会影响 WebSocket 和 WebRTC PeerConnection（参见 https://crbug.com/563644）。要将页面设为离线，可以使用 Page.setOfflineMode()。

可以通过导入 PredefinedNetworkConditions 来使用预定义的网络条件列表。

emulateTimezone(timezoneId)

emulateVisionDeficiency(type)

在页面上模拟给定的视觉缺陷。

evaluate(pageFunction, args)

在页面的上下文中求值一个函数，并返回结果。

如果传给 page.evaluate 的函数返回一个 Promise，则该方法会等待该 Promise 解析，并返回其值。

evaluateHandle(pageFunction, args)

备注：

page.evaluate 与 page.evaluateHandle 之间的唯一区别是 evaluateHandle 会将返回值包装在页内对象中。

如果传给 page.evaluateHandle 的函数返回 Promise，该函数将等待 promise 解析并返回其值。

你可以传入字符串而不是函数（不过推荐使用函数，因为函数更易于调试，并且可以配合 TypeScript 使用）：

evaluateOnNewDocument(pageFunction, args)

添加一个函数，该函数将在以下任一场景中被调用：

• 每当页面被导航时

• 每当子框架被附加或导航时。在这种情况下，该函数会在新附加的框架的上下文中被调用。

该函数在文档创建之后、任何脚本运行之前被调用。这对于修改 JavaScript 环境很有用，例如为 Math.random 播种。

exposeFunction(name, pptrFunction)

该方法在页面的 window 对象上添加一个名为 name 的函数。调用时，该函数会在 node.js 中执行 puppeteerFunction，并返回一个 Promise，该 Promise 解析为 puppeteerFunction 的返回值。

如果 puppeteerFunction 返回 Promise，该 Promise 将被 await。

extensionRealms()

获取页面主框架中的扩展执行环境列表。这些环境对应于在页面上运行的扩展内容脚本。

是 mainFrame().extensionRealms() 的快捷方式。

focus(selector)

此方法获取与 selector 匹配的元素并使其获得焦点。如果没有与 selector 匹配的元素，该方法会抛出错误。

备注：

是 page.mainFrame().focus(selector) 的快捷方式。

frames()

附加到页面的所有框架的数组。

getDefaultNavigationTimeout()

最大导航时间（毫秒）。

getDefaultTimeout()

最大时间（毫秒）。

goBack(options)

此方法导航到历史记录中的上一个页面。

goForward(options)

此方法导航到历史记录中的下一个页面。

goto(url, options)

将框架或页面导航到给定的 url。

备注：

导航到 about:blank 或使用不同哈希导航到相同 URL 将成功并返回 null。

在无头 shell 中，当远程服务器返回任何有效的 HTTP 状态码（包括 404 "Not Found" 和 500 "Internal Server Error"）时，此方法不会抛出错误。此类响应的状态码可以通过调用 HTTPResponse.status() 获取。

hasDevTools()

（实验性） 如果 DevTools 已附加到当前页面，则返回 true。使用 Page.openDevTools() 获取 DevTools 页面。

hover(selector)

此方法获取与 selector 匹配的元素，在需要时将其滚动到视图中，然后使用 Page.mouse 悬停在元素的中心。如果没有与 selector 匹配的元素，该方法会抛出错误。

备注：

是 page.mainFrame().hover(selector) 的快捷方式。

isClosed()

指示页面已关闭。

isDragInterceptionEnabled()

deprecated

如果正在拦截拖拽事件，则为 true，否则为 false。

已废弃：

我们不再支持拦截拖拽负载。请使用 ElementHandle 上的新拖拽 API 进行拖拽（或直接使用 Page.mouse）。

isJavaScriptEnabled()

如果页面启用了 JavaScript，则为 true，否则为 false。

isServiceWorkerBypassed()

如果 service worker 被绕过，则为 true，否则为 false。

locator(selector)

为提供的选择器创建定位器。有关详细信息和受支持的操作，请参阅 Locator。

locator(func)

为提供的函数创建定位器。有关详细信息和受支持的操作，请参阅 Locator。

mainFrame()

页面的主框架。

metrics()

包含指标（以键/值对形式）的对象。

备注：

所有时间戳都使用单调时间：自过去任意一点以来单调递增的秒数。

openDevTools()

如果尚未打开，则为该页面打开 DevTools，并返回 DevTools 页面。此方法仅在 Chrome 中可用。

pdf(options)

使用 print CSS 媒体类型生成页面的 PDF。

备注：

要使用 screen 媒体类型生成 PDF，请在调用 page.pdf() 之前调用 `page.emulateMediaType('screen')`。

默认情况下，page.pdf() 生成的 PDF 会为打印修改颜色。请使用 `-webkit-print-color-adjust` 属性强制渲染精确的颜色。

queryObjects(prototypeHandle)

此方法遍历 JavaScript 堆，查找所有具有给定原型的对象。

reload(options)

重新加载页面。

removeExposedFunction(name)

该方法会从页面的 window 对象中移除先前通过 $Page.exposeFunction() 添加的名为 name 的函数。

removeScriptToEvaluateOnNewDocument(identifier)

移除由 Page.evaluateOnNewDocument 注入到页面中的脚本。

resize(params)

（实验性） 调整此页面的浏览器窗口大小，使内容区域（不包括浏览器 UI）具有指定的宽度和高度。

screencast(options)

（实验性） 捕获此页面的屏幕录像。

备注：

默认情况下，所有录制内容都将使用 WebM 格式，采用 VP9 视频编解码器，帧率为 30 FPS。

你的系统上必须安装 ffmpeg。

screenshot(options)

捕获此页面的截图。

备注：

在 BrowserContext 中拍摄截图时，以下方法将自动等待截图完成，以防止干扰截图过程：BrowserContext.newPage()、Browser.newPage()、Page.close()。

调用 Page.bringToFront() 不会等待现有的截图操作。

screenshot(options)

select(selector, values)

一旦所有提供的选项都被选中，就会触发 change 和 input 事件。如果没有与 selector 匹配的 <select> 元素，该方法会抛出错误。

备注：

是 page.mainFrame().select() 的快捷方式。

setBypassCSP(enabled)

切换绕过页面的内容安全策略（Content-Security-Policy）。

备注：

注意：CSP 绕过发生在 CSP 初始化时，而非求值时。通常，这意味着 page.setBypassCSP 应在导航到该域名之前调用。

setBypassServiceWorker(bypass)

切换对每个请求忽略 service worker。

setCacheEnabled(enabled)

根据启用状态切换对每个请求忽略缓存。默认情况下，缓存是启用的。

setContent(html, options)

设置页面的内容。

setCookie(cookies)

deprecated

已废弃：

页面级 Cookie API 已废弃。请改用 Browser.setCookie() 或 BrowserContext.setCookie()。

setDefaultNavigationTimeout(timeout)

此设置将更改以下方法及相关快捷方式的默认最大导航时间：

• page.goBack(options)

• page.goForward(options)

• page.goto(url,options)

• page.reload(options)

• page.setContent(html,options)

• page.waitForNavigation(options)

setDefaultTimeout(timeout)

setDragInterception(enabled)

deprecated

已废弃：

我们不再支持拦截拖拽负载。请使用 ElementHandle 上的新拖拽 API 进行拖拽（或直接使用 Page.mouse）。

setExtraHTTPHeaders(headers)

额外的 HTTP 标头将随页面发起的每个请求一起发送。

setGeolocation(options)

设置页面的地理位置。

备注：

请考虑使用 BrowserContext.overridePermissions() 授予页面读取其地理位置的权限。

setJavaScriptEnabled(enabled)

备注：

注意：更改此值不会影响已经运行过的脚本。它将在下次导航时完全生效。

setOfflineMode(enabled)

模拟离线模式。

它不会更改由 Page.emulateNetworkConditions() 设置的上传/下载/延迟参数。

setRequestInterception(value)

激活请求拦截可以启用 HTTPRequest.abort()、HTTPRequest.continue() 和 HTTPRequest.respond() 方法。这提供了修改页面发出的网络请求的能力。

一旦启用请求拦截，每个请求都会停滞，除非它被继续、响应、中止，或通过浏览器缓存完成。

有关更多详细信息，请参阅请求拦截指南。

setUserAgent(userAgent, userAgentMetadata)

deprecated

已废弃：

请改用 Page.setUserAgent()。

setUserAgent(options)

setViewport(viewport)

page.setViewport 会调整页面大小。许多网站并不期望手机改变尺寸，因此你应该在导航到页面之前设置视口。

在单个浏览器中有多个页面的情况下，每个页面都可以有自己的视口大小。将视口设置为 null 会将视口重置为其默认值。

备注：

注意：在某些情况下，设置视口会重新加载页面，以便设置 isMobile 或 hasTouch 属性。

tap(selector)

此方法获取与 selector 匹配的元素，在需要时将其滚动到视图中，然后使用 Page.touchscreen 点击元素的中心。如果没有与 selector 匹配的元素，该方法会抛出错误。

备注：

是 page.mainFrame().tap(selector) 的快捷方式。

target()

deprecated

创建此页面的目标。

已废弃：

要创建 CDP 会话，请直接使用 Page.createCDPSession()。要识别由此页面产生的页面，请改用 PageEvent.Popup 事件。

title()

页面的标题。

备注：

是 page.mainFrame().title() 的快捷方式。

triggerExtensionAction(extension)

触发指定扩展针对此页面的默认操作。这会模拟在浏览器工具栏中点击扩展的图标。

type(selector, text, options)

为文本中的每个字符发送 keydown、keypress/input 和 keyup 事件。

要按下特殊键（如 Control 或 ArrowDown），请使用 Keyboard.press()。

url()

页面的 URL。

备注：

是 page.mainFrame().url() 的快捷方式。

viewport()

返回当前页面的视口设置，而不检查实际的页面视口。

这要么是先前通过 Page.setViewport() 调用设置的视口，要么是通过 ConnectOptions.defaultViewport 设置的默认视口。

waitForDevicePrompt(options)

此方法通常与触发设备请求的操作配合使用，例如来自 WebBluetooth 等 API 的请求。

waitForFileChooser(options)

此方法通常与触发文件选择的操作配合使用。

备注：

在"有头"浏览器中，此方法会导致本机文件选择器对话框对用户不显示。

waitForFrame(urlOrPredicate, options)

等待与给定条件匹配的框架出现。

waitForFunction(pageFunction, options, args)

等待提供的函数 pageFunction 在页面的上下文中求值时返回真值。

waitForNavigation(options)

等待页面导航到新 URL 或重新加载。当你运行的代码会间接导致页面导航时，这很有用。

备注：

使用 History API 更改 URL 被视为一次导航。

waitForNetworkIdle(options)

等待网络空闲。

备注：

该函数将始终至少等待设定的 IdleTime。

waitForRequest(urlOrPredicate, options)

备注：

可选等待参数有：

• timeout：最大等待时间（毫秒），默认为 30 秒，传入 0 可禁用超时。可以使用 Page.setDefaultTimeout() 方法更改默认值。

• signal：允许你取消 waitForRequest 调用的信号对象。

waitForResponse(urlOrPredicate, options)

备注：

可选参数有：

• timeout：最大等待时间（毫秒），默认为 30 秒，传入 0 可禁用超时。可以使用 Page.setDefaultTimeout() 方法更改默认值。

• signal：允许你取消 waitForResponse 调用的信号对象。

waitForSelector(selector, options)

等待 selector 出现在页面中。如果在调用方法时 selector 已经存在，该方法将立即返回。如果在等待了 timeout 毫秒后 selector 仍未出现，该函数将抛出错误。

备注：

参数 options 中的可选参数有：

• visible：布尔值，等待元素出现在 DOM 中并且可见，即不具有 display: none 或 visibility: hidden CSS 属性。默认为 false。

• hidden：等待元素在 DOM 中找不到或被隐藏，即具有 display: none 或 visibility: hidden CSS 属性。默认为 false。

• timeout：最大等待时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。可以使用 Page.setDefaultTimeout() 方法更改默认值。

• signal：允许你取消 waitForSelector 调用的信号对象。

windowId()

（实验性） 返回页面的窗口 ID。

workers()

与页面关联的所有专用 WebWorkers。

备注：

这不包含 ServiceWorker。