FrameLocator
FrameLocator 表示页面上 `iframe` 的视图。它捕获了足以检索 `iframe` 和在该 iframe 中定位元素的逻辑。FrameLocator 可以使用 Locator.ContentFrame、Page.FrameLocator() 或 Locator.FrameLocator() 方法创建。
var locator = page.Locator("#my-frame").ContentFrame.GetByText("Submit");
await locator.ClickAsync();
严格性
帧定位器是严格的。这意味着如果一个给定的选择器匹配多个元素,所有对帧定位器的操作都将抛出错误。
// 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 时,您可以创建一个框架定位器,它将进入 iframe 并允许选择 iframe 中的元素。
用法
FrameLocator.FrameLocator(selector);
参数
返回
GetByAltText
新增于:v1.27允许根据元素的 alt 文本定位元素。
用法
例如,此方法将通过 alt 文本“Playwright logo”找到图像
<img alt='Playwright logo'>
await page.GetByAltText("Playwright logo").ClickAsync();
参数
-
用于定位元素的文本。
-
options
FrameLocatorGetByAltTextOptions?
(可选)
返回
GetByLabel
新增于:v1.27允许通过关联的 <label>
或 aria-labelledby
元素的文本或 aria-label
属性来定位输入元素。
用法
例如,此方法将在以下 DOM 中通过标签“用户名”和“密码”找到输入
<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");
参数
-
用于定位元素的文本。
-
options
FrameLocatorGetByLabelOptions?
(可选)
返回
GetByPlaceholder
新增于:v1.27允许通过占位符文本定位输入元素。
用法
例如,考虑以下 DOM 结构。
<input type="email" placeholder="name@example.com" />
您可以按占位符文本定位输入框后填充它
await page
.GetByPlaceholder("name@example.com")
.FillAsync("playwright@microsoft.com");
参数
-
用于定位元素的文本。
-
options
FrameLocatorGetByPlaceholderOptions?
(可选)
返回
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();
参数
-
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?
(可选)-
通常由
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|NameRegex
string? | 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。如有必要,使用 Selectors.SetTestIdAttribute() 配置不同的测试 ID 属性。
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));
参数
-
用于定位元素的文本。
-
options
FrameLocatorGetByTextOptions?
(可选)
返回
详情
按文本匹配始终会规范化空格,即使是精确匹配也是如此。例如,它会将多个空格转换为一个空格,将换行符转换为空格,并忽略前导和尾随空格。
类型为 button
和 submit
的输入元素通过其 value
而不是文本内容进行匹配。例如,通过文本 "登录"
定位匹配 <input type=button value="登录">
。
GetByTitle
新增于:v1.27允许通过元素的 title 属性定位元素。
用法
考虑以下 DOM 结构。
<span title='Issues count'>25 issues</span>
您可以通过 title 文本定位它后检查问题数量
await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");
参数
-
用于定位元素的文本。
-
options
FrameLocatorGetByTitleOptions?
(可选)
返回
Locator
新增于: v1.17此方法在定位器的子树中查找匹配指定选择器的元素。它也接受过滤选项,类似于 Locator.Filter() 方法。
用法
FrameLocator.Locator(selectorOrLocator, options);
参数
-
selectorOrLocator
string | Locator#用于解析 DOM 元素的选择器或定位器。
-
options
FrameLocatorLocatorOptions?
(可选)-
将方法结果缩小到包含匹配此相对定位符的元素的那些。例如,
article
中有text=Playwright
匹配<article><div>Playwright</div></article>
。内部定位器**必须相对于**外部定位器,并从外部定位器匹配开始查询,而不是文档根。例如,您可以在
<article><content><div>Playwright</div></content></article>
中找到包含div
的content
。但是,查找包含article div
的content
将失败,因为内部定位器必须是相对的,并且不应使用 `content` 之外的任何元素。请注意,外部和内部定位器必须属于同一个框架。内部定位器不能包含 FrameLocator。
-
匹配不包含与内部定位器匹配的元素的那些元素。内部定位器是根据外部定位器进行查询的。例如,不包含
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>
。
-
返回
Owner
新增于: v1.43返回一个 Locator 对象,该对象指向与此帧定位符相同的 `iframe`。
当您在某个地方获取了一个 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。
返回第一个匹配帧的定位器。
用法
FrameLocator.First
返回
Last
新增于: v1.17请改用 Locator.Last 后接 Locator.ContentFrame。
返回最后一个匹配帧的定位器。
用法
FrameLocator.Last
返回
Nth
新增于: v1.17请改用 Locator.Nth() 后接 Locator.ContentFrame。
返回第 n 个匹配帧的定位器。它是基于零的,`nth(0)` 选择第一个帧。
用法
FrameLocator.Nth(index);
参数
返回