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 等辅助技术使用。
coverage	readonly	覆盖范围	Coverage 类提供了收集有关页面所使用的 JavaScript 和 CSS 部分的信息的方法。
keyboard	readonly	键盘	Keyboard 提供了用于管理虚拟键盘的 api。高级 API 是 Keyboard.type()，它采用原始字符并在页面上生成正确的 keydown、keypress/input 和 keyup 事件。
mouse	readonly	Mouse	Mouse 类在相对于视口左上角的主框架 CSS 像素中运行。
touchscreen	readonly	触摸屏	Touchscreen 类公开触摸屏事件。
tracing	readonly	追踪	Tracing 类公开跟踪审计接口。

方法

¥Methods

方法	修饰符	描述
$(selector)		在页面内运行 document.querySelector。如果没有元素与选择器匹配，则返回值解析为 null。
$$(selector)		该方法在页面内运行 document.querySelectorAll。如果没有元素与选择器匹配，则返回值解析为 []。
$$eval(selector, pageFunction, args)		此方法在页面内运行 Array.from(document.querySelectorAll(selector))，并将结果作为第一个参数传递给 pageFunction。
$eval(selector, pageFunction, args)		此方法在页面内运行 document.querySelector，并将结果作为第一个参数传递给 pageFunction。
addScriptTag(options)		将 <script> 标记添加到具有所需 URL 或内容的页面中。
addStyleTag(options)		将 <link rel="stylesheet"> 标记添加到具有所需 URL 的页面中，或将 <style type="text/css"> 标记添加到内容中。 page.mainFrame().addStyleTag(options) 的快捷方式。
addStyleTag(options)
authenticate(credentials)		提供 HTTP authentication 的凭据。
bringToFront()		将页面置于前面（激活选项卡）。
browser()		获取页面所属的浏览器。
browserContext()		获取页面所属的浏览器上下文。
click(selector, options)		此方法使用 selector 获取元素，如果需要，将其滚动到视图中，然后使用 Page.mouse 单击元素的中心。如果没有与 selector 匹配的元素，该方法将抛出错误。
close(options)
content()		页面的完整 HTML 内容，包括 DOCTYPE。
cookies(urls)		如果未指定 URL，则此方法返回当前页面 URL 的 cookie。如果指定了 URL，则仅返回这些 URL 的 cookie。
createCDPSession()		创建附加到页面的 Chrome Devtools 协议会话。
createPDFStream(options)		使用 print CSS 媒体类型生成页面的 PDF。
deleteCookie(cookies)
emulate(device)		模拟给定设备的指标和用户代理。 为了帮助模拟，Puppeteer 提供了可通过 KnownDevices 的已知设备列表。
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)
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 匹配的元素，该方法将抛出错误。
frames()		附加到页面的所有框架的数组。
getDefaultTimeout()		最长时间（以毫秒为单位）。
goBack(options)		此方法导航到历史记录中的上一页。
goForward(options)		此方法导航到历史记录的下一页。
goto(url, options)		将页面导航到给定的 url。
hover(selector)		此方法使用 selector 获取元素，如果需要，将其滚动到视图中，然后使用 Page.mouse 将鼠标悬停在元素的中心上。如果没有与 selector 匹配的元素，该方法将抛出错误。
isClosed()		表示该页面已关闭。
isDragInterceptionEnabled()		如果拖动事件被拦截，则为 true，否则为 false。
isJavaScriptEnabled()		如果页面启用了 JavaScript，则为 true，否则为 false。
isServiceWorkerBypassed()		如果 Service Worker 被绕过，则为 true，否则为 false。
locator(selector)		为提供的选择器创建一个定位器。有关详细信息和支持的操作，请参阅 定位器。
locator(func)		为提供的函数创建一个定位器。有关详细信息和支持的操作，请参阅 定位器。
mainFrame()		页面的主框架。
metrics()		包含指标作为键/值对的对象。
pdf(options)		使用 print CSS 媒体类型生成页面的 PDF。
queryObjects(prototypeHandle)		此方法迭代 JavaScript 堆并查找具有给定原型的所有对象。
reload(options)		重新加载页面。
removeExposedFunction(name)		该方法从页面的 window 对象中删除先前通过 $Page.exposeFunction() 添加的名为 name 的函数。
removeScriptToEvaluateOnNewDocument(identifier)		删除通过 Page.evaluateOnNewDocument 注入页面的脚本。
screencast(options)		捕获此 page 的截屏视频。
screenshot(options)		捕获此 page 的屏幕截图。
screenshot(options)
select(selector, values)		选择所有提供的选项后，触发 change 和 input 事件。如果没有 <select> 元素与 selector 匹配，该方法将引发错误。
setBypassCSP(enabled)		切换绕过页面的内容安全策略。
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)
setExtraHTTPHeaders(headers)		额外的 HTTP 标头将随页面发起的每个请求一起发送。 提示 所有 HTTP 标头名称均为小写。（HTTP 标头不区分大小写，因此这不会影响你的服务器代码。） 注意 page.setExtraHTTPHeaders 不保证传出请求中标头的顺序。
setGeolocation(options)		设置页面的地理位置。
setJavaScriptEnabled(enabled)
setOfflineMode(enabled)		将网络连接设置为离线。 它不会改变 Page.emulateNetworkConditions() 中使用的参数
setRequestInterception(value)		激活请求拦截会启用 HTTPRequest.abort()、HTTPRequest.continue() 和 HTTPRequest.respond() 方法。这提供了修改页面发送的网络请求的能力。 一旦启用请求拦截，每个请求都会停止，除非继续、响应或中止；或者使用浏览器缓存完成。 有关详细信息，请参阅 请求拦截指南。
setUserAgent(userAgent, userAgentMetadata)
setViewport(viewport)		page.setViewport 将调整页面大小。许多网站不希望手机改变大小，因此你应该在导航到页面之前设置视口。 在单个浏览器中有多个页面的情况下，每个页面可以有自己的视口大小。
tap(selector)		此方法使用 selector 获取元素，如果需要，将其滚动到视图中，然后使用 Page.touchscreen 点击元素的中心。如果没有与 selector 匹配的元素，该方法将抛出错误。
target()		创建此页面的目标。
title()		页面的标题
type(selector, text, options)		为文本中的每个字符发送 keydown、keypress/input 和 keyup 事件。 要按特殊键，例如 Control 或 ArrowDown，请使用 Keyboard.press()。
url()		页面的 URL。
viewport()		返回当前页面视口设置，而不检查实际页面视口。 这可以是使用先前的 Page.setViewport() 调用设置的视口，也可以是通过 BrowserConnectOptions.defaultViewport 设置的默认视口。
waitForDevicePrompt(options)		此方法通常与从 API（例如 WebBluetooth）触发设备请求的操作结合使用。 提醒 必须在发送设备请求之前调用此函数。它不会返回当前活动的设备提示。
waitForFileChooser(options)		此方法通常与触发文件选择的操作结合使用。 提醒 必须在启动文件选择器之前调用此函数。它不会返回当前活动的文件选择器。
waitForFrame(urlOrPredicate, options)		等待匹配给定条件的帧出现。
waitForFunction(pageFunction, options, args)		等待提供的函数 pageFunction 在页面上下文中计算时返回真值。
waitForNavigation(options)		等待页面导航到新 URL 或重新加载。当你运行将间接导致页面导航的代码时，它非常有用。
waitForNetworkIdle(options)		等待网络空闲。
waitForRequest(urlOrPredicate, options)
waitForResponse(urlOrPredicate, options)
waitForSelector(selector, options)		等待 selector 出现在页面中。如果在调用该方法时 selector 已经存在，该方法将立即返回。如果等待 timeout 毫秒后 selector 没有出现，函数将抛出异常。
workers()		所有与该页面相关的专用 WebWorkers。