Skip to main content

FrameLocator

FrameLocator 表示页面上 iframe 的一个视图。它捕获的逻辑足以检索 iframe 并定位该 iframe 中的元素。FrameLocator 可以通过 locator.contentFrame()、page.frameLocator() 或 locator.frameLocator() 方法创建。

🌐 FrameLocator represents a view to the iframe on the page. It captures the logic sufficient to retrieve the iframe and locate elements in that iframe. FrameLocator can be created with either locator.contentFrame(), page.frameLocator() or locator.frameLocator() method.

const locator = page.locator('#my-frame').contentFrame().getByText('Submit');
await locator.click();

严格

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

🌐 Frame locators are strict. This means that all operations on frame locators will throw if more than one element matches a given selector.

// Throws if there are several frames in DOM:
await page.locator('.result-frame').contentFrame().getByRole('button').click();

// Works because we explicitly tell locator to pick the first frame:
await page.locator('.result-frame').contentFrame().first().getByRole('button').click();

将 Locator 转换为 FrameLocator

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

🌐 If you have a Locator object pointing to an iframe it can be converted to FrameLocator using locator.contentFrame().

将 FrameLocator 转换为 Locator

如果你有一个 FrameLocator 对象，它可以使用 frameLocator.owner() 转换为指向相同 iframe 的 Locator。

🌐 If you have a FrameLocator object it can be converted to Locator pointing to the same iframe using frameLocator.owner().

方法​

🌐 Methods

frameLocator​

Added in: v1.17 frameLocator.frameLocator

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

🌐 When working with iframes, you can create a frame locator that will enter the iframe and allow selecting elements in that iframe.

用法

frameLocator.frameLocator(selector);

参数

  • selector string#

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

返回

getByAltText​

Added in: v1.27 frameLocator.getByAltText

允许通过替代文本定位元素。

🌐 Allows locating elements by their alt text.

用法

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

🌐 For example, this method will find the image by alt text "Playwright logo":

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

参数

  • text string | RegExp#

    用于定位元素的文本。

  • options Object (optional)

    • exact boolean (optional)#

      是否查找完全匹配：区分大小写并匹配整个字符串。默认为 false。在通过正则表达式定位时会被忽略。请注意，完全匹配仍会去除空白字符。

返回

getByLabel​

Added in: v1.27 frameLocator.getByLabel

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

🌐 Allows locating input elements by the text of the associated <label> or aria-labelledby element, or by the aria-label attribute.

用法

例如，这种方法将在以下 DOM 中根据标签“用户名”和“密码”查找输入项：

🌐 For example, this method will find inputs by label "Username" and "Password" in the following DOM:

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

参数

  • text string | RegExp#

    用于定位元素的文本。

  • options Object (optional)

    • exact boolean (optional)#

      是否查找完全匹配：区分大小写并匹配整个字符串。默认为 false。在通过正则表达式定位时会被忽略。请注意，完全匹配仍会去除空白字符。

返回

getByPlaceholder​

Added in: v1.27 frameLocator.getByPlaceholder

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

🌐 Allows locating input elements by the placeholder text.

用法

例如，考虑以下 DOM 结构。

🌐 For example, consider the following DOM structure.

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

你可以在通过占位符文本找到输入后填充输入：

🌐 You can fill the input after locating it by the placeholder text:

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

参数

  • text string | RegExp#

    用于定位元素的文本。

  • options Object (optional)

    • exact boolean (optional)#

      是否查找完全匹配：区分大小写并匹配整个字符串。默认为 false。在通过正则表达式定位时会被忽略。请注意，完全匹配仍会去除空白字符。

返回

getByRole​

Added in: v1.27 frameLocator.getByRole

允许通过元素的ARIA 角色、ARIA 属性和可访问名称来定位元素。

🌐 Allows locating elements by their ARIA role, ARIA attributes and accessible name.

用法

考虑以下 DOM 结构。

🌐 Consider the following DOM structure.

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

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

🌐 You can locate each element by it's implicit role:

await expect(page.getByRole('heading', { name: 'Sign up' })).toBeVisible();

await page.getByRole('checkbox', { name: 'Subscribe' }).check();

await page.getByRole('button', { name: /submit/i }).click();

参数

  • role "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"#

    所需的咏叹调角色。

  • options Object (optional)

    • checked boolean (optional)#

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

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

    • disabled boolean (optional)#

      通常由 aria-disabled 或 disabled 设置的属性。

      note

      与大多数其他属性不同，disabled 是通过 DOM 层级继承的。了解更多关于 aria-disabled 的信息。

    • exact boolean (optional) Added in: v1.28#

      是否与name完全匹配：区分大小写且匹配整个字符串。默认为 false。当name是正则表达式时将被忽略。请注意，完全匹配仍会去除空格。

    • expanded boolean (optional)#

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

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

    • includeHidden boolean (optional)#

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

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

    • level number (optional)#

      一个通常存在于角色 heading、listitem、row、treeitem 的数字属性，对 <h1>-<h6> 元素有默认值。

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

    • name string | RegExp (optional)#

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

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

    • pressed boolean (optional)#

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

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

    • selected boolean (optional)#

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

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

返回

详情

角色选择器不能替代无障碍审查和符合性测试，而是提供关于ARIA指南的早期反馈。

🌐 Role selector does not replace accessibility audits and conformance tests, but rather gives early feedback about the ARIA guidelines.

许多HTML元素都隐含着[定义角色]（https://w3c.github.io/html-aam/#html-element-role-mappings），角色选择器会识别该角色。你可以在这里找到所有[支持的角色]（https://www.w3.org/TR/wai-aria-1.2/#role_definitions）。ARIA 指南不建议通过将“role”和/或“aria-*”属性设置为默认值来重复隐式角色和属性。

🌐 Many html elements have an implicitly defined role that is recognized by the role selector. You can find all the supported roles here. ARIA guidelines do not recommend duplicating implicit roles and attributes by setting role and/or aria-* attributes to default values.

getByTestId​

Added in: v1.27 frameLocator.getByTestId

通过测试 ID 定位元素。

🌐 Locate element by the test id.

用法

考虑以下 DOM 结构。

🌐 Consider the following DOM structure.

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

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

🌐 You can locate the element by it's test id:

await page.getByTestId('directions').click();

参数

返回

详情

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

🌐 By default, the data-testid attribute is used as a test id. Use selectors.setTestIdAttribute() to configure a different test id attribute if necessary.

// Set custom test id attribute from @playwright/test config:
import { defineConfig } from '@playwright/test';

export default defineConfig({
  use: {
    testIdAttribute: 'data-pw'
  },
});

getByText​

Added in: v1.27 frameLocator.getByText

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

🌐 Allows locating elements that contain given text.

另请参阅 locator.filter()，它允许按其他条件匹配，例如可访问角色，然后按文本内容进行筛选。

🌐 See also locator.filter() that allows to match by another criteria, like an accessible role, and then filter by the text content.

用法

考虑以下 DOM 结构：

🌐 Consider the following DOM structure:

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

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

🌐 You can locate by text substring, exact string, or a regular expression:

// Matches <span>
page.getByText('world');

// Matches first <div>
page.getByText('Hello world');

// Matches second <div>
page.getByText('Hello', { exact: true });

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

// Matches second <div>
page.getByText(/^hello$/i);

参数

  • text string | RegExp#

    用于定位元素的文本。

  • options Object (optional)

    • exact boolean (optional)#

      是否查找完全匹配：区分大小写并匹配整个字符串。默认为 false。在通过正则表达式定位时会被忽略。请注意，完全匹配仍会去除空白字符。

返回

详情

文本匹配总是会规范化空白字符，即使是完全匹配。例如，它会将多个空格变为一个，将换行符变为空格，并忽略开头和结尾的空白。

🌐 Matching by text always normalizes whitespace, even with exact match. For example, it turns multiple spaces into one, turns line breaks into spaces and ignores leading and trailing whitespace.

类型为 button 和 submit 的输入元素是通过它们的 value 而不是文本内容来匹配的。例如，通过文本 "Log in" 定位会匹配 <input type=button value="Log in">。

🌐 Input elements of the type button and submit are matched by their value instead of the text content. For example, locating by text "Log in" matches <input type=button value="Log in">.

getByTitle​

Added in: v1.27 frameLocator.getByTitle

允许通过标题属性定位元素。

🌐 Allows locating elements by their title attribute.

用法

考虑以下 DOM 结构。

🌐 Consider the following DOM structure.

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

你可以通过标题文本找到问题后查看问题数：

🌐 You can check the issues count after locating it by the title text:

await expect(page.getByTitle('Issues count')).toHaveText('25 issues');

参数

  • text string | RegExp#

    用于定位元素的文本。

  • options Object (optional)

    • exact boolean (optional)#

      是否查找完全匹配：区分大小写并匹配整个字符串。默认为 false。在通过正则表达式定位时会被忽略。请注意，完全匹配仍会去除空白字符。

返回

locator​

Added in: v1.17 frameLocator.locator

该方法在定位子树中找到与指定选择符匹配的元素。它还接受过滤选项，类似于 [locator.filter（）]（/api/class-locator.mdx#locator-filter） 方法。

🌐 The method finds an element matching the specified selector in the locator's subtree. It also accepts filter options, similar to locator.filter() method.

了解有关定位器的更多信息。

用法

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

参数

  • selectorOrLocator string | Locator#

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

  • options Object (optional)

    • has Locator (optional)#

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

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

      请注意，外部定位器和内部定位器必须属于同一帧。内部定位器不能包含 FrameLocator。

    • hasNot Locator (optional) Added in: v1.33#

      匹配不包含与内层定位器匹配的元素的元素。内层定位器是在外层定位器范围内查询的。例如，不包含 div 的 article 会匹配 <article><span>Playwright</span></article>。

      请注意，外部定位器和内部定位器必须属于同一帧。内部定位器不能包含 FrameLocator。

    • hasNotText string | RegExp (optional) Added in: v1.33#

      匹配其内部（可能在子元素或后代元素中）不包含指定文本的元素。传入string时，匹配不区分大小写，并搜索子字符串。

    • hasText string | RegExp (optional)#

      匹配包含指定文本的元素，该文本可能位于子元素或后代元素中。如果传入一个[字符串]，匹配不区分大小写，并搜索子字符串。例如，"Playwright" 可以匹配 <article><div>Playwright</div></article>。

返回

owner​

Added in: v1.43 frameLocator.owner

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

🌐 Returns a Locator object pointing to the same iframe as this frame locator.

当你在某处获得了一个 FrameLocator 对象，并且之后想要与 iframe 元素进行交互时，这很有用。

🌐 Useful when you have a FrameLocator object obtained somewhere, and later on would like to interact with the iframe element.

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

🌐 For a reverse operation, use locator.contentFrame().

用法

const frameLocator = page.locator('iframe[name="embedded"]').contentFrame();
// ...
const locator = frameLocator.owner();
await expect(locator).toBeVisible();

返回

已弃用​

🌐 Deprecated

first​

Added in: v1.17 frameLocator.first
已弃用

而是使用 locator.first()，然后使用 locator.contentFrame()。

🌐 Use locator.first() followed by locator.contentFrame() instead.

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

🌐 Returns locator to the first matching frame.

用法

frameLocator.first();

返回

last​

Added in: v1.17 frameLocator.last
已弃用

而是使用 locator.last()，然后使用 locator.contentFrame()。

🌐 Use locator.last() followed by locator.contentFrame() instead.

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

🌐 Returns locator to the last matching frame.

用法

frameLocator.last();

返回

nth​

Added in: v1.17 frameLocator.nth
已弃用

请改为使用 locator.nth()，然后使用 locator.contentFrame()。

🌐 Use locator.nth() followed by locator.contentFrame() instead.

返回第 n 个匹配框架的定位器。它是从零开始的，nth(0) 选择第一个框架。

🌐 Returns locator to the n-th matching frame. It's zero based, nth(0) selects the first frame.

用法

frameLocator.nth(index);

参数

返回