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()

将定位器转换为框架定位器

如果您有一个指向iframe的Locator对象，可以使用locator.content_frame将其转换为FrameLocator。

将FrameLocator转换为Locator

如果您有一个FrameLocator对象，可以通过frame_locator.owner将其转换为指向相同iframe的Locator。

方法​

frame_locator​

在使用iframe时，您可以创建一个框架定位器，该定位器将进入iframe并允许选择该iframe中的元素。

用法

frame_locator.frame_locator(selector)

参数

• selector str#

  解析DOM元素时使用的选择器。

返回

• 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。使用正则表达式定位时忽略此选项。请注意完全匹配仍会修剪空白字符。

返回

• 定位器#

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。使用正则表达式定位时忽略此选项。请注意完全匹配仍会修剪空白字符。

返回

• 定位器#

get_by_placeholder​

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

用法

例如，考虑以下DOM结构。

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

您可以通过占位符文本定位后填写输入框：

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。使用正则表达式定位时忽略此选项。请注意完全匹配仍会修剪空白字符。

返回

• 定位器#

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 (可选)#

  用于匹配accessible name的选项。默认情况下，匹配不区分大小写并搜索子字符串，使用exact来控制此行为。

  了解更多关于accessible name的信息。

• pressed bool (可选)#

  通常由aria-pressed设置的属性。

  了解更多关于aria-pressed的信息。

• selected bool (可选)#

  通常由aria-selected设置的属性。

  了解更多关于aria-selected的信息。

返回

• 定位器#

详情

角色选择器不能替代无障碍审计和合规性测试，而是提供关于ARIA指南的早期反馈。

Many html elements have an implicitly defined role that is recognized by the role selector. You can find all the supported roles here. ARIA guidelines do not recommend duplicating implicit roles and attributes by setting role and/or aria-* attributes to default values.

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。

返回

• 定位器#

详情

默认情况下，data-testid属性被用作测试ID。如有需要，可使用selectors.set_test_id_attribute()来配置不同的测试ID属性。

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。使用正则表达式定位时忽略此选项。请注意完全匹配仍会修剪空白字符。

返回

• 定位器#

详情

按文本匹配时总是会规范化空白字符，即使是精确匹配。例如，它会将多个空格转换为一个，将换行符转换为空格，并忽略开头和结尾的空白字符。

类型为button和submit的输入元素是通过它们的value值而非文本内容来匹配的。例如，通过文本"Log in"定位会匹配到<input type=button value="Log in">。

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.filter()方法。

了解更多关于定位器的信息。

用法

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

参数

• selector_or_locator str | Locator#

  用于解析DOM元素时使用的选择器或定位器。

• has Locator (可选)#

  将方法的结果范围缩小到包含匹配此相对定位器的元素。例如，article 包含 text=Playwright 会匹配 <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#

  匹配内部某处不包含指定文本的元素，可能在子元素或后代元素中。当传入[string]时，匹配不区分大小写并搜索子字符串。

• has_text str | Pattern (可选)#

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

返回

• 定位器#

属性​

所有者​

返回一个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()

返回

• 定位器#

已弃用​

第一个​

返回定位器到第一个匹配的框架。

用法

frame_locator.first

返回

• FrameLocator#

最后​

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

用法

frame_locator.last

返回

• FrameLocator#

第n个​

返回定位器到第n个匹配的帧。它是基于零的，nth(0)选择第一个帧。

用法

frame_locator.nth(index)

参数

• index int# 索引

返回

• FrameLocator#