Frame

在任何時間點，頁面都會透過 Page.MainFrame 和 Frame.ChildFrames 方法公開其目前的 frame 樹狀結構。

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

Page.FrameAttached - 當 frame 附加到頁面時觸發。一個 Frame 只能附加到頁面一次。
Page.FrameNavigated - 當 frame 提交導航到不同的 URL 時觸發。
Page.FrameDetached - 當 frame 從頁面分離時觸發。一個 Frame 只能從頁面分離一次。

傾印 frame 樹狀結構的範例

using Microsoft.Playwright;
using System;
using System.Threading.Tasks;

class FrameExamples
{
    public static async Task Main()
    {
        using var playwright = await Playwright.CreateAsync();
        await using var browser = await playwright.Firefox.LaunchAsync();
        var page = await browser.NewPageAsync();

        await page.GotoAsync("https://www.bing.com");
        DumpFrameTree(page.MainFrame, string.Empty);
    }

    private static void DumpFrameTree(IFrame frame, string indent)
    {
        Console.WriteLine($"{indent}{frame.Url}");
        foreach (var child in frame.ChildFrames)
            DumpFrameTree(child, indent + " ");
    }
}

方法

AddScriptTagAsync

在 v1.9 之前新增

frame.AddScriptTagAsync

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

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

用法

await Frame.AddScriptTagAsync(options);

引數

options FrameAddScriptTagOptions? (選用)
- Content string? (選用)#
  
  要注入到 frame 中的原始 JavaScript 內容。
- Path string? (選用)#
  
  要注入到 frame 中的 JavaScript 檔案路徑。如果 path 是相對路徑，則會相對於目前的工作目錄解析。
- Type string? (選用)#
  
  腳本類型。使用 'module' 載入 JavaScript ES6 模組。請參閱 script 以取得更多詳細資訊。
- Url string? (選用)#
  
  要新增的腳本 URL。

傳回

ElementHandle #

AddStyleTagAsync

在 v1.9 之前新增

frame.AddStyleTagAsync

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

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

用法

await Frame.AddStyleTagAsync(options);

引數

options FrameAddStyleTagOptions? (選用)
- Content string? (選用)#
  
  要注入到 frame 中的原始 CSS 內容。
- Path string? (選用)#
  
  要注入到 frame 中的 CSS 檔案路徑。如果 path 是相對路徑，則會相對於目前的工作目錄解析。
- Url string? (選用)#
  
  <link> 標籤的 URL。

傳回

ElementHandle #

ChildFrames

在 v1.9 之前新增

frame.ChildFrames

用法

Frame.ChildFrames

傳回

IEnumerable<Frame>#

ContentAsync

在 v1.9 之前新增

frame.ContentAsync

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

用法

await Frame.ContentAsync();

傳回

string #

DragAndDropAsync

新增於：v1.13

frame.DragAndDropAsync

用法

await Frame.DragAndDropAsync(source, target, options);

引數

source string #

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

要搜尋要放置到其上的元素的選取器。如果有多個元素符合選取器，將會使用第一個。
options FrameDragAndDropOptions? (選用)
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- SourcePosition SourcePosition? (選用)新增於：v1.14#
  - X [float]
  - Y [float]
  在此點擊來源元素，相對於元素 padding box 的左上角。如果未指定，則會使用元素的某些可見點。
- Strict bool? (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- TargetPosition TargetPosition? (選用)新增於：v1.14#
  - X [float]
  - Y [float]
  在此點放置到目標元素上，相對於元素 padding box 的左上角。如果未指定，則會使用元素的某些可見點。
- Timeout [float]? (選用)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)#
  
  設定後，此方法只會執行可操作性檢查，並略過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。

傳回

void #

EvaluateAsync

在 v1.9 之前新增

frame.EvaluateAsync

傳回 expression 的傳回值。

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

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

用法

var result = await frame.EvaluateAsync<int>("([x, y]) => Promise.resolve(x * y)", new[] { 7, 8 });
Console.WriteLine(result);

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

Console.WriteLine(await frame.EvaluateAsync<int>("1 + 2")); // prints "3"

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

var bodyHandle = await frame.EvaluateAsync("document.body");
var html = await frame.EvaluateAsync<string>("([body, suffix]) => body.innerHTML + suffix", new object [] { bodyHandle, "hello" });
await bodyHandle.DisposeAsync();

引數

expression string #

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

要傳遞至 expression 的選用引數。

傳回

[object]#

EvaluateHandleAsync

在 v1.9 之前新增

frame.EvaluateHandleAsync

以 JSHandle 形式傳回 expression 的傳回值。

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

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

用法

// Handle for the window object.
var aWindowHandle = await frame.EvaluateHandleAsync("() => Promise.resolve(window)");

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

var docHandle = await frame.EvaluateHandleAsync("document"); // Handle for the `document`

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

var handle = await frame.EvaluateHandleAsync("() => document.body");
var resultHandle = await frame.EvaluateHandleAsync("([body, suffix]) => body.innerHTML + suffix", new object[] { handle, "hello" });
Console.WriteLine(await resultHandle.JsonValueAsync<string>());
await resultHandle.DisposeAsync();

引數

expression string #

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

要傳遞至 expression 的選用引數。

傳回

JSHandle #

FrameElementAsync

在 v1.9 之前新增

frame.FrameElementAsync

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

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

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

用法

var frameElement = await frame.FrameElementAsync();
var contentFrame = await frameElement.ContentFrameAsync();
Console.WriteLine(frame == contentFrame); // -> True

傳回

ElementHandle #

FrameLocator

新增於：v1.17

frame.FrameLocator

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

用法

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

var locator = frame.FrameLocator("#my-iframe").GetByText("Submit");
await locator.ClickAsync();

引數

selector string #

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

傳回

FrameLocator #

GetByAltText

新增於：v1.27

frame.GetByAltText

允許依據元素的 alt 文字定位元素。

用法

例如，此方法將依據 alt 文字 "Playwright logo" 尋找影像

<img alt='Playwright logo'>

await page.GetByAltText("Playwright logo").ClickAsync();

引數

text string | Regex #

要用於定位元素的文字。
options FrameGetByAltTextOptions? (選用)
- Exact bool? (選用)#
  
  是否尋找完全符合的項目：區分大小寫和全字串。預設為 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">

await page.GetByLabel("Username").FillAsync("john");
await page.GetByLabel("Password").FillAsync("secret");

引數

text string | Regex #

要用於定位元素的文字。
options FrameGetByLabelOptions? (選用)
- Exact bool? (選用)#
  
  是否尋找完全符合的項目：區分大小寫和全字串。預設為 false。當依據規則運算式定位時會忽略。請注意，完全符合仍然會修剪空格。

傳回

Locator #

GetByPlaceholder

新增於：v1.27

frame.GetByPlaceholder

允許依據 placeholder 文字定位輸入元素。

用法

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

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

您可以在依據 placeholder 文字定位輸入後填寫輸入

await page
    .GetByPlaceholder("name@example.com")
    .FillAsync("playwright@microsoft.com");

引數

text string | Regex #

要用於定位元素的文字。
options FrameGetByPlaceholderOptions? (選用)
- Exact bool? (選用)#
  
  是否尋找完全符合的項目：區分大小寫和全字串。預設為 false。當依據規則運算式定位時會忽略。請注意，完全符合仍然會修剪空格。

傳回

Locator #

GetByRole

新增於：v1.27

frame.GetByRole

允許依據元素的 ARIA 角色、ARIA 屬性和可存取名稱定位元素。

用法

請考慮下列 DOM 結構。

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

您可以依據每個元素的隱含角色定位它

await Expect(Page
    .GetByRole(AriaRole.Heading, new() { Name = "Sign up" }))
    .ToBeVisibleAsync();

await page
    .GetByRole(AriaRole.Checkbox, new() { Name = "Subscribe" })
    .CheckAsync();

await page
    .GetByRole(AriaRole.Button, new() {
        NameRegex = new Regex("submit", RegexOptions.IgnoreCase)
    })
    .ClickAsync();

引數

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 FrameGetByRoleOptions? (選用)
- Checked bool? (選用)#
  
  通常由 aria-checked 或原生 <input type=checkbox> 控制項設定的屬性。
  
  深入瞭解 aria-checked。
- Disabled bool? (選用)#
  
  通常由 aria-disabled 或 disabled 設定的屬性。
  
  注意
  與大多數其他屬性不同，disabled 是透過 DOM 階層繼承的。深入瞭解 aria-disabled。
- Exact bool? (選用)新增於：v1.28#
  
  是否完全比對 Name|NameRegex：區分大小寫和全字串。預設為 false。當 Name|NameRegex 是規則運算式時會忽略。請注意，完全符合仍然會修剪空格。
- Expanded bool? (選用)#
  
  通常由 aria-expanded 設定的屬性。
  
  深入瞭解 aria-expanded。
- IncludeHidden bool? (選用)#
  
  控制是否比對隱藏元素的選項。預設情況下，只有非隱藏元素（如 ARIA 定義）會由角色選取器比對。
  
  深入瞭解 aria-hidden。
- Level int? (選用)#
  
  數字屬性，通常用於角色 heading、listitem、row、treeitem，<h1>-<h6> 元素具有預設值。
  
  深入瞭解 aria-level。
- Name|NameRegex string? | Regex? (選用)#
  
  比對可存取名稱的選項。預設情況下，比對不區分大小寫並搜尋子字串，使用 Exact 來控制此行為。
  
  深入瞭解可存取名稱。
- Pressed bool? (選用)#
  
  通常由 aria-pressed 設定的屬性。
  
  深入瞭解 aria-pressed。
- Selected bool? (選用)#
  
  通常由 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 定位它

await page.GetByTestId("directions").ClickAsync();

引數

testId string | Regex #

要用於定位元素的 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() { Exact = true });

// Matches both <div>s
page.GetByText(new Regex("Hello"));

// Matches second <div>
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase));

引數

text string | Regex #

要用於定位元素的文字。
options FrameGetByTextOptions? (選用)
- Exact bool? (選用)#
  
  是否尋找完全符合的項目：區分大小寫和全字串。預設為 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>

您可以在依據標題文字定位元素後，檢查問題計數

await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");

引數

text string | Regex #

要用於定位元素的文字。
options FrameGetByTitleOptions? (選填)
- Exact bool? (選填)#
  
  是否尋找完全符合的項目：區分大小寫和全字串。預設為 false。當依據規則運算式定位時會忽略。請注意，完全符合仍然會修剪空格。

傳回

Locator #

GotoAsync

在 v1.9 之前新增

frame.GotoAsync

傳回主要資源的回應。若發生多次重新導向，導航將會以最後一次重新導向的回應來解析。

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

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

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

注意

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

注意

Headless 模式不支援導航到 PDF 文件。請參閱上游問題。

用法

await Frame.GotoAsync(url, options);

引數

url string #

要導航框架前往的 URL。URL 應包含 scheme，例如 https://。
options FrameGotoOptions? (選填)
- Referer string? (選填)#
  
  Referer 標頭值。如果提供此值，其優先順序會高於 Page.SetExtraHTTPHeadersAsync() 設定的 referer 標頭值。
- Timeout [float]? (選填)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選填)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作完成。
  - 'load' - 當 load 事件觸發時，視為操作完成。
  - 'networkidle' - **不建議** 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，而是依賴網頁斷言來評估準備狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

Response?#

IsDetached

在 v1.9 之前新增

frame.IsDetached

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

用法

Frame.IsDetached

傳回

bool #

IsEnabledAsync

在 v1.9 之前新增

frame.IsEnabledAsync

傳回元素是否為啟用狀態。

用法

await Frame.IsEnabledAsync(selector, options);

引數

selector string #

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

傳回

bool #

Locator

新增於：v1.14

frame.Locator

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

深入了解定位器.

用法

Frame.Locator(selector, options);

引數

selector string #

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

傳回

Locator #

Name

在 v1.9 之前新增

frame.Name

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

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

注意

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

用法

Frame.Name

傳回

string #

Page

在 v1.9 之前新增

frame.Page

傳回包含此框架的頁面。

用法

Frame.Page

傳回

Page #

ParentFrame

在 v1.9 之前新增

frame.ParentFrame

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

用法

Frame.ParentFrame

傳回

Frame?#

SetContentAsync

在 v1.9 之前新增

frame.SetContentAsync

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

用法

await Frame.SetContentAsync(html, options);

引數

html string #

要指派給頁面的 HTML 標記。
options FrameSetContentOptions? (選填)
- Timeout [float]? (選填)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選填)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作完成。
  - 'load' - 當 load 事件觸發時，視為操作完成。
  - 'networkidle' - **不建議** 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，而是依賴網頁斷言來評估準備狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

void #

TitleAsync

在 v1.9 之前新增

frame.TitleAsync

傳回頁面標題。

用法

await Frame.TitleAsync();

傳回

string #

Url

在 v1.9 之前新增

frame.Url

傳回框架的 url。

用法

Frame.Url

傳回

string #

WaitForFunctionAsync

在 v1.9 之前新增

frame.WaitForFunctionAsync

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

用法

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

using Microsoft.Playwright;
using System.Threading.Tasks;

class FrameExamples
{
    public static async Task Main()
    {
        using var playwright = await Playwright.CreateAsync();
        await using var browser = await playwright.Firefox.LaunchAsync();
        var page = await browser.NewPageAsync();
        await page.SetViewportSizeAsync(50, 50);
        await page.MainFrame.WaitForFunctionAsync("window.innerWidth < 100");
    }
}

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

var selector = ".foo";
await page.MainFrame.WaitForFunctionAsync("selector => !!document.querySelector(selector)", selector);

引數

expression string #

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

要傳遞至 expression 的選用引數。
options FrameWaitForFunctionOptions? (選填)
- PollingInterval [float]? (選填)#
  
  如果指定，則會將其視為函數將執行的間隔 (以毫秒為單位)。預設情況下，如果未指定選項，則 expression 會在 requestAnimationFrame 回呼中執行。
- Timeout [float]? (選填)#
  
  等待的最大時間 (以毫秒為單位)。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

JSHandle #

WaitForLoadStateAsync

在 v1.9 之前新增

frame.WaitForLoadStateAsync

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

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

注意

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

用法

await frame.ClickAsync("button");
await frame.WaitForLoadStateAsync(); // Defaults to LoadState.Load

引數

state enum LoadState { Load, DOMContentLoaded, NetworkIdle }? (選填)#

要等待的選用載入狀態，預設為 load。如果在載入目前文檔時已達到該狀態，則此方法會立即解析。可以是下列其中之一
- 'load' - 等待 load 事件觸發。
- 'domcontentloaded' - 等待 DOMContentLoaded 事件觸發。
- 'networkidle' - **不建議** 等待直到至少 500 毫秒沒有網路連線。請勿將此方法用於測試，而是依賴網頁斷言來評估準備狀態。
options FrameWaitForLoadStateOptions? (選填)
- Timeout [float]? (選填)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

WaitForURLAsync

新增於：v1.11

frame.WaitForURLAsync

等待框架導航到給定的 URL。

用法

await frame.ClickAsync("a.delayed-navigation"); // clicking the link will indirectly cause a navigation
await frame.WaitForURLAsync("**/target.html");

引數

url string | Regex | Func<string, bool>#

在等待導航時要比對的 glob 模式、regex 模式或接收 URL 的述詞。請注意，如果參數是沒有萬用字元的字串，則此方法將等待導航到與該字串完全相同的 URL。
options FrameWaitForURLOptions? (選填)
- Timeout [float]? (選填)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選填)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作完成。
  - 'load' - 當 load 事件觸發時，視為操作完成。
  - 'networkidle' - **不建議** 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，而是依賴網頁斷言來評估準備狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

void #

已過時

CheckAsync

在 v1.9 之前新增

frame.CheckAsync

不建議使用

請改用基於定位器的 Locator.CheckAsync()。深入了解定位器。

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

尋找符合 selector 的元素。如果沒有，則等待直到符合的元素附加到 DOM。
確保符合的元素是核取方塊或單選輸入。如果不是，此方法會擲回錯誤。如果元素已核取，此方法會立即傳回。
等待對符合的元素進行可操作性檢查，除非設定 Force 選項。如果在檢查期間元素分離，則會重試整個操作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 在元素的中心點擊。
確保元素現在已核取。如果沒有，此方法會擲回錯誤。

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

用法

await Frame.CheckAsync(selector, options);

引數

selector string #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options FrameCheckOptions? (選填)
- Force bool? (選填)#
  
  是否略過可操作性檢查。預設為 false。
- NoWaitAfter bool? (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選填)新增於：v1.11#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距框的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選填)新增於：v1.11#
  
  設定後，此方法只會執行可操作性檢查，並略過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。

傳回

void #

ClickAsync

在 v1.9 之前新增

frame.ClickAsync

不建議使用

請改用基於定位器的 Locator.ClickAsync()。深入了解定位器。

此方法會透過執行下列步驟來點擊符合 selector 的元素

尋找符合 selector 的元素。如果沒有，則等待直到符合的元素附加到 DOM。
等待對符合的元素進行可操作性檢查，除非設定 Force 選項。如果在檢查期間元素分離，則會重試整個操作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 在元素的中心點擊，或指定的 Position。
等待啟動的導航成功或失敗，除非設定 NoWaitAfter 選項。

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

用法

await Frame.ClickAsync(selector, options);

引數

selector string #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options FrameClickOptions? (選填)
- Button enum MouseButton { Left, Right, Middle }? (選填)#
  
  預設為 left。
- ClickCount int? (選填)#
  
  預設為 1。請參閱 UIEvent.detail。
- Delay [float]? (選填)#
  
  mousedown 和 mouseup 之間等待的時間 (以毫秒為單位)。預設為 0。
- Force bool? (選填)#
  
  是否略過可操作性檢查。預設為 false。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (選填)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- NoWaitAfter bool? (選填)#
  
  已棄用
  此選項在未來將預設為 true。
  
  啟動導航的動作正在等待這些導航發生以及頁面開始載入。您可以透過設定此旗標來選擇不等待。您只需要在特殊情況下使用此選項，例如導航到無法存取的頁面。預設為 false。
- Position Position? (選填)#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距框的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選填)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。可用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

void #

DblClickAsync

在 v1.9 之前新增

frame.DblClickAsync

不建議使用

請改用基於定位器的 Locator.DblClickAsync()。深入了解定位器。

此方法會透過執行下列步驟來雙擊符合 selector 的元素

尋找符合 selector 的元素。如果沒有，則等待直到符合的元素附加到 DOM。
等待對符合的元素進行可操作性檢查，除非設定 Force 選項。如果在檢查期間元素分離，則會重試整個操作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 在元素的中心雙擊，或指定的 Position。如果 dblclick() 的第一次點擊觸發導航事件，此方法將會擲回錯誤。

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

注意

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

用法

await Frame.DblClickAsync(selector, options);

引數

selector string #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options FrameDblClickOptions? (選填)
- Button enum MouseButton { Left, Right, Middle }? (選填)#
  
  預設為 left。
- Delay [float]? (選填)#
  
  mousedown 和 mouseup 之間等待的時間 (以毫秒為單位)。預設為 0。
- Force bool? (選填)#
  
  是否略過可操作性檢查。預設為 false。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (選填)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- NoWaitAfter bool? (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選填)#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距框的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選填)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。可用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

void #

DispatchEventAsync

在 v1.9 之前新增

frame.DispatchEventAsync

不建議使用

請改用基於定位器的 Locator.DispatchEventAsync()。深入了解定位器。

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

用法

await frame.DispatchEventAsync("button#submit", "click");

在底層，它會根據給定的 type 建立事件的實例，使用 eventInit 屬性初始化它，並在元素上分派它。預設情況下，事件是 composed、cancelable 和 bubble。

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

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

// Note you can only create DataTransfer in Chromium and Firefox
var dataTransfer = await frame.EvaluateHandleAsync("() => new DataTransfer()");
await frame.DispatchEventAsync("#source", "dragstart", new { dataTransfer });

引數

selector 字串 (string)#

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

DOM 事件類型：例如 "click"、"dragstart" 等。
eventInit EvaluationArgument (評估引數)? (選用)#

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

傳回

void #

EvalOnSelectorAsync

新增於：v1.9

frame.EvalOnSelectorAsync

不建議使用

此方法不會等待元素通過可操作性檢查，因此可能會導致測試不穩定。請改用 Locator.EvaluateAsync()、其他 Locator 輔助方法或網頁優先的斷言。

傳回 expression (表達式) 的傳回值。

此方法會在框架內尋找符合指定選取器的元素，並將其作為第一個引數傳遞給 expression (表達式)。如果沒有元素符合選取器，此方法會擲回錯誤。

如果 expression (表達式) 傳回 Promise，則 Frame.EvalOnSelectorAsync() 將等待 Promise 解析並傳回其值。

用法

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

引數

selector 字串 (string)#

要查詢的選取器。
expression 字串 (string)#

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

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

傳回

[object]#

EvalOnSelectorAllAsync

新增於：v1.9

frame.EvalOnSelectorAllAsync

不建議使用

在大多數情況下，Locator.EvaluateAllAsync()、其他 Locator 輔助方法和網頁優先的斷言效果更佳。

傳回 expression (表達式) 的傳回值。

此方法會在框架內尋找符合指定選取器的所有元素，並將相符元素的陣列作為第一個引數傳遞給 expression (表達式)。

如果 expression (表達式) 傳回 Promise，則 Frame.EvalOnSelectorAllAsync() 將等待 Promise 解析並傳回其值。

用法

var divsCount = await frame.EvalOnSelectorAllAsync<bool>("div", "(divs, min) => divs.length >= min", 10);

引數

selector 字串 (string)#

要查詢的選取器。
expression 字串 (string)#

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

要傳遞給 expression (表達式) 的選用引數。

傳回

[object]#

FillAsync

在 v1.9 之前新增

frame.FillAsync

不建議使用

請改用基於 Locator 的 Locator.FillAsync()。閱讀更多關於 locators (定位器) 的資訊。

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

如果目標元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法會擲回錯誤。但是，如果元素位於具有關聯 control (控制項) 的 <label> 元素內，則會改為填寫該控制項。

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

用法

await Frame.FillAsync(selector, value, options);

引數

selector 字串 (string)#

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

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

傳回

void #

FocusAsync

在 v1.9 之前新增

frame.FocusAsync

不建議使用

請改用基於 Locator 的 Locator.FocusAsync()。閱讀更多關於 locators (定位器) 的資訊。

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

用法

await Frame.FocusAsync(selector, options);

引數

selector 字串 (string)#

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

傳回

void #

GetAttributeAsync

在 v1.9 之前新增

frame.GetAttributeAsync

不建議使用

請改用基於 Locator 的 Locator.GetAttributeAsync()。閱讀更多關於 locators (定位器) 的資訊。

傳回元素屬性值。

用法

await Frame.GetAttributeAsync(selector, name, options);

引數

selector 字串 (string)#

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

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

傳回

字串 (string)?#

HoverAsync

在 v1.9 之前新增

frame.HoverAsync

不建議使用

請改用基於 Locator 的 Locator.HoverAsync()。閱讀更多關於 locators (定位器) 的資訊。

此方法會透過執行以下步驟，將滑鼠懸停在符合 selector (選取器) 的元素上

尋找符合 selector (選取器) 的元素。如果沒有，請等待直到相符的元素附加到 DOM。
等待相符元素上的 actionability (可操作性) 檢查，除非設定 Force (強制) 選項。如果在檢查期間元素被分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 將滑鼠懸停在元素的中心，或指定的 Position (位置)。

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

用法

await Frame.HoverAsync(selector, options);

引數

selector 字串 (string)#

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options FrameHoverOptions? (選用)
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設為 false。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (選用)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- NoWaitAfter bool? (選用)新增於：v1.28#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距框的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選填)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。可用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

void #

InnerHTMLAsync

在 v1.9 之前新增

frame.InnerHTMLAsync

不建議使用

請改用基於 Locator 的 Locator.InnerHTMLAsync()。閱讀更多關於 locators (定位器) 的資訊。

傳回 element.innerHTML。

用法

await Frame.InnerHTMLAsync(selector, options);

引數

selector 字串 (string)#

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

傳回

字串 (string)#

InnerTextAsync

在 v1.9 之前新增

frame.InnerTextAsync

不建議使用

請改用基於 Locator 的 Locator.InnerTextAsync()。閱讀更多關於 locators (定位器) 的資訊。

傳回 element.innerText。

用法

await Frame.InnerTextAsync(selector, options);

引數

selector 字串 (string)#

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

傳回

字串 (string)#

InputValueAsync

新增於：v1.13

frame.InputValueAsync

不建議使用

請改用基於 Locator 的 Locator.InputValueAsync()。閱讀更多關於 locators (定位器) 的資訊。

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

針對非輸入元素擲回錯誤。但是，如果元素位於具有關聯 control (控制項) 的 <label> 元素內，則傳回該控制項的值。

用法

await Frame.InputValueAsync(selector, options);

引數

selector 字串 (string)#

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

傳回

字串 (string)#

IsCheckedAsync

在 v1.9 之前新增

frame.IsCheckedAsync

不建議使用

請改用基於 Locator 的 Locator.IsCheckedAsync()。閱讀更多關於 locators (定位器) 的資訊。

傳回元素是否被選中。如果元素不是核取方塊或 radio 輸入，則擲回錯誤。

用法

await Frame.IsCheckedAsync(selector, options);

引數

selector 字串 (string)#

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

傳回

bool #

IsDisabledAsync

在 v1.9 之前新增

frame.IsDisabledAsync

不建議使用

請改用基於 Locator 的 Locator.IsDisabledAsync()。閱讀更多關於 locators (定位器) 的資訊。

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

用法

await Frame.IsDisabledAsync(selector, options);

引數

selector 字串 (string)#

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

傳回

bool #

IsEditableAsync

在 v1.9 之前新增

frame.IsEditableAsync

不建議使用

請改用基於 Locator 的 Locator.IsEditableAsync()。閱讀更多關於 locators (定位器) 的資訊。

傳回元素是否為 editable (可編輯)。

用法

await Frame.IsEditableAsync(selector, options);

引數

selector 字串 (string)#

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

傳回

bool #

IsHiddenAsync

在 v1.9 之前新增

frame.IsHiddenAsync

不建議使用

請改用基於 Locator 的 Locator.IsHiddenAsync()。閱讀更多關於 locators (定位器) 的資訊。

傳回元素是否為 hidden (隱藏)，與 visible (可見) 相反。不符合任何元素的 selector (選取器) 會被視為 hidden (隱藏)。

用法

await Frame.IsHiddenAsync(selector, options);

引數

selector 字串 (string)#

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

傳回

bool #

IsVisibleAsync

在 v1.9 之前新增

frame.IsVisibleAsync

不建議使用

請改用基於 Locator 的 Locator.IsVisibleAsync()。閱讀更多關於 locators (定位器) 的資訊。

傳回元素是否為 visible (可見)。不符合任何元素的 selector (選取器) 會被視為 not visible (不可見)。

用法

await Frame.IsVisibleAsync(selector, options);

引數

selector 字串 (string)#

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

傳回

bool #

PressAsync

在 v1.9 之前新增

frame.PressAsync

不建議使用

請改用基於 Locator 的 Locator.PressAsync()。閱讀更多關於 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" 等快捷鍵。當使用修飾鍵指定時，在按下後續按鍵時，修飾鍵會被按下並保持按住狀態。

用法

await Frame.PressAsync(selector, key, options);

引數

selector 字串 (string)#

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

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

傳回

void #

QuerySelectorAsync

新增於：v1.9

frame.QuerySelectorAsync

不建議使用

請改用基於 Locator 的 Frame.Locator()。閱讀更多關於 locators (定位器) 的資訊。

傳回指向框架元素的 ElementHandle。

caution (注意)

不建議使用 ElementHandle，請改用 Locator 物件和網頁優先的斷言。

此方法會在框架內尋找符合指定選取器的元素。如果沒有元素符合選取器，則傳回 null。

用法

await Frame.QuerySelectorAsync(selector, options);

引數

selector 字串 (string)#

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

傳回

ElementHandle?#

QuerySelectorAllAsync

新增於：v1.9

frame.QuerySelectorAllAsync

不建議使用

請改用基於 Locator 的 Frame.Locator()。閱讀更多關於 locators (定位器) 的資訊。

傳回指向框架元素的 ElementHandle 集合。

caution (注意)

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

此方法會在框架內尋找符合指定選取器的所有元素。如果沒有元素符合選取器，則傳回空陣列。

用法

await Frame.QuerySelectorAllAsync(selector);

引數

selector 字串 (string)#

要查詢的選取器。

傳回

IEnumerable<ElementHandle>#

在 v1.9 之前新增

frame.RunAndWaitForNavigationAsync

已棄用

此方法本質上具有競爭性，請改用 Frame.WaitForURLAsync()。

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

用法

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

await frame.RunAndWaitForNavigationAsync(async () =>
{
    // Clicking the link will indirectly cause a navigation.
    await frame.ClickAsync("a.delayed-navigation");
});

// Resolves after navigation has finished

注意

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

引數

action Func<Task>新增於：v1.12#

觸發事件的動作。
options FrameRunAndWaitForNavigationOptions? (選用)
- Timeout [float]? (選用)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Url|UrlRegex|UrlFunc 字串 (string)? | Regex (Regex)? | Func<字串 (string)?, bool> (選用)#
  
  在等待導航時要比對的 glob 模式、regex 模式或接收 URL 的述詞。請注意，如果參數是沒有萬用字元的字串，則此方法將等待導航到與該字串完全相同的 URL。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選用)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作完成。
  - 'load' - 當 load 事件觸發時，視為操作完成。
  - 'networkidle' - **不建議** 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，而是依賴網頁斷言來評估準備狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

Response (回應)?#

在 v1.9 之前新增

frame.WaitForNavigationAsync

已棄用

此方法本質上具有競爭性，請改用 Frame.WaitForURLAsync()。

用法

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

await frame.RunAndWaitForNavigationAsync(async () =>
{
    // Clicking the link will indirectly cause a navigation.
    await frame.ClickAsync("a.delayed-navigation");
});

// Resolves after navigation has finished

注意

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

引數

options FrameRunAndWaitForNavigationOptions? (選用)
- Timeout [float]? (選用)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Url|UrlRegex|UrlFunc 字串 (string)? | Regex (Regex)? | Func<字串 (string)?, bool> (選用)#
  
  在等待導航時要比對的 glob 模式、regex 模式或接收 URL 的述詞。請注意，如果參數是沒有萬用字元的字串，則此方法將等待導航到與該字串完全相同的 URL。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選用)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作完成。
  - 'load' - 當 load 事件觸發時，視為操作完成。
  - 'networkidle' - **不建議** 當至少 500 毫秒沒有網路連線時，視為操作完成。請勿將此方法用於測試，而是依賴網頁斷言來評估準備狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作完成。

傳回

Response (回應)?#

SelectOptionAsync

在 v1.9 之前新增

frame.SelectOptionAsync

不建議使用

請改用基於 Locator 的 Locator.SelectOptionAsync()。閱讀更多關於 locators (定位器) 的資訊。

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

如果目標元素不是 <select> 元素，此方法會擲回錯誤。但是，如果元素位於具有關聯 control (控制項) 的 <label> 元素內，則會改為使用該控制項。

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

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

用法

// Single selection matching the value or label
await frame.SelectOptionAsync("select#colors", new[] { "blue" });
// single selection matching both the value and the label
await frame.SelectOptionAsync("select#colors", new[] { new SelectOptionValue() { Label = "blue" } });
// multiple selection
await frame.SelectOptionAsync("select#colors", new[] { "red", "green", "blue" });

引數

selector 字串 (string)#

要查詢的選取器。
values string | ElementHandle | IEnumerable | SelectOption | IEnumerable | IEnumerable?#
- Value string? (選用)
  
  依 option.value 比對。選用。
- Label string? (選用)
  
  依 option.label 比對。選用。
- Index int? (選用)
  
  依索引比對。選用。
要選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有相符的選項，否則只會選取第一個符合傳遞選項之一的選項。字串值會同時比對值和標籤。如果所有指定的屬性都符合，則選項會被視為相符。
options FrameSelectOptionOptions? (選用)
- Force bool? (選用)新增於：v1.13#
  
  是否略過可操作性檢查。預設為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Strict bool? (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

IEnumerable<string>#

SetCheckedAsync

新增於：v1.15

frame.SetCheckedAsync

不建議使用

改用基於 locator 的 Locator.SetCheckedAsync()。深入瞭解 locators。

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

尋找符合 selector 的元素。如果沒有，則等到相符的元素附加到 DOM 為止。
確保相符的元素是核取方塊或單選輸入。如果不是，此方法會擲回例外狀況。
如果元素已具有正確的勾選狀態，則此方法會立即傳回。
等待相符元素上的 actionability 檢查，除非設定 Force 選項。如果在檢查期間元素已分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 在元素的中心點擊。
確保元素現在已勾選或取消勾選。如果不是，此方法會擲回例外狀況。

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

用法

await Frame.SetCheckedAsync(selector, checked, options);

引數

selector string #

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

是否要勾選或取消勾選核取方塊。
options FrameSetCheckedOptions? (選用)
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距框的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)#
  
  設定後，此方法只會執行可操作性檢查，並略過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。

傳回

void #

SetInputFilesAsync

在 v1.9 之前新增

frame.SetInputFilesAsync

不建議使用

改用基於 locator 的 Locator.SetInputFilesAsync()。深入瞭解 locators。

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

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

用法

await Frame.SetInputFilesAsync(selector, files, options);

引數

selector string #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
files string | IEnumerable<string> | FilePayload | IEnumerable<FilePayload>#
- Name string
  
  檔案名稱
- MimeType string
  
  檔案類型
- Buffer byte[]
  
  檔案內容
options FrameSetInputFilesOptions? (選用)
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Strict bool? (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

TapAsync

在 v1.9 之前新增

frame.TapAsync

不建議使用

改用基於 locator 的 Locator.TapAsync()。深入瞭解 locators。

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

尋找符合 selector 的元素。如果沒有，則等到相符的元素附加到 DOM 為止。
等待相符元素上的 actionability 檢查，除非設定 Force 選項。如果在檢查期間元素已分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.Touchscreen 點擊元素的中心，或指定的 Position。

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

注意

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

用法

await Frame.TapAsync(selector, options);

引數

selector string #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options FrameTapOptions? (選用)
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設為 false。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (選用)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距框的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選填)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設為 false。可用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

void #

TextContentAsync

在 v1.9 之前新增

frame.TextContentAsync

不建議使用

改用基於 locator 的 Locator.TextContentAsync()。深入瞭解 locators。

傳回 element.textContent。

用法

await Frame.TextContentAsync(selector, options);

引數

selector string #

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

傳回

string?#

TypeAsync

在 v1.9 之前新增

frame.TypeAsync

已棄用

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

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

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

用法

引數

selector string #

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

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

傳回

void #

UncheckAsync

在 v1.9 之前新增

frame.UncheckAsync

不建議使用

改用基於 locator 的 Locator.UncheckAsync()。深入瞭解 locators。

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

尋找符合 selector 的元素。如果沒有，則等到相符的元素附加到 DOM 為止。
確保相符的元素是核取方塊或單選輸入。如果不是，此方法會擲回例外狀況。如果元素已取消勾選，則此方法會立即傳回。
等待相符元素上的 actionability 檢查，除非設定 Force 選項。如果在檢查期間元素已分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 在元素的中心點擊。
確保元素現在已取消勾選。如果不是，此方法會擲回例外狀況。

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

用法

await Frame.UncheckAsync(selector, options);

引數

selector string #

用於搜尋元素的選取器。如果有多個元素符合選取器，則會使用第一個。
options FrameUncheckOptions? (選用)
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選填)新增於：v1.11#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距框的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選填)新增於：v1.11#
  
  設定後，此方法只會執行可操作性檢查，並略過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。

傳回

void #

WaitForSelectorAsync

在 v1.9 之前新增

frame.WaitForSelectorAsync

不建議使用

改用可判斷可見性的網頁判斷提示或基於 locator 的 Locator.WaitForAsync()。深入瞭解 locators。

當 selector 指定的元素符合 State 選項時傳回。如果等待 hidden 或 detached，則傳回 null。

注意

Playwright 會在執行動作之前自動等待元素準備就緒。使用 Locator 物件和網頁優先判斷提示，可讓程式碼免於等待 selector。

等待 selector 符合 State 選項 (從 dom 顯示/消失，或變成可見/隱藏)。如果在呼叫方法時，selector 已符合條件，則方法會立即傳回。如果 selector 在 Timeout 毫秒內未符合條件，則函式會擲回例外狀況。

用法

此方法適用於跨導覽

using Microsoft.Playwright;
using System;
using System.Threading.Tasks;

class FrameExamples
{
    public static async Task Main()
    {
        using var playwright = await Playwright.CreateAsync();
        await using var browser = await playwright.Chromium.LaunchAsync();
        var page = await browser.NewPageAsync();

        foreach (var currentUrl in new[] { "https://www.google.com", "https://bbc.com" })
        {
            await page.GotoAsync(currentUrl);
            element = await page.MainFrame.WaitForSelectorAsync("img");
            Console.WriteLine($"Loaded image: {await element.GetAttributeAsync("src")}");
        }
    }
}

引數

selector string #

要查詢的選取器。
options FrameWaitForSelectorOptions? (選用)
- State enum WaitForSelectorState { Attached, Detached, Visible, Hidden }? (選用)#
  
  預設為 'visible'。可以是
  - 'attached' - 等待元素出現在 DOM 中。
  - 'detached' - 等待元素未出現在 DOM 中。
  - 'visible' - 等待元素具有非空的邊界框且沒有 visibility:hidden。請注意，沒有任何內容或具有 display:none 的元素具有空的邊界框，且不被視為可見。
  - 'hidden' - 等待元素從 DOM 分離，或具有空的邊界框或 visibility:hidden。這與 'visible' 選項相反。
- Strict bool? (選用)新增於：v1.14#
  
  若為 true，則呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

ElementHandle?#

WaitForTimeoutAsync

在 v1.9 之前新增

frame.WaitForTimeoutAsync

不建議使用

永遠不要在生產環境中等待逾時。等待時間的測試本質上是不穩定的。改用 Locator 動作和自動等待的網頁判斷提示。

等待指定的 timeout 毫秒數。

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

用法

await Frame.WaitForTimeoutAsync(timeout);

引數

timeout [float]#

要等待的逾時

傳回

void #

方法​

AddScriptTagAsync​

AddStyleTagAsync​

ChildFrames​

ContentAsync​

DragAndDropAsync​

EvaluateAsync​

EvaluateHandleAsync​

FrameElementAsync​

FrameLocator​

GetByAltText​

GetByLabel​

GetByPlaceholder​

GetByRole​

GetByTestId​

GetByText​

GetByTitle​

GotoAsync​

IsDetached​

IsEnabledAsync​

Locator​

Name​

Page​

ParentFrame​

SetContentAsync​

TitleAsync​

Url​

WaitForFunctionAsync​

WaitForLoadStateAsync​

WaitForURLAsync​

已過時​

CheckAsync​

ClickAsync​

DblClickAsync​

DispatchEventAsync​

EvalOnSelectorAsync​

EvalOnSelectorAllAsync​

FillAsync​

FocusAsync​

GetAttributeAsync​

HoverAsync​

InnerHTMLAsync​

InnerTextAsync​

InputValueAsync​

IsCheckedAsync​

IsDisabledAsync​

IsEditableAsync​

IsHiddenAsync​

IsVisibleAsync​

PressAsync​

QuerySelectorAsync​

QuerySelectorAllAsync​

RunAndWaitForNavigationAsync​

WaitForNavigationAsync​

SelectOptionAsync​

SetCheckedAsync​

SetInputFilesAsync​

TapAsync​

TextContentAsync​

TypeAsync​

UncheckAsync​

WaitForSelectorAsync​

WaitForTimeoutAsync​

方法

AddScriptTagAsync

AddStyleTagAsync

ChildFrames

ContentAsync

DragAndDropAsync

EvaluateAsync

EvaluateHandleAsync

FrameElementAsync

FrameLocator

GetByAltText

GetByLabel

GetByPlaceholder

GetByRole

GetByTestId

GetByText

GetByTitle

GotoAsync

IsDetached

IsEnabledAsync

Locator

Name

Page

ParentFrame

SetContentAsync

TitleAsync

Url

WaitForFunctionAsync

WaitForLoadStateAsync

WaitForURLAsync

已過時

CheckAsync

ClickAsync

DblClickAsync

DispatchEventAsync

EvalOnSelectorAsync

EvalOnSelectorAllAsync

FillAsync

FocusAsync

GetAttributeAsync

HoverAsync

InnerHTMLAsync

InnerTextAsync

InputValueAsync

IsCheckedAsync

IsDisabledAsync

IsEditableAsync

IsHiddenAsync

IsVisibleAsync

PressAsync

QuerySelectorAsync

QuerySelectorAllAsync

RunAndWaitForNavigationAsync

WaitForNavigationAsync

SelectOptionAsync

SetCheckedAsync

SetInputFilesAsync

TapAsync

TextContentAsync

TypeAsync

UncheckAsync

WaitForSelectorAsync

WaitForTimeoutAsync