框架

在任何时间点，页面都通过 page.mainFrame() 和 frame.childFrames() 方法公开其当前的框架树。

Frame 对象的生命周期由三个事件控制，这些事件在页面对象上分派

page.on('frameattached') - 当框架附加到页面时触发。框架只能附加到页面一次。
page.on('framenavigated') - 当框架提交导航到不同的 URL 时触发。
page.on('framedetached') - 当框架从页面分离时触发。框架只能从页面分离一次。

转储框架树的示例

const { firefox } = require('playwright');  // Or 'chromium' or 'webkit'.

(async () => {
  const browser = await firefox.launch();
  const page = await browser.newPage();
  await page.goto('https://www.google.com/chrome/browser/canary.html');
  dumpFrameTree(page.mainFrame(), '');
  await browser.close();

  function dumpFrameTree(frame, indent) {
    console.log(indent + frame.url());
    for (const child of frame.childFrames())
      dumpFrameTree(child, indent + '  ');
  }
})();

方法

addScriptTag

在 v1.9 之前添加

frame.addScriptTag

当脚本的 onload 触发或脚本内容注入到框架中时，返回添加的标签。

将一个 <script> 标签添加到页面中，并使用所需的 url 或内容。

用法

await frame.addScriptTag();
await frame.addScriptTag(options);

参数

options 对象 （可选）
- content 字符串 （可选）#
  
  要注入到框架中的原始 JavaScript 内容。
- path 字符串 （可选）#
  
  要注入到框架中的 JavaScript 文件的路径。如果 path 是相对路径，则相对于当前工作目录解析。
- type 字符串 （可选）#
  
  脚本类型。使用 'module' 加载 JavaScript ES6 模块。有关更多详细信息，请参阅 script。
- url 字符串 （可选）#
  
  要添加的脚本的 URL。

返回值

Promise<元素句柄>#

addStyleTag

在 v1.9 之前添加

frame.addStyleTag

当样式表的 onload 触发或 CSS 内容注入到框架中时，返回添加的标签。

将一个 <link rel="stylesheet"> 标签添加到页面中，并使用所需的 url 或一个 <style type="text/css"> 标签和内容。

用法

await frame.addStyleTag();
await frame.addStyleTag(options);

参数

options 对象 （可选）
- content 字符串 （可选）#
  
  要注入到框架中的原始 CSS 内容。
- path 字符串 （可选）#
  
  要注入到框架中的 CSS 文件的路径。如果 path 是相对路径，则相对于当前工作目录解析。
- url 字符串 （可选）#
  
  <link> 标签的 URL。

返回值

Promise<元素句柄>#

childFrames

在 v1.9 之前添加

frame.childFrames

用法

frame.childFrames();

返回值

数组<框架>#

content

在 v1.9 之前添加

frame.content

获取框架的完整 HTML 内容，包括文档类型。

用法

await frame.content();

返回值

Promise<字符串>#

dragAndDrop

在以下版本中添加：v1.13

frame.dragAndDrop

用法

await frame.dragAndDrop(source, target);
await frame.dragAndDrop(source, target, options);

参数

source 字符串 #

用于搜索要拖动的元素的选择器。如果有多个元素满足选择器，则使用第一个。
target 字符串 #

用于搜索要拖放到其上的元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- force 布尔值 （可选）#
  
  是否绕过可操作性检查。默认为 false。
- noWaitAfter 布尔值 （可选）#
  
  已弃用
  此选项无效。
  
  此选项无效。
- sourcePosition 对象 （可选）在以下版本中添加：v1.14#
  - x 数字
  - y 数字
  在此点点击源元素，相对于元素填充框的左上角。如果未指定，则使用元素的某个可见点。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- targetPosition 对象 （可选）在以下版本中添加：v1.14#
  - x 数字
  - y 数字
  在此点将目标元素放在目标元素上，相对于元素填充框的左上角。如果未指定，则使用元素的某个可见点。
- timeout 数字 （可选）#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
- trial 布尔值 （可选）#
  
  设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于在元素准备好执行操作之前等待，而无需执行它。

返回值

Promise<void>#

评估

在 v1.9 之前添加

frame.evaluate

返回pageFunction的返回值。

如果传递给frame.evaluate()的函数返回一个Promise，那么frame.evaluate()将等待Promise解析并返回其值。

如果传递给frame.evaluate()的函数返回一个非可序列化的值，那么frame.evaluate()将返回undefined。Playwright还支持传输一些JSON无法序列化的附加值：-0、NaN、Infinity、-Infinity。

用法

const result = await frame.evaluate(([x, y]) => {
  return Promise.resolve(x * y);
}, [7, 8]);
console.log(result); // prints "56"

也可以传入字符串而不是函数。

console.log(await frame.evaluate('1 + 2')); // prints "3"

ElementHandle实例可以作为参数传递给frame.evaluate()

const bodyHandle = await frame.evaluate('document.body');
const html = await frame.evaluate(([body, suffix]) =>
  body.innerHTML + suffix, [bodyHandle, 'hello'],
);
await bodyHandle.dispose();

参数

pageFunction 函数 | 字符串 #

在页面上下文中要执行的函数。
arg EvaluationArgument (可选)#

传递给pageFunction的可选参数。

返回值

Promise<可序列化>#

evaluateHandle

在 v1.9 之前添加

frame.evaluateHandle

将pageFunction的返回值作为JSHandle返回。

frame.evaluate()和frame.evaluateHandle()之间的唯一区别是frame.evaluateHandle()返回JSHandle。

如果传递给frame.evaluateHandle()的函数返回一个Promise，那么frame.evaluateHandle()将等待Promise解析并返回其值。

用法

// Handle for the window object
const aWindowHandle = await frame.evaluateHandle(() => Promise.resolve(window));

也可以传入字符串而不是函数。

const aHandle = await frame.evaluateHandle('document'); // Handle for the 'document'.

JSHandle实例可以作为参数传递给frame.evaluateHandle()

const aHandle = await frame.evaluateHandle(() => document.body);
const resultHandle = await frame.evaluateHandle(([body, suffix]) =>
  body.innerHTML + suffix, [aHandle, 'hello'],
);
console.log(await resultHandle.jsonValue());
await resultHandle.dispose();

参数

pageFunction 函数 | 字符串 #

在页面上下文中要执行的函数。
arg EvaluationArgument (可选)#

传递给pageFunction的可选参数。

返回值

Promise<JSHandle>#

frameElement

在 v1.9 之前添加

frame.frameElement

返回与该框架对应的frame或iframe元素句柄。

这是elementHandle.contentFrame()的反向操作。请注意，返回的句柄实际上属于父框架。

如果框架在frameElement()返回之前已分离，则此方法将抛出错误。

用法

const frameElement = await frame.frameElement();
const contentFrame = await frameElement.contentFrame();
console.log(frame === contentFrame);  // -> true

返回值

Promise<ElementHandle>#

frameLocator

新增于：v1.17

frame.frameLocator

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

用法

以下代码片段在id为my-frame的iframe中查找文本为“Submit”的元素，例如<iframe id="my-frame">

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

参数

selector 字符串 #

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

返回值

FrameLocator #

getByAltText

新增于：v1.27

frame.getByAltText

允许通过alt文本定位元素。

用法

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

<img alt='Playwright logo'>

await page.getByAltText('Playwright logo').click();

参数

text 字符串 | 正则表达式 #

要定位元素的文本。
options 对象 （可选）
- exact 布尔值 (可选)#
  
  是否查找完全匹配：区分大小写且为整个字符串。默认为false。在通过正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

Locator #

getByLabel

新增于：v1.27

frame.getByLabel

允许通过关联的<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').fill('john');
await page.getByLabel('Password').fill('secret');

参数

text 字符串 | 正则表达式 #

要定位元素的文本。
options 对象 （可选）
- exact 布尔值 (可选)#
  
  是否查找完全匹配：区分大小写且为整个字符串。默认为false。在通过正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

Locator #

getByPlaceholder

新增于：v1.27

frame.getByPlaceholder

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

用法

例如，考虑以下DOM结构。

<input type="email" placeholder="[email protected]" />

您可以通过占位符文本定位输入后填写输入

await page
    .getByPlaceholder('[email protected]')
    .fill('[email protected]');

参数

text 字符串 | 正则表达式 #

要定位元素的文本。
options 对象 （可选）
- exact 布尔值 (可选)#
  
  是否查找完全匹配：区分大小写且为整个字符串。默认为false。在通过正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

Locator #

getByRole

新增于：v1.27

frame.getByRole

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

用法

考虑以下DOM结构。

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

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

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

所需的aria角色。
options 对象 （可选）
- checked 布尔值 (可选)#
  
  通常由aria-checked或原生<input type=checkbox>控件设置的属性。
  
  了解有关aria-checked的更多信息。
- disabled 布尔值 (可选)#
  
  通常由aria-disabled或disabled设置的属性。
  
  注意
  
  与大多数其他属性不同，disabled 会通过 DOM 层次结构继承。了解更多关于 aria-disabled。
- exact 布尔值 (可选)新增于：v1.28#
  
  是否精确匹配 name：区分大小写且匹配整个字符串。默认为 false。当 name 为正则表达式时忽略。请注意，精确匹配仍然会去除空格。
- expanded 布尔值 (可选)#
  
  通常由 aria-expanded 设置的属性。
  
  了解更多关于 aria-expanded。
- includeHidden 布尔值 (可选)#
  
  控制是否匹配隐藏元素的选项。默认情况下，只有非隐藏元素（如 ARIA 定义）才会被角色选择器匹配。
  
  了解更多关于 aria-hidden。
- level 数字 (可选)#
  
  通常存在于 heading、listitem、row、treeitem 等角色中的数字属性，对于 <h1>-<h6> 元素具有默认值。
  
  了解更多关于 aria-level。
- name 字符串 | 正则表达式 (可选)#
  
  用于匹配可访问名称的选项。默认情况下，匹配不区分大小写并搜索子字符串，使用 exact 控制此行为。
  
  了解更多关于可访问名称。
- pressed 布尔值 (可选)#
  
  通常由 aria-pressed 设置的属性。
  
  了解更多关于 aria-pressed。
- selected 布尔值 (可选)#
  
  通常由 aria-selected 设置的属性。
  
  了解更多关于 aria-selected。

返回值

定位器 #

详情

角色选择器**不会取代**可访问性审计和一致性测试，而是提供关于 ARIA 指南的早期反馈。

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

getByTestId

新增于：v1.27

frame.getByTestId

根据测试 ID 定位元素。

用法

考虑以下DOM结构。

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

您可以根据元素的测试 ID 定位它。

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

参数

testId 字符串 | 正则表达式 #

要根据其定位元素的 ID。

返回值

定位器 #

详情

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

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

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

getByText

新增于：v1.27

frame.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', { exact: true });

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

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

参数

text 字符串 | 正则表达式 #

要定位元素的文本。
options 对象 （可选）
- exact 布尔值 (可选)#
  
  是否查找完全匹配：区分大小写且为整个字符串。默认为false。在通过正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

定位器 #

详情

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

类型为 button 和 submit 的输入元素将根据其 value 而不是文本内容进行匹配。例如，根据文本 "Log in" 进行定位将匹配 <input type=button value="Log in">。

getByTitle

新增于：v1.27

frame.getByTitle

允许根据元素的 title 属性定位元素。

用法

考虑以下DOM结构。

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

您可以在根据标题文本定位后检查问题计数。

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

参数

text 字符串 | 正则表达式 #

要定位元素的文本。
options 对象 （可选）
- exact 布尔值 (可选)#
  
  是否查找完全匹配：区分大小写且为整个字符串。默认为false。在通过正则表达式定位时忽略。请注意，完全匹配仍然会修剪空格。

返回值

定位器 #

goto

在 v1.9 之前添加

frame.goto

返回主资源响应。如果发生多次重定向，导航将解析最后一个重定向的响应。

如果出现以下情况，该方法将抛出错误：

存在 SSL 错误（例如，自签名证书）。
目标 URL 无效。
导航期间超过了超时时间。
远程服务器没有响应或无法访问。
主资源加载失败。

当远程服务器返回任何有效的 HTTP 状态代码时，该方法不会抛出错误，包括 404“未找到”和 500“内部服务器错误”。可以通过调用 response.status() 获取此类响应的状态代码。

注意

该方法要么抛出错误，要么返回主资源响应。唯一的例外是导航到 about:blank 或使用不同哈希值导航到同一 URL，这将成功并返回 null。

注意

无头模式不支持导航到 PDF 文档。请参阅上游问题。

用法

await frame.goto(url);
await frame.goto(url, options);

参数

url 字符串 #

要导航到的框架的 URL。url 应包含方案，例如 https://。
options 对象 （可选）
- referer 字符串 (可选)#
  
  Referer 标头值。如果提供，它将优先于由 page.setExtraHTTPHeaders() 设置的 Referer 标头值。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大操作时间。默认为 0 - 无超时。默认值可以通过配置中的 navigationTimeout 选项更改，或者使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法更改。
- waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#
  
  何时认为操作成功，默认为 load。事件可以是：
  - 'domcontentloaded' - 当触发 DOMContentLoaded 事件时，认为操作已完成。
  - 'load' - 当触发 load 事件时，认为操作已完成。
  - 'networkidle' - 不建议使用 当至少 500 毫秒内没有网络连接时，认为操作已完成。不要将此方法用于测试，而是依靠 Web 断言来评估就绪状态。
  - 'commit' - 当收到网络响应并开始加载文档时，认为操作已完成。

返回值

Promise<null | 响应>#

isDetached

在 v1.9 之前添加

frame.isDetached

如果框架已分离，则返回 true，否则返回 false。

用法

frame.isDetached();

返回值

布尔值 #

isEnabled

在 v1.9 之前添加

frame.isEnabled

返回元素是否已启用。

用法

await frame.isEnabled(selector);
await frame.isEnabled(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<布尔值>#

定位器

在以下版本中添加：v1.14

frame.locator

此方法返回一个元素定位器，可用于对该页面/框架执行操作。在执行操作之前，定位器会立即解析为元素，因此对同一定位器的一系列操作实际上可能在不同的 DOM 元素上执行。如果这些操作之间的 DOM 结构发生了变化，就会发生这种情况。

详细了解定位器.

用法

frame.locator(selector);
frame.locator(selector, options);

参数

selector 字符串 #

解析DOM元素时要使用的选择器。
options 对象 （可选）
- has Locator (可选)#
  
  将方法的结果缩小到包含与该相对定位器匹配的元素的那些结果。例如，包含 text=Playwright 的 article 匹配 <article><div>Playwright</div></article>。
  
  内部定位器**必须相对于**外部定位器，并且从外部定位器匹配开始查询，而不是从文档根开始。例如，您可以在 <article><content><div>Playwright</div></content></article> 中找到包含 div 的 content。但是，查找包含 article div 的 content 会失败，因为内部定位器必须是相对的，并且不应使用 content 之外的任何元素。
  
  请注意，外部和内部定位器必须属于同一框架。内部定位器不得包含 FrameLocator。
- hasNot Locator (可选)新增于：v1.33#
  
  匹配不包含与内部定位器匹配的元素的元素。内部定位器针对外部定位器进行查询。例如，不包含 div 的 article 匹配 <article><span>Playwright</span></article>。
  
  请注意，外部和内部定位器必须属于同一框架。内部定位器不得包含 FrameLocator。
- hasNotText 字符串 | 正则表达式 (可选)新增于：v1.33#
  
  匹配内部（可能在子元素或后代元素中）不包含指定文本的元素。当传递一个字符串时，匹配不区分大小写并搜索子字符串。
- hasText 字符串 | 正则表达式 (可选)#
  
  匹配内部（可能在子元素或后代元素中）包含指定文本的元素。当传递一个字符串时，匹配不区分大小写并搜索子字符串。例如，"Playwright" 匹配 <article><div>Playwright</div></article>。

返回值

Locator #

名称

在 v1.9 之前添加

frame.name

返回框架中标签中指定的 name 属性。

如果名称为空，则返回 id 属性。

注意

此值在创建框架时计算一次，如果稍后更改属性，则不会更新。

用法

frame.name();

返回值

字符串 #

页面

在 v1.9 之前添加

frame.page

返回包含此框架的页面。

用法

frame.page();

返回值

Page #

父框架

在 v1.9 之前添加

frame.parentFrame

父框架（如果有）。分离的框架和主框架返回 null。

用法

frame.parentFrame();

返回值

null | Frame #

设置内容

在 v1.9 之前添加

frame.setContent

此方法在内部调用 document.write()，继承其所有特定特性和行为。

用法

await frame.setContent(html);
await frame.setContent(html, options);

参数

html 字符串 #

要分配给页面的 HTML 标记。
options 对象 （可选）
- timeout 数字 (可选)#
  
  以毫秒为单位的最大操作时间。默认为 0 - 无超时。默认值可以通过配置中的 navigationTimeout 选项更改，或者使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法更改。
- waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#
  
  何时认为操作成功，默认为 load。事件可以是：
  - 'domcontentloaded' - 当触发 DOMContentLoaded 事件时，认为操作已完成。
  - 'load' - 当触发 load 事件时，认为操作已完成。
  - 'networkidle' - 不建议使用 当至少 500 毫秒内没有网络连接时，认为操作已完成。不要将此方法用于测试，而是依靠 Web 断言来评估就绪状态。
  - 'commit' - 当收到网络响应并开始加载文档时，认为操作已完成。

返回值

Promise<void>#

标题

在 v1.9 之前添加

frame.title

返回页面标题。

用法

await frame.title();

返回值

Promise<字符串>#

网址

在 v1.9 之前添加

frame.url

返回框架的网址。

用法

frame.url();

返回值

字符串 #

等待函数

在 v1.9 之前添加

frame.waitForFunction

当pageFunction返回真值时返回，并返回该值。

用法

frame.waitForFunction() 可用于观察视口大小的变化

const { firefox } = require('playwright');  // Or 'chromium' or 'webkit'.

(async () => {
  const browser = await firefox.launch();
  const page = await browser.newPage();
  const watchDog = page.mainFrame().waitForFunction('window.innerWidth < 100');
  await page.setViewportSize({ width: 50, height: 50 });
  await watchDog;
  await browser.close();
})();

要将参数传递给 frame.waitForFunction 函数的谓词

const selector = '.foo';
await frame.waitForFunction(selector => !!document.querySelector(selector), selector);

参数

pageFunction 函数 | 字符串 #

在页面上下文中要执行的函数。
arg EvaluationArgument (可选)#

要传递给 pageFunction 的可选参数。
options 对象 （可选）
- polling 数字 | "raf" (可选)#
  
  如果 polling 为 'raf'，则 pageFunction 会在 requestAnimationFrame 回调中不断执行。如果 polling 为数字，则将其视为以毫秒为单位的间隔，在此间隔内将执行该函数。默认为 raf。
- timeout 数字 (可选)#
  
  以毫秒为单位等待的最长时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或者使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<JSHandle>#

等待加载状态

在 v1.9 之前添加

frame.waitForLoadState

等待达到所需的加载状态。

当框架达到所需的加载状态时返回，默认为 load。调用此方法时，必须已提交导航。如果当前文档已达到所需状态，则立即解析。

注意

大多数情况下，不需要此方法，因为 Playwright 会在每个操作之前自动等待。

用法

await frame.click('button'); // Click triggers navigation.
await frame.waitForLoadState(); // Waits for 'load' state by default.

参数

state "load" | "domcontentloaded" | "networkidle" (可选)#

要等待的可选加载状态，默认为 load。如果在加载当前文档时已达到该状态，则该方法会立即解析。可以是以下之一：
- 'load' - 等待触发 load 事件。
- 'domcontentloaded' - 等待触发 DOMContentLoaded 事件。
- 'networkidle' - **不建议** 等待至少 500 毫秒没有网络连接。不要将此方法用于测试，而是依靠 Web 断言来评估就绪状态。
options 对象 （可选）
- timeout 数字 (可选)#
  
  以毫秒为单位的最大操作时间。默认为 0 - 无超时。默认值可以通过配置中的 navigationTimeout 选项更改，或者使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<void>#

waitForURL

新增于：v1.11

frame.waitForURL

等待框架导航到给定的 URL。

用法

await frame.click('a.delayed-navigation'); // Clicking the link will indirectly cause a navigation
await frame.waitForURL('**/target.html');

参数

url 字符串 | 正则表达式 | 函数(URL):布尔值 #

一个 glob 模式、正则表达式模式或接收 URL 的断言函数，用于在等待导航时进行匹配。请注意，如果参数是没有任何通配符的字符串，则该方法将等待导航到与该字符串完全相同的 URL。
options 对象 （可选）
- timeout 数字 (可选)#
  
  以毫秒为单位的最大操作时间。默认为 0 - 无超时。默认值可以通过配置中的 navigationTimeout 选项更改，或者使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法更改。
- waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#
  
  何时认为操作成功，默认为 load。事件可以是：
  - 'domcontentloaded' - 当触发 DOMContentLoaded 事件时，认为操作已完成。
  - 'load' - 当触发 load 事件时，认为操作已完成。
  - 'networkidle' - 不建议使用 当至少 500 毫秒内没有网络连接时，认为操作已完成。不要将此方法用于测试，而是依靠 Web 断言来评估就绪状态。
  - 'commit' - 当收到网络响应并开始加载文档时，认为操作已完成。

返回值

Promise<void>#

已弃用

$

新增于：v1.9

frame.$

不推荐

请改用基于定位器的 frame.locator()。阅读更多关于定位器的信息。

返回指向框架元素的 ElementHandle。

注意

不建议使用 ElementHandle，请改用 Locator 对象和 Web-first 断言。

该方法在框架内查找与指定选择器匹配的元素。如果没有任何元素与选择器匹配，则返回 null。

用法

await frame.$(selector);
await frame.$(selector, options);

参数

selector 字符串 #

要查询的选择器。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。

返回值

Promise<null | ElementHandle>#

$$

新增于：v1.9

frame.$$

不推荐

请改用基于定位器的 frame.locator()。阅读更多关于定位器的信息。

返回指向框架元素的 ElementHandles。

注意

不建议使用 ElementHandle，请改用 Locator 对象。

该方法在框架内查找所有与指定选择器匹配的元素。如果没有任何元素与选择器匹配，则返回空数组。

用法

await frame.$$(selector);

参数

selector 字符串 #

要查询的选择器。

返回值

Promise<数组<ElementHandle>>#

$eval

新增于：v1.9

frame.$eval

不推荐

此方法不会等待元素通过可操作性检查，因此可能导致测试不稳定。请改用 locator.evaluate()、其他 Locator 辅助方法或 Web-first 断言。

返回 pageFunction 的返回值。

该方法在框架内查找与指定选择器匹配的元素，并将其作为第一个参数传递给 pageFunction。如果没有任何元素与选择器匹配，则该方法会抛出错误。

如果 pageFunction 返回一个 Promise，则 frame.$eval() 将等待 Promise 解析并返回其值。

用法

const searchValue = await frame.$eval('#search', el => el.value);
const preloadHref = await frame.$eval('link[rel=preload]', el => el.href);
const html = await frame.$eval('.main-container', (e, suffix) => e.outerHTML + suffix, 'hello');

参数

selector 字符串 #

要查询的选择器。
pageFunction 函数(元素) | 字符串 #

在页面上下文中要执行的函数。
arg EvaluationArgument (可选)#

要传递给 pageFunction 的可选参数。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。

返回值

Promise<可序列化>#

$$eval

新增于：v1.9

frame.$$eval

不推荐

在大多数情况下，locator.evaluateAll()、其他 Locator 辅助方法和 Web-first 断言可以更好地完成工作。

返回 pageFunction 的返回值。

该方法在框架内查找所有与指定选择器匹配的元素，并将匹配元素的数组作为第一个参数传递给 pageFunction。

如果 pageFunction 返回一个 Promise，则 frame.$$eval() 将等待 Promise 解析并返回其值。

用法

const divsCounts = await frame.$$eval('div', (divs, min) => divs.length >= min, 10);

参数

selector 字符串 #

要查询的选择器。
pageFunction 函数(数组<元素>) | 字符串 #

在页面上下文中要执行的函数。
arg EvaluationArgument (可选)#

要传递给 pageFunction 的可选参数。

返回值

Promise<可序列化>#

check

在 v1.9 之前添加

frame.check

不推荐

请改用基于定位器的 locator.check()。阅读更多关于定位器的信息。

此方法通过执行以下步骤来检查与 selector 匹配的元素

查找与 selector 匹配的元素。如果没有，则等待匹配的元素附加到 DOM。
确保匹配的元素是复选框或单选按钮输入。如果不是，则此方法会抛出错误。如果元素已选中，则此方法会立即返回。
等待匹配元素上的可操作性检查，除非设置了 force 选项。如果元素在检查期间分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.mouse 点击元素的中心。
确保元素现在已选中。如果不是，则此方法会抛出错误。

如果所有步骤组合在指定的 timeout 内未完成，则此方法会抛出 TimeoutError。传递零超时将禁用此功能。

用法

await frame.check(selector);
await frame.check(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- force 布尔值 (可选)#
  
  是否绕过可操作性检查。默认为 false。
- noWaitAfter 布尔值 (可选)#
  
  已弃用
  此选项无效。
  
  此选项无效。
- position 对象 (可选)新增于：v1.11#
  - x 数字
  - y 数字
  相对于元素填充盒左上角的一个点。如果未指定，则使用元素的某个可见点。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
- trial 布尔值 (可选)新增于：v1.11#
  
  设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于在元素准备好执行操作之前等待，而无需执行它。

返回值

Promise<void>#

click

在 v1.9 之前添加

frame.click

不推荐

请改用基于定位器的 locator.click()。了解更多关于定位器的信息。

此方法通过执行以下步骤来点击与选择器匹配的元素

查找与选择器匹配的元素。如果没有找到，则等待匹配的元素附加到 DOM。
等待匹配元素上的可操作性检查，除非设置了 force 选项。如果在检查期间元素被分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.mouse 点击元素的中心，或指定的位置。
等待已启动的导航成功或失败，除非设置了 noWaitAfter 选项。

如果所有步骤组合在指定的超时时间内未完成，则此方法将抛出 TimeoutError。传递零超时将禁用此功能。

用法

await frame.click(selector);
await frame.click(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- button "left" | "right" | "middle" (可选)#
  
  默认为 left。
- clickCount 数字 (可选)#
  
  默认为 1。参见 UIEvent.detail。
- delay 数字 (可选)#
  
  在毫秒内等待 mousedown 和 mouseup 之间的时间。默认为 0。
- force 布尔值 (可选)#
  
  是否绕过可操作性检查。默认为 false。
- modifiers 数组<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (可选)#
  
  要按下的修饰键。确保在操作期间仅按下这些修饰键，然后恢复当前修饰键。如果未指定，则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control"，在 macOS 上解析为 "Meta"。
- noWaitAfter 布尔值 (可选)#
  
  已弃用
  此选项将来将默认为 true。
  
  启动导航的操作将等待这些导航发生并等待页面开始加载。您可以通过设置此标志选择退出等待。您只需要在特殊情况下使用此选项，例如导航到不可访问的页面。默认为 false。
- position 对象 (可选)#
  - x 数字
  - y 数字
  相对于元素填充盒左上角的一个点。如果未指定，则使用元素的某个可见点。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
- trial 布尔值 (可选)新增于：v1.11#
  
  设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于在不执行操作的情况下等待元素准备好执行操作。请注意，无论 trial 如何，键盘 modifiers 都会被按下，以允许测试仅在按下这些键时才可见的元素。

返回值

Promise<void>#

dblclick

在 v1.9 之前添加

frame.dblclick

不推荐

请改用基于定位器的 locator.dblclick()。了解更多关于定位器的信息。

此方法通过执行以下步骤来双击与选择器匹配的元素

查找与选择器匹配的元素。如果没有找到，则等待匹配的元素附加到 DOM。
等待匹配元素上的可操作性检查，除非设置了 force 选项。如果在检查期间元素被分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.mouse 双击元素的中心，或指定的位置。如果 dblclick() 的第一次点击触发导航事件，则此方法将抛出错误。

如果所有步骤组合在指定的超时时间内未完成，则此方法将抛出 TimeoutError。传递零超时将禁用此功能。

注意

frame.dblclick() 分派两个 click 事件和一个 dblclick 事件。

用法

await frame.dblclick(selector);
await frame.dblclick(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- button "left" | "right" | "middle" (可选)#
  
  默认为 left。
- delay 数字 (可选)#
  
  在毫秒内等待 mousedown 和 mouseup 之间的时间。默认为 0。
- force 布尔值 (可选)#
  
  是否绕过可操作性检查。默认为 false。
- modifiers 数组<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (可选)#
  
  要按下的修饰键。确保在操作期间仅按下这些修饰键，然后恢复当前修饰键。如果未指定，则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control"，在 macOS 上解析为 "Meta"。
- noWaitAfter 布尔值 (可选)#
  
  已弃用
  此选项无效。
  
  此选项无效。
- position 对象 (可选)#
  - x 数字
  - y 数字
  相对于元素填充盒左上角的一个点。如果未指定，则使用元素的某个可见点。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
- trial 布尔值 (可选)新增于：v1.11#
  
  设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于在不执行操作的情况下等待元素准备好执行操作。请注意，无论 trial 如何，键盘 modifiers 都会被按下，以允许测试仅在按下这些键时才可见的元素。

返回值

Promise<void>#

dispatchEvent

在 v1.9 之前添加

frame.dispatchEvent

不推荐

请改用基于定位器的 locator.dispatchEvent()。了解更多关于定位器的信息。

以下代码片段在元素上分派 click 事件。无论元素的可见性状态如何，都会分派 click。这等效于调用 element.click()。

用法

await frame.dispatchEvent('button#submit', 'click');

在底层，它根据给定的类型创建一个事件实例，使用 eventInit 属性对其进行初始化，并在元素上分派它。事件默认为 composed、cancelable 和冒泡。

由于 eventInit 是特定于事件的，请参阅事件文档以获取初始属性列表

如果希望将实时对象传递到事件中，您还可以将 JSHandle 指定为属性值

// Note you can only create DataTransfer in Chromium and Firefox
const dataTransfer = await frame.evaluateHandle(() => new DataTransfer());
await frame.dispatchEvent('#source', 'dragstart', { dataTransfer });

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
type 字符串 #

DOM 事件类型："click"、"dragstart" 等。
eventInit 评估参数 (可选)#

可选的特定于事件的初始化属性。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<void>#

fill

在 v1.9 之前添加

frame.fill

不推荐

请改用基于定位器的 locator.fill()。了解更多关于定位器的信息。

此方法等待与选择器匹配的元素，等待可操作性检查，聚焦该元素，填充它并在填充后触发一个input事件。请注意，您可以传递一个空字符串来清除输入字段。

如果目标元素不是<input>、<textarea>或[contenteditable]元素，则此方法会抛出错误。但是，如果元素位于具有关联控件的<label>元素内，则将填充该控件。

要发送细粒度的键盘事件，请使用locator.pressSequentially()。

用法

await frame.fill(selector, value);
await frame.fill(selector, value, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
value 字符串 #

要为<input>、<textarea>或[contenteditable]元素填充的值。
options 对象 （可选）
- force 布尔值 (可选)在以下版本中添加：v1.13#
  
  是否绕过可操作性检查。默认为 false。
- noWaitAfter 布尔值 (可选)#
  
  已弃用
  此选项无效。
  
  此选项无效。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<void>#

focus

在 v1.9 之前添加

frame.focus

不推荐

请改用基于定位器的locator.focus()。详细了解定位器。

此方法使用选择器获取元素并聚焦它。如果没有与选择器匹配的元素，则该方法会等待直到 DOM 中出现匹配的元素。

用法

await frame.focus(selector);
await frame.focus(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<void>#

getAttribute

在 v1.9 之前添加

frame.getAttribute

不推荐

请改用基于定位器的locator.getAttribute()。详细了解定位器。

返回元素属性值。

用法

await frame.getAttribute(selector, name);
await frame.getAttribute(selector, name, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
name 字符串 #

要获取值的属性名称。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<null | 字符串>#

hover

在 v1.9 之前添加

frame.hover

不推荐

请改用基于定位器的locator.hover()。详细了解定位器。

此方法通过执行以下步骤将鼠标悬停在与选择器匹配的元素上

查找与选择器匹配的元素。如果没有，则等待直到将匹配的元素附加到 DOM。
等待对匹配元素进行可操作性检查，除非设置了force选项。如果在检查期间元素分离，则会重试整个操作。
如果需要，将元素滚动到视图中。
使用page.mouse将鼠标悬停在元素的中心或指定的位置上。

当所有步骤组合在指定的超时期间未完成时，此方法会抛出TimeoutError。传递零超时将禁用此功能。

用法

await frame.hover(selector);
await frame.hover(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- force 布尔值 (可选)#
  
  是否绕过可操作性检查。默认为 false。
- modifiers 数组<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (可选)#
  
  要按下的修饰键。确保在操作期间仅按下这些修饰键，然后恢复当前修饰键。如果未指定，则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control"，在 macOS 上解析为 "Meta"。
- noWaitAfter 布尔值 (可选)新增于：v1.28#
  
  已弃用
  此选项无效。
  
  此选项无效。
- position 对象 (可选)#
  - x 数字
  - y 数字
  相对于元素填充盒左上角的一个点。如果未指定，则使用元素的某个可见点。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
- trial 布尔值 (可选)新增于：v1.11#
  
  设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于在不执行操作的情况下等待元素准备好执行操作。请注意，无论 trial 如何，键盘 modifiers 都会被按下，以允许测试仅在按下这些键时才可见的元素。

返回值

Promise<void>#

innerHTML

在 v1.9 之前添加

frame.innerHTML

不推荐

请改用基于定位器的locator.innerHTML()。详细了解定位器。

返回element.innerHTML。

用法

await frame.innerHTML(selector);
await frame.innerHTML(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<字符串>#

innerText

在 v1.9 之前添加

frame.innerText

不推荐

请改用基于定位器的locator.innerText()。详细了解定位器。

返回element.innerText。

用法

await frame.innerText(selector);
await frame.innerText(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<字符串>#

inputValue

在以下版本中添加：v1.13

frame.inputValue

不推荐

请改用基于定位器的locator.inputValue()。详细了解定位器。

返回所选<input>或<textarea>或<select>元素的input.value。

对于非输入元素会抛出错误。但是，如果元素位于具有关联控件的<label>元素内，则返回该控件的值。

用法

await frame.inputValue(selector);
await frame.inputValue(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<字符串>#

isChecked

在 v1.9 之前添加

frame.isChecked

不推荐

请改用基于定位器的locator.isChecked()。详细了解定位器。

返回元素是否被选中。如果元素不是复选框或单选按钮输入，则抛出错误。

用法

await frame.isChecked(selector);
await frame.isChecked(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<布尔值>#

isDisabled

在 v1.9 之前添加

frame.isDisabled

不推荐

请改用基于定位器的 locator.isDisabled()。了解更多关于定位器的信息。

返回元素是否被禁用，与启用相反。

用法

await frame.isDisabled(selector);
await frame.isDisabled(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<布尔值>#

isEditable

在 v1.9 之前添加

frame.isEditable

不推荐

请改用基于定位器的 locator.isEditable()。了解更多关于定位器的信息。

返回元素是否可编辑。

用法

await frame.isEditable(selector);
await frame.isEditable(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<布尔值>#

isHidden

在 v1.9 之前添加

frame.isHidden

不推荐

请改用基于定位器的 locator.isHidden()。了解更多关于定位器的信息。

返回元素是否隐藏，与可见相反。不匹配任何元素的 selector 被认为是隐藏的。

用法

await frame.isHidden(selector);
await frame.isHidden(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  已弃用
  此选项被忽略。 frame.isHidden() 不会等待元素变为隐藏状态，并立即返回。

返回值

Promise<布尔值>#

isVisible

在 v1.9 之前添加

frame.isVisible

不推荐

请改用基于定位器的 locator.isVisible()。了解更多关于定位器的信息。

返回元素是否可见。不匹配任何元素的 selector 被认为是不可见的。

用法

await frame.isVisible(selector);
await frame.isVisible(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  已弃用
  此选项被忽略。 frame.isVisible() 不会等待元素变为可见状态，并立即返回。

返回值

Promise<布尔值>#

press

在 v1.9 之前添加

frame.press

不推荐

请改用基于定位器的 locator.press()。了解更多关于定位器的信息。

key 可以指定预期的 keyboardEvent.key 值或单个字符以生成文本。可以在此处找到 key 值的超集。键的示例包括

F1 - F12、Digit0- Digit9、KeyA- KeyZ、Backquote、Minus、Equal、Backslash、Backspace、Tab、Delete、Escape、ArrowDown、End、Enter、Home、Insert、PageDown、PageUp、ArrowRight、ArrowUp 等。

以下修改快捷方式也受支持：Shift、Control、Alt、Meta、ShiftLeft、ControlOrMeta。ControlOrMeta 在 Windows 和 Linux 上解析为 Control，在 macOS 上解析为 Meta。

按住 Shift 将以大写形式键入与 key 对应的文本。

如果 key 是单个字符，则区分大小写，因此值 a 和 A 将分别生成不同的文本。

也支持 key: "Control+o"、key: "Control++ 或 key: "Control+Shift+T" 等快捷方式。当与修饰符一起指定时，修饰符会被按下并保持按住状态，同时按下后续键。

用法

await frame.press(selector, key);
await frame.press(selector, key, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
key 字符串 #

要按下的键的名称或要生成的字符，例如 ArrowLeft 或 a。
options 对象 （可选）
- delay 数字 (可选)#
  
  在 keydown 和 keyup 之间等待的时间（以毫秒为单位）。默认为 0。
- noWaitAfter 布尔值 (可选)#
  
  已弃用
  此选项将来将默认为 true。
  
  启动导航的操作将等待这些导航发生并等待页面开始加载。您可以通过设置此标志选择退出等待。您只需要在特殊情况下使用此选项，例如导航到不可访问的页面。默认为 false。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<void>#

selectOption

在 v1.9 之前添加

frame.selectOption

不推荐

请改用基于定位器的 locator.selectOption()。了解更多关于定位器的信息。

此方法等待匹配 selector 的元素，等待可操作性检查，等待 <select> 元素中所有指定的选项出现，然后选择这些选项。

如果目标元素不是 <select> 元素，则此方法会抛出错误。但是，如果元素位于具有关联 control 的 <label> 元素内，则将使用该 control。

返回已成功选择的选项值的数组。

在所有提供的选项都已选择后，触发 change 和 input 事件。

用法

// Single selection matching the value or label
frame.selectOption('select#colors', 'blue');

// single selection matching both the value and the label
frame.selectOption('select#colors', { label: 'Blue' });

// multiple selection
frame.selectOption('select#colors', 'red', 'green', 'blue');

参数

selector 字符串 #

要查询的选择器。
values null | 字符串 | ElementHandle | 数组<字符串> | 对象 | 数组<ElementHandle> | 数组<对象>#
- value 字符串 (可选)
  
  根据 option.value 匹配。可选。
- label 字符串 (可选)
  
  根据option.label匹配。可选。
- index 数字 (可选)
  
  根据索引匹配。可选。
要选择的选项。如果<select>具有multiple属性，则选择所有匹配的选项，否则仅选择匹配传递选项之一的第一个选项。字符串值匹配值和标签。如果所有指定的属性都匹配，则认为选项匹配。
options 对象 （可选）
- force 布尔值 (可选)在以下版本中添加：v1.13#
  
  是否绕过可操作性检查。默认为 false。
- noWaitAfter 布尔值 (可选)#
  
  已弃用
  此选项无效。
  
  此选项无效。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<数组<字符串>>#

setChecked

新增于：v1.15

frame.setChecked

不推荐

请改用基于定位器的 locator.setChecked()。详细了解定位器。

此方法通过执行以下步骤来选中或取消选中与选择器匹配的元素

查找与选择器匹配的元素。如果没有，则等待匹配的元素附加到 DOM。
确保匹配的元素是复选框或单选按钮输入。如果不是，此方法将抛出错误。
如果元素已具有正确的选中状态，则此方法立即返回。
等待匹配元素上的可操作性检查，除非设置了 force 选项。如果元素在检查期间分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.mouse 点击元素的中心。
确保元素现在已选中或取消选中。如果不是，此方法将抛出错误。

当所有步骤组合在指定的超时时间内未完成时，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

用法

await frame.setChecked(selector, checked);
await frame.setChecked(selector, checked, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
checked 布尔值 #

是否选中或取消选中复选框。
options 对象 （可选）
- force 布尔值 (可选)#
  
  是否绕过可操作性检查。默认为 false。
- noWaitAfter 布尔值 (可选)#
  
  已弃用
  此选项无效。
  
  此选项无效。
- position 对象 (可选)#
  - x 数字
  - y 数字
  相对于元素填充盒左上角的一个点。如果未指定，则使用元素的某个可见点。
- strict 布尔值 (可选)#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
- trial 布尔值 (可选)#
  
  设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于在元素准备好执行操作之前等待，而无需执行它。

返回值

Promise<void>#

setInputFiles

在 v1.9 之前添加

frame.setInputFiles

不推荐

请改用基于定位器的 locator.setInputFiles()。详细了解定位器。

将文件输入的值设置为这些文件路径或文件。如果一些filePaths是相对路径，则相对于当前工作目录解析它们。对于空数组，清除选定的文件。

此方法期望选择器指向输入元素。但是，如果元素位于具有关联控制的<label>元素内，则改为定位控制。

用法

await frame.setInputFiles(selector, files);
await frame.setInputFiles(selector, files, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
files 字符串 | 数组<字符串> | 对象 | 数组<对象>#
- name 字符串
  
  文件名
- mimeType 字符串
  
  文件类型
- buffer Buffer
  
  文件内容
options 对象 （可选）
- noWaitAfter 布尔值 (可选)#
  
  已弃用
  此选项无效。
  
  此选项无效。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<void>#

tap

在 v1.9 之前添加

frame.tap

不推荐

请改用基于定位器的 locator.tap()。详细了解定位器。

此方法通过执行以下步骤来点击与选择器匹配的元素

查找与选择器匹配的元素。如果没有，则等待匹配的元素附加到 DOM。
等待匹配元素上的可操作性检查，除非设置了 force 选项。如果元素在检查期间分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.touchscreen 点击元素的中心或指定的位置。

当所有步骤组合在指定的超时时间内未完成时，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

注意

frame.tap() 要求浏览器上下文的hasTouch选项设置为true。

用法

await frame.tap(selector);
await frame.tap(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- force 布尔值 (可选)#
  
  是否绕过可操作性检查。默认为 false。
- modifiers 数组<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (可选)#
  
  要按下的修饰键。确保在操作期间仅按下这些修饰键，然后恢复当前修饰键。如果未指定，则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control"，在 macOS 上解析为 "Meta"。
- noWaitAfter 布尔值 (可选)#
  
  已弃用
  此选项无效。
  
  此选项无效。
- position 对象 (可选)#
  - x 数字
  - y 数字
  相对于元素填充盒左上角的一个点。如果未指定，则使用元素的某个可见点。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
- trial 布尔值 (可选)新增于：v1.11#
  
  设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于在不执行操作的情况下等待元素准备好执行操作。请注意，无论 trial 如何，键盘 modifiers 都会被按下，以允许测试仅在按下这些键时才可见的元素。

返回值

Promise<void>#

textContent

在 v1.9 之前添加

frame.textContent

不推荐

请改用基于定位器的 locator.textContent()。详细了解定位器。

返回element.textContent。

用法

await frame.textContent(selector);
await frame.textContent(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<null | 字符串>#

type

在 v1.9 之前添加

frame.type

已弃用

在大多数情况下，您应该使用 locator.fill() 代替。只有当页面上有特殊的键盘处理时，您才需要逐个按下键 - 在这种情况下，使用 locator.pressSequentially()。

为文本中的每个字符发送 keydown、keypress/input 和 keyup 事件。frame.type 可用于发送细粒度的键盘事件。要填充表单字段中的值，请使用 frame.fill()。

要按下特殊键，如 Control 或 ArrowDown，请使用 keyboard.press()。

用法

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
text 字符串 #

要输入到聚焦元素中的文本。
options 对象 （可选）
- delay 数字 (可选)#
  
  键击之间等待的时间（毫秒）。默认为 0。
- noWaitAfter 布尔值 (可选)#
  
  已弃用
  此选项无效。
  
  此选项无效。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<void>#

取消选中

在 v1.9 之前添加

frame.uncheck

不推荐

使用基于定位器的 locator.uncheck() 代替。阅读更多关于定位器的信息。

此方法通过执行以下步骤来选中与 selector 匹配的元素

查找与 selector 匹配的元素。如果没有，则等待将匹配的元素附加到 DOM。
确保匹配的元素是复选框或单选输入。如果不是，此方法将抛出错误。如果元素已取消选中，则此方法立即返回。
等待对匹配元素的可操作性检查，除非设置了 force 选项。如果在检查期间元素被分离，则整个操作将重试。
如果需要，将元素滚动到视图中。
使用 page.mouse 点击元素的中心。
确保元素现在已取消选中。如果不是，此方法将抛出错误。

当所有步骤组合在指定的 timeout 内未完成时，此方法将抛出 TimeoutError。传递零超时将禁用此功能。

用法

await frame.uncheck(selector);
await frame.uncheck(selector, options);

参数

selector 字符串 #

用于搜索元素的选择器。如果有多个元素满足选择器，则使用第一个。
options 对象 （可选）
- force 布尔值 (可选)#
  
  是否绕过可操作性检查。默认为 false。
- noWaitAfter 布尔值 (可选)#
  
  已弃用
  此选项无效。
  
  此选项无效。
- position 对象 (可选)新增于：v1.11#
  - x 数字
  - y 数字
  相对于元素填充盒左上角的一个点。如果未指定，则使用元素的某个可见点。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。
- trial 布尔值 (可选)新增于：v1.11#
  
  设置后，此方法仅执行可操作性检查并跳过操作。默认为 false。用于在元素准备好执行操作之前等待，而无需执行它。

返回值

Promise<void>#

在 v1.9 之前添加

frame.waitForNavigation

已弃用

此方法本质上是竞争条件，请改用 frame.waitForURL()。

等待框架导航并返回主资源响应。如果发生多次重定向，则导航将解析为最后一次重定向的响应。如果导航到不同的锚点或由于历史记录 API 使用而导致的导航，则导航将解析为 null。

用法

此方法等待框架导航到新的 URL。当您运行将间接导致框架导航的代码时，这很有用。请考虑以下示例

// Start waiting for navigation before clicking. Note no await.
const navigationPromise = page.waitForNavigation();
await page.getByText('Navigate after timeout').click();
await navigationPromise;

注意

使用历史记录 API 更改 URL 被视为导航。

参数

options 对象 （可选）
- timeout 数字 (可选)#
  
  以毫秒为单位的最大操作时间。默认为 0 - 无超时。默认值可以通过配置中的 navigationTimeout 选项更改，或者使用 browserContext.setDefaultNavigationTimeout()、browserContext.setDefaultTimeout()、page.setDefaultNavigationTimeout() 或 page.setDefaultTimeout() 方法更改。
- url 字符串 | 正则表达式 | 函数(URL):布尔值 (可选)#
  
  一个 glob 模式、正则表达式模式或接收 URL 的断言函数，用于在等待导航时进行匹配。请注意，如果参数是没有任何通配符的字符串，则该方法将等待导航到与该字符串完全相同的 URL。
- waitUntil "load" | "domcontentloaded" | "networkidle" | "commit" (可选)#
  
  何时认为操作成功，默认为 load。事件可以是：
  - 'domcontentloaded' - 当触发 DOMContentLoaded 事件时，认为操作已完成。
  - 'load' - 当触发 load 事件时，认为操作已完成。
  - 'networkidle' - 不建议使用 当至少 500 毫秒内没有网络连接时，认为操作已完成。不要将此方法用于测试，而是依靠 Web 断言来评估就绪状态。
  - 'commit' - 当收到网络响应并开始加载文档时，认为操作已完成。

返回值

Promise<null | Response>#

waitForSelector

在 v1.9 之前添加

frame.waitForSelector

不推荐

使用断言可见性或基于定位器的 locator.waitFor() 代替。阅读更多关于定位器的信息。

当由 selector 指定的元素满足 state 选项时返回。如果等待 hidden 或 detached，则返回 null。

注意

Playwright 会自动等待元素准备好后再执行操作。使用 Locator 对象和 Web 首要断言使代码无需等待 selector。

等待 selector 满足 state 选项（出现在 DOM 中/从 DOM 中消失，或变得可见/隐藏）。如果在调用方法时 selector 已经满足条件，则该方法将立即返回。如果 selector 在 timeout 毫秒内不满足条件，则该函数将抛出错误。

用法

此方法跨导航工作

const { chromium } = require('playwright');  // Or 'firefox' or 'webkit'.

(async () => {
  const browser = await chromium.launch();
  const page = await browser.newPage();
  for (const currentURL of ['https://google.com', 'https://bbc.com']) {
    await page.goto(currentURL);
    const element = await page.mainFrame().waitForSelector('img');
    console.log('Loaded image: ' + await element.getAttribute('src'));
  }
  await browser.close();
})();

参数

selector 字符串 #

要查询的选择器。
options 对象 （可选）
- state "attached" | "detached" | "visible" | "hidden" (可选)#
  
  默认为 'visible'。可以是：
  - 'attached' - 等待元素出现在 DOM 中。
  - 'detached' - 等待元素不在 DOM 中。
  - 'visible' - 等待元素具有非空边界框且没有 visibility:hidden。请注意，没有任何内容或具有 display:none 的元素具有空边界框，不被视为可见。
  - 'hidden' - 等待元素从 DOM 中分离，或具有空边界框或 visibility:hidden。这与 'visible' 选项相反。
- strict 布尔值 （可选）在以下版本中添加：v1.14#
  
  如果为真，则调用需要选择器解析为单个元素。如果给定的选择器解析为多个元素，则调用会抛出异常。
- timeout 数字 (可选)#
  
  以毫秒为单位的最大时间。默认为 0 - 无超时。默认值可以通过配置中的 actionTimeout 选项更改，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法更改。

返回值

Promise<null | ElementHandle>#

waitForTimeout

在 v1.9 之前添加

frame.waitForTimeout

不推荐

永远不要在生产环境中等待超时。等待时间的测试本质上是不稳定的。使用 Locator 操作和自动等待的 Web 断言。

等待给定的 timeout（毫秒）。

请注意，frame.waitForTimeout() 仅应用于调试。在生产环境中使用计时器的测试将是不稳定的。请改用网络事件、选择器变得可见等信号。

用法

await frame.waitForTimeout(timeout);

参数

timeout 数字 #

要等待的超时时间

返回值

Promise<void>#

方法​

addScriptTag​

addStyleTag​

childFrames​

content​

dragAndDrop​

评估​

evaluateHandle​

frameElement​

frameLocator​

getByAltText​

getByLabel​

getByPlaceholder​

getByRole​

getByTestId​

getByText​

getByTitle​

goto​

isDetached​

isEnabled​

定位器​

名称​

页面​

父框架​

设置内容​

标题​

网址​

等待函数​

等待加载状态​

waitForURL​

已弃用​

$​

$$​

$eval​

$$eval​

check​

click​

dblclick​

dispatchEvent​

fill​

focus​

getAttribute​

hover​

innerHTML​

innerText​

inputValue​

isChecked​

isDisabled​

isEditable​

isHidden​

isVisible​

press​

selectOption​

setChecked​

setInputFiles​

tap​

textContent​

type​

取消选中​

waitForNavigation​

waitForSelector​

waitForTimeout​

方法

addScriptTag

addStyleTag

childFrames

content

dragAndDrop

评估

evaluateHandle

frameElement

frameLocator

getByAltText

getByLabel

getByPlaceholder

getByRole

getByTestId

getByText

getByTitle

goto

isDetached

isEnabled

定位器

名称

页面

父框架

设置内容

标题

网址

等待函数

等待加载状态

waitForURL

已弃用

$

$$

$eval

$$eval

check

click

dblclick

dispatchEvent

fill

focus

getAttribute

hover

innerHTML

innerText

inputValue

isChecked

isDisabled

isEditable

isHidden

isVisible

press

selectOption

setChecked

setInputFiles

tap

textContent

type

取消选中

waitForNavigation

waitForSelector

waitForTimeout