FrameLocator

FrameLocator 代表頁面上 iframe 的視圖。它捕捉了足夠的邏輯來檢索 iframe 並在該 iframe 中定位元素。FrameLocator 可以使用 locator.contentFrame()、page.frameLocator() 或 locator.frameLocator() 方法建立。

const locator = page.locator('#my-frame').contentFrame().getByText('Submit');
await locator.click();

嚴格性

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

// Throws if there are several frames in DOM:
await page.locator('.result-frame').contentFrame().getByRole('button').click();

// Works because we explicitly tell locator to pick the first frame:
await page.locator('.result-frame').contentFrame().first().getByRole('button').click();

將 Locator 轉換為 FrameLocator

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

將 FrameLocator 轉換為 Locator

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

方法

frameLocator

新增於：v1.17

frameLocator.frameLocator

當使用 iframes 時，您可以建立一個 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').click();

參數

text string | RegExp #

用於定位元素的文字。
options Object (選用)
- exact 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">

await page.getByLabel('Username').fill('john');
await page.getByLabel('Password').fill('secret');

參數

text string | RegExp #

用於定位元素的文字。
options Object (選用)
- exact boolean (選用)#
  
  是否尋找完全符合的項目：區分大小寫且完全字串符合。預設為 false。透過正規表示式定位時會忽略。請注意，完全符合仍會修剪空白字元。

回傳

Locator #

getByPlaceholder

新增於：v1.27

frameLocator.getByPlaceholder

允許透過 placeholder 文字定位輸入元素。

用法

例如，考慮以下 DOM 結構。

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

您可以在透過 placeholder 文字定位輸入框後填寫內容

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

參數

text string | RegExp #

用於定位元素的文字。
options Object (選用)
- exact 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>

您可以透過每個元素的隱含角色來定位它們

await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();

await page.getByRole('checkbox', { name: 'Subscribe' }).check();

await page.getByRole('button', { name: /submit/i }).click();

參數

role "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 Object (選用)
- checked boolean (選用)#
  
  通常由 aria-checked 或原生 <input type=checkbox> 控制項設定的屬性。
  
  深入瞭解 aria-checked。
- disabled boolean (選用)#
  
  通常由 aria-disabled 或 disabled 設定的屬性。
  
  注意
  與大多數其他屬性不同，disabled 是透過 DOM 階層繼承的。深入瞭解 aria-disabled。
- exact boolean (選用)Added in: v1.28#
  
  是否 name 完全符合：區分大小寫且完全字串符合。預設為 false。當 name 是正規表示式時會忽略。請注意，完全符合仍會修剪空白字元。
- expanded boolean (選用)#
  
  通常由 aria-expanded 設定的屬性。
  
  深入瞭解 aria-expanded。
- includeHidden boolean (選用)#
  
  控制是否比對隱藏元素的選項。預設情況下，角色選擇器僅比對非隱藏元素，如 ARIA 定義，會由角色選擇器比對。
  
  深入瞭解 aria-hidden。
- level number (選用)#
  
  數字屬性，通常用於角色 heading、listitem、row、treeitem，<h1>-<h6> 元素具有預設值。
  
  深入瞭解 aria-level。
- name string | RegExp (選用)#
  
  比對可存取名稱的選項。預設情況下，比對不區分大小寫，並搜尋子字串，使用 exact 來控制此行為。
  
  深入瞭解可存取名稱。
- pressed boolean (選用)#
  
  通常由 aria-pressed 設定的屬性。
  
  深入瞭解 aria-pressed。
- selected 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 定位它

await page.getByTestId('directions').click();

參數

testId string | RegExp #

用於定位元素的 ID。

回傳

Locator #

詳細資訊

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

// Set custom test id attribute from @playwright/test config:
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  },
});

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', { exact: true });

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

// Matches second <div>
page.getByText(/^hello$/i);

參數

text string | RegExp #

用於定位元素的文字。
options Object (選用)
- exact 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>

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

await expect(page.getByTitle('Issues count')).toHaveText('25 issues');

參數

text string | RegExp #

用於定位元素的文字。
options Object (選用)
- exact boolean (選用)#
  
  是否尋找完全符合的項目：區分大小寫且完全字串符合。預設為 false。透過正規表示式定位時會忽略。請注意，完全符合仍會修剪空白字元。

回傳

Locator #

locator

新增於：v1.17

frameLocator.locator

此方法會在定位器的子樹中找到符合指定選擇器的元素。它也接受篩選選項，類似於 locator.filter() 方法。

深入瞭解定位器.

用法

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

參數

selectorOrLocator string | Locator #

解析 DOM 元素時使用的選擇器或定位器。
options Object (選用)
- has Locator (選用)#
  
  將方法結果縮小到包含符合此相對定位器的元素的結果。例如，具有 text=Playwright 的 article 會比對 <article><div>Playwright</div></article>。
  
  內部定位器必須相對於外部定位器，並且從外部定位器比對開始查詢，而不是文件根目錄。例如，您可以在 <article><content><div>Playwright</div></content></article> 中找到具有 div 的 content。但是，尋找具有 article div 的 content 將會失敗，因為內部定位器必須是相對的，並且不應使用 content 之外的任何元素。
  
  請注意，外部和內部定位器必須屬於同一個 frame。內部定位器不得包含 FrameLocator。
- hasNot Locator (選用)Added in: v1.33#
  
  比對不包含符合內部定位器元素的元素。內部定位器是針對外部定位器查詢的。例如，沒有 div 的 article 會比對 <article><span>Playwright</span></article>。
  
  請注意，外部和內部定位器必須屬於同一個 frame。內部定位器不得包含 FrameLocator。
- hasNotText string | RegExp (選用)Added in: v1.33#
  
  比對不包含指定文字（可能在子元素或後代元素中）的元素。當傳遞 string 時，比對不區分大小寫，並搜尋子字串。
- hasText string | RegExp (選用)#
  
  比對包含指定文字（可能在子元素或後代元素中）的元素。當傳遞 string 時，比對不區分大小寫，並搜尋子字串。例如，"Playwright" 比對 <article><div>Playwright</div></article>。

回傳

Locator #

owner

新增於：v1.43

frameLocator.owner

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

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

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

用法

const frameLocator = page.locator('iframe[name="embedded"]').contentFrame();
// ...
const locator = frameLocator.owner();
await expect(locator).toBeVisible();

回傳

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 number #

回傳

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