Frame 類別

表示一個 DOM 框架。

要理解框架，您可以將框架視為 <iframe> 元素。就像 iframes 一樣，框架可以巢狀，當 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)		將 <script> 標籤插入具有所需網址或內容的頁面中。
addStyleTag(options)		將具有所需網址的 HTMLStyleElement 插入框架中
addStyleTag(options)		將具有所需網址的 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。 警告 無頭殼模式不支援導覽至 PDF 文件。請參閱上游問題。 在無頭殼中，當遠端伺服器傳回任何有效的 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)		等待符合給定選擇器的元素出現在框架中。 此方法會跨導覽運作。