FrameLocator

FrameLocator 代表页面上 iframe 的视图。它包含了检索 iframe 并在该 iframe 中定位元素所需的逻辑。可以使用 Locator.ContentFrame、Page.FrameLocator() 或 Locator.FrameLocator() 方法创建 FrameLocator。

var locator = page.Locator("#my-frame").ContentFrame.GetByText("Submit");
await locator.ClickAsync();

严格性

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

// 如果 DOM 中有多个框架，则抛出异常：
await page.Locator(".result-frame").ContentFrame.GetByRole(AriaRole.Button).ClickAsync();

// 因为我们明确告诉定位器选择第一个框架，所以可以正常工作：
await page.Locator(".result-frame").First.ContentFrame.getByRole(AriaRole.Button).ClickAsync();

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

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

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

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

方法

FrameLocator

新增于：v1.17

frameLocator.FrameLocator

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

用法

FrameLocator.FrameLocator(selector);

参数

selector string #

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

返回值

FrameLocator #

GetByAltText

新增于：v1.27

frameLocator.GetByAltText

允许通过元素的替代文本（alt text）定位元素。

用法

例如，此方法将通过替代文本 “Playwright logo” 找到图片：

<img alt='Playwright logo'>

await page.GetByAltText("Playwright logo").ClickAsync();

参数

text string | Regex #

用于定位元素的文本。
options FrameLocatorGetByAltTextOptions?（可选）
- Exact bool?（可选）#
  
  是否查找完全匹配项：区分大小写且为全字符串匹配。默认为 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").FillAsync("john");
await page.GetByLabel("Password").FillAsync("secret");

参数

text string | Regex #

用于定位元素的文本。
options FrameLocatorGetByLabelOptions? （可选）
- Exact bool? （可选）#
  
  是否查找精确匹配项：区分大小写且为全字符串匹配。默认为 false。通过正则表达式定位时将忽略此选项。请注意，精确匹配仍会修剪空白字符。

返回值

Locator #

GetByPlaceholder

新增于：v1.27

frameLocator.GetByPlaceholder

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

用法

例如，考虑以下 DOM 结构。

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

你可以通过占位符文本定位到输入框后，填充内容：

await page
   .GetByPlaceholder("name@example.com")
   .FillAsync("playwright@microsoft.com");

参数

text string | Regex # 用于定位元素的文本。
options FrameLocatorGetByPlaceholderOptions?（可选）
- Exact bool?（可选）# 是否查找精确匹配项：区分大小写且为全字符串匹配。默认为 false。通过正则表达式定位时将忽略此选项。请注意，精确匹配仍会去除空白字符。

返回值

Locator #

GetByRole

新增于：v1.27frameLocator.GetByRole 允许通过 ARIA 角色、ARIA 属性和可访问名称定位元素。

用法

考虑以下 DOM 结构。

<h3>注册</h3>
<label>
  <input type="checkbox" /> 订阅
</label>
<br/>
<button>提交</button>

你可以通过元素的隐式角色定位每个元素：

await Expect(Page
    .GetByRole(AriaRole.Heading, new() { Name = "注册" }))
    .ToBeVisibleAsync();

await page
    .GetByRole(AriaRole.Checkbox, new() { Name = "订阅" })
    .CheckAsync();

await page
    .GetByRole(AriaRole.Button, new() {
        NameRegex = new Regex("提交", RegexOptions.IgnoreCase)
    })
    .ClickAsync();

参数

role enum AriaRole { 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 FrameLocatorGetByRoleOptions?（可选）
- Checked bool?（可选）#
  
  通常由 aria-checked 或原生 <input type=checkbox> 控件设置的属性。
  
  了解更多关于 aria-checked 的信息。
- Disabled bool?（可选）#
  
  通常由 aria-disabled 或 disabled 设置的属性。
  
  备注
  与大多数其他属性不同，disabled 会通过 DOM 层次结构继承。了解更多关于 aria-disabled 的信息。
- Exact bool?（可选）新增于：v1.28#
  
  Name|NameRegex 是否完全匹配：区分大小写且匹配整个字符串。默认为 false。当 Name|NameRegex 是正则表达式时，此选项将被忽略。请注意，完全匹配仍会修剪空白字符。
- Expanded bool?（可选）#
  
  通常由 aria-expanded 设置的属性。
  
  了解更多关于 aria-expanded 的信息。
- IncludeHidden bool?（可选）#
  
  控制是否匹配隐藏元素的选项。默认情况下，根据 ARIA 定义，角色选择器仅匹配非隐藏元素。
  
  了解更多关于 aria-hidden 的信息。
- Level int?（可选）#
  
  通常用于 heading、listitem、row、treeitem 角色的数字属性，<h1>-<h6> 元素有默认值。
  
  了解更多关于 aria-level 的信息。
- Name|NameRegex string? | Regex?（可选）#
  
  用于匹配可访问名称的选项。默认情况下，匹配不区分大小写并搜索子字符串，使用 Exact 来控制此行为。
  
  了解更多关于可访问名称的信息。
- Pressed bool?（可选）#
  
  通常由 aria-pressed 设置的属性。
  
  了解更多关于 aria-pressed 的信息。
- Selected bool?（可选）#
  
  通常由 aria-selected 设置的属性。
  
  了解更多关于 aria-selected 的信息。

返回值

Locator #

详细信息

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

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

GetByTestId

新增于：v1.27

frameLocator.GetByTestId

通过测试 ID 定位元素。

用法

考虑以下 DOM 结构。

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

你可以通过其测试 ID 定位该元素：

await page.GetByTestId("directions").ClickAsync();

参数

testId string | Regex #

用于定位元素的 ID。

返回值

Locator #

详细信息

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

GetByText

新增于：v1.27

frameLocator.GetByText

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

另请参阅 Locator.Filter()，它允许通过其他条件（如可访问角色）进行匹配，然后按文本内容进行筛选。

用法

考虑以下 DOM 结构：

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

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

// 匹配 <span>
page.GetByText("world");

// 匹配第一个 <div>
page.GetByText("Hello world");

// 匹配第二个 <div>
page.GetByText("Hello", new() { Exact = true });

// 匹配两个 <div>
page.GetByText(new Regex("Hello"));

// 匹配第二个 <div>
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase));

参数

text string | Regex #

用于定位元素的文本。
options FrameLocatorGetByTextOptions?（可选）
- Exact bool?（可选）#
  
  是否查找精确匹配项：区分大小写且为全字符串匹配。默认为 false。通过正则表达式定位时将忽略此选项。请注意，精确匹配仍会修剪空白字符。

返回值

Locator #

详细信息

即使是精确匹配，按文本匹配也总会对空白字符进行规范化处理。例如，将多个空格合并为一个，将换行符转换为空格，并忽略前导和尾随的空白字符。

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

GetByTitle

添加于：v1.27

frameLocator.GetByTitle

允许通过元素的 title 属性定位元素。

用法

考虑以下 DOM 结构。

<span title='问题数量'>25 个问题</span>

通过标题文本定位后，你可以检查问题数量：

await Expect(Page.GetByTitle("问题数量")).toHaveText("25 个问题");

参数

text string | Regex #

用于定位元素的文本。
options FrameLocatorGetByTitleOptions?（可选）
- Exact bool?（可选）#
  
  是否查找精确匹配项：区分大小写且为全字符串匹配。默认为 false。通过正则表达式定位时将忽略此选项。请注意，精确匹配仍会修剪空白字符。

返回值

Locator #

Locator

添加于：v1.17

frameLocator.Locator

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

详细了解定位器。

用法

FrameLocator.Locator(selectorOrLocator, options);

参数

selectorOrLocator string | Locator #

解析 DOM 元素时使用的选择器或定位器。
options FrameLocatorLocatorOptions?（可选）
- Has Locator?（可选）#
  
  将该方法的结果范围缩小到包含与该相对定位器匹配的元素的结果。例如，有 text=Playwright 的 article 与 <article><div>Playwright</div></article> 匹配。
  
  内部定位器 必须相对于 外部定位器，并且从外部定位器匹配的位置开始查询，而不是从文档根开始。例如，在 <article><content><div>Playwright</div></content></article> 中，你可以找到有 div 的 content。但是，查找有 article div 的 content 将会失败，因为内部定位器必须是相对的，并且不应使用 content 之外的任何元素。
  
  请注意，外部和内部定位器必须属于同一框架。内部定位器不能包含 FrameLocator。
- HasNot Locator? 新增于：v1.33#
  
  匹配不包含与内部定位器匹配的元素的元素。内部定位器是相对于外部定位器进行查询的。例如，没有 div 的 article 与 <article><span>Playwright</span></article> 匹配。
  
  请注意，外部和内部定位器必须属于同一框架。内部定位器不能包含 FrameLocator。
- HasNotText|HasNotTextRegex string? | Regex?（可选）新增于：v1.33#
  
  匹配在内部（可能在子元素或后代元素中）不包含指定文本的元素。传入 string 时，匹配不区分大小写，并搜索子字符串。
- HasText|HasTextRegex string? | Regex?（可选）#
  
  匹配在内部（可能在子元素或后代元素中）包含指定文本的元素。传入 string 时，匹配不区分大小写，并搜索子字符串。例如，"Playwright" 与 <article><div>Playwright</div></article> 匹配。

返回值

Locator #

Owner

新增于：v1.43

frameLocator.Owner

返回一个 Locator 对象，该对象指向与此帧定位器相同的 iframe。

当你在某个地方获取到一个 FrameLocator 对象，之后想要与 iframe 元素进行交互时，此方法很有用。

对于反向操作，请使用 Locator.ContentFrame。

用法

var frameLocator = Page.Locator("iframe[name=\"embedded\"]").ContentFrame;
// ...
var locator = frameLocator.Owner;
await Expect(locator).ToBeVisibleAsync();

返回值

Locator #

已弃用

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 int #

返回值

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