Page 类

¥Page class

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

¥Page provides methods to interact with a single tab or extension background page in the browser.

注意

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

¥One Browser instance might have multiple Page instances.

签名：

¥Signature:

export declare abstract class Page extends EventEmitter<PageEvents>

Extends: EventEmitter<PageEvents>

备注

¥Remarks

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

¥The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the Page class.

示例 1

¥Example 1

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

¥This example creates a page, navigates it to a URL, and then saves a screenshot:

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 枚举中记录的各种事件。

¥The Page class extends from Puppeteer's EventEmitter class and will emit various events which are documented in the PageEvent enum.

示例 2

¥Example 2

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

¥This example logs a message for a single page load event:

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

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

¥To unsubscribe from events use the EventEmitter.off() method:

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

属性

¥Properties

属性	修饰符	类型	描述
accessibility	readonly	无障碍	Accessibility 类提供了检查浏览器的辅助功能树的方法。可访问性树由 屏幕阅读器 或 switches 等辅助技术使用。 评论： 可访问性是一个非常特定于平台的东西。在不同的平台上，有不同的屏幕阅读器，可能会产生截然不同的输出。 Blink - Chrome's rendering engine - 有一个 "可达性树" 的概念，然后将其转换为不同平台特定的 API。Accessibility 命名空间使用户可以访问 Blink Accessibility Tree。 当从 Blink AX 树转换为特定于平台的 AX 树或通过辅助技术本身时，大多数可访问性树都会被过滤掉。默认情况下，Puppeteer 尝试近似此过滤，仅公开树的 "interesting" 节点。 此类的构造函数被标记为内部构造函数。第三方代码不应直接调用构造函数或创建扩展 Accessibility 类的子类。
coverage	readonly	覆盖范围	Coverage 类提供了收集有关页面所使用的 JavaScript 和 CSS 部分的信息的方法。 评论： 要以 伊斯坦布尔 可以使用的形式输出覆盖范围，请参阅 puppeteer-to-istanbul。 此类的构造函数被标记为内部构造函数。第三方代码不应直接调用构造函数或创建扩展 Coverage 类的子类。
keyboard	readonly	键盘	Keyboard 提供了用于管理虚拟键盘的 api。高级 API 是 Keyboard.type()，它采用原始字符并在页面上生成正确的 keydown、keypress/input 和 keyup 事件。 评论： 为了更好地控制，你可以使用 Keyboard.down()、Keyboard.up() 和 Keyboard.sendCharacter() 手动触发事件，就像它们是从真正的键盘生成的一样。 在 macOS 上，诸如 ⌘ A -> 全选之类的键盘快捷键不起作用。参见 #1313。 此类的构造函数被标记为内部构造函数。第三方代码不应直接调用构造函数或创建扩展 Keyboard 类的子类。
mouse	readonly	Mouse	Mouse 类在相对于视口左上角的主框架 CSS 像素中运行。 评论： 每个 page 对象都有自己的鼠标，可通过 Page.mouse 访问。 此类的构造函数被标记为内部构造函数。第三方代码不应直接调用构造函数或创建扩展 Mouse 类的子类。
touchscreen	readonly	触摸屏	Touchscreen 类公开触摸屏事件。
tracing	readonly	追踪	Tracing 类公开跟踪审计接口。 评论： 你可以使用 tracing.start 和 tracing.stop 创建可在 Chrome DevTools 或 时间轴查看器 中打开的跟踪文件。 此类的构造函数被标记为内部构造函数。第三方代码不应直接调用构造函数或创建扩展 Tracing 类的子类。

方法

¥Methods

方法	修饰符	描述
$(selector)		查找与选择器匹配的第一个元素。如果没有元素与选择器匹配，则返回值解析为 null。 评论： Page.mainFrame().$(selector) 的快捷方式。
$$(选择器，选项)		在页面上查找与选择器匹配的元素。如果没有元素与选择器匹配，则返回值解析为 []。 评论： Page.mainFrame().$$(selector) 的快捷方式。
$$eval(selector, pageFunction, args)		此方法返回与选择器匹配的所有元素，并将结果数组作为第一个参数传递给 pageFunction。 评论： 如果 pageFunction 返回一个 Promise，$$eval 将等待 Promise 解析，然后返回其值。
$eval(selector, pageFunction, args)		此方法查找页面中与选择器匹配的第一个元素，并将结果作为第一个参数传递给 pageFunction。 评论： 如果没有找到与 selector 匹配的元素，该方法将抛出错误。 如果 pageFunction 返回一个 Promise，$eval 将等待 Promise 解析，然后返回其值。
addScriptTag(options)		将 <script> 标记添加到具有所需 URL 或内容的页面中。 评论： page.mainFrame().addScriptTag(options) 的快捷方式。
addStyleTag(options)		将 <link rel="stylesheet"> 标记添加到具有所需 URL 的页面中，或将 <style type="text/css"> 标记添加到内容中。 page.mainFrame().addStyleTag(options) 的快捷方式。
addStyleTag(options)
authenticate(credentials)		提供 HTTP authentication 的凭据。 注意 将在后台打开请求拦截以实现身份验证。这可能会影响性能。 评论： 要禁用身份验证，请传递 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。
createCDPSession()		创建附加到页面的 Chrome Devtools 协议会话。
createPDFStream(options)		使用 print CSS 媒体类型生成页面的 PDF。 评论： 要生成具有 screen 媒体类型的 PDF，请在调用 page.pdf() 之前调用 page.emulateMediaType('screen')。 默认情况下，page.pdf() 会生成带有修改颜色的 pdf 以便打印。使用 -webkit-print-color-adjust 属性强制渲染精确的颜色。
deleteCookie(cookies)
emulate(device)		模拟给定设备的指标和用户代理。 为了帮助模拟，Puppeteer 提供了可通过 KnownDevices 的已知设备列表。 评论： 该方法是调用两个方法的快捷方式：Page.setUserAgent() 和 Page.setViewport()。 此方法将调整页面大小。许多网站不希望手机改变尺寸，因此你应该在导航到页面之前进行模拟。
emulateCPUThrottling(factor)		启用 CPU 限制以模拟慢速 CPU。
emulateIdleState(overrides)		模拟空闲状态。如果未设置参数，则清除空闲状态模拟。
emulateMediaFeatures(features)
emulateMediaType(type)
emulateNetworkConditions(networkConditions)		这不会影响 WebSocket 和 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()		附加到页面的所有框架的数组。
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()	deprecated	如果拖动事件被拦截，则为 true，否则为 false。 已弃用： 我们不再支持拦截拖动有效负载。使用 ElementHandle 上的新拖动 API 进行拖动（或仅使用 Page.mouse）。
isJavaScriptEnabled()		如果页面启用了 JavaScript，则为 true，否则为 false。
isServiceWorkerBypassed()		如果 Service Worker 被绕过，则为 true，否则为 false。
locator(selector)		为提供的选择器创建一个定位器。有关详细信息和支持的操作，请参阅 定位器。
locator(func)		为提供的函数创建一个定位器。有关详细信息和支持的操作，请参阅 定位器。
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)		（实验性）捕获此 page 的截屏视频。 评论： 所有录制内容均为 WebM 格式，使用 VP9 视频编解码器。FPS 为 30。 你的系统上必须安装有 ffmpeg。
screenshot(options)		捕获此 page 的屏幕截图。 评论： 在 BrowserContext 中截屏时，以下方法将自动等待截屏完成，以防止干扰截屏过程：BrowserContext.newPage(), Browser.newPage(), Page.close(). 调用 Page.bringToFront() 不会等待现有的屏幕截图操作。
screenshot(options)
select(selector, values)		选择所有提供的选项后，触发 change 和 input 事件。如果没有 <select> 元素与 selector 匹配，该方法将引发错误。 评论： page.mainFrame().select() 的快捷方式
setBypassCSP(enabled)		切换绕过页面的内容安全策略。 评论： 注意：CSP 绕过发生在 CSP 初始化时而不是评估时。通常，这意味着应在导航到域之前调用 page.setBypassCSP。
setBypassServiceWorker(bypass)		切换忽略每个请求的 Service Worker。
setCacheEnabled(enabled)		根据启用状态切换忽略每个请求的缓存。默认情况下，缓存已启用。
setContent(html, options)		设置页面的内容。
setCookie(cookies)
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 标头将随页面发起的每个请求一起发送。 提示 所有 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()	deprecated	创建此页面的目标。 已弃用： 直接使用 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() 调用设置的视口，也可以是通过 BrowserConnectOptions.defaultViewport 设置的默认视口。
waitForDevicePrompt(options)		此方法通常与从 API（例如 WebBluetooth）触发设备请求的操作结合使用。 提醒 必须在发送设备请求之前调用此函数。它不会返回当前活动的设备提示。
waitForFileChooser(options)		此方法通常与触发文件选择的操作结合使用。 提醒 必须在启动文件选择器之前调用此函数。它不会返回当前活动的文件选择器。 提醒 目前不支持拦截通过 DOM API（例如 window.showOpenFilePicker）触发的文件对话框。 评论： 在 "有头" 浏览器中，此方法会为用户生成原生文件选择器对话框 not showing up。
waitForFrame(urlOrPredicate, options)		等待匹配给定条件的帧出现。
waitForFunction(pageFunction, options, args)		等待提供的函数 pageFunction 在页面上下文中计算时返回真值。
waitForNavigation(options)		等待页面导航到新 URL 或重新加载。当你运行将间接导致页面导航的代码时，它非常有用。 评论： 使用 历史 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