FrameLocator
FrameLocator 表示页面上 iframe 的视图。 它捕获了检索 iframe 并在该 iframe 中定位元素的逻辑。 FrameLocator 可以使用 Locator.ContentFrame、Page.FrameLocator() 或 Locator.FrameLocator() 方法创建。
var locator = page.Locator("#my-frame").ContentFrame.GetByText("Submit");
await locator.ClickAsync();
严格性
Frame 定位器是严格的。 这意味着如果多个元素匹配给定的选择器，则对 frame 定位器的所有操作都将抛出错误。
// Throws if there are several frames in DOM:
await page.Locator(".result-frame").ContentFrame.GetByRole(AriaRole.Button).ClickAsync();
// Works because we explicitly tell locator to pick the first frame:
await page.Locator(".result-frame").First.ContentFrame.getByRole(AriaRole.Button).ClickAsync();
将 Locator 转换为 FrameLocator
如果您有一个指向 iframe 的 Locator 对象，则可以使用 Locator.ContentFrame 将其转换为 FrameLocator。
将 FrameLocator 转换为 Locator
如果您有一个 FrameLocator 对象，则可以使用 FrameLocator.Owner 将其转换为指向同一 iframe 的 Locator。
方法
FrameLocator
添加于: v1.17当使用 iframe 时，您可以创建一个 frame 定位器，该定位器将进入 iframe 并允许在 iframe 中选择元素。
用法
FrameLocator.FrameLocator(selector);
参数
返回值
GetByAltText
添加于: v1.27允许通过元素的 alt 文本定位元素。
用法
例如，此方法将通过 alt 文本 “Playwright logo” 查找图像
<img alt='Playwright logo'>
await page.GetByAltText("Playwright logo").ClickAsync();
参数
-
用于定位元素的文本。
-
optionsFrameLocatorGetByAltTextOptions?(可选)
返回值
GetByLabel
添加于: v1.27允许通过关联的 <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");
参数
-
用于定位元素的文本。
-
optionsFrameLocatorGetByLabelOptions?(可选)
返回值
GetByPlaceholder
添加于: v1.27允许通过占位符文本定位输入元素。
用法
例如，考虑以下 DOM 结构。
<input type="email" placeholder="[email protected]" />
您可以在通过占位符文本定位输入框后填充内容
await page
.GetByPlaceholder("[email protected]")
.FillAsync("[email protected]");
参数
-
用于定位元素的文本。
-
optionsFrameLocatorGetByPlaceholderOptions?(可选)
返回值
GetByRole
添加于: v1.27允许通过元素的 ARIA 角色、ARIA 属性 和 可访问名称来定位元素。
用法
考虑以下 DOM 结构。
<h3>Sign up</h3>
<label>
<input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>
您可以按每个元素的隐式角色定位
await Expect(Page
.GetByRole(AriaRole.Heading, new() { Name = "Sign up" }))
.ToBeVisibleAsync();
await page
.GetByRole(AriaRole.Checkbox, new() { Name = "Subscribe" })
.CheckAsync();
await page
.GetByRole(AriaRole.Button, new() {
NameRegex = new Regex("submit", RegexOptions.IgnoreCase)
})
.ClickAsync();
参数
-
roleenum 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 角色。
-
optionsFrameLocatorGetByRoleOptions?(可选)-
通常由
aria-checked或原生<input type=checkbox>控件设置的属性。了解更多关于
aria-checked。 -
通常由
aria-disabled或disabled设置的属性。注意与大多数其他属性不同，
disabled是通过 DOM 层次结构继承的。 了解更多关于aria-disabled。 -
Name|NameRegex 是否完全匹配：区分大小写且全字符串匹配。 默认为 false。 当 Name|NameRegex 是正则表达式时忽略。 请注意，完全匹配仍然会修剪空格。
-
通常由
aria-expanded设置的属性。了解更多关于
aria-expanded。 -
控制是否匹配隐藏元素的可选项。 默认情况下，只有非隐藏元素，如 ARIA 定义，才会被角色选择器匹配。
了解更多关于
aria-hidden。 -
通常存在于角色
heading、listitem、row、treeitem的数字属性，对于<h1>-<h6>元素具有默认值。了解更多关于
aria-level。 -
Name|NameRegexstring? | Regex? (可选)#用于匹配 可访问名称 的选项。 默认情况下，匹配不区分大小写并搜索子字符串，使用 Exact 来控制此行为。
了解更多关于 可访问名称。
-
通常由
aria-pressed设置的属性。了解更多关于
aria-pressed。 -
通常由
aria-selected设置的属性。了解更多关于
aria-selected。
-
返回值
详情
角色选择器不能替代可访问性审核和一致性测试，而是提供关于 ARIA 指南的早期反馈。
许多 html 元素都具有隐式 定义的角色，该角色可被角色选择器识别。 您可以在 此处找到所有支持的角色。 ARIA 指南不建议通过将 role 和/或 aria-* 属性设置为默认值来复制隐式角色和属性。
GetByTestId
添加于: v1.27通过测试 ID 定位元素。
用法
考虑以下 DOM 结构。
<button data-testid="directions">Itinéraire</button>
您可以通过元素的测试 ID 定位元素
await page.GetByTestId("directions").ClickAsync();
参数
返回值
详情
默认情况下，data-testid 属性用作测试 ID。 如果需要配置不同的测试 ID 属性，请使用 Selectors.SetTestIdAttribute()。
GetByText
添加于: v1.27允许定位包含给定文本的元素。
另请参阅 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", new() { Exact = true });
// Matches both <div>s
page.GetByText(new Regex("Hello"));
// Matches second <div>
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase));
参数
-
用于定位元素的文本。
-
optionsFrameLocatorGetByTextOptions?(可选)
返回值
详情
即使是完全匹配，按文本匹配也始终会规范化空格。 例如，它将多个空格变成一个空格，将换行符变成空格，并忽略前导和尾随空格。
类型为 button 和 submit 的输入元素通过其 value 而不是文本内容进行匹配。 例如，按文本 "Log in" 定位会匹配 <input type=button value="Log in">。
GetByTitle
添加于: v1.27允许通过元素的 title 属性定位元素。
用法
考虑以下 DOM 结构。
<span title='Issues count'>25 issues</span>
您可以在通过标题文本定位问题计数后检查问题计数
await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");
参数
-
用于定位元素的文本。
-
optionsFrameLocatorGetByTitleOptions?(可选)
返回值
Locator
添加于: v1.17该方法在定位器的子树中查找与指定选择器匹配的元素。 它还接受筛选器选项，类似于 Locator.Filter() 方法。
用法
FrameLocator.Locator(selectorOrLocator, options);
参数
-
selectorOrLocatorstring | Locator#用于解析 DOM 元素的选择器或定位器。
-
optionsFrameLocatorLocatorOptions?(可选)-
将方法的搜索结果缩小到那些包含与此相对定位器匹配的元素的元素。 例如，具有
text=Playwright的article匹配<article><div>Playwright</div></article>。内部定位器必须相对于外部定位器，并且从外部定位器匹配项开始查询，而不是从文档根开始查询。 例如，您可以在
<article><content><div>Playwright</div></content></article>中找到具有div的content。 但是，查找具有article div的content将会失败，因为内部定位器必须是相对的，并且不应使用content之外的任何元素。请注意，外部定位器和内部定位器必须属于同一 frame。 内部定位器不得包含 FrameLocator。
-
HasNotLocator? (可选)添加于: v1.33#匹配不包含与内部定位器匹配的元素的元素。 内部定位器是针对外部定位器查询的。 例如，不具有
div的article匹配<article><span>Playwright</span></article>。请注意，外部定位器和内部定位器必须属于同一 frame。 内部定位器不得包含 FrameLocator。
-
HasNotText|HasNotTextRegexstring? | Regex? (可选)添加于: v1.33#匹配在内部某处（可能在子元素或后代元素中）不包含指定文本的元素。 当传递 string 时，匹配不区分大小写并搜索子字符串。
-
HasText|HasTextRegexstring? | Regex? (可选)#匹配在内部某处（可能在子元素或后代元素中）包含指定文本的元素。 当传递 string 时，匹配不区分大小写并搜索子字符串。 例如，
"Playwright"匹配<article><div>Playwright</div></article>。
-
返回值
Owner
添加于: v1.43返回指向与此 frame 定位器相同的 iframe 的 Locator 对象。
当您在某处获得 FrameLocator 对象，并且稍后想要与 iframe 元素交互时，此方法非常有用。
对于反向操作，请使用 Locator.ContentFrame。
用法
var frameLocator = Page.Locator("iframe[name=\"embedded\"]").ContentFrame;
// ...
var locator = frameLocator.Owner;
await Expect(locator).ToBeVisibleAsync();
返回值
已弃用
First
添加于: v1.17请改用 Locator.First，然后使用 Locator.ContentFrame。
返回指向第一个匹配 frame 的定位器。
用法
FrameLocator.First
返回值
Last
添加于: v1.17请改用 Locator.Last，然后使用 Locator.ContentFrame。
返回指向最后一个匹配 frame 的定位器。
用法
FrameLocator.Last
返回值
Nth
添加于: v1.17请改用 Locator.Nth()，然后使用 Locator.ContentFrame。
返回指向第 n 个匹配 frame 的定位器。 它是从零开始的，nth(0) 选择第一个 frame。
用法
FrameLocator.Nth(index);
参数
返回值