Skip to main content

FrameLocator

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

const locator = page.frameLocator('#my-frame').getByText('Submit');
await locator.click();

严格模式

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

// Throws if there are several frames in DOM:
await page.frameLocator('.result-frame').getByRole('button').click();

// Works because we explicitly tell locator to pick the first frame:
await page.frameLocator('.result-frame').first().getByRole('button').click();

将 Locator 转换为 FrameLocator

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

const frameLocator = locator.frameLocator(':scope');

frameLocator.first()​

Added in: v1.17

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

frameLocator.frameLocator(selector)​

Added in: v1.17

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

frameLocator.getByAltText(text[, options])​

Added in: v1.27
  • text <string|RegExp> 用于定位元素的文本。#
  • options? <Object>
    • exact? <boolean> 是否查找精确匹配：区分大小写且全字符串匹配。默认为 false。按正则表达式定位时忽略。请注意，精确匹配仍会修剪空格。#
  • returns: <Locator>#

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

<img alt='Castle'>

frameLocator.getByLabel(text[, options])​

Added in: v1.27
  • text <string|RegExp> 用于定位元素的文本。#
  • options? <Object>
    • exact? <boolean> 是否查找精确匹配：区分大小写且全字符串匹配。默认为 false。按正则表达式定位时忽略。请注意，精确匹配仍会修剪空格。#
  • returns: <Locator>#

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

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

frameLocator.getByPlaceholder(text[, options])​

Added in: v1.27
  • text <string|RegExp> 用于定位元素的文本。#
  • options? <Object>
    • exact? <boolean> 是否查找精确匹配：区分大小写且全字符串匹配。默认为 false。按正则表达式定位时忽略。请注意，精确匹配仍会修剪空格。#
  • returns: <Locator>#

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

<input placeholder="Country">

frameLocator.getByRole(role[, options])​

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

  • options? <Object>

    • checked? <boolean> 通常由 aria-checked 或原生 <input type=checkbox> 控件设置的属性。checked 的可用值为 true、false 和 "mixed"。#

      了解有关 aria-checked 的更多信息。

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

      note

      与大多数其他属性不同，disabled 通过 DOM 层次结构继承。了解有关 aria-disabled 的更多信息。

    • expanded? <boolean> 通常由 aria-expanded 设置的布尔属性。#

      了解有关 aria-expanded 的更多信息。

    • includeHidden? <boolean> 控制是否匹配隐藏元素的布尔属性。默认情况下，角色选择器仅匹配 ARIA 定义 的非隐藏元素。#

      了解有关 aria-hidden 的更多信息。

    • level? <number> 通常存在于角色 heading、listitem、row、treeitem 中的数字属性，对于 <h1>-<h6> 元素具有默认值。#

      了解有关 aria-level 的更多信息。

    • name? <string|RegExp> 匹配 可访问名称 的字符串属性。#

      了解有关 可访问名称 的更多信息。

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

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

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

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

  • returns: <Locator>#

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

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

frameLocator.getByTestId(testId)​

Added in: v1.27

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

frameLocator.getByText(text[, options])​

Added in: v1.27
  • text <string|RegExp> 用于定位元素的文本。#
  • options? <Object>
    • exact? <boolean> 是否查找精确匹配：区分大小写且全字符串匹配。默认为 false。按正则表达式定位时忽略。请注意，精确匹配仍会修剪空格。#
  • returns: <Locator>#

允许定位包含给定文本的元素。考虑以下 DOM 结构：

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

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

// Matches <span>
page.getByText('world')

// Matches first <div>
page.getByText('Hello world')

// Matches second <div>
page.getByText('Hello', { exact: true })

// Matches both <div>s
page.getByText(/Hello/)

// Matches second <div>
page.getByText(/^hello$/i)

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

note

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

note

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

frameLocator.getByTitle(text[, options])​

Added in: v1.27
  • text <string|RegExp> 用于定位元素的文本。#
  • options? <Object>
    • exact? <boolean> 是否查找精确匹配：区分大小写且全字符串匹配。默认为 false。按正则表达式定位时忽略。请注意，精确匹配仍会修剪空格。#
  • returns: <Locator>#

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

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

frameLocator.last()​

Added in: v1.17

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

frameLocator.locator(selector[, options])​

Added in: v1.17

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

  • options? <Object>

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

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

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

  • returns: <Locator>#

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

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

frameLocator.nth(index)​

Added in: v1.17

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