跳转到主要内容

FrameLocator

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

Locator locator = page.locator("#my-frame").contentFrame().getByText("Submit");
locator.click();

严格性

帧定位器是严格的。这意味着如果一个给定的选择器匹配多个元素,所有对帧定位器的操作都将抛出错误。

// Throws if there are several frames in DOM:
page.locator(".result-frame").contentFrame().getByRole(AriaRole.BUTTON).click();

// Works because we explicitly tell locator to pick the first frame:
page.locator(".result-frame").first().contentFrame().getByRole(AriaRole.BUTTON).click();

将 Locator 转换为 FrameLocator

如果您有一个指向 iframeLocator 对象,可以使用 Locator.contentFrame() 将其转换为 FrameLocator

将 FrameLocator 转换为 Locator

如果您有一个 FrameLocator 对象,可以使用 FrameLocator.owner() 将其转换为指向同一 iframeLocator


方法

frameLocator

新增于: v1.17 frameLocator.frameLocator

使用 iframe 时,您可以创建一个框架定位器,它将进入 iframe 并允许选择 iframe 中的元素。

用法

FrameLocator.frameLocator(selector);

参数

  • selector String#

    用于解析 DOM 元素的选取器。

返回


getByAltText

新增于:v1.27 frameLocator.getByAltText

允许根据元素的 alt 文本定位元素。

用法

例如,此方法将通过 alt 文本“Playwright logo”找到图像

<img alt='Playwright logo'>
page.getByAltText("Playwright logo").click();

参数

  • text String | Pattern#

    用于定位元素的文本。

  • options FrameLocator.GetByAltTextOptions (可选)

    • setExact boolean (可选)#

      是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。

返回


getByLabel

新增于:v1.27 frameLocator.getByLabel

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

用法

例如,此方法将在以下 DOM 中通过标签“用户名”和“密码”找到输入

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">
page.getByLabel("Username").fill("john");
page.getByLabel("Password").fill("secret");

参数

  • text String | Pattern#

    用于定位元素的文本。

  • options FrameLocator.GetByLabelOptions (可选)

    • setExact boolean (可选)#

      是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。

返回


getByPlaceholder

新增于:v1.27 frameLocator.getByPlaceholder

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

用法

例如,考虑以下 DOM 结构。

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

您可以按占位符文本定位输入框后填充它

page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com");

参数

  • text String | Pattern#

    用于定位元素的文本。

  • options FrameLocator.GetByPlaceholderOptions (可选)

    • setExact boolean (可选)#

      是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。

返回


getByRole

新增于:v1.27 frameLocator.getByRole

允许根据元素的 ARIA 角色ARIA 属性可访问名称 定位元素。

用法

考虑以下 DOM 结构。

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

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

assertThat(page
.getByRole(AriaRole.HEADING,
new Page.GetByRoleOptions().setName("Sign up")))
.isVisible();

page.getByRole(AriaRole.CHECKBOX,
new Page.GetByRoleOptions().setName("Subscribe"))
.check();

page.getByRole(AriaRole.BUTTON,
new Page.GetByRoleOptions().setName(
Pattern.compile("submit", Pattern.CASE_INSENSITIVE)))
.click();

参数

  • 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 FrameLocator.GetByRoleOptions (可选)

    • setChecked boolean (可选)#

      通常由 aria-checked 或原生 <input type=checkbox> 控件设置的属性。

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

    • setDisabled boolean (可选)#

      通常由 aria-disableddisabled 设置的属性。

      注意

      与大多数其他属性不同,disabled 在 DOM 层次结构中是继承的。了解更多关于 aria-disabled 的信息。

    • setExact boolean (可选)新增于: v1.28#

      setName 是否完全匹配:区分大小写且完全匹配字符串。默认为 false。当 setName 是正则表达式时,忽略此项。请注意,完全匹配仍会修剪空白。

    • setExpanded boolean (可选)#

      通常由 aria-expanded 设置的属性。

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

    • setIncludeHidden boolean (可选)#

      控制是否匹配隐藏元素的选项。默认情况下,只有非隐藏元素(由 ARIA 定义)由角色选择器匹配。

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

    • setLevel int (可选)#

      通常用于角色 headinglistitemrowtreeitem 的数字属性,<h1>-<h6> 元素具有默认值。

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

    • setName String | Pattern (可选)#

      匹配 可访问名称 的选项。默认情况下,匹配不区分大小写并搜索子字符串,使用 setExact 控制此行为。

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

    • setPressed boolean (可选)#

      通常由 aria-pressed 设置的属性。

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

    • setSelected boolean (可选)#

      通常由 aria-selected 设置的属性。

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

返回

详情

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

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


getByTestId

新增于:v1.27 frameLocator.getByTestId

按测试 ID 定位元素。

用法

考虑以下 DOM 结构。

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

您可以通过其测试 ID 定位元素

page.getByTestId("directions").click();

参数

返回

详情

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


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", new Page.GetByTextOptions().setExact(true));

// Matches both <div>s
page.getByText(Pattern.compile("Hello"));

// Matches second <div>
page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE));

参数

  • text String | Pattern#

    用于定位元素的文本。

  • options FrameLocator.GetByTextOptions (可选)

    • setExact boolean (可选)#

      是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。

返回

详情

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

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


getByTitle

新增于:v1.27 frameLocator.getByTitle

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

用法

考虑以下 DOM 结构。

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

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

assertThat(page.getByTitle("Issues count")).hasText("25 issues");

参数

  • text String | Pattern#

    用于定位元素的文本。

  • options FrameLocator.GetByTitleOptions (可选)

    • setExact boolean (可选)#

      是否查找完全匹配:区分大小写和全字符串。默认为 false。通过正则表达式定位时忽略。请注意,精确匹配仍会去除空白。

返回


locator

新增于: v1.17 frameLocator.locator

此方法在定位器的子树中查找与指定选择器匹配的元素。它还接受筛选选项,类似于 Locator.filter() 方法。

了解更多关于定位器.

用法

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

参数

  • selectorOrLocator String | Locator#

    用于解析 DOM 元素的选择器或定位器。

  • options FrameLocator.LocatorOptions (可选)

    • setHas Locator (可选)#

      将方法的结果缩小到那些包含与此相对定位器匹配的元素的元素。例如,包含 text=Playwrightarticle 匹配 <article><div>Playwright</div></article>

      内部定位器**必须相对于**外部定位器,并且从外部定位器匹配开始查询,而不是从文档根开始。例如,您可以在 <article><content><div>Playwright</div></content></article> 中找到包含 divcontent。但是,查找包含 article divcontent 将失败,因为内部定位器必须是相对的,并且不应使用 content 之外的任何元素。

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

    • setHasNot Locator (可选)新增于:v1.33#

      匹配不包含与内部定位器匹配的元素的元素。内部定位器针对外部定位器进行查询。例如,不包含 divarticle 匹配 <article><span>Playwright</span></article>

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

    • setHasNotText String | Pattern (可选)新增于:v1.33#

      匹配不包含指定文本的元素,该文本可能在子元素或后代元素中。当传递 字符串 时,匹配不区分大小写并搜索子字符串。

    • setHasText String | Pattern (可选)#

      匹配包含指定文本的元素,该文本可能在子元素或后代元素中。当传递 字符串 时,匹配不区分大小写并搜索子字符串。例如,"Playwright" 匹配 <article><div>Playwright</div></article>

返回


owner

新增于: v1.43 frameLocator.owner

返回一个 Locator 对象,指向与此框架定位器相同的 iframe

当您在某处获取了一个 FrameLocator 对象,之后希望与 iframe 元素进行交互时,此功能很有用。

对于反向操作,请使用 Locator.contentFrame()

用法

FrameLocator frameLocator = page.locator("iframe[name=\"embedded\"]").contentFrame();
// ...
Locator locator = frameLocator.owner();
assertThat(locator).isVisible();

返回


已弃用

first

新增于: v1.17 frameLocator.first
已废弃

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

用法

FrameLocator.first();

返回


last

新增于: v1.17 frameLocator.last
已废弃

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

用法

FrameLocator.last();

返回


nth

新增于: v1.17 frameLocator.nth
已废弃

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

用法

FrameLocator.nth(index);

参数

返回