FrameLocator

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

同步
非同步

locator = page.locator("my-frame").content_frame.get_by_text("Submit")
locator.click()

locator = page.locator("#my-frame").content_frame.get_by_text("Submit")
await locator.click()

嚴格模式

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

同步
非同步

# Throws if there are several frames in DOM:
page.locator('.result-frame').content_frame.get_by_role('button').click()

# Works because we explicitly tell locator to pick the first frame:
page.locator('.result-frame').first.content_frame.get_by_role('button').click()

# Throws if there are several frames in DOM:
await page.locator('.result-frame').content_frame.get_by_role('button').click()

# Works because we explicitly tell locator to pick the first frame:
await page.locator('.result-frame').first.content_frame.get_by_role('button').click()

將 Locator 轉換為 FrameLocator

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

將 FrameLocator 轉換為 Locator

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

方法

frame_locator

加入於：v1.17

frameLocator.frame_locator

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

用法

frame_locator.frame_locator(selector)

參數

selector str #

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

FrameLocator #

get_by_alt_text

加入於：v1.27

frameLocator.get_by_alt_text

允許通過元素的 alt 文字定位元素。

用法

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

<img alt='Playwright logo'>

同步
非同步

page.get_by_alt_text("Playwright logo").click()

await page.get_by_alt_text("Playwright logo").click()

參數

text str | Pattern #

用於定位元素的文字。
exact bool (選填)#

是否尋找完全匹配項：區分大小寫且全字串匹配。預設為 false。當通過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空白。

Locator #

get_by_label

加入於：v1.27

frameLocator.get_by_label

允許通過關聯的 <label> 或 aria-labelledby 元素的文字，或通過 aria-label 屬性來定位輸入元素。

用法

例如，此方法將在以下 DOM 中通過標籤「使用者名稱」和「密碼」找到輸入框

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

同步
非同步

page.get_by_label("Username").fill("john")
page.get_by_label("Password").fill("secret")

await page.get_by_label("Username").fill("john")
await page.get_by_label("Password").fill("secret")

參數

text str | Pattern #

用於定位元素的文字。
exact bool (選填)#

是否尋找完全匹配項：區分大小寫且全字串匹配。預設為 false。當通過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空白。

Locator #

get_by_placeholder

加入於：v1.27

frameLocator.get_by_placeholder

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

用法

例如，考慮以下 DOM 結構。

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

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

同步
非同步

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

await page.get_by_placeholder("name@example.com").fill("playwright@microsoft.com")

參數

text str | Pattern #

用於定位元素的文字。
exact bool (選填)#

是否尋找完全匹配項：區分大小寫且全字串匹配。預設為 false。當通過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空白。

Locator #

get_by_role

加入於：v1.27

frameLocator.get_by_role

允許通過元素的 ARIA role、ARIA 屬性和可訪問名稱來定位元素。

用法

考慮以下 DOM 結構。

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

您可以通過每個元素的隱含 role 來定位它們

同步
非同步

expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

page.get_by_role("checkbox", name="Subscribe").check()

page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).click()

await expect(page.get_by_role("heading", name="Sign up")).to_be_visible()

await page.get_by_role("checkbox", name="Subscribe").check()

await page.get_by_role("button", name=re.compile("submit", re.IGNORECASE)).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 role。
checked bool (選填)#

通常由 aria-checked 或原生 <input type=checkbox> 控制項設定的屬性。

了解更多關於 aria-checked。
disabled bool (選填)#

通常由 aria-disabled 或 disabled 設定的屬性。

注意
與大多數其他屬性不同，disabled 是通過 DOM 階層繼承的。了解更多關於 aria-disabled。
exact bool (選填)加入於：v1.28#

name 是否完全匹配：區分大小寫且全字串匹配。預設為 false。當 name 是正則表達式時忽略。請注意，完全匹配仍然會修剪空白。
expanded bool (選填)#

通常由 aria-expanded 設定的屬性。

了解更多關於 aria-expanded。
include_hidden bool (選填)#

控制是否匹配隱藏元素的選項。預設情況下，只有非隱藏元素（如 ARIA 定義）會被 role 選擇器匹配。

了解更多關於 aria-hidden。
level int (選填)#

數字屬性，通常存在於 role 為 heading、listitem、row、treeitem 的元素中，<h1>-<h6> 元素具有預設值。

了解更多關於 aria-level。
name str | Pattern (選填)#

用於匹配可訪問名稱的選項。預設情況下，匹配不區分大小寫並搜索子字串，使用 exact 來控制此行為。

了解更多關於可訪問名稱。
pressed bool (選填)#

通常由 aria-pressed 設定的屬性。

了解更多關於 aria-pressed。
selected bool (選填)#

通常由 aria-selected 設定的屬性。

了解更多關於 aria-selected。

Locator #

詳細資訊

Role 選擇器不能取代無障礙功能稽核和一致性測試，而是提供關於 ARIA 指南的早期反饋。

許多 html 元素具有隱含的定義 role，role 選擇器可以識別它。您可以在這裡找到所有支援的 role。ARIA 指南不建議通過將 role 和/或 aria-* 屬性設定為預設值來複製隱含 role 和屬性。

get_by_test_id

加入於：v1.27

frameLocator.get_by_test_id

通過測試 ID 定位元素。

用法

考慮以下 DOM 結構。

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

您可以通过元素的测试 ID 定位元素

同步
非同步

page.get_by_test_id("directions").click()

await page.get_by_test_id("directions").click()

參數

test_id str | Pattern #

用於定位元素的 ID。

Locator #

詳細資訊

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

get_by_text

加入於：v1.27

frameLocator.get_by_text

允許定位包含給定文字的元素。

另請參閱 locator.filter()，它允許通過另一個條件（如可訪問 role）進行匹配，然後通過文字內容進行篩選。

用法

考慮以下 DOM 結構

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

您可以通過文字子字串、完全字串或正則表達式進行定位

同步
非同步

# Matches <span>
page.get_by_text("world")

# Matches first <div>
page.get_by_text("Hello world")

# Matches second <div>
page.get_by_text("Hello", exact=True)

# Matches both <div>s
page.get_by_text(re.compile("Hello"))

# Matches second <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

# Matches <span>
page.get_by_text("world")

# Matches first <div>
page.get_by_text("Hello world")

# Matches second <div>
page.get_by_text("Hello", exact=True)

# Matches both <div>s
page.get_by_text(re.compile("Hello"))

# Matches second <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

參數

text str | Pattern #

用於定位元素的文字。
exact bool (選填)#

是否尋找完全匹配項：區分大小寫且全字串匹配。預設為 false。當通過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空白。

Locator #

詳細資訊

即使使用完全匹配，按文字匹配始終會正規化空白。例如，它將多個空格轉換為一個空格，將換行符轉換為空格，並忽略前導和尾隨空白。

類型為 button 和 submit 的輸入元素通過它們的 value 而不是文字內容進行匹配。例如，按文字 "Log in" 定位會匹配 <input type=button value="Log in">。

get_by_title

加入於：v1.27

frameLocator.get_by_title

允許通過元素的 title 屬性定位元素。

用法

考慮以下 DOM 結構。

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

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

同步
非同步

expect(page.get_by_title("Issues count")).to_have_text("25 issues")

await expect(page.get_by_title("Issues count")).to_have_text("25 issues")

參數

text str | Pattern #

用於定位元素的文字。
exact bool (選填)#

是否尋找完全匹配項：區分大小寫且全字串匹配。預設為 false。當通過正則表達式定位時忽略。請注意，完全匹配仍然會修剪空白。

Locator #

locator

加入於：v1.17

frameLocator.locator

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

了解更多關於定位器.

用法

frame_locator.locator(selector_or_locator)
frame_locator.locator(selector_or_locator, **kwargs)

參數

selector_or_locator str | Locator #

用於解析 DOM 元素的選擇器或定位器。
has Locator (選填)#

將方法結果縮小到包含與此相對定位器匹配的元素的結果。例如，包含 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。

內部定位器必須相對於外部定位器，並且從外部定位器匹配開始查詢，而不是從文檔根目錄開始查詢。例如，您可以找到 content，它在 <article><content><div>Playwright</div></content></article> 中包含 div。但是，尋找包含 article div 的 content 將會失敗，因為內部定位器必須是相對的，並且不應使用 content 外部的任何元素。

請注意，外部和內部定位器必須屬於同一個 frame。內部定位器不得包含 FrameLocator。
has_not Locator (選填)加入於：v1.33#

匹配不包含與內部定位器匹配的元素的元素。內部定位器是針對外部定位器查詢的。例如，不包含 div 的 article 匹配 <article><span>Playwright</span></article>。

請注意，外部和內部定位器必須屬於同一個 frame。內部定位器不得包含 FrameLocator。
has_not_text str | Pattern (選填)加入於：v1.33#

匹配在內部某處（可能在子元素或後代元素中）不包含指定文字的元素。當傳遞 [字串] 時，匹配不區分大小寫並搜索子字串。
has_text str | Pattern (選填)#

匹配在內部某處（可能在子元素或後代元素中）包含指定文字的元素。當傳遞 [字串] 時，匹配不區分大小寫並搜索子字串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。

Locator #

屬性

owner

加入於：v1.43

frameLocator.owner

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

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

對於反向操作，請使用 locator.content_frame。

用法

同步
非同步

frame_locator = page.locator("iframe[name=\"embedded\"]").content_frame
# ...
locator = frame_locator.owner
expect(locator).to_be_visible()

frame_locator = page.locator("iframe[name=\"embedded\"]").content_frame
# ...
locator = frame_locator.owner
await expect(locator).to_be_visible()

Locator #

已停用

first

加入於：v1.17

frameLocator.first

已停用

請改用 locator.first，然後使用 locator.content_frame。

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

用法

frame_locator.first

FrameLocator #

last

加入於：v1.17

frameLocator.last

已停用

請改用 locator.last，然後使用 locator.content_frame。

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

用法

frame_locator.last

FrameLocator #

nth

加入於：v1.17

frameLocator.nth

已停用

請改用 locator.nth()，然後使用 locator.content_frame。

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

用法

frame_locator.nth(index)

參數

index int #

FrameLocator #

方法​

frame_locator​

get_by_alt_text​

get_by_label​

get_by_placeholder​

get_by_role​

get_by_test_id​

get_by_text​

get_by_title​

locator​

屬性​

owner​

已停用​

first​

last​

nth​

方法

frame_locator

get_by_alt_text

get_by_label

get_by_placeholder

get_by_role

get_by_test_id

get_by_text

get_by_title

locator

屬性

owner

已停用

first

last

nth