Skip to main content

FrameLocator

FrameLocator 表示对页面上 iframe 的视图。它捕获了检索 iframe 和定位该 iframe 中元素的逻辑。FrameLocator 可以使用 page.frame_locator(selector) 或 locator.frame_locator(selector) 方法创建。

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

严格性

Frame locators 是严格的。这意味着如果多于一个元素匹配给定的选择器，则对 frame locators 的所有操作都将抛出异常。

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

# 正常工作，因为我们显式告诉 locator 选择第一个 frame：
page.frame_locator('.result-frame').first.get_by_role('button').click()

将 Locator 转换为 FrameLocator

如果你有一个指向 iframe 的 Locator 对象，可以使用 :scope CSS 选择器将其转换为 FrameLocator：

frameLocator = locator.frame_locator(":scope");

frame_locator.first​

Added in: v1.17

返回匹配的第一个 frame 的 locator。

frame_locator.frame_locator(selector)​

Added in: v1.17

当使用 iframes 时，你可以创建一个 frame locator，它将进入 iframe 并允许在该 iframe 中选择元素。

frame_locator.get_by_alt_text(text, **kwargs)​

Added in: v1.27
  • text <str|Pattern> 要定位元素的文本。#
  • exact <bool> 是否进行精确匹配：区分大小写且全字符串匹配。默认为 false。在通过正则表达式定位时忽略此选项。请注意，精确匹配仍会修剪空格。#
  • 返回值: <Locator>#

允许通过其 alt 文本定位元素。例如，此方法将通过 alt 文本 "Castle" 找到图像：

<img alt='Castle'>

frame_locator.get_by_label(text, **kwargs)​

Added in: v1.27
  • text <str|Pattern> 要定位元素的文本。#
  • exact <bool> 是否进行精确匹配：区分大小写且全字符串匹配。默认为 false。在通过正则表达式定位时忽略此选项。请注意，精确匹配仍会修剪空格。#
  • 返回值: <Locator>#

允许通过关联标签的文本定位输入元素。例如，此方法将在以下 DOM 中通过标签文本 Password 找到输入框：

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

frame_locator.get_by_placeholder(text, **kwargs)​

Added in: v1.27
  • text <str|Pattern> 要定位元素的文本。#
  • exact <bool> 是否进行精确匹配：区分大小写且全字符串匹配。默认为 false。在通过正则表达式定位时忽略此选项。请注意，精确匹配仍会修剪空格。#
  • 返回值: <Locator>#

允许通过 placeholder 文本定位输入元素。例如，此方法将通过 placeholder "Country" 找到输入框：

<input placeholder="Country">

frame_locator.get_by_role(role, **kwargs)​

Added in: v1.27

  • 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> 控件设置的属性。checked 的可用值为 true、false 和 "mixed"。#

    了解更多关于 aria-checked。

  • disabled <bool> 通常由 aria-disabled 或 disabled 设置的布尔属性。#

    note

    与大多数其他属性不同，disabled 在 DOM 层次结构中继承。了解更多关于 aria-disabled。

  • 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 的字符串属性。#

    了解更多关于 accessible name。

  • pressed <bool> 通常由 aria-pressed 设置的属性。pressed 的可用值为 true、false 和 "mixed"。#

    了解更多关于 aria-pressed。

  • selected <bool> 通常由 aria-selected 设置的布尔属性。#

    了解更多关于 aria-selected。

  • 返回值: <Locator>#

允许通过 ARIA 角色, ARIA 属性 和 accessible name 定位元素。 请注意，角色选择器不能取代可访问性审核和一致性测试，而是提供有关 ARIA 指南的早期反馈。

请注意，许多 html 元素具有由角色选择器识别的隐式定义角色。你可以在此处找到所有支持的角色。ARIA 指南不建议通过将 role 和/或 aria-* 属性设置为默认值来重复隐式角色和属性。

frame_locator.get_by_test_id(test_id)​

Added in: v1.27
  • test_id <str> 用于定位元素的 Id。#
  • 返回值: <Locator>#

通过 test id 定位元素。默认情况下，使用 data-testid 属性作为 test id。如有必要，使用 selectors.set_test_id_attribute(attribute_name) 配置不同的 test id 属性。

frame_locator.get_by_text(text, **kwargs)​

Added in: v1.27
  • text <str|Pattern> 要定位元素的文本。#
  • exact <bool> 是否进行精确匹配：区分大小写且全字符串匹配。默认为 false。在通过正则表达式定位时忽略此选项。请注意，精确匹配仍会修剪空格。#
  • 返回值: <Locator>#

允许定位包含给定文本的元素。考虑以下 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))

另请参阅 locator.filter(**kwargs)，它允许按其他条件（如可访问角色）进行匹配，然后按文本内容进行过滤。

note

即使使用精确匹配，按文本匹配也会始终标准化空白。例如，它将多个空格变成一个，将换行符变成空格，并忽略前导和尾随空白。

note

类型为 button 和 submit 的输入元素由其 value 而不是文本内容匹配。例如，按文本 "Log in" 定位会匹配 <input type=button value="Log in">。

frame_locator.get_by_title(text, **kwargs)​

Added in: v1.27
  • text <str|Pattern> 要定位元素的文本。#
  • exact <bool> 是否进行精确匹配：区分大小写且全字符串匹配。默认为 false。在通过正则表达式定位时忽略此选项。请注意，精确匹配仍会修剪空格。#
  • 返回值: <Locator>#

允许通过其 title 定位元素。例如，此方法将通过 title "Submit" 找到按钮：

<button title='Place the order'>Order Now</button>

frame_locator.last​

Added in: v1.17

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

frame_locator.locator(selector, **kwargs)​

Added in: v1.17

  • selector <str> 解析 DOM 元素时使用的选择器。有关详细信息，请参阅使用选择器。#

  • has <Locator> 匹配包含匹配内部 locator 的元素的元素。内部 locator 针对外部 locator 进行查询。例如，具有 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。#

    请注意，外部和内部 locator 必须属于同一个 frame。内部 locator 不得包含 FrameLocator。

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

  • 返回值: <Locator>#

此方法在定位器的子树中查找匹配指定选择器的元素。它还接受过滤器选项，类似于 locator.filter(**kwargs) 方法。

了解更多关于 locators。

frame_locator.nth(index)​

Added in: v1.17

返回第 n 个匹配 frame 的 locator。它是零基索引，nth(0) 选择第一个 frame。