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

允许通过替代文本定位元素。

用法

例如，此方法将通过替代文本“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

允许通过占位符文本定位输入元素。

用法

例如，考虑以下 DOM 结构。

<input type="email" placeholder="[email protected]" />

您可以通过占位符文本定位输入后填充输入

同步
异步

page.get_by_placeholder("[email protected]").fill("[email protected]")

await page.get_by_placeholder("[email protected]").fill("[email protected]")

参数

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>

您可以根据元素的测试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()，它允许根据其他条件（如可访问角色）进行匹配，然后根据文本内容进行筛选。

用法

考虑以下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>。

内部定位器**必须相对于**外部定位器，并且从外部定位器匹配开始查询，而不是从文档根开始。例如，您可以在<article><content><div>Playwright</div></content></article>中找到包含div的content。但是，查找包含article div的content将失败，因为内部定位器必须是相对的，并且不应使用content之外的任何元素。

请注意，外部和内部定位器必须属于同一个框架。内部定位器不能包含FrameLocator。
has_not Locator （可选）新增于：v1.33#

匹配不包含匹配内部定位器的元素的元素。内部定位器针对外部定位器进行查询。例如，不包含div的article匹配<article><span>Playwright</span></article>。

请注意，外部和内部定位器必须属于同一个框架。内部定位器不能包含FrameLocator。
has_not_text str | Pattern （可选）新增于：v1.33#

匹配在内部（可能在子元素或后代元素中）不包含指定文本的元素。当传递[字符串]时，匹配不区分大小写并搜索子字符串。
has_text str | Pattern （可选）#

匹配在内部（可能在子元素或后代元素中）包含指定文本的元素。当传递[字符串]时，匹配不区分大小写并搜索子字符串。例如，"Playwright"匹配<article><div>Playwright</div></article>。

返回值

Locator #

属性

owner

新增于：v1.43

frameLocator.owner

返回一个Locator对象，该对象指向与该框架定位器相同的iframe。

当您在某个地方获得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_locator.first

返回值

FrameLocator #

last

新增于：v1.17

frameLocator.last

已弃用

请改用locator.last，后跟locator.content_frame。

返回指向最后一个匹配框架的定位器。

用法

frame_locator.last

返回值

FrameLocator #

nth

新增于：v1.17

frameLocator.nth

已弃用

请改用locator.nth()，后跟locator.content_frame。

返回指向第n个匹配框架的定位器。它是从0开始的，nth(0)选择第一个框架。

用法

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