FrameLocator

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

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

严格性

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

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

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

将定位器转换为 FrameLocator

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

将 FrameLocator 转换为定位器

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

方法

frameLocator

新增于：v1.17

frameLocator.frameLocator

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

用法

frameLocator.frameLocator(selector);

参数

selector 字符串 #

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

返回值

FrameLocator #

getByAltText

新增于：v1.27

frameLocator.getByAltText

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

用法

例如，此方法将通过替代文本“Playwright logo”查找图像

<img alt='Playwright logo'>

await page.getByAltText('Playwright logo').click();

参数

text 字符串 | 正则表达式 #

要定位元素的文本。
options 对象 (可选)
- exact 布尔值 (可选)#
  
  是否查找完全匹配：区分大小写和整个字符串。默认为 false。在通过正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

Locator #

getByLabel

新增于：v1.27

frameLocator.getByLabel

允许通过关联的<label>或aria-labelledby元素的文本或aria-label属性来定位输入元素。

用法

例如，此方法将在以下 DOM 中通过标签“Username”和“Password”查找输入

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

await page.getByLabel('Username').fill('john');
await page.getByLabel('Password').fill('secret');

参数

text 字符串 | 正则表达式 #

要定位元素的文本。
options 对象 (可选)
- exact 布尔值 (可选)#
  
  是否查找完全匹配：区分大小写和整个字符串。默认为 false。在通过正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

Locator #

getByPlaceholder

新增于：v1.27

frameLocator.getByPlaceholder

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

用法

例如，考虑以下 DOM 结构。

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

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

await page
    .getByPlaceholder('[email protected]')
    .fill('[email protected]');

参数

text 字符串 | 正则表达式 #

要定位元素的文本。
options 对象 (可选)
- exact 布尔值 (可选)#
  
  是否查找完全匹配：区分大小写和整个字符串。默认为 false。在通过正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

Locator #

getByRole

新增于：v1.27

frameLocator.getByRole

允许通过其ARIA 角色、ARIA 属性和可访问名称来定位元素。

用法

考虑以下 DOM 结构。

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

您可以通过其隐式角色定位每个元素

await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();

await page.getByRole('checkbox', { name: 'Subscribe' }).check();

await page.getByRole('button', { name: /submit/i }).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 角色。
options 对象 (可选)
- checked 布尔值 (可选)#
  
  通常由aria-checked或本机<input type=checkbox>控件设置的属性。
  
  详细了解aria-checked。
- disabled 布尔值 (可选)#
  
  通常由aria-disabled或disabled设置的属性。
  
  注意
  与大多数其他属性不同，disabled 会通过 DOM 层次结构继承。详细了解aria-disabled。
- exact 布尔值 (可选)新增于：v1.28#
  
  是否name完全匹配：区分大小写和整个字符串。默认为 false。当name是正则表达式时忽略。请注意，完全匹配仍然会修剪空格。
- expanded 布尔值 (可选)#
  
  通常由aria-expanded设置的属性。
  
  详细了解aria-expanded。
- includeHidden 布尔值 (可选)#
  
  控制是否匹配隐藏元素的选项。默认情况下，只有非隐藏元素（如ARIA 定义的）才会通过角色选择器匹配。
  
  详细了解aria-hidden。
- level 数字 （可选）#
  
  一个通常用于 heading、listitem、row、treeitem 等角色的数字属性，对于 <h1>-<h6> 元素具有默认值。
  
  了解更多关于 aria-level 的信息。
- name 字符串 | 正则表达式 （可选）#
  
  用于匹配可访问名称的选项。默认情况下，匹配不区分大小写并搜索子字符串，使用 exact 控制此行为。
  
  了解更多关于可访问名称的信息。
- pressed 布尔值 （可选）#
  
  通常由 aria-pressed 设置的属性。
  
  了解更多关于 aria-pressed 的信息。
- selected 布尔值 （可选）#
  
  通常由 aria-selected 设置的属性。
  
  了解更多关于 aria-selected 的信息。

返回值

定位器 #

详情

角色选择器**不会取代**可访问性审计和一致性测试，而是提供关于 ARIA 指南的早期反馈。

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

getByTestId

新增于：v1.27

frameLocator.getByTestId

根据测试 ID 定位元素。

用法

考虑以下 DOM 结构。

<button data-testid="directions">Itinéraire</button>

您可以根据元素的测试 ID 定位它。

await page.getByTestId('directions').click();

参数

testId 字符串 | 正则表达式 #

用于定位元素的 ID。

返回值

定位器 #

详情

默认情况下，data-testid 属性用作测试 ID。如有必要，请使用 selectors.setTestIdAttribute() 配置不同的测试 ID 属性。

// Set custom test id attribute from @playwright/test config:
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  },
});

getByText

新增于：v1.27

frameLocator.getByText

允许定位包含给定文本的元素。

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

用法

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

参数

text 字符串 | 正则表达式 #

要定位元素的文本。
options 对象 (可选)
- exact 布尔值 （可选）#
  
  是否查找完全匹配：区分大小写和整个字符串。默认为 false。在通过正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

定位器 #

详情

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

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

getByTitle

新增于：v1.27

frameLocator.getByTitle

允许根据元素的 title 属性定位元素。

用法

考虑以下 DOM 结构。

<span title='Issues count'>25 issues</span>

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

await expect(page.getByTitle('Issues count')).toHaveText('25 issues');

参数

text 字符串 | 正则表达式 #

要定位元素的文本。
options 对象 (可选)
- exact 布尔值 （可选）#
  
  是否查找完全匹配：区分大小写和整个字符串。默认为 false。在通过正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

定位器 #

locator

新增于：v1.17

frameLocator.locator

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

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

用法

frameLocator.locator(selectorOrLocator);
frameLocator.locator(selectorOrLocator, options);

参数

selectorOrLocator 字符串 | 定位器 #

解析 DOM 元素时使用的选择器或定位器。
options 对象 (可选)
- has 定位器 （可选）#
  
  将方法的结果缩小到包含与该相对定位器匹配的元素的那些元素。例如，包含 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。
  
  内部定位器**必须相对于**外部定位器，并且从外部定位器匹配开始查询，而不是从文档根开始。例如，您可以在 <article><content><div>Playwright</div></content></article> 中找到包含 div 的 content。但是，查找包含 article div 的 content 将失败，因为内部定位器必须是相对的，并且不应使用 content 之外的任何元素。
  
  请注意，外部和内部定位器必须属于同一个框架。内部定位器不得包含 FrameLocator。
- hasNot 定位器 （可选）新增于：v1.33#
  
  匹配不包含与内部定位器匹配的元素的元素。内部定位器针对外部定位器进行查询。例如，不包含 div 的 article 匹配 <article><span>Playwright</span></article>。
  
  请注意，外部和内部定位器必须属于同一个框架。内部定位器不得包含 FrameLocator。
- hasNotText 字符串 | 正则表达式 （可选）新增于：v1.33#
  
  匹配在内部（可能在子元素或后代元素中）不包含指定文本的元素。当传递字符串时，匹配不区分大小写并搜索子字符串。
- hasText 字符串 | 正则表达式 （可选）#
  
  匹配在内部（可能在子元素或后代元素中）包含指定文本的元素。当传递字符串时，匹配不区分大小写并搜索子字符串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。

返回值

定位器 #

owner

新增于：v1.43

frameLocator.owner

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

当您在某个地方获得了一个 FrameLocator 对象，并且稍后想要与 iframe 元素交互时，这很有用。

对于反向操作，请使用 locator.contentFrame()。

用法

const frameLocator = page.locator('iframe[name="embedded"]').contentFrame();
// ...
const locator = frameLocator.owner();
await expect(locator).toBeVisible();

返回值

定位器 #

已弃用

first

新增于：v1.17

frameLocator.first

已弃用

请改用 locator.first() 后跟 locator.contentFrame()。

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

用法

frameLocator.first();

返回值

FrameLocator #

last

新增于：v1.17

frameLocator.last

已弃用

请改用 locator.last() 后跟 locator.contentFrame()。

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

用法

frameLocator.last();

返回值

FrameLocator #

nth

新增于：v1.17

frameLocator.nth

已弃用

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

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

用法

frameLocator.nth(index);

参数

index 数字 #

返回值

FrameLocator #

方法​

frameLocator​

getByAltText​

getByLabel​

getByPlaceholder​

getByRole​

getByTestId​

getByText​

getByTitle​

locator​

owner​

已弃用​

first​

last​

nth​

方法

frameLocator

getByAltText

getByLabel

getByPlaceholder

getByRole

getByTestId

getByText

getByTitle

locator

owner

已弃用

first

last

nth