页面类

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

注意

一个 Browser 实例可能具有多个 Page 实例。

签名

export declare abstract class Page extends EventEmitter<PageEvents>

继承自： EventEmitter<PageEvents>

备注

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

示例 1

此示例创建一个页面，将其导航到 URL，然后保存屏幕截图

import puppeteer from 'puppeteer';

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

Page 类继承自 Puppeteer 的 EventEmitter 类，并将发出各种事件，这些事件记录在 PageEvent 枚举中。

示例 2

此示例记录单个页面 load 事件的消息

page.once('load', () => console.log('Page loaded!'));

要取消订阅事件，请使用 EventEmitter.off() 方法

function logRequest(interceptedRequest) {
  console.log('A request was made:', interceptedRequest.url());
}
page.on('request', logRequest);
// Sometime later...
page.off('request', logRequest);

属性

属性	修饰符	类型	描述
accessibility	只读	Accessibility	Accessibility 类提供用于检查浏览器的辅助功能树的方法。辅助功能树由辅助技术（如屏幕阅读器或开关）使用。 备注 辅助功能是非常特定于平台的事情。在不同的平台上，有不同的屏幕阅读器，它们的输出可能大相径庭。 Blink（Chrome 的渲染引擎）具有“辅助功能树”的概念，然后将其转换为不同的特定于平台的 API。Accessibility 命名空间允许用户访问 Blink Accessibility Tree。 从 Blink AX Tree 转换为特定于平台的 AX-Tree 或由辅助技术本身进行转换时，会过滤掉大多数辅助功能树。默认情况下，Puppeteer 尝试近似这种过滤，仅公开树的“有趣”节点。 此类的构造函数标记为内部函数。第三方代码不应直接调用构造函数或创建扩展 Accessibility 类的子类。
coverage	只读	Coverage	Coverage 类提供用于收集有关页面使用的 JavaScript 和 CSS 部分的信息的方法。 备注 要以 Istanbul 可以使用的格式输出覆盖率，请参阅puppeteer-to-istanbul。 此类的构造函数标记为内部函数。第三方代码不应直接调用构造函数或创建扩展 Coverage 类的子类。
keyboard	只读	Keyboard	Keyboard 提供用于管理虚拟键盘的 API。高级 API 是 Keyboard.type()，它接收原始字符并在页面上生成正确的 keydown、keypress/input 和 keyup 事件。 备注 为了更精细地控制，可以使用 Keyboard.down()、Keyboard.up() 和 Keyboard.sendCharacter() 来手动触发事件，就像它们是由真实键盘生成的一样。 在 macOS 上，类似 ⌘ A -> 全选的键盘快捷键不起作用。请参阅 #1313。 此类的构造函数标记为内部函数。第三方代码不应直接调用构造函数或创建扩展 Keyboard 类的子类。
mouse	只读	Mouse	Mouse 类在相对于视口左上角的 main-frame CSS 像素中运行。 备注 每个 page 对象都有自己的 Mouse，可以使用 Page.mouse 访问。 此类的构造函数标记为内部函数。第三方代码不应直接调用构造函数或创建扩展 Mouse 类的子类。
touchscreen	只读	Touchscreen	Touchscreen 类公开触摸屏事件。
tracing	只读	Tracing	Tracing 类公开跟踪审计接口。 备注 可以使用 tracing.start 和 tracing.stop 来创建跟踪文件，该文件可以在 Chrome DevTools 或 时间轴查看器中打开。 此类的构造函数标记为内部函数。第三方代码不应直接调用构造函数或创建扩展 Tracing 类的子类。

方法

方法	修饰符	描述
$(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 身份验证 的凭据。 注意 将在后台启用请求拦截来实现身份验证。这可能会影响性能。 备注 要禁用身份验证，请传递 null。
bringToFront()		将页面移到前面（激活选项卡）。
browser()		获取页面所属的浏览器。
browserContext()		获取页面所属的浏览器上下文。
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)	已弃用	如果未指定 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)	已弃用	已弃用 页面级 cookie API 已弃用。请改用 Browser.deleteCookie() 或 BrowserContext.deleteCookie()。
emulate(device)		模拟给定设备的指标和用户代理。 为了辅助模拟，Puppeteer 提供了一个已知设备列表，可以通过 KnownDevices 获取。 备注 此方法是调用两个方法的快捷方式：Page.setUserAgent() 和 Page.setViewport()。 此方法将调整页面大小。许多网站不希望手机更改大小，因此您应该在导航到页面之前进行模拟。
emulateCPUThrottling(factor)		启用 CPU 节流以模拟慢速 CPU。
emulateIdleState(overrides)		模拟空闲状态。如果未设置任何参数，则清除空闲状态模拟。
emulateMediaFeatures(features)
emulateMediaType(type)
emulateNetworkConditions(networkConditions)		这不会影响 WebSockets 和 WebRTC PeerConnections（请参阅 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，它将被等待。 注意 通过 page.exposeFunction 安装的函数在导航中幸存下来。
focus(selector)		此方法使用 selector 获取一个元素并使其获得焦点。如果没有与 selector 匹配的元素，则该方法会抛出错误。 备注 是 page.mainFrame().focus(selector) 的快捷方式。
frames()		附加到页面的所有框架的数组。
getDefaultNavigationTimeout()		最大导航时间（毫秒）。
getDefaultTimeout()		最大时间（毫秒）。
goBack(options)		此方法导航到历史记录中的上一页。
goForward(options)		此方法导航到历史记录中的下一页。
goto(url, options)		将框架或页面导航到给定的 url。 备注 导航到 about:blank 或导航到具有不同哈希值的相同 URL 将成功并返回 null。 警告 无头 shell 模式不支持导航到 PDF 文档。请参阅 上游问题。 在无头 shell 中，当远程服务器返回任何有效的 HTTP 状态代码（包括 404 “未找到” 和 500 “内部服务器错误”）时，此方法不会抛出错误。可以通过调用 HTTPResponse.status() 来检索此类响应的状态代码。
hover(selector)		此方法使用 selector 获取一个元素，如果需要，将其滚动到视图中，然后使用 Page.mouse 将鼠标悬停在元素的中心。如果没有与 selector 匹配的元素，则该方法会抛出错误。 备注 是 page.mainFrame().hover(selector) 的快捷方式。
isClosed()		指示页面已关闭。
isDragInterceptionEnabled()	已弃用	如果正在拦截拖动事件，则为 true，否则为 false。 已弃用 我们不再支持拦截拖动有效负载。使用在 ElementHandle 上找到的新拖动 API 进行拖动（或仅使用 Page.mouse）。
isJavaScriptEnabled()		如果页面启用了 JavaScript，则为 true，否则为 false。
isServiceWorkerBypassed()		如果正在绕过 service worker，则为 true，否则为 false。
locator(selector)		为提供的选择器创建一个定位器。有关详细信息和支持的操作，请参阅 Locator。
locator(func)		为提供的函数创建一个定位器。有关详细信息和支持的操作，请参阅 Locator。
mainFrame()		页面的主框架。
metrics()		包含度量作为键/值对的对象。 备注 所有时间戳都以单调时间表示：自过去任意时间点以来单调递增的时间（以秒为单位）。
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 注入到页面中的脚本。
screencast(options)		（实验性） 捕获此 页面 的屏幕广播。 备注 所有录音都将使用 WebM 格式，使用 VP9 视频编解码器。FPS 为 30。 您的系统上必须安装 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)		切换绕过页面的内容安全策略。 备注 注意：CSP 绕过发生在 CSP 初始化时，而不是评估时。通常，这意味着应该在导航到域之前调用 page.setBypassCSP。
setBypassServiceWorker(bypass)		切换是否忽略每个请求的 service worker。
setCacheEnabled(enabled)		基于启用状态切换是否忽略每个请求的缓存。默认情况下，缓存是启用的。
setContent(html, options)		设置页面的内容。
setCookie(cookies)	已弃用	已弃用 页面级 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)	已弃用	已弃用 我们不再支持拦截拖动有效负载。使用在 ElementHandle 上找到的新拖动 API 进行拖动（或仅使用 Page.mouse）。
setExtraHTTPHeaders(headers)		额外的 HTTP 标头将随页面发起的每个请求一起发送。 提示 所有 HTTP 标头名称都小写。（HTTP 标头不区分大小写，因此这不应影响您的服务器代码。） 注意 page.setExtraHTTPHeaders 不保证传出请求中标头的顺序。
setGeolocation(options)		设置页面的地理位置。 备注 考虑使用 BrowserContext.overridePermissions() 来授予页面读取其地理位置的权限。
setJavaScriptEnabled(enabled)		备注 注意：更改此值不会影响已运行的脚本。它将在下次导航时完全生效。
setOfflineMode(enabled)		将网络连接设置为离线。 它不会更改 Page.emulateNetworkConditions() 中使用的参数
setRequestInterception(value)		激活请求拦截会启用 HTTPRequest.abort()、HTTPRequest.continue() 和 HTTPRequest.respond() 方法。这提供了修改页面发出的网络请求的功能。 一旦启用请求拦截，每个请求都将停滞，除非它被继续、响应或中止；或使用浏览器缓存完成。 有关更多详细信息，请参阅 请求拦截指南。
setUserAgent(userAgent, userAgentMetadata)
setViewport(viewport)		page.setViewport 将调整页面大小。许多网站不希望手机更改大小，因此您应该在导航到页面之前设置视口。 在单个浏览器中有多个页面的情况下，每个页面都可以有自己的视口大小。将视口设置为 null 会将其重置为其默认值。 备注 注意：在某些情况下，设置视口会重新加载页面，以便设置 isMobile 或 hasTouch 属性。
tap(selector)		此方法使用 selector 获取一个元素，如果需要，将其滚动到视图中，然后使用 Page.touchscreen 点击元素的中心。如果没有与 selector 匹配的元素，则该方法会抛出错误。 备注 是 page.mainFrame().tap(selector) 的快捷方式。
target()	已弃用	此页面是从目标创建的。 已弃用 直接使用 Page.createCDPSession()。
title()		页面的标题 备注 page.mainFrame().title() 的快捷方式。
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)		此方法通常与触发文件选择的操作相结合使用。 注意 必须在启动文件选择器之前调用此方法。它不会返回当前活动的文件选择器。 注意 当前不支持拦截通过 DOM API（如 window.showOpenFilePicker）触发的文件对话框。 备注 在“有头”浏览器中，此方法会导致本机文件选择器对话框不显示给用户。
waitForFrame(urlOrPredicate, options)		等待与给定条件匹配的框架出现。
waitForFunction(pageFunction, options, args)		等待提供的函数 pageFunction 在页面上下文中求值时返回真值。
waitForNavigation(options)		等待页面导航到新的 URL 或重新加载。当您运行的代码会间接导致页面导航时，此方法非常有用。 备注 使用 History API 更改 URL 被视为导航。
waitForNetworkIdle(options)		等待网络空闲。
waitForRequest(urlOrPredicate, options)		备注 可选的等待参数有 timeout：最大等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 Page.setDefaultTimeout() 方法更改默认值。
waitForResponse(urlOrPredicate, options)		备注 可选参数有 timeout：最大等待时间（以毫秒为单位），默认为 30 秒，传递 0 以禁用超时。可以使用 Page.setDefaultTimeout() 方法更改默认值。
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() 方法更改默认值。
workers()		与该页面关联的所有专用 WebWorkers。 备注 这不包含 ServiceWorkers