Frame 类

¥Frame class

代表一个 DOM 框架。

¥Represents a DOM frame.

要理解框架，你可以将框架视为 <iframe> 元素。就像 iframe 一样，框架可以嵌套，并且当 JavaScript 在框架中执行时，JavaScript 不会影响 JavaScript 执行所在的环境框架内的框架。

¥To understand frames, you can think of frames as <iframe> elements. Just like iframes, frames can be nested, and when JavaScript is executed in a frame, the JavaScript does not effect frames inside the ambient frame the JavaScript executes in.

签名：

¥Signature:

export declare abstract class Frame extends EventEmitter<FrameEvents>

Extends: EventEmitter<FrameEvents>

备注

¥Remarks

框架生命周期由三个事件控制，这些事件都在父 page 上调度：

¥Frame lifecycles are controlled by three events that are all dispatched on the parent page:

• PageEvent.FrameAttached - PageEvent.FrameNavigated - PageEvent.FrameDetached

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

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

示例 1

¥Example 1

在任何时间点，pages 通过 Page.mainFrame() 和 Frame.childFrames() 方法公开其当前的帧树。

¥At any point in time, pages expose their current frame tree via the Page.mainFrame() and Frame.childFrames() methods.

示例 2

¥Example 2

转储框架树的示例：

¥An example of dumping frame tree:

import puppeteer from 'puppeteer';

(async () => {
  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

¥Example 3

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

¥An example of getting text from an iframe element:

const frame = page.frames().find(frame => frame.name() === 'myframe');
const text = await frame.$eval('.selector', element => element.textContent);
console.log(text);

属性

¥Properties

属性	修饰符	类型	描述
detached	readonly	boolean

方法

¥Methods

方法	修饰符	描述
$(selector)		查询框架中与给定选择器匹配的元素。
$$(selector)		查询框架中与给定选择器匹配的所有元素。
$$eval(selector, pageFunction, args)		对与框架中给定选择器匹配的元素数组运行给定函数。 如果给定的函数返回一个 Promise，那么此方法将等待直到 Promise 解析。
$eval(selector, pageFunction, args)		在框架中与给定选择器匹配的第一个元素上运行给定函数。 如果给定的函数返回一个 Promise，那么此方法将等待直到 Promise 解析。
addScriptTag(options)		将 <script> 标记添加到具有所需 url 或内容的页面中。
addStyleTag(options)		将 HTMLStyleElement 添加到具有所需 URL 的框架中
addStyleTag(options)		将 HTMLLinkElement 添加到具有所需 URL 的框架中
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() 相同，只是它在此框架的上下文中运行。
evaluateHandle(pageFunction, args)		行为与 Page.evaluateHandle() 相同，只是它在此框架的上下文中运行。
focus(selector)		聚焦与 selector 匹配的第一个元素。
frameElement()
goto(url, options)		将框架导航到给定的 url。 评论： 导航到 about:blank 或导航到具有不同哈希值的同一 URL 将成功并返回 null。 警告 无头模式不支持导航至 PDF 文档。参见 上游问题。
hover(selector)		将指针悬停在与 selector 匹配的第一个元素的中心上。
isDetached()	deprecated	如果框架已分离，则为 true。否则，false。 已弃用： 使用 detached 获取器。
isOOPFrame()		如果该帧是进程外 (OOP) 帧，则为 true。否则，false。
locator(selector)		为提供的选择器创建一个定位器。有关详细信息和支持的操作，请参阅 定位器。 评论： Locators API 是实验性的，我们不会遵循 semver 对 Locators API 进行重大更改。
locator(func)		为提供的函数创建一个定位器。有关详细信息和支持的操作，请参阅 定位器。 评论： Locators API 是实验性的，我们不会遵循 semver 对 Locators API 进行重大更改。
name()	deprecated	标签中指定的框架的 name 属性。 已弃用： 使用 const element = await frame.frameElement(); const nameOrId = await element.evaluate(frame => frame.name ?? frame.id); 评论： 该值在框架创建时计算一次，如果以后属性更改，该值将不会更新。
page()		与框架关联的页面。
parentFrame()		父框架（如果有）。分离框架和主框架返回 null。
select(selector, values)		在第一个 <select> 元素上选择与 selector 匹配的一组值。
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)		等待框架导航。当你运行将间接导致框架导航的代码时，它非常有用。 使用 历史 API 更改 URL 被视为导航。
waitForSelector(selector, options)		等待与给定选择器匹配的元素出现在框架中。 此方法适用于各种导航。