Frame

在每個時間點，頁面都會透過 Page.mainFrame() 和 Frame.childFrames() 方法公開其目前的 frame 樹狀結構。

Frame 物件的生命週期由三個事件控制，這些事件會在頁面物件上分派

Page.onFrameAttached(handler) - 當 frame 附加到頁面時觸發。一個 Frame 只能附加到頁面一次。
Page.onFrameNavigated(handler) - 當 frame 提交導覽至不同的 URL 時觸發。
Page.onFrameDetached(handler) - 當 frame 從頁面分離時觸發。一個 Frame 只能從頁面分離一次。

frame 樹狀結構傾印範例

import com.microsoft.playwright.*;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      BrowserType firefox = playwright.firefox();
      Browser browser = firefox.launch();
      Page page = browser.newPage();
      page.navigate("https://www.google.com/chrome/browser/canary.html");
      dumpFrameTree(page.mainFrame(), "");
      browser.close();
    }
  }
  static void dumpFrameTree(Frame frame, String indent) {
    System.out.println(indent + frame.url());
    for (Frame child : frame.childFrames()) {
      dumpFrameTree(child, indent + "  ");
    }
  }
}

方法

addScriptTag

在 v1.9 之前新增

frame.addScriptTag

當 script 的 onload 事件觸發或 script 內容被注入到 frame 時，傳回新增的標籤。

將 <script> 標籤新增到具有所需 url 或內容的頁面中。

用法

Frame.addScriptTag();
Frame.addScriptTag(options);

引數

options Frame.AddScriptTagOptions (選用)
- setContent String (選用)#
  
  要注入到 frame 的原始 JavaScript 內容。
- setPath Path (選用)#
  
  要注入到 frame 的 JavaScript 檔案路徑。如果 path 是相對路徑，則會相對於目前的工作目錄解析。
- setType String (選用)#
  
  Script 類型。使用 'module' 以載入 JavaScript ES6 模組。請參閱 script 以取得更多詳細資訊。
- setUrl String (選用)#
  
  要新增之 script 的 URL。

傳回

ElementHandle #

addStyleTag

在 v1.9 之前新增

frame.addStyleTag

當 stylesheet 的 onload 事件觸發或 CSS 內容被注入到 frame 時，傳回新增的標籤。

將 <link rel="stylesheet"> 標籤新增到具有所需 url 的頁面中，或將具有內容的 <style type="text/css"> 標籤新增到頁面中。

用法

Frame.addStyleTag();
Frame.addStyleTag(options);

引數

options Frame.AddStyleTagOptions (選用)
- setContent String (選用)#
  
  要注入到 frame 的原始 CSS 內容。
- setPath Path (選用)#
  
  要注入到 frame 的 CSS 檔案路徑。如果 path 是相對路徑，則會相對於目前的工作目錄解析。
- setUrl String (選用)#
  
  <link> 標籤的 URL。

傳回

ElementHandle #

childFrames

在 v1.9 之前新增

frame.childFrames

用法

Frame.childFrames();

傳回

List<Frame>#

content

在 v1.9 之前新增

frame.content

取得 frame 的完整 HTML 內容，包括 doctype。

用法

Frame.content();

傳回

String #

dragAndDrop

新增於：v1.13

frame.dragAndDrop

用法

Frame.dragAndDrop(source, target);
Frame.dragAndDrop(source, target, options);

引數

source String #

要搜尋要拖曳之元素的選取器。如果有多個元素符合選取器，將會使用第一個。
target String #

要搜尋要拖放至其上的元素的選取器。如果有多個元素符合選取器，將會使用第一個。
options Frame.DragAndDropOptions (選用)
- setForce boolean (選用)#
  
  是否略過可操作性檢查。預設為 false。
- setNoWaitAfter boolean (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setSourcePosition SourcePosition (選用)新增於：v1.14#
  - setX double
  - setY double
  在此點按一下來源元素，此點相對於元素 padding box 的左上角。如果未指定，則會使用元素的某些可見點。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTargetPosition TargetPosition (選用)新增於：v1.14#
  - setX double
  - setY double
  在此點將元素拖放到目標元素上，此點相對於元素 padding box 的左上角。如果未指定，則會使用元素的某些可見點。
- setTimeout double (選用)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial boolean (選用)#
  
  設定後，此方法只會執行可操作性檢查並略過動作。預設為 false。在執行動作之前，等待元素準備就緒時很有用。

傳回

void #

evaluate

在 v1.9 之前新增

frame.evaluate

傳回 expression 的傳回值。

如果傳遞至 Frame.evaluate() 的函式傳回 Promise，則 Frame.evaluate() 將會等待 promise 解析並傳回其值。

如果傳遞至 Frame.evaluate() 的函式傳回非 Serializable 值，則 Frame.evaluate() 會傳回 undefined。Playwright 也支援傳輸一些額外的非 JSON 可序列化的值：-0、NaN、Infinity、-Infinity。

用法

Object result = frame.evaluate("([x, y]) => {\n" +
  "  return Promise.resolve(x * y);\n" +
  "}", Arrays.asList(7, 8));
System.out.println(result); // prints "56"

字串也可以傳遞進來，而不是函式。

System.out.println(frame.evaluate("1 + 2")); // prints "3"

ElementHandle 執行個體可以作為引數傳遞至 Frame.evaluate()

ElementHandle bodyHandle = frame.evaluate("document.body");
String html = (String) frame.evaluate("([body, suffix]) => body.innerHTML + suffix", Arrays.asList(bodyHandle, "hello"));
bodyHandle.dispose();

引數

expression String #

要在瀏覽器環境中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動叫用該函式。
arg EvaluationArgument (選用)#

要傳遞至 expression 的選用引數。

傳回

Object #

evaluateHandle

在 v1.9 之前新增

frame.evaluateHandle

將 expression 的傳回值以 JSHandle 傳回。

Frame.evaluate() 和 Frame.evaluateHandle() 之間唯一的差異在於 Frame.evaluateHandle() 傳回 JSHandle。

如果傳遞至 Frame.evaluateHandle() 的函式傳回 Promise，則 Frame.evaluateHandle() 將會等待 promise 解析並傳回其值。

用法

// Handle for the window object.
JSHandle aWindowHandle = frame.evaluateHandle("() => Promise.resolve(window)");

字串也可以傳遞進來，而不是函式。

JSHandle aHandle = frame.evaluateHandle("document"); // Handle for the "document".

JSHandle 執行個體可以作為引數傳遞至 Frame.evaluateHandle()

JSHandle aHandle = frame.evaluateHandle("() => document.body");
JSHandle resultHandle = frame.evaluateHandle("([body, suffix]) => body.innerHTML + suffix", Arrays.asList(aHandle, "hello"));
System.out.println(resultHandle.jsonValue());
resultHandle.dispose();

引數

expression String #

要在瀏覽器環境中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動叫用該函式。
arg EvaluationArgument (選用)#

要傳遞至 expression 的選用引數。

傳回

JSHandle #

frameElement

在 v1.9 之前新增

frame.frameElement

傳回對應於此 frame 的 frame 或 iframe 元素控制代碼。

這是 ElementHandle.contentFrame() 的反向。請注意，傳回的控制代碼實際上屬於父 frame。

如果在 frameElement() 傳回之前 frame 已分離，則此方法會擲回錯誤。

用法

ElementHandle frameElement = frame.frameElement();
Frame contentFrame = frameElement.contentFrame();
System.out.println(frame == contentFrame);  // -> true

傳回

ElementHandle #

frameLocator

新增於：v1.17

frame.frameLocator

使用 iframe 時，您可以建立 frame 定位器，此定位器將會進入 iframe 並允許在該 iframe 中選取元素。

用法

以下程式碼片段會在 id 為 my-frame 的 iframe 中尋找文字為「Submit」的元素，例如 <iframe id="my-frame">

Locator locator = frame.frameLocator("#my-iframe").getByText("Submit");
locator.click();

引數

selector String #

解析 DOM 元素時要使用的選取器。

傳回

FrameLocator #

getByAltText

新增於：v1.27

frame.getByAltText

允許依據元素的替代文字尋找元素。

用法

例如，此方法將依據替代文字「Playwright logo」尋找影像

<img alt='Playwright logo'>

page.getByAltText("Playwright logo").click();

引數

text String | Pattern #

要尋找元素的文字。
options Frame.GetByAltTextOptions (選用)
- setExact boolean (選用)#
  
  是否尋找完全相符的項目：區分大小寫且為完整字串。預設為 false。依據規則運算式尋找時會忽略。請注意，完全相符仍然會修剪空格。

傳回

Locator #

getByLabel

新增於：v1.27

frame.getByLabel

允許依據相關聯的 <label> 或 aria-labelledby 元素的文字，或依據 aria-label 屬性尋找輸入元素。

用法

例如，此方法將在下列 DOM 中依據標籤「Username」和「Password」尋找輸入

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">

page.getByLabel("Username").fill("john");
page.getByLabel("Password").fill("secret");

引數

text String | Pattern #

要尋找元素的文字。
options Frame.GetByLabelOptions (選用)
- setExact boolean (選用)#
  
  是否尋找完全相符的項目：區分大小寫且為完整字串。預設為 false。依據規則運算式尋找時會忽略。請注意，完全相符仍然會修剪空格。

傳回

Locator #

getByPlaceholder

新增於：v1.27

frame.getByPlaceholder

允許依據預留位置文字尋找輸入元素。

用法

例如，請考量下列 DOM 結構。

<input type="email" placeholder="name@example.com" />

您可以在依據預留位置文字尋找輸入後填寫輸入

page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com");

引數

text String | Pattern #

要尋找元素的文字。
options Frame.GetByPlaceholderOptions (選用)
- setExact boolean (選用)#
  
  是否尋找完全相符的項目：區分大小寫且為完整字串。預設為 false。依據規則運算式尋找時會忽略。請注意，完全相符仍然會修剪空格。

傳回

Locator #

getByRole

新增於：v1.27

frame.getByRole

允許依據元素的ARIA 角色、ARIA 屬性和協助工具名稱尋找元素。

用法

請考量下列 DOM 結構。

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

您可以依據每個元素的隱含角色尋找元素

assertThat(page
    .getByRole(AriaRole.HEADING,
               new Page.GetByRoleOptions().setName("Sign up")))
    .isVisible();

page.getByRole(AriaRole.CHECKBOX,
               new Page.GetByRoleOptions().setName("Subscribe"))
    .check();

page.getByRole(AriaRole.BUTTON,
               new Page.GetByRoleOptions().setName(
                   Pattern.compile("submit", Pattern.CASE_INSENSITIVE)))
    .click();

引數

role enum AriaRole { ALERT, ALERTDIALOG, APPLICATION, ARTICLE, BANNER, BLOCKQUOTE, BUTTON, CAPTION, CELL, CHECKBOX, CODE, COLUMNHEADER, COMBOBOX, COMPLEMENTARY, CONTENTINFO, DEFINITION, DELETION, DIALOG, DIRECTORY, DOCUMENT, EMPHASIS, FEED, FIGURE, FORM, GENERIC, GRID, GRIDCELL, GROUP, HEADING, IMG, INSERTION, LINK, LIST, LISTBOX, LISTITEM, LOG, MAIN, MARQUEE, MATH, METER, MENU, MENUBAR, MENUITEM, MENUITEMCHECKBOX, MENUITEMRADIO, NAVIGATION, NONE, NOTE, OPTION, PARAGRAPH, PRESENTATION, PROGRESSBAR, RADIO, RADIOGROUP, REGION, ROW, ROWGROUP, ROWHEADER, SCROLLBAR, SEARCH, SEARCHBOX, SEPARATOR, SLIDER, SPINBUTTON, STATUS, STRONG, SUBSCRIPT, SUPERSCRIPT, SWITCH, TAB, TABLE, TABLIST, TABPANEL, TERM, TEXTBOX, TIME, TIMER, TOOLBAR, TOOLTIP, TREE, TREEGRID, TREEITEM }#

必要的 aria 角色。
options Frame.GetByRoleOptions (選用)
- setChecked boolean (選用)#
  
  通常由 aria-checked 或原生 <input type=checkbox> 控制項設定的屬性。
  
  深入瞭解 aria-checked。
- setDisabled boolean (選用)#
  
  通常由 aria-disabled 或 disabled 設定的屬性。
  
  注意
  與大多數其他屬性不同，disabled 會透過 DOM 階層繼承。深入瞭解 aria-disabled。
- setExact boolean (選用)新增於：v1.28#
  
  setName 是否完全相符：區分大小寫且為完整字串。預設為 false。setName 為規則運算式時會忽略。請注意，完全相符仍然會修剪空格。
- setExpanded boolean (選用)#
  
  通常由 aria-expanded 設定的屬性。
  
  深入瞭解 aria-expanded。
- setIncludeHidden boolean (選用)#
  
  控制是否比對隱藏元素的選項。預設情況下，只有非隱藏元素 (如 ARIA 定義) 會由角色選取器比對。
  
  深入瞭解 aria-hidden。
- setLevel int (選用)#
  
  數字屬性，通常適用於角色 heading、listitem、row、treeitem，且 <h1>-<h6> 元素具有預設值。
  
  深入瞭解 aria-level。
- setName String | Pattern (選用)#
  
  比對協助工具名稱的選項。預設情況下，比對不區分大小寫並搜尋子字串，使用 setExact 控制此行為。
  
  深入瞭解協助工具名稱。
- setPressed boolean (選用)#
  
  通常由 aria-pressed 設定的屬性。
  
  深入瞭解 aria-pressed。
- setSelected boolean (選用)#
  
  通常由 aria-selected 設定的屬性。
  
  深入瞭解 aria-selected。

傳回

Locator #

詳細資訊

角色選取器不會取代協助工具稽核和一致性測試，而是提供有關 ARIA 指導方針的早期意見反應。

許多 html 元素具有隱含的定義角色，角色選取器會辨識此角色。您可以在此處找到所有支援的角色。ARIA 指導方針不建議透過將 role 和/或 aria-* 屬性設定為預設值來重複隱含角色和屬性。

getByTestId

新增於：v1.27

frame.getByTestId

依據測試 ID 尋找元素。

用法

請考量下列 DOM 結構。

<button data-testid="directions">Itinéraire</button>

您可以依據元素的測試 ID 尋找元素

page.getByTestId("directions").click();

引數

testId String | Pattern #

要依據尋找元素的 ID。

傳回

Locator #

詳細資訊

預設情況下，data-testid 屬性會用作測試 ID。如有必要，請使用 Selectors.setTestIdAttribute() 設定不同的測試 ID 屬性。

getByText

新增於：v1.27

frame.getByText

允許尋找包含指定文字的元素。

另請參閱 Locator.filter()，其允許依據另一個準則 (例如協助工具角色) 比對，然後依據文字內容篩選。

用法

請考量下列 DOM 結構

<div>Hello <span>world</span></div>
<div>Hello</div>

您可以依據文字子字串、完全字串或規則運算式尋找

// Matches <span>
page.getByText("world");

// Matches first <div>
page.getByText("Hello world");

// Matches second <div>
page.getByText("Hello", new Page.GetByTextOptions().setExact(true));

// Matches both <div>s
page.getByText(Pattern.compile("Hello"));

// Matches second <div>
page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE));

引數

text String | Pattern #

要尋找元素的文字。
options Frame.GetByTextOptions (選用)
- setExact boolean (選用)#
  
  是否尋找完全相符的項目：區分大小寫且為完整字串。預設為 false。依據規則運算式尋找時會忽略。請注意，完全相符仍然會修剪空格。

傳回

Locator #

詳細資訊

依據文字比對一律會正規化空格，即使是完全相符也一樣。例如，它會將多個空格變成一個，將換行符號變成空格，並忽略開頭和結尾空格。

類型為 button 和 submit 的輸入元素會依據其 value 而不是文字內容進行比對。例如，依據文字 "Log in" 尋找會比對 <input type=button value="Log in">。

getByTitle

新增於：v1.27

frame.getByTitle

允許依據元素的 title 屬性尋找元素。

用法

請考量下列 DOM 結構。

<span title='Issues count'>25 issues</span>

您可以在依據標題文字尋找後檢查問題計數

assertThat(page.getByTitle("Issues count")).hasText("25 issues");

引數

text 字串 | 正規表示式 #

要尋找元素的文字。
options Frame.GetByTitleOptions (選填)
- setExact 布林值 (選填)#
  
  是否尋找完全相符的項目：區分大小寫且為完整字串。預設為 false。依據規則運算式尋找時會忽略。請注意，完全相符仍然會修剪空格。

傳回

定位器 #

isDetached

在 v1.9 之前新增

frame.isDetached

如果框架已分離，則傳回 true，否則傳回 false。

用法

Frame.isDetached();

傳回

布林值 #

isEnabled

在 v1.9 之前新增

frame.isEnabled

傳回元素是否為啟用。

用法

Frame.isEnabled(selector);
Frame.isEnabled(selector, options);

引數

selector 字串 #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.IsEnabledOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout 雙精度浮點數 (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

布林值 #

locator

新增於：v1.14

frame.locator

此方法會傳回元素定位器，可用於對此頁面/框架執行動作。定位器會在執行動作之前立即解析為元素，因此對同一個定位器執行的一系列動作實際上可能會在不同的 DOM 元素上執行。如果這些動作之間的 DOM 結構已變更，就會發生這種情況。

深入瞭解定位器.

用法

Frame.locator(selector);
Frame.locator(selector, options);

引數

selector 字串 #

解析 DOM 元素時要使用的選取器。
options Frame.LocatorOptions (選填)
- setHas 定位器 (選填)#
  
  將方法結果縮小到包含符合此相對定位器的元素的結果。例如，具有 text=Playwright 的 article 符合 <article><div>Playwright</div></article>。
  
  內部定位器**必須相對於**外部定位器，並從外部定位器比對開始查詢，而不是文件根目錄。例如，您可以找到在 <article><content><div>Playwright</div></content></article> 中具有 div 的 content。但是，尋找具有 article div 的 content 將會失敗，因為內部定位器必須是相對的，且不應使用 content 外部的任何元素。
  
  請注意，外部和內部定位器必須屬於同一個框架。內部定位器不得包含 FrameLocator。
- setHasNot 定位器 (選填)新增於：v1.33#
  
  比對不包含符合內部定位器的元素的元素。內部定位器會針對外部定位器查詢。例如，不具有 div 的 article 符合 <article><span>Playwright</span></article>。
  
  請注意，外部和內部定位器必須屬於同一個框架。內部定位器不得包含 FrameLocator。
- setHasNotText 字串 | 正規表示式 (選填)新增於：v1.33#
  
  比對不在內部某處 (可能在子元素或後代元素中) 包含指定文字的元素。當傳遞字串時，比對會區分大小寫並搜尋子字串。
- setHasText 字串 | 正規表示式 (選填)#
  
  比對在內部某處 (可能在子元素或後代元素中) 包含指定文字的元素。當傳遞字串時，比對會區分大小寫並搜尋子字串。例如，"Playwright" 符合 <article><div>Playwright</div></article>。

傳回

定位器 #

name

在 v1.9 之前新增

frame.name

傳回標籤中指定的框架名稱屬性。

如果名稱為空，則改為傳回 id 屬性。

注意

此值在建立框架時計算一次，如果屬性稍後變更，則不會更新。

用法

Frame.name();

傳回

字串 #

navigate

在 v1.9 之前新增

frame.navigate

傳回主要資源回應。如果發生多次重新導向，則導覽將會以最後一次重新導向的回應解析。

在下列情況下，此方法將會擲回錯誤：

發生 SSL 錯誤 (例如，在自我簽署憑證的情況下)。
目標 URL 無效。
導覽期間超出setTimeout。
遠端伺服器未回應或無法連線。
主要資源載入失敗。

當遠端伺服器傳回任何有效的 HTTP 狀態碼時，此方法不會擲回錯誤，包括 404 "Not Found" 和 500 "Internal Server Error"。此類回應的狀態碼可以透過呼叫 Response.status() 擷取。

注意

此方法會擲回錯誤或傳回主要資源回應。唯一的例外是導覽至 about:blank 或導覽至具有不同雜湊的相同 URL，這會成功並傳回 null。

注意

無頭模式不支援導覽至 PDF 文件。請參閱上游問題。

用法

Frame.navigate(url);
Frame.navigate(url, options);

引數

url 字串 #

要導覽框架至的 URL。URL 應包含結構描述，例如 https://。
options Frame.NavigateOptions (選填)
- setReferer 字串 (選填)#
  
  Referer 標頭值。如果提供，則會優先於 Page.setExtraHTTPHeaders() 設定的 referer 標頭值。
- setTimeout 雙精度浮點數 (選填)#
  
  最大操作時間 (毫秒)，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultNavigationTimeout()、BrowserContext.setDefaultTimeout()、Page.setDefaultNavigationTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setWaitUntil enum WaitUntilState { LOAD, DOMCONTENTLOADED, NETWORKIDLE, COMMIT } (選填)#
  
  何時應視為操作成功，預設為 load。事件可以是：
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - **不建議使用** 當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，請改為依賴 Web 判斷提示來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。

傳回

null | 回應 #

page

在 v1.9 之前新增

frame.page

傳回包含此框架的頁面。

用法

Frame.page();

傳回

頁面 #

parentFrame

在 v1.9 之前新增

frame.parentFrame

父框架 (如果有的話)。已分離的框架和主要框架傳回 null。

用法

Frame.parentFrame();

傳回

null | 框架 #

setContent

在 v1.9 之前新增

frame.setContent

此方法會在內部呼叫 document.write()，繼承其所有特定特性和行為。

用法

Frame.setContent(html);
Frame.setContent(html, options);

引數

html 字串 #

要指派給頁面的 HTML 標記。
options Frame.SetContentOptions (選填)
- setTimeout 雙精度浮點數 (選填)#
  
  最大操作時間 (毫秒)，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultNavigationTimeout()、BrowserContext.setDefaultTimeout()、Page.setDefaultNavigationTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setWaitUntil enum WaitUntilState { LOAD, DOMCONTENTLOADED, NETWORKIDLE, COMMIT } (選填)#
  
  何時應視為操作成功，預設為 load。事件可以是：
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - **不建議使用** 當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，請改為依賴 Web 判斷提示來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。

傳回

void #

title

在 v1.9 之前新增

frame.title

傳回頁面標題。

用法

Frame.title();

傳回

字串 #

url

在 v1.9 之前新增

frame.url

傳回框架的 URL。

用法

Frame.url();

傳回

字串 #

waitForFunction

在 v1.9 之前新增

frame.waitForFunction

當 expression 傳回真值時傳回，並傳回該值。

用法

Frame.waitForFunction() 可用於觀察視窗大小變更

import com.microsoft.playwright.*;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      BrowserType firefox = playwright.firefox();
      Browser browser = firefox.launch();
      Page page = browser.newPage();
      page.setViewportSize(50, 50);
      page.mainFrame().waitForFunction("window.innerWidth < 100");
      browser.close();
    }
  }
}

若要將引數傳遞至 frame.waitForFunction 函式的述詞

String selector = ".foo";
frame.waitForFunction("selector => !!document.querySelector(selector)", selector);

引數

expression 字串 #

要在瀏覽器環境中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動叫用該函式。
arg EvaluationArgument (選填)#

要傳遞至 expression 的選填引數。
options Frame.WaitForFunctionOptions (選填)
- setPollingInterval 雙精度浮點數 (選填)#
  
  如果指定，則會將其視為函數將執行的間隔 (以毫秒為單位)。預設情況下，如果未指定選項，則 expression 會在 requestAnimationFrame 回呼中執行。
- setTimeout 雙精度浮點數 (選填)#
  
  要等待的最大時間 (以毫秒為單位)。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

JSHandle #

waitForLoadState

在 v1.9 之前新增

frame.waitForLoadState

等待達到所需的載入狀態。

當框架達到所需的載入狀態時，預設為 load，此方法會傳回。導覽必須在呼叫此方法時已提交。如果目前文件已達到所需的狀態，則會立即解析。

注意

大多數時候，不需要此方法，因為 Playwright 會在每次動作前自動等待。

用法

frame.click("button"); // Click triggers navigation.
frame.waitForLoadState(); // Waits for "load" state by default.

引數

state enum LoadState { LOAD, DOMCONTENTLOADED, NETWORKIDLE } (選填)#

要等待的選填載入狀態，預設為 load。如果載入目前文件時已達到狀態，則此方法會立即解析。可以是下列其中一種：
- 'load' - 等待 load 事件觸發。
- 'domcontentloaded' - 等待 DOMContentLoaded 事件觸發。
- 'networkidle' - **不建議使用** 等待直到至少 500 毫秒沒有網路連線。請勿將此方法用於測試，請改為依賴 Web 判斷提示來評估就緒狀態。
options Frame.WaitForLoadStateOptions (選填)
- setTimeout 雙精度浮點數 (選填)#
  
  最大操作時間 (毫秒)，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultNavigationTimeout()、BrowserContext.setDefaultTimeout()、Page.setDefaultNavigationTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

waitForURL

新增於：v1.11

frame.waitForURL

等待框架導覽至指定的 URL。

用法

frame.click("a.delayed-navigation"); // Clicking the link will indirectly cause a navigation
frame.waitForURL("**/target.html");

引數

url 字串 | 正規表示式 | Predicate<字串>#

在等待導覽時要比對的 glob 模式、正規表示式模式或述詞 (接收 [URL])。請注意，如果參數是沒有萬用字元的字串，則此方法將等待導覽至與字串完全相同的 URL。
options Frame.WaitForURLOptions (選填)
- setTimeout 雙精度浮點數 (選填)#
  
  最大操作時間 (毫秒)，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultNavigationTimeout()、BrowserContext.setDefaultTimeout()、Page.setDefaultNavigationTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setWaitUntil enum WaitUntilState { LOAD, DOMCONTENTLOADED, NETWORKIDLE, COMMIT } (選填)#
  
  何時應視為操作成功，預設為 load。事件可以是：
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - **不建議使用** 當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，請改為依賴 Web 判斷提示來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。

傳回

void #

已過時

check

在 v1.9 之前新增

frame.check

不建議使用

請改用以定位器為基礎的 Locator.check()。深入瞭解定位器。

此方法會透過執行下列步驟來檢查符合 selector 的元素：

尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM 為止。
確保符合的元素是核取方塊或選項按鈕輸入。如果不是，此方法會擲回例外。如果元素已核取，此方法會立即傳回。
除非設定 setForce 選項，否則等待符合的元素上的可操作性檢查。如果元素在檢查期間分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.mouse() 在元素的中心按一下。
確保元素現在已核取。如果沒有，此方法會擲回例外。

當所有步驟組合未在指定的 setTimeout 期間完成時，此方法會擲回 TimeoutError。傳遞零逾時會停用此功能。

用法

Frame.check(selector);
Frame.check(selector, options);

引數

selector 字串 #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.CheckOptions (選填)
- setForce 布林值 (選填)#
  
  是否略過可操作性檢查。預設為 false。
- setNoWaitAfter 布林值 (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (選填)新增於：v1.11#
  - setX double
  - setY double
  要使用的點，相對於元素填補方塊的左上角。如果未指定，則使用元素的某些可見點。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout 雙精度浮點數 (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial 布林值 (選填)新增於：v1.11#
  
  設定後，此方法只會執行可操作性檢查並略過動作。預設為 false。在執行動作之前，等待元素準備就緒時很有用。

傳回

void #

click

在 v1.9 之前新增

frame.click

不建議使用

請改用以定位器為基礎的 Locator.click()。深入瞭解定位器。

此方法會透過執行下列步驟來按一下符合 selector 的元素：

尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM 為止。
除非設定 setForce 選項，否則等待符合的元素上的可操作性檢查。如果元素在檢查期間分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.mouse() 在元素的中心或指定的 setPosition 中按一下。
等待啟動的導覽成功或失敗，除非設定 setNoWaitAfter 選項。

當所有步驟組合未在指定的 setTimeout 期間完成時，此方法會擲回 TimeoutError。傳遞零逾時會停用此功能。

用法

Frame.click(selector);
Frame.click(selector, options);

引數

selector 字串 #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.ClickOptions (選填)
- setButton enum MouseButton { LEFT, RIGHT, MIDDLE } (選填)#
  
  預設為 left。
- setClickCount 整數 (選填)#
  
  預設為 1。請參閱 UIEvent.detail。
- setDelay 雙精度浮點數 (選填)#
  
  mousedown 和 mouseup 之間要等待的時間 (以毫秒為單位)。預設為 0。
- setForce 布林值 (選填)#
  
  是否略過可操作性檢查。預設為 false。
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (選填)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則會使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- setNoWaitAfter 布林值 (選填)#
  
  已棄用
  此選項在未來將預設為 true。
  
  啟動導覽的動作正在等待這些導覽發生以及頁面開始載入。您可以透過設定此旗標來選擇不等待。您只需要在特殊情況下使用此選項，例如導覽至無法存取的頁面。預設為 false。
- setPosition Position (選填)#
  - setX double
  - setY double
  要使用的點，相對於元素填補方塊的左上角。如果未指定，則使用元素的某些可見點。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout 雙精度浮點數 (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial 布林值 (選填)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。適用於等待元素準備好執行動作，而無需執行動作。請注意，鍵盤 modifiers 將會按下，而不論 trial 為何，以允許測試僅在按下這些按鍵時才可見的元素。

傳回

void #

dblclick

在 v1.9 之前新增

frame.dblclick

不建議使用

請改用以定位器為基礎的 Locator.dblclick()。深入瞭解定位器。

此方法會透過執行下列步驟來按兩下符合 selector 的元素：

尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM 為止。
除非設定 setForce 選項，否則等待符合的元素上的可操作性檢查。如果元素在檢查期間分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.mouse() 在元素的中心或指定的 setPosition 中按兩下。如果 dblclick() 的第一次按一下觸發導覽事件，此方法將會擲回例外。

當所有步驟組合未在指定的 setTimeout 期間完成時，此方法會擲回 TimeoutError。傳遞零逾時會停用此功能。

注意

frame.dblclick() 會分派兩個 click 事件和一個 dblclick 事件。

用法

Frame.dblclick(selector);
Frame.dblclick(selector, options);

引數

selector 字串 #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.DblclickOptions (選填)
- setButton enum MouseButton { LEFT, RIGHT, MIDDLE } (選填)#
  
  預設為 left。
- setDelay 雙精度浮點數 (選填)#
  
  mousedown 和 mouseup 之間要等待的時間 (以毫秒為單位)。預設為 0。
- setForce 布林值 (選填)#
  
  是否略過可操作性檢查。預設為 false。
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (選填)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則會使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- setNoWaitAfter 布林值 (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (選填)#
  - setX double
  - setY double
  要使用的點，相對於元素填補方塊的左上角。如果未指定，則使用元素的某些可見點。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout 雙精度浮點數 (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial 布林值 (選填)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。適用於等待元素準備好執行動作，而無需執行動作。請注意，鍵盤 modifiers 將會按下，而不論 trial 為何，以允許測試僅在按下這些按鍵時才可見的元素。

傳回

void #

dispatchEvent

在 v1.9 之前新增

frame.dispatchEvent

不建議使用

請改用以定位器為基礎的 Locator.dispatchEvent()。深入瞭解定位器。

以下程式碼片段會在元素上分派 click 事件。無論元素的顯示狀態為何，都會分派 click。這相當於呼叫 element.click()。

用法

frame.dispatchEvent("button#submit", "click");

在幕後，它會根據指定的 type 建立事件的執行個體，使用 eventInit 屬性初始化它，並在元素上分派它。事件預設為 composed、cancelable 和 bubble。

由於 eventInit 是事件特定的，請參閱事件文件以取得初始屬性清單

如果您希望將即時物件傳遞到事件中，您也可以將 JSHandle 指定為屬性值

// Note you can only create DataTransfer in Chromium and Firefox
JSHandle dataTransfer = frame.evaluateHandle("() => new DataTransfer()");
Map<String, Object> arg = new HashMap<>();
arg.put("dataTransfer", dataTransfer);
frame.dispatchEvent("#source", "dragstart", arg);

引數

selector 字串 #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
type String #

DOM 事件類型："click"、"dragstart" 等。
eventInit EvaluationArgument (選填)#

選填的事件特定初始化屬性。
options Frame.DispatchEventOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

evalOnSelector

新增於：v1.9

frame.evalOnSelector

不建議使用

此方法不會等待元素通過可操作性檢查，因此可能導致測試不穩定。請改用 Locator.evaluate()、其他 Locator 輔助方法或 web-first assertions。

傳回 expression 的傳回值。

此方法會在 frame 中尋找符合指定 selector 的元素，並將其作為第一個引數傳遞給 expression。如果沒有元素符合 selector，此方法會拋出錯誤。

如果 expression 傳回 Promise，則 Frame.evalOnSelector() 會等待 Promise 解析並傳回其值。

用法

String searchValue = (String) frame.evalOnSelector("#search", "el => el.value");
String preloadHref = (String) frame.evalOnSelector("link[rel=preload]", "el => el.href");
String html = (String) frame.evalOnSelector(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello");

引數

selector String #

要查詢的 selector。
expression String #

要在瀏覽器環境中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動叫用該函式。
arg EvaluationArgument (選填)#

要傳遞給 expression 的選填引數。
options Frame.EvalOnSelectorOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

傳回

Object #

evalOnSelectorAll

新增於：v1.9

frame.evalOnSelectorAll

不建議使用

在大多數情況下，Locator.evaluateAll()、其他 Locator 輔助方法和 web-first assertions 會是更好的選擇。

傳回 expression 的傳回值。

此方法會在 frame 中尋找所有符合指定 selector 的元素，並將符合元素的陣列作為第一個引數傳遞給 expression。

如果 expression 傳回 Promise，則 Frame.evalOnSelectorAll() 會等待 Promise 解析並傳回其值。

用法

boolean divsCounts = (boolean) page.evalOnSelectorAll("div", "(divs, min) => divs.length >= min", 10);

引數

selector String #

要查詢的 selector。
expression String #

要在瀏覽器環境中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動叫用該函式。
arg EvaluationArgument (選填)#

要傳遞給 expression 的選填引數。

傳回

Object #

fill

在 v1.9 之前新增

frame.fill

不建議使用

請改用基於 locator 的 Locator.fill()。閱讀更多關於 locators 的資訊。

此方法會等待符合 selector 的元素，等待可操作性檢查，聚焦元素，填寫內容，並在填寫後觸發 input 事件。請注意，您可以傳遞空字串來清除輸入欄位。

如果目標元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法會拋出錯誤。然而，如果元素位於具有關聯 control 的 <label> 元素內，則會改為填寫 control。

若要傳送細緻的鍵盤事件，請使用 Locator.pressSequentially()。

用法

Frame.fill(selector, value);
Frame.fill(selector, value, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
value String #

要為 <input>、<textarea> 或 [contenteditable] 元素填寫的值。
options Frame.FillOptions (選填)
- setForce boolean (選填)新增於：v1.13#
  
  是否略過可操作性檢查。預設為 false。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

focus

在 v1.9 之前新增

frame.focus

不建議使用

請改用基於 locator 的 Locator.focus()。閱讀更多關於 locators 的資訊。

此方法會取得具有 selector 的元素並聚焦它。如果沒有符合 selector 的元素，此方法會等待直到 DOM 中出現符合的元素。

用法

Frame.focus(selector);
Frame.focus(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.FocusOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

getAttribute

在 v1.9 之前新增

frame.getAttribute

不建議使用

請改用基於 locator 的 Locator.getAttribute()。閱讀更多關於 locators 的資訊。

傳回元素屬性值。

用法

Frame.getAttribute(selector, name);
Frame.getAttribute(selector, name, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
name String #

要取得值的屬性名稱。
options Frame.GetAttributeOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

null | String #

hover

在 v1.9 之前新增

frame.hover

不建議使用

請改用基於 locator 的 Locator.hover()。閱讀更多關於 locators 的資訊。

此方法透過執行以下步驟，將游標懸停在符合 selector 的元素上

尋找符合 selector 的元素。如果沒有，請等待直到符合的元素附加到 DOM。
除非設定了 setForce 選項，否則請等待對符合元素進行可操作性檢查。如果在檢查期間元素分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.mouse() 將游標懸停在元素的中心，或指定的 setPosition。

當所有步驟組合起來在指定的 setTimeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

用法

Frame.hover(selector);
Frame.hover(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.HoverOptions (選填)
- setForce boolean (選填)#
  
  是否略過可操作性檢查。預設為 false。
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (選填)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則會使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- setNoWaitAfter boolean (選填)新增於：v1.28#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (選填)#
  - setX double
  - setY double
  要使用的點，相對於元素填補方塊的左上角。如果未指定，則使用元素的某些可見點。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial 布林值 (選填)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。適用於等待元素準備好執行動作，而無需執行動作。請注意，鍵盤 modifiers 將會按下，而不論 trial 為何，以允許測試僅在按下這些按鍵時才可見的元素。

傳回

void #

innerHTML

在 v1.9 之前新增

frame.innerHTML

不建議使用

請改用基於 locator 的 Locator.innerHTML()。閱讀更多關於 locators 的資訊。

傳回 element.innerHTML。

用法

Frame.innerHTML(selector);
Frame.innerHTML(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.InnerHTMLOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

String #

innerText

在 v1.9 之前新增

frame.innerText

不建議使用

請改用基於 locator 的 Locator.innerText()。閱讀更多關於 locators 的資訊。

傳回 element.innerText。

用法

Frame.innerText(selector);
Frame.innerText(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.InnerTextOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

String #

inputValue

新增於：v1.13

frame.inputValue

不建議使用

請改用基於 locator 的 Locator.inputValue()。閱讀更多關於 locators 的資訊。

傳回所選取 <input> 或 <textarea> 或 <select> 元素的 input.value。

對於非輸入元素會拋出錯誤。然而，如果元素位於具有關聯 control 的 <label> 元素內，則會傳回 control 的值。

用法

Frame.inputValue(selector);
Frame.inputValue(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.InputValueOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

String #

isChecked

在 v1.9 之前新增

frame.isChecked

不建議使用

請改用基於 locator 的 Locator.isChecked()。閱讀更多關於 locators 的資訊。

傳回元素是否被核取。如果元素不是核取方塊或 radio 輸入，則會拋出錯誤。

用法

Frame.isChecked(selector);
Frame.isChecked(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.IsCheckedOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

boolean #

isDisabled

在 v1.9 之前新增

frame.isDisabled

不建議使用

請改用基於 locator 的 Locator.isDisabled()。閱讀更多關於 locators 的資訊。

傳回元素是否已停用，與 enabled 相反。

用法

Frame.isDisabled(selector);
Frame.isDisabled(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.IsDisabledOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

boolean #

isEditable

在 v1.9 之前新增

frame.isEditable

不建議使用

請改用基於 locator 的 Locator.isEditable()。閱讀更多關於 locators 的資訊。

傳回元素是否為可編輯。

用法

Frame.isEditable(selector);
Frame.isEditable(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.IsEditableOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

boolean #

isHidden

在 v1.9 之前新增

frame.isHidden

不建議使用

請改用基於 locator 的 Locator.isHidden()。閱讀更多關於 locators 的資訊。

傳回元素是否隱藏，與 visible 相反。不符合任何元素的 selector 會被視為隱藏。

用法

Frame.isHidden(selector);
Frame.isHidden(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.IsHiddenOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  已棄用
  此選項會被忽略。Frame.isHidden() 不會等待元素變成隱藏，並立即傳回。

傳回

boolean #

isVisible

在 v1.9 之前新增

frame.isVisible

不建議使用

請改用基於 locator 的 Locator.isVisible()。閱讀更多關於 locators 的資訊。

傳回元素是否可見。不符合任何元素的 selector 會被視為不可見。

用法

Frame.isVisible(selector);
Frame.isVisible(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.IsVisibleOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  已棄用
  此選項會被忽略。Frame.isVisible() 不會等待元素變成可見，並立即傳回。

傳回

boolean #

press

在 v1.9 之前新增

frame.press

不建議使用

請改用基於 locator 的 Locator.press()。閱讀更多關於 locators 的資訊。

key 可以指定預期的 keyboardEvent.key 值或產生文字的單一字元。key 值的超集可以在這裡找到。按鍵範例包括

F1 - F12、Digit0- Digit9、KeyA- KeyZ、Backquote、Minus、Equal、Backslash、Backspace、Tab、Delete、Escape、ArrowDown、End、Enter、Home、Insert、PageDown、PageUp、ArrowRight、ArrowUp 等。

也支援以下修改快捷鍵：Shift、Control、Alt、Meta、ShiftLeft、ControlOrMeta。ControlOrMeta 在 Windows 和 Linux 上解析為 Control，在 macOS 上解析為 Meta。

按住 Shift 將會輸入與大寫 key 對應的文字。

如果 key 是單一字元，則會區分大小寫，因此值 a 和 A 將會產生不同的各自文字。

也支援諸如 key: "Control+o"、key: "Control++ 或 key: "Control+Shift+T" 之類的快捷鍵。當使用修飾鍵指定時，在按下後續按鍵時，會按下並按住修飾鍵。

用法

Frame.press(selector, key);
Frame.press(selector, key, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
key String #

要按下的按鍵名稱或要產生的字元，例如 ArrowLeft 或 a。
options Frame.PressOptions (選填)
- setDelay double (選填)#
  
  keydown 和 keyup 之間等待的時間，以毫秒為單位。預設為 0。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項在未來將預設為 true。
  
  啟動導覽的動作正在等待這些導覽發生以及頁面開始載入。您可以透過設定此旗標來選擇不等待。您只需要在特殊情況下使用此選項，例如導覽至無法存取的頁面。預設為 false。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

querySelector

新增於：v1.9

frame.querySelector

不建議使用

請改用基於 locator 的 Frame.locator()。閱讀更多關於 locators 的資訊。

傳回指向 frame 元素的 ElementHandle。

注意

不建議使用 ElementHandle，請改用 Locator 物件和 web-first assertions。

此方法會在 frame 中尋找符合指定 selector 的元素。如果沒有元素符合 selector，則傳回 null。

用法

Frame.querySelector(selector);
Frame.querySelector(selector, options);

引數

selector String #

要查詢的 selector。
options Frame.QuerySelectorOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

傳回

null | ElementHandle #

querySelectorAll

新增於：v1.9

frame.querySelectorAll

不建議使用

請改用基於 locator 的 Frame.locator()。閱讀更多關於 locators 的資訊。

傳回指向 frame 元素的 ElementHandle 陣列。

注意

不建議使用 ElementHandle，請改用 Locator 物件。

此方法會在 frame 中尋找所有符合指定 selector 的元素。如果沒有元素符合 selector，則傳回空陣列。

用法

Frame.querySelectorAll(selector);

引數

selector String #

要查詢的 selector。

傳回

List<ElementHandle>#

selectOption

在 v1.9 之前新增

frame.selectOption

不建議使用

請改用基於 locator 的 Locator.selectOption()。閱讀更多關於 locators 的資訊。

此方法會等待符合 selector 的元素，等待可操作性檢查，等待直到所有指定的選項都出現在 <select> 元素中，然後選取這些選項。

如果目標元素不是 <select> 元素，此方法會拋出錯誤。然而，如果元素位於具有關聯 control 的 <label> 元素內，則會改為使用 control。

傳回已成功選取的選項值陣列。

一旦選取所有提供的選項，就會觸發 change 和 input 事件。

用法

// Single selection matching the value or label
frame.selectOption("select#colors", "blue");
// single selection matching both the value and the label
frame.selectOption("select#colors", new SelectOption().setLabel("Blue"));
// multiple selection
frame.selectOption("select#colors", new String[] {"red", "green", "blue"});

引數

selector String #

要查詢的 selector。
values null | String | ElementHandle | String[] | SelectOption | ElementHandle[] | SelectOption[]#
- setValue String (選填)
  
  依 option.value 匹配。選填。
- setLabel String (選填)
  
  依 option.label 匹配。選填。
- setIndex int (選填)
  
  依索引匹配。選填。
要選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有符合的選項，否則只會選取第一個符合傳遞選項之一的選項。字串值會同時匹配值和標籤。如果所有指定的屬性都匹配，則選項會被視為匹配。
options Frame.SelectOptionOptions (選填)
- setForce boolean (選填)新增於：v1.13#
  
  是否略過可操作性檢查。預設為 false。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

List<String>#

setChecked

新增於：v1.15

frame.setChecked

不建議使用

請改用基於 Locator 的 Locator.setChecked()。閱讀更多關於 locators 的資訊。

此方法透過執行以下步驟，勾選或取消勾選符合 selector 的元素

尋找符合 selector 的元素。如果沒有，則等待直到符合的元素附加到 DOM。
確保匹配的元素是核取方塊或單選輸入。如果不是，此方法會拋出例外。
如果元素已處於正確的勾選狀態，此方法會立即返回。
等待匹配元素上的 actionability 檢查，除非設定了 setForce 選項。如果元素在檢查期間分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.mouse() 在元素的中心按一下。
確保元素現在已勾選或取消勾選。如果不是，此方法會拋出例外。

當所有步驟組合起來在指定的 setTimeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

用法

Frame.setChecked(selector, checked);
Frame.setChecked(selector, checked, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
checked boolean #

是否勾選或取消勾選核取方塊。
options Frame.SetCheckedOptions (選填)
- setForce boolean (選填)#
  
  是否略過可操作性檢查。預設為 false。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (選填)#
  - setX double
  - setY double
  要使用的點，相對於元素填補方塊的左上角。如果未指定，則使用元素的某些可見點。
- setStrict boolean (選填)#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial boolean (選填)#
  
  設定後，此方法只會執行可操作性檢查並略過動作。預設為 false。在執行動作之前，等待元素準備就緒時很有用。

傳回

void #

setInputFiles

在 v1.9 之前新增

frame.setInputFiles

不建議使用

請改用基於 Locator 的 Locator.setInputFiles()。閱讀更多關於 locators 的資訊。

將檔案輸入的值設定為這些檔案路徑或檔案。如果某些 filePaths 是相對路徑，則它們會相對於目前的工作目錄解析。對於空陣列，清除選取的檔案。

此方法預期 selector 指向 input 元素。但是，如果元素位於具有關聯 control 的 <label> 元素內，則會改為目標控制項。

用法

Frame.setInputFiles(selector, files);
Frame.setInputFiles(selector, files, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
files Path | Path[] | FilePayload | FilePayload[]#
- setName String
  
  檔案名稱
- setMimeType String
  
  檔案類型
- setBuffer byte[]
  
  檔案內容
options Frame.SetInputFilesOptions (選填)
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

tap

在 v1.9 之前新增

frame.tap

不建議使用

請改用基於 Locator 的 Locator.tap()。閱讀更多關於 locators 的資訊。

此方法透過執行以下步驟，點擊符合 selector 的元素

尋找符合 selector 的元素。如果沒有，則等待直到符合的元素附加到 DOM。
等待匹配元素上的 actionability 檢查，除非設定了 setForce 選項。如果元素在檢查期間分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.touchscreen() 點擊元素的中心，或指定的 setPosition。

當所有步驟組合起來在指定的 setTimeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

注意

frame.tap() 要求瀏覽器內容的 hasTouch 選項設定為 true。

用法

Frame.tap(selector);
Frame.tap(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.TapOptions (選填)
- setForce boolean (選填)#
  
  是否略過可操作性檢查。預設為 false。
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (選填)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則會使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (選填)#
  - setX double
  - setY double
  要使用的點，相對於元素填補方塊的左上角。如果未指定，則使用元素的某些可見點。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial 布林值 (選填)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。適用於等待元素準備好執行動作，而無需執行動作。請注意，鍵盤 modifiers 將會按下，而不論 trial 為何，以允許測試僅在按下這些按鍵時才可見的元素。

傳回

void #

textContent

在 v1.9 之前新增

frame.textContent

不建議使用

請改用基於 Locator 的 Locator.textContent()。閱讀更多關於 locators 的資訊。

傳回 element.textContent。

用法

Frame.textContent(selector);
Frame.textContent(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.TextContentOptions (選填)
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

null | String #

type

在 v1.9 之前新增

frame.type

已棄用

在大多數情況下，您應該使用 Locator.fill() 來代替。只有在頁面上有特殊的鍵盤處理時，才需要逐個按下按鍵 - 在這種情況下，請使用 Locator.pressSequentially()。

為文字中的每個字元傳送 keydown、keypress/input 和 keyup 事件。frame.type 可用於傳送細微的鍵盤事件。若要在表單欄位中填寫值，請使用 Frame.fill()。

若要按下特殊按鍵，例如 Control 或 ArrowDown，請使用 Keyboard.press()。

用法

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
text String #

要輸入到焦點元素中的文字。
options Frame.TypeOptions (選填)
- setDelay double (選填)#
  
  按鍵之間等待的時間，以毫秒為單位。預設為 0。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

uncheck

在 v1.9 之前新增

frame.uncheck

不建議使用

請改用基於 Locator 的 Locator.uncheck()。閱讀更多關於 locators 的資訊。

此方法透過執行以下步驟，檢查符合 selector 的元素

尋找符合 selector 的元素。如果沒有，則等待直到符合的元素附加到 DOM。
確保匹配的元素是核取方塊或單選輸入。如果不是，此方法會拋出例外。如果元素已取消勾選，此方法會立即返回。
等待匹配元素上的 actionability 檢查，除非設定了 setForce 選項。如果元素在檢查期間分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.mouse() 在元素的中心按一下。
確保元素現在已取消勾選。如果不是，此方法會拋出例外。

當所有步驟組合起來在指定的 setTimeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

用法

Frame.uncheck(selector);
Frame.uncheck(selector, options);

引數

selector String #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options Frame.UncheckOptions (選填)
- setForce boolean (選填)#
  
  是否略過可操作性檢查。預設為 false。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (選填)新增於：v1.11#
  - setX double
  - setY double
  要使用的點，相對於元素填補方塊的左上角。如果未指定，則使用元素的某些可見點。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial 布林值 (選填)新增於：v1.11#
  
  設定後，此方法只會執行可操作性檢查並略過動作。預設為 false。在執行動作之前，等待元素準備就緒時很有用。

傳回

void #

在 v1.9 之前新增

frame.waitForNavigation

已棄用

此方法本質上是競爭性的，請改用 Frame.waitForURL()。

等待框架導航並傳回主要資源回應。在多次重新導向的情況下，導航將使用最後一次重新導向的回應來解析。如果導航到不同的錨點或由於 History API 使用而導航，則導航將使用 null 解析。

用法

此方法等待框架導航到新的 URL。當您執行會間接導致框架導航的程式碼時，這很有用。請考慮以下範例

// The method returns after navigation has finished
frame.waitForNavigation(() -> {
  // Clicking the link will indirectly cause a navigation
  frame.click("a.delayed-navigation");
});

注意

使用 History API 變更 URL 被視為導航。

引數

options Frame.WaitForNavigationOptions (選填)
- setTimeout double (選填)#
  
  最大操作時間 (毫秒)，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultNavigationTimeout()、BrowserContext.setDefaultTimeout()、Page.setDefaultNavigationTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setUrl String | Pattern | Predicate<String> (選填)#
  
  在等待導覽時要比對的 glob 模式、正規表示式模式或述詞 (接收 [URL])。請注意，如果參數是沒有萬用字元的字串，則此方法將等待導覽至與字串完全相同的 URL。
- setWaitUntil enum WaitUntilState { LOAD, DOMCONTENTLOADED, NETWORKIDLE, COMMIT } (選填)#
  
  何時應視為操作成功，預設為 load。事件可以是：
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - **不建議使用** 當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，請改為依賴 Web 判斷提示來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。
callback Runnable新增於：v1.9#

執行觸發事件之動作的回呼函數。

傳回

null | Response #

waitForSelector

在 v1.9 之前新增

frame.waitForSelector

不建議使用

請改用 web assertions 來斷言可見性，或基於 locator 的 Locator.waitFor()。閱讀更多關於 locators 的資訊。

當 selector 指定的元素滿足 setState 選項時返回。如果等待 hidden 或 detached，則返回 null。

注意

Playwright 會自動等待元素準備就緒，然後再執行動作。使用 Locator 物件和 web-first assertions 使程式碼無需 wait-for-selector。

等待 selector 滿足 setState 選項（出現/從 dom 中消失，或變得可見/隱藏）。如果在呼叫方法時，selector 已經滿足條件，則該方法將立即返回。如果 selector 在 setTimeout 毫秒內未滿足條件，則該函數將拋出例外。

用法

此方法跨導航工作

import com.microsoft.playwright.*;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      BrowserType chromium = playwright.chromium();
      Browser browser = chromium.launch();
      Page page = browser.newPage();
      for (String currentURL : Arrays.asList("https://google.com", "https://bbc.com")) {
        page.navigate(currentURL);
        ElementHandle element = page.mainFrame().waitForSelector("img");
        System.out.println("Loaded image: " + element.getAttribute("src"));
      }
      browser.close();
    }
  }
}

引數

selector String #

要查詢的 selector。
options Frame.WaitForSelectorOptions (選填)
- setState enum WaitForSelectorState { ATTACHED, DETACHED, VISIBLE, HIDDEN } (選填)#
  
  預設為 'visible'。可以是
  - 'attached' - 等待元素出現在 DOM 中。
  - 'detached' - 等待元素不顯示在 DOM 中。
  - 'visible' - 等待元素具有非空的邊界框且沒有 visibility:hidden。請注意，沒有任何內容或具有 display:none 的元素具有空的邊界框，並且不被視為可見。
  - 'hidden' - 等待元素從 DOM 中分離，或具有空的邊界框或 visibility:hidden。這與 'visible' 選項相反。
- setStrict boolean (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- setTimeout double (選填)#
  
  以毫秒為單位的最大時間。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

null | ElementHandle #

waitForTimeout

在 v1.9 之前新增

frame.waitForTimeout

不建議使用

永遠不要在生產環境中等待逾時。等待時間的測試本質上是不穩定的。請改用 Locator 動作和自動等待的 web assertions。

等待給定的 timeout 毫秒。

請注意，frame.waitForTimeout() 僅應用於偵錯。在生產環境中使用計時器的測試將會變得不穩定。請改用訊號，例如網路事件、選取器變得可見等。

用法

Frame.waitForTimeout(timeout);

引數

timeout double #

要等待的逾時時間

傳回

void #

方法​

addScriptTag​

addStyleTag​

childFrames​

content​

dragAndDrop​

evaluate​

evaluateHandle​

frameElement​

frameLocator​

getByAltText​

getByLabel​

getByPlaceholder​

getByRole​

getByTestId​

getByText​

getByTitle​

isDetached​

isEnabled​

locator​

name​

navigate​

page​

parentFrame​

setContent​

title​

url​

waitForFunction​

waitForLoadState​

waitForURL​

已過時​

check​

click​

dblclick​

dispatchEvent​

evalOnSelector​

evalOnSelectorAll​

fill​

focus​

getAttribute​

hover​

innerHTML​

innerText​

inputValue​

isChecked​

isDisabled​

isEditable​

isHidden​

isVisible​

press​

querySelector​

querySelectorAll​

selectOption​

setChecked​

setInputFiles​

tap​

textContent​

type​

uncheck​

waitForNavigation​

waitForSelector​

waitForTimeout​

方法

addScriptTag

addStyleTag

childFrames

content

dragAndDrop

evaluate

evaluateHandle

frameElement

frameLocator

getByAltText

getByLabel

getByPlaceholder

getByRole

getByTestId

getByText

getByTitle

isDetached

isEnabled

locator

name

navigate

page

parentFrame

setContent

title

url

waitForFunction

waitForLoadState

waitForURL

已過時

check

click

dblclick

dispatchEvent

evalOnSelector

evalOnSelectorAll

fill

focus

getAttribute

hover

innerHTML

innerText

inputValue

isChecked

isDisabled

isEditable

isHidden

isVisible

press

querySelector

querySelectorAll

selectOption

setChecked

setInputFiles

tap

textContent

type

uncheck

waitForNavigation

waitForSelector

waitForTimeout