Frame 类

表示一个 DOM 框架。

要理解框架，你可以将框架视为 <iframe> 元素。就像 iframe 一样，框架可以嵌套，并且当在框架中执行 JavaScript 时，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';

(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

一个从 iframe 元素获取文本的示例

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

属性

属性	修饰符	类型	描述
detached	只读	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()。
focus(selector)		聚焦与 selector 匹配的第一个元素。
frameElement()
goto(url, options)		将框架或页面导航到给定的 url。 备注 导航到 about:blank 或使用不同的哈希导航到相同的 URL 将成功并返回 null。 警告 无头 shell 模式不支持导航到 PDF 文档。请参阅上游问题。 在无头 shell 中，当远程服务器返回任何有效的 HTTP 状态代码时，包括 404“未找到”和 500“内部服务器错误”，此方法不会抛出错误。可以通过调用 HTTPResponse.status() 来检索此类响应的状态代码。
hover(selector)		将指针悬停在与 selector 匹配的第一个元素的中心上方。
isDetached()	已弃用	如果框架已分离，则为 true。否则，为 false。 已弃用 使用 detached getter。
locator(selector)		为提供的选择器创建定位器。有关详细信息和支持的操作，请参阅Locator。
locator(func)		为提供的函数创建定位器。有关详细信息和支持的操作，请参阅Locator。
name()	已弃用	在标签中指定的框架的 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)		等待与给定选择器匹配的元素出现在框架中。 此方法在导航过程中有效。