FrameLocator

FrameLocator 代表頁面上 iframe 的視圖。它擷取了足夠的邏輯來檢索 iframe 並在該 iframe 中定位元素。FrameLocator 可以使用 Locator.ContentFrame、Page.FrameLocator() 或 Locator.FrameLocator() 方法建立。

var locator = page.Locator("#my-frame").ContentFrame.GetByText("Submit");
await locator.ClickAsync();

嚴格性

Frame 定位器是嚴格的。這表示如果有多個元素符合給定的選擇器，則對 frame 定位器的所有操作都會擲回例外。

// Throws if there are several frames in DOM:
await page.Locator(".result-frame").ContentFrame.GetByRole(AriaRole.Button).ClickAsync();

// Works because we explicitly tell locator to pick the first frame:
await page.Locator(".result-frame").First.ContentFrame.getByRole(AriaRole.Button).ClickAsync();

將 Locator 轉換為 FrameLocator

如果您有一個指向 iframe 的 Locator 物件，則可以使用 Locator.ContentFrame 將其轉換為 FrameLocator。

將 FrameLocator 轉換為 Locator

如果您有一個 FrameLocator 物件，則可以使用 FrameLocator.Owner 將其轉換為指向相同 iframe 的 Locator。

方法

FrameLocator

新增於：v1.17

frameLocator.FrameLocator

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

用法

FrameLocator.FrameLocator(selector);

引數

selector string #

用於解析 DOM 元素的選擇器。

傳回

FrameLocator #

GetByAltText

新增於：v1.27

frameLocator.GetByAltText

允許依元素的替代文字 (alt text) 定位元素。

用法

例如，此方法將依替代文字「Playwright logo」尋找圖片

<img alt='Playwright logo'>

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

引數

text string | Regex #

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

傳回

Locator #

GetByLabel

新增於：v1.27

frameLocator.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 FrameLocatorGetByLabelOptions? (選用)
- Exact bool? (選用)#
  
  是否尋找完全相符的項目：區分大小寫且完全符合字串。預設為 false。當依規則運算式定位時，會忽略此選項。請注意，完全相符仍然會修剪空白字元。

傳回

Locator #

GetByPlaceholder

新增於：v1.27

frameLocator.GetByPlaceholder

允許依預留位置文字來定位輸入元素。

用法

例如，考慮下列 DOM 結構。

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

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

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

引數

text string | Regex #

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

傳回

Locator #

GetByRole

新增於：v1.27

frameLocator.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 FrameLocatorGetByRoleOptions? (選用)
- 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

frameLocator.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

frameLocator.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 FrameLocatorGetByTextOptions? (選用)
- Exact bool? (選用)#
  
  是否尋找完全相符的項目：區分大小寫且完全符合字串。預設為 false。當依規則運算式定位時，會忽略此選項。請注意，完全相符仍然會修剪空白字元。

傳回

Locator #

詳細資訊

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

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

GetByTitle

新增於：v1.27

frameLocator.GetByTitle

允許依元素的 title 屬性來定位元素。

用法

考慮下列 DOM 結構。

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

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

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

引數

text string | Regex #

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

傳回

Locator #

Locator

新增於：v1.17

frameLocator.Locator

此方法會在定位器的子樹狀結構中尋找符合指定選取器的元素。它也接受篩選選項，類似於 Locator.Filter() 方法。

深入了解定位器.

用法

FrameLocator.Locator(selectorOrLocator, options);

引數

selectorOrLocator string | Locator #

用於解析 DOM 元素的選取器或定位器。
options FrameLocatorLocatorOptions? (選用)
- 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 #

Owner

新增於：v1.43

frameLocator.Owner

傳回 Locator 物件，該物件指向與此 frame 定位器相同的 iframe。

當您在某處取得 FrameLocator 物件，稍後想要與 iframe 元素互動時，這非常有用。

對於反向操作，請使用 Locator.ContentFrame。

用法

var frameLocator = Page.Locator("iframe[name=\"embedded\"]").ContentFrame;
// ...
var locator = frameLocator.Owner;
await Expect(locator).ToBeVisibleAsync();

傳回

Locator #

已淘汰

First

新增於：v1.17

frameLocator.First

已淘汰

請改用 Locator.First，然後接著使用 Locator.ContentFrame。

傳回第一個相符框架的定位器。

用法

FrameLocator.First

傳回

FrameLocator #

Last

新增於：v1.17

frameLocator.Last

已淘汰

請改用 Locator.Last，然後接著使用 Locator.ContentFrame。

傳回最後一個相符框架的定位器。

用法

FrameLocator.Last

傳回

FrameLocator #

Nth

新增於：v1.17

frameLocator.Nth

已淘汰

請改用 Locator.Nth()，然後接著使用 Locator.ContentFrame。

傳回第 n 個相符框架的定位器。它是從零開始的，nth(0) 選取第一個框架。

用法

FrameLocator.Nth(index);

引數

index int #

傳回

FrameLocator #

方法​

FrameLocator​

GetByAltText​

GetByLabel​

GetByPlaceholder​

GetByRole​

GetByTestId​

GetByText​

GetByTitle​

Locator​

Owner​

已淘汰​

First​

Last​

Nth​

方法

FrameLocator

GetByAltText

GetByLabel

GetByPlaceholder

GetByRole

GetByTestId

GetByText

GetByTitle

Locator

Owner

已淘汰

First

Last

Nth