FrameLocator

FrameLocator 表示页面上的 iframe 的视图。它包含了获取 iframe 并在该 iframe 中定位元素所需的逻辑。可以通过 Locator.contentFrame()、Page.frameLocator() 或 Locator.frameLocator() 方法创建 FrameLocator。

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

严格模式

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

// 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

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

将 FrameLocator 转换为 Locator

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

方法

frameLocator

添加于: v1.17

frameLocator.frameLocator

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

用法

FrameLocator.frameLocator(selector);

参数

selector String | Pattern #

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

返回值

FrameLocator #

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。通过正则表达式定位时忽略。请注意，精确匹配仍会去除空白字符。

返回值

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">

page.getByLabel("Username").fill("john");
page.getByLabel("Password").fill("secret");

参数

text String | Pattern #

用于定位元素的文本。
options FrameLocator.GetByLabelOptions (可选)
- setExact boolean (可选)#
  
  是否查找精确匹配：区分大小写且匹配整个字符串。默认为 false。通过正则表达式定位时忽略。请注意，精确匹配仍会去除空白字符。

返回值

Locator #

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。通过正则表达式定位时忽略。请注意，精确匹配仍会去除空白字符。

返回值

Locator #

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-disabled 或 disabled 设置的属性。
  
  注意
  与大多数其他属性不同，disabled 通过 DOM 层次结构继承。了解更多关于 aria-disabled 的信息。
- setExact boolean (可选)添加于: v1.28#
  
  是否精确匹配 setName：区分大小写且匹配整个字符串。默认为 false。当 setName 是正则表达式时忽略。请注意，精确匹配仍会去除空白字符。
- setExpanded boolean (可选)#
  
  通常由 aria-expanded 设置的属性。
  
  了解更多关于 aria-expanded 的信息。
- setIncludeHidden boolean (可选)#
  
  控制是否匹配隐藏元素的选项。默认情况下，角色选择器仅匹配非隐藏元素（如 ARIA 定义）。
  
  了解更多关于 aria-hidden 的信息。
- setLevel int (可选)#
  
  通常用于 heading、listitem、row、treeitem 角色的数值属性，<h1>-<h6> 元素有默认值。
  
  了解更多关于 aria-level 的信息。
- setName String | Pattern (可选)#
  
  匹配可访问名称的选项。默认情况下，匹配不区分大小写并搜索子字符串，使用 setExact 来控制此行为。
  
  了解更多关于可访问名称的信息。
- setPressed boolean (可选)#
  
  通常由 aria-pressed 设置的属性。
  
  了解更多关于 aria-pressed 的信息。
- setSelected boolean (可选)#
  
  通常由 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 定位元素

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

参数

testId String | Pattern #

用于定位元素的 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>

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

// 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。通过正则表达式定位时忽略。请注意，精确匹配仍会去除空白字符。

返回值

Locator #

详情

即使是精确匹配，按文本匹配也会规范化空白字符。例如，它将多个空格变成一个，将换行符变成空格，并忽略前导和尾随空白字符。

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 文本定位后，您可以检查问题数量

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

参数

text String | Pattern #

用于定位元素的文本。
options FrameLocator.GetByTitleOptions (可选)
- setExact boolean (可选)#
  
  是否查找精确匹配：区分大小写且匹配整个字符串。默认为 false。通过正则表达式定位时忽略。请注意，精确匹配仍会去除空白字符。

返回值

Locator #

locator

添加于: v1.17

frameLocator.locator

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

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

用法

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

参数

selectorOrLocator String | Locator #

解析 DOM 元素时使用的选择器或定位器。
options FrameLocator.LocatorOptions (可选)
- setHas Locator (可选)#
  
  将方法结果缩小到包含与此相对定位器匹配的元素的那些结果。例如，包含 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。
  
  内部定位器必须相对于外部定位器，并且从外部定位器的匹配项开始查询，而不是从文档根开始。例如，您可以在 <article><content><div>Playwright</div></content></article> 中找到包含 div 的 content。但是，查找包含 article div 的 content 将失败，因为内部定位器必须是相对的，不应使用 content 外部的任何元素。
  
  请注意，外部定位器和内部定位器必须属于同一帧。内部定位器不得包含 FrameLocator。
- setHasNot Locator (可选)添加于: v1.33#
  
  匹配不包含与内部定位器匹配的元素的元素。内部定位器相对于外部定位器进行查询。例如，不包含 div 的 article 匹配 <article><span>Playwright</span></article>。
  
  请注意，外部定位器和内部定位器必须属于同一帧。内部定位器不得包含 FrameLocator。
- setHasNotText String | Pattern (可选)添加于: v1.33#
  
  匹配内部某个位置（可能在子元素或后代元素中）不包含指定文本的元素。当传入字符串时，匹配不区分大小写并搜索子字符串。
- setHasText String | Pattern (可选)#
  
  匹配内部某个位置（可能在子元素或后代元素中）包含指定文本的元素。当传入字符串时，匹配不区分大小写并搜索子字符串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。

返回值

Locator #

owner

添加于: v1.43

frameLocator.owner

返回一个 Locator 对象，指向与此 FrameLocator 相同的 iframe。

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

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

用法

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

返回值

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 个匹配帧的定位器。它是从零开始的，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