Frame 类

表示一个 DOM 框架。

要理解框架，你可以把框架想象成 <iframe> 元素。与 iframe 一样，框架可以嵌套；当 JavaScript 在某个框架中执行时，该 JavaScript 不会影响其执行所在的框架内部的框架。

签名

export declare abstract class Frame extends EventEmitter<FrameEvents>

继承自： EventEmitter<FrameEvents>

备注

框架的生命周期由三个事件控制，这些事件都在父级页面上触发：

PageEvent.FrameAttached - PageEvent.FrameNavigated - PageEvent.FrameDetached

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

示例 1

在任何时间点，页面都会通过 Page.mainFrame() 和 Frame.childFrames() 方法暴露其当前的框架树。

示例 2

转储框架树的示例：

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://www.google.com/chrome/browser/canary.html');
dumpFrameTree(page.mainFrame(), '');
await browser.close();

function dumpFrameTree(frame, indent) {
  console.log(indent + frame.url());
  for (const child of frame.childFrames()) {
    dumpFrameTree(child, indent + '  ');
  }
}

示例 3

从 iframe 元素中获取文本的示例：

const frames = page.frames();
let frame = null;
for (const currentFrame of frames) {
  const frameElement = await currentFrame.frameElement();
  const name = await frameElement.evaluate(el => el.getAttribute('name'));
  if (name === 'myframe') {
    frame = currentFrame;
    break;
  }
}
if (frame) {
  const text = await frame.$eval('.selector', element => element.textContent);
  console.log(text);
} else {
  console.error('Frame with name "myframe" not found.');
}

属性

属性	修饰符	类型	说明
detached	`readonly`	boolean

方法

方法	修饰符	说明
$(selector)		在框架中查询与给定选择器匹配的元素。
$$(selector, options)		在框架中查询与给定选择器匹配的所有元素。
$$eval(selector, pageFunction, args)		在框架中对与给定选择器匹配的元素数组运行给定的函数。如果给定的函数返回 Promise，则此方法将等待该 Promise 解析。
$eval(selector, pageFunction, args)		在框架中对与给定选择器匹配的第一个元素运行给定的函数。如果给定的函数返回 Promise，则此方法将等待该 Promise 解析。
addScriptTag(options)		将具有所需 url 或内容的 `<script>` 标签添加到页面中。
addStyleTag(options)		将具有所需 URL 的 `HTMLStyleElement` 添加到框架中。
addStyleTag(options)		将具有所需 URL 的 `HTMLLinkElement` 添加到框架中。
childFrames()		子框架的数组。
click(selector, options)		点击第一个与 `selector` 匹配的元素。备注：如果 `click()` 触发了导航事件，并且存在一个独立的 `page.waitForNavigation()` Promise 需要解析，你可能会遇到竞态条件，从而产生意想不到的结果。点击并等待导航的正确写法如下： `const [response] = await Promise.all([ page.waitForNavigation(waitOptions), frame.click(selector, clickOptions), ]);`
content()		框架的完整 HTML 内容，包括 DOCTYPE。
evaluate(pageFunction, args)		其行为与 Page.evaluate() 完全相同，只是它在此框架的上下文中运行。详细信息请参阅 Page.evaluate()。
evaluateHandle(pageFunction, args)		其行为与 Page.evaluateHandle() 完全相同，只是它在此框架的上下文中运行。详细信息请参阅 Page.evaluateHandle()。
extensionRealms()		检索与此框架关联的扩展执行 realm 列表。扩展执行 realm 由注入到该框架中的扩展内容脚本创建。
focus(selector)		聚焦与 `selector` 匹配的第一个元素。
frameElement()
goto(url, options)		将框架或页面导航到给定的 `url`。备注：导航到 `about:blank`，或使用不同 hash 导航到相同 URL，都会成功并返回 `null`。 ⚠️警告无头 shell 模式不支持导航到 PDF 文档。请参阅上游问题。在无头 shell 中，当远程服务器返回任何有效的 HTTP 状态码（包括 404 "Not Found" 和 500 "Internal Server Error"）时，此方法不会抛出错误。此类响应的状态码可以通过调用 HTTPResponse.status() 获取。
hover(selector)		将指针悬停在匹配 `selector` 的第一个元素的中心。
isDetached()	`deprecated`	如果框架已被分离，则为 `true`，否则为 `false`。已废弃：请改用 `detached` getter。
locator(selector)		为提供的选择器创建一个定位器。有关详细信息和支持的操作，请参阅 Locator。
locator(func)		为提供的函数创建一个定位器。有关详细信息和支持的操作，请参阅 Locator。
name()	`deprecated`	框架的 `name` 属性，与标签中指定的一致。已废弃：请使用 `const element = await frame.frameElement(); const nameOrId = await element.evaluate(frame => frame.name ?? frame.id);` 备注：此值在框架创建时计算一次，之后更改该属性也不会更新。
page()		与框架关联的页面。
parentFrame()		父框架（如果有）。分离的框架和主框架返回 `null`。
select(selector, values)		在第一个与 `selector` 匹配的 `<select>` 元素上选择一组值。
setContent(html, options)		设置框架的内容。
tap(selector)		轻触第一个与 `selector` 匹配的元素。
title()		框架的标题。
type(selector, text, options)		为文本中的每个字符发送 `keydown`、`keypress`/`input` 和 `keyup` 事件。备注：要按下特殊键（如 `Control` 或 `ArrowDown`），请使用 Keyboard.press()。
url()		框架的 URL。
waitForFunction(pageFunction, options, args)
waitForNavigation(options)		等待框架导航。当你运行的代码会间接导致框架导航时，此方法很有用。使用 History API 更改 URL 被视为一次导航。
waitForSelector(selector, options)		等待与给定选择器匹配的元素出现在框架中。此方法可跨导航使用。