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 locator 是严格的。这意味着，如果有多个元素匹配给定选择器，所有对 frame locator 的操作都会抛出异常。

同步
异步

# 如果 DOM 中有多个 frame，会抛出异常：
page.locator('.result-frame').content_frame.get_by_role('button').click()

# 这样写不会抛出异常，因为我们明确指定了选择第一个 frame：
page.locator('.result-frame').first.content_frame.get_by_role('button').click()

# 如果 DOM 中有多个 frame，会抛出异常：
await page.locator('.result-frame').content_frame.get_by_role('button').click()

# 这样写不会抛出异常，因为我们明确指定了选择第一个 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 locator，进入 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 中通过标签 "Username" 和 "Password" 找到输入框：

<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 角色、ARIA 属性和可访问名称定位元素。

用法

考虑如下 DOM 结构：

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

你可以通过元素的隐式角色定位每个元素：

同步
异步

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 角色。
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。

了解更多关于 aria-hidden。
level int (可选)#

通常用于 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 #

详情

角色选择器并不能替代可访问性审查和合规性测试，但可以对 ARIA 指南提供早期反馈。

许多 html 元素有隐式定义的角色，角色选择器能够识别。你可以在这里查看所有支持的角色。ARIA 指南不推荐通过设置 role 和/或 aria-* 属性为默认值来重复隐式角色和属性。

get_by_test_id

新增于: v1.27

frameLocator.get_by_test_id

通过测试 id 定位元素。

用法

考虑如下 DOM 结构：

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

你可以通过 test 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。如果需要配置不同的测试 id 属性，可以使用 selectors.set_test_id_attribute()。

get_by_text

新增于: v1.27

frameLocator.get_by_text

允许通过包含指定文本的方式定位元素。

另见 locator.filter()，它允许先按其他条件（如可访问角色）匹配，再根据文本内容进行过滤。

用法

考虑如下 DOM 结构：

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

你可以通过文本子串、精确字符串或正则表达式进行定位：

同步
异步

# 匹配 <span>
page.get_by_text("world")

# 匹配第一个 <div>
page.get_by_text("Hello world")

# 匹配第二个 <div>
page.get_by_text("Hello", exact=True)

# 匹配两个 <div>
page.get_by_text(re.compile("Hello"))

# 匹配第二个 <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

# 匹配 <span>
page.get_by_text("world")

# 匹配第一个 <div>
page.get_by_text("Hello world")

# 匹配第二个 <div>
page.get_by_text("Hello", exact=True)

# 匹配两个 <div>
page.get_by_text(re.compile("Hello"))

# 匹配第二个 <div>
page.get_by_text(re.compile("^hello$", re.IGNORECASE))

参数

text str | Pattern #

用于定位元素的文本。
exact bool (可选)#

是否精确匹配：区分大小写且全字符串匹配。默认为 false。使用正则表达式定位时会被忽略。注意精确匹配仍会去除空白字符。

返回值

Locator #

详情

通过文本匹配时总是会规范化空白字符，即使是精确匹配。例如，会将多个空格合并为一个，将换行符转换为空格，并忽略首尾空白。

类型为 button 和 submit 的 input 元素会通过其 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>

你可以通过 title 文本定位后检查 issues 数量：

同步
异步

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 的子树中查找与指定选择器匹配的元素。它也接受过滤选项，类似于 locator.filter() 方法。

了解更多关于 locator 的内容。

用法

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

参数

selector_or_locator str | Locator #

用于解析 DOM 元素的选择器或 locator。
has Locator (可选)#

将方法结果缩小到包含与该相对 locator 匹配元素的那些。例如，article 包含 text=Playwright 匹配 <article><div>Playwright</div></article>。

内部 locator 必须是相对的，并且是从外部 locator 匹配项开始查询，而不是从文档根节点。例如，你可以在 <article><content><div>Playwright</div></content></article> 中找到包含 div 的 content。但如果查找包含 article div 的 content 会失败，因为内部 locator 必须是相对的，不能使用 content 之外的元素。

注意外部和内部 locator 必须属于同一个 frame。内部 locator 不能包含 FrameLocator。
has_not Locator (可选) 新增于: v1.33#

匹配不包含与内部 locator 匹配元素的元素。内部 locator 会针对外部 locator 查询。例如，article 不包含 div 匹配 <article><span>Playwright</span></article>。

注意外部和内部 locator 必须属于同一个 frame。内部 locator 不能包含 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 locator 相同 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

Deprecated

请改用 locator.first 后接 locator.content_frame。

返回第一个匹配 frame 的 locator。

用法

frame_locator.first

返回值

FrameLocator #

last

新增于: v1.17

frameLocator.last

Deprecated

请改用 locator.last 后接 locator.content_frame。

返回最后一个匹配 frame 的 locator。

用法

frame_locator.last

返回值

FrameLocator #

nth

新增于: v1.17

frameLocator.nth

Deprecated

请改用 locator.nth() 后接 locator.content_frame。

返回第 n 个匹配 frame 的 locator。索引从 0 开始，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