跳到主要内容

FrameLocator

FrameLocator 表示页面上 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()

严格性

框架定位器是严格的。这意味着如果多个元素匹配给定的选择器，则对框架定位器的所有操作都将抛出错误。

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

将 Locator 转换为 FrameLocator

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

将 FrameLocator 转换为 Locator

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

方法​

frame_locator​

新增于：v1.17 frameLocator.frame_locator

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

用法

frame_locator.frame_locator(selector)

参数

  • selector str#

    用于解析 DOM 元素的选择器。

返回值

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

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool （可选）#

    是否进行精确匹配：区分大小写和整字符串匹配。默认为 false。按正则表达式定位时忽略。请注意，精确匹配仍然会移除首尾空白。

返回值

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

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool （可选）#

    是否进行精确匹配：区分大小写和整字符串匹配。默认为 false。按正则表达式定位时忽略。请注意，精确匹配仍然会移除首尾空白。

返回值

get_by_placeholder​

新增于：v1.27 frameLocator.get_by_placeholder

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

用法

例如，考虑以下 DOM 结构。

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

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

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

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool （可选）#

    是否进行精确匹配：区分大小写和整字符串匹配。默认为 false。按正则表达式定位时忽略。请注意，精确匹配仍然会移除首尾空白。

返回值

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

参数

  • 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 的信息。

返回值

详情

角色选择器 不会替代 可访问性审计和合规性测试，而是提供关于 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()

参数

返回值

详情

默认情况下，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))

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool （可选）#

    是否进行精确匹配：区分大小写和整字符串匹配。默认为 false。按正则表达式定位时忽略。请注意，精确匹配仍然会移除首尾空白。

返回值

详情

按文本匹配总是规范化空白，即使是精确匹配也是如此。例如，它将多个空格变成一个空格，将换行符变成空格，并忽略前导和尾随空白。

类型为 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>

您可以通过 title 文本定位后检查问题数量

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

参数

  • text str | Pattern#

    用于定位元素的文本。

  • exact bool （可选）#

    是否进行精确匹配：区分大小写和整字符串匹配。默认为 false。按正则表达式定位时忽略。请注意，精确匹配仍然会移除首尾空白。

返回值

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

返回值

属性​

owner​

新增于：v1.43 frameLocator.owner

返回一个指向与此框架定位器相同的 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()

返回值

已弃用​

first​

新增于：v1.17 frameLocator.first
已弃用

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

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

用法

frame_locator.first

返回值

last​

新增于：v1.17 frameLocator.last
已弃用

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

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

用法

frame_locator.last

返回值

nth​

新增于：v1.17 frameLocator.nth
已弃用

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

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

用法

frame_locator.nth(index)

参数

返回值