FrameLocator

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

Locator locator = page.locator("#my-frame").contentFrame().getByText("Submit");
locator.click();

嚴格模式

Frame 定位器為嚴格模式。這表示如果有多個元素符合給定的選擇器，則對 frame 定位器的所有操作都會拋出錯誤。

// Throws if there are several frames in DOM:
page.locator(".result-frame").contentFrame().getByRole(AriaRole.BUTTON).click();

// Works because we explicitly tell locator to pick the first frame:
page.locator(".result-frame").first().contentFrame().getByRole(AriaRole.BUTTON).click();

將 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 文字定位元素。

用法

例如，此方法將通過 alt 文字「Playwright logo」找到圖片

<img alt='Playwright logo'>

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

參數

text String | Pattern #

用於定位元素的文字。
options FrameLocator.GetByAltTextOptions (可選)
- setExact boolean (可選)#
  
  是否尋找完全匹配項：區分大小寫和全字串。預設為 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">

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

參數

text String | Pattern #

用於定位元素的文字。
options FrameLocator.GetByLabelOptions (可選)
- setExact boolean (可選)#
  
  是否尋找完全匹配項：區分大小寫和全字串。預設為 false。當通過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空格。

Locator #

getByPlaceholder

新增於版本: v1.27

frameLocator.getByPlaceholder

允許通過佔位符文字定位輸入元素。

用法

例如，考慮以下 DOM 結構。

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

您可以在通過佔位符文字定位輸入後填寫輸入

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

參數

text String | Pattern #

用於定位元素的文字。
options FrameLocator.GetByPlaceholderOptions (可選)
- setExact boolean (可選)#
  
  是否尋找完全匹配項：區分大小寫和全字串。預設為 false。當通過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空格。

Locator #

getByRole

新增於版本: v1.27

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

frameLocator.getByTestId

通過測試 ID 定位元素。

用法

考慮以下 DOM 結構。

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

您可以通過元素的測試 ID 定位元素

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

參數

testId String | Pattern #

用於定位元素的 ID。

Locator #

詳細資訊

預設情況下，data-testid 屬性用作測試 ID。如果需要配置不同的測試 ID 屬性，請使用 Selectors.setTestIdAttribute()。

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 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 FrameLocator.GetByTextOptions (可選)
- setExact boolean (可選)#
  
  是否尋找完全匹配項：區分大小寫和全字串。預設為 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>

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

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

參數

text String | Pattern #

用於定位元素的文字。
options FrameLocator.GetByTitleOptions (可選)
- setExact boolean (可選)#
  
  是否尋找完全匹配項：區分大小寫和全字串。預設為 false。當通過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空格。

Locator #

locator

新增於版本: v1.17

frameLocator.locator

此方法在定位器的子樹中查找與指定選擇器匹配的元素。它還接受篩選選項，類似於 Locator.filter() 方法。

了解更多關於定位器的資訊.

用法

FrameLocator.locator(selectorOrLocator);
FrameLocator.locator(selectorOrLocator, options);

參數

selectorOrLocator String | Locator #

用於解析 DOM 元素的選擇器或定位器。
options FrameLocator.LocatorOptions (可選)
- setHas Locator (可選)#
  
  將方法的結果縮小到包含與此相對定位器匹配的元素的結果。例如，具有 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。
  
  內部定位器必須相對於外部定位器，並且從外部定位器匹配開始查詢，而不是從文檔根目錄開始查詢。例如，您可以在 <article><content><div>Playwright</div></content></article> 中找到具有 div 的 content。但是，查找具有 article div 的 content 將會失敗，因為內部定位器必須是相對的，並且不應使用 content 之外的任何元素。
  
  請注意，外部和內部定位器必須屬於同一 frame。內部定位器不得包含 FrameLocator。
- setHasNot Locator (可選)新增於版本: v1.33#
  
  匹配不包含與內部定位器匹配的元素的元素。內部定位器是針對外部定位器查詢的。例如，不具有 div 的 article 匹配 <article><span>Playwright</span></article>。
  
  請注意，外部和內部定位器必須屬於同一 frame。內部定位器不得包含 FrameLocator。
- setHasNotText String | Pattern (可選)新增於版本: v1.33#
  
  匹配在某處內部（可能在子元素或後代元素中）不包含指定文字的元素。當傳遞字串時，匹配不區分大小寫並搜索子字串。
- setHasText String | Pattern (可選)#
  
  匹配在某處內部（可能在子元素或後代元素中）包含指定文字的元素。當傳遞字串時，匹配不區分大小寫並搜索子字串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。

Locator #

owner

新增於版本: v1.43

frameLocator.owner

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

當您在某處獲得 FrameLocator 物件，並且稍後想要與 iframe 元素互動時，此功能很有用。

對於反向操作，請使用 Locator.contentFrame()。

用法

FrameLocator frameLocator = page.locator("iframe[name=\"embedded\"]").contentFrame();
// ...
Locator locator = frameLocator.owner();
assertThat(locator).isVisible();

Locator #

已棄用

first

新增於版本: v1.17

frameLocator.first

已棄用

請改用 Locator.first()，後接 Locator.contentFrame()。

返回第一個匹配 frame 的定位器。

用法

FrameLocator.first();

FrameLocator #

last

新增於版本: v1.17

frameLocator.last

已棄用

請改用 Locator.last()，後接 Locator.contentFrame()。

返回最後一個匹配 frame 的定位器。

用法

FrameLocator.last();

FrameLocator #

nth

新增於版本: v1.17

frameLocator.nth

已棄用

請改用 Locator.nth()，後接 Locator.contentFrame()。

返回第 n 個匹配 frame 的定位器。它是從零開始的，nth(0) 選擇第一個 frame。

用法

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