Frame
在任何时候,页面都会通过 Page.mainFrame() 和 Frame.childFrames() 方法暴露其当前的框架树。
Frame 对象的生命周期由在页面对象上分发的三个事件控制。
- Page.onFrameAttached(handler) - 当框架附加到页面时触发。一个框架只能附加到页面一次。
- Page.onFrameNavigated(handler) - 当框架提交导航到不同 URL 时触发。
- Page.onFrameDetached(handler) - 当框架从页面分离时触发。一个框架只能从页面分离一次。
转储框架树的示例
import com.microsoft.playwright.*;
public class Example {
public static void main(String[] args) {
try (Playwright playwright = Playwright.create()) {
BrowserType firefox = playwright.firefox();
Browser browser = firefox.launch();
Page page = browser.newPage();
page.navigate("https://www.google.com/chrome/browser/canary.html");
dumpFrameTree(page.mainFrame(), "");
browser.close();
}
}
static void dumpFrameTree(Frame frame, String indent) {
System.out.println(indent + frame.url());
for (Frame child : frame.childFrames()) {
dumpFrameTree(child, indent + " ");
}
}
}
方法
addScriptTag
v1.9 之前添加当脚本的 onload 事件触发或脚本内容注入到框架中时,返回添加的标签。
将带有所需 url 或内容的 <script>
标签添加到页面中。
用法
Frame.addScriptTag();
Frame.addScriptTag(options);
参数
options
Frame.AddScriptTagOptions
(可选)
返回
addStyleTag
v1.9 之前添加当样式表的 onload 事件触发或 CSS 内容注入到框架中时,返回添加的标签。
将带有所需 url 的 <link rel="stylesheet">
标签或带有内容的 <style type="text/css">
标签添加到页面中。
用法
Frame.addStyleTag();
Frame.addStyleTag(options);
参数
options
Frame.AddStyleTagOptions
(可选)
返回
childFrames
v1.9 之前添加用法
Frame.childFrames();
返回
content
v1.9 之前添加获取框架的完整 HTML 内容,包括 doctype。
用法
Frame.content();
返回
dragAndDrop
添加于:v1.13用法
Frame.dragAndDrop(source, target);
Frame.dragAndDrop(source, target, options);
参数
-
用于搜索要拖动的元素的选择器。如果有多个元素满足选择器,将使用第一个。
-
用于搜索要拖放到的元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.DragAndDropOptions
(可选)-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
setSourcePosition
SourcePosition (可选)新增于:v1.14#在此点(相对于元素内边距框的左上角)点击源元素。如果未指定,则使用元素的某个可见点。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
setTargetPosition
TargetPosition (可选)新增于:v1.14#在此点(相对于元素内边距框的左上角)拖放到目标元素。如果未指定,则使用元素的某个可见点。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。用于等待元素准备好执行操作而无需实际执行。
-
返回
evaluate
v1.9 之前添加返回 expression 的返回值。
如果传递给 Frame.evaluate() 的函数返回一个 Promise,那么 Frame.evaluate() 将等待该 Promise 解析并返回其值。
如果传递给 Frame.evaluate() 的函数返回一个不可 序列化 的值,那么 Frame.evaluate() 返回 undefined
。Playwright 还支持传输一些不能被 JSON
序列化的额外值:-0
、NaN
、Infinity
、-Infinity
。
用法
Object result = frame.evaluate("([x, y]) => {\n" +
" return Promise.resolve(x * y);\n" +
"}", Arrays.asList(7, 8));
System.out.println(result); // prints "56"
也可以传入字符串而不是函数。
System.out.println(frame.evaluate("1 + 2")); // prints "3"
ElementHandle 实例可以作为参数传递给 Frame.evaluate()
ElementHandle bodyHandle = frame.evaluate("document.body");
String html = (String) frame.evaluate("([body, suffix]) => body.innerHTML + suffix", Arrays.asList(bodyHandle, "hello"));
bodyHandle.dispose();
参数
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument (可选)#要传递给 expression 的可选参数。
返回
evaluateHandle
v1.9 之前添加将 expression 的返回值作为 JSHandle 返回。
Frame.evaluate() 和 Frame.evaluateHandle() 唯一的区别是 Frame.evaluateHandle() 返回 JSHandle。
如果传递给 Frame.evaluateHandle() 的函数返回一个 Promise,那么 Frame.evaluateHandle() 将等待该 Promise 解析并返回其值。
用法
// Handle for the window object.
JSHandle aWindowHandle = frame.evaluateHandle("() => Promise.resolve(window)");
也可以传入字符串而不是函数。
JSHandle aHandle = frame.evaluateHandle("document"); // Handle for the "document".
JSHandle 实例可以作为参数传递给 Frame.evaluateHandle()
JSHandle aHandle = frame.evaluateHandle("() => document.body");
JSHandle resultHandle = frame.evaluateHandle("([body, suffix]) => body.innerHTML + suffix", Arrays.asList(aHandle, "hello"));
System.out.println(resultHandle.jsonValue());
resultHandle.dispose();
参数
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument (可选)#要传递给 expression 的可选参数。
返回
frameElement
v1.9 之前添加返回与此框架对应的 frame
或 iframe
元素句柄。
这是 ElementHandle.contentFrame() 的反操作。请注意,返回的句柄实际上属于父框架。
如果框架在 frameElement()
返回之前已分离,则此方法会抛出错误。
用法
ElementHandle frameElement = frame.frameElement();
Frame contentFrame = frameElement.contentFrame();
System.out.println(frame == contentFrame); // -> true
返回
frameLocator
新增于: v1.17使用 iframe 时,您可以创建一个框架定位器,它将进入 iframe 并允许选择 iframe 中的元素。
用法
以下代码片段在 id 为 my-frame
的 iframe 中查找文本为“提交”的元素,例如 <iframe id="my-frame">
Locator locator = frame.frameLocator("#my-iframe").getByText("Submit");
locator.click();
参数
返回
getByAltText
新增于:v1.27允许根据元素的 alt 文本定位元素。
用法
例如,此方法将通过 alt 文本“Playwright logo”找到图像
<img alt='Playwright logo'>
page.getByAltText("Playwright logo").click();
参数
-
用于定位元素的文本。
-
options
Frame.GetByAltTextOptions
(可选)
返回
getByLabel
新增于:v1.27允许通过关联的 <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");
参数
-
用于定位元素的文本。
-
options
Frame.GetByLabelOptions
(可选)
返回
getByPlaceholder
新增于:v1.27允许通过占位符文本定位输入元素。
用法
例如,考虑以下 DOM 结构。
<input type="email" placeholder="name@example.com" />
您可以按占位符文本定位输入框后填充它
page.getByPlaceholder("name@example.com").fill("playwright@microsoft.com");
参数
-
用于定位元素的文本。
-
options
Frame.GetByPlaceholderOptions
(可选)
返回
getByRole
新增于:v1.27允许通过元素的 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
枚举 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
Frame.GetByRoleOptions
(可选)-
通常由
aria-checked
或原生<input type=checkbox>
控件设置的属性。了解更多关于
aria-checked
的信息。 -
通常由
aria-disabled
或disabled
设置的属性。注意与大多数其他属性不同,
disabled
在 DOM 层次结构中是继承的。了解更多关于aria-disabled
的信息。 -
setExact
boolean (可选)新增于: v1.28#setName 是否完全匹配:区分大小写和完整字符串。默认为 false。当 setName 是正则表达式时忽略。请注意,精确匹配仍会去除空格。
-
通常由
aria-expanded
设置的属性。了解更多关于
aria-expanded
的信息。 -
控制是否匹配隐藏元素的选项。默认情况下,只有非隐藏元素(由 ARIA 定义)由角色选择器匹配。
了解更多关于
aria-hidden
的信息。 -
通常用于角色
heading
、listitem
、row
、treeitem
的数字属性,<h1>-<h6>
元素具有默认值。了解更多关于
aria-level
的信息。 -
匹配 可访问名称 的选项。默认情况下,匹配不区分大小写并搜索子字符串,使用 setExact 控制此行为。
了解更多关于 可访问名称 的信息。
-
通常由
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 定位元素
page.getByTestId("directions").click();
参数
返回
详情
默认情况下,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 Page.GetByTextOptions().setExact(true));
// Matches both <div>s
page.getByText(Pattern.compile("Hello"));
// Matches second <div>
page.getByText(Pattern.compile("^hello$", Pattern.CASE_INSENSITIVE));
参数
-
用于定位元素的文本。
-
options
Frame.GetByTextOptions
(可选)
返回
详情
按文本匹配始终会规范化空格,即使是精确匹配也是如此。例如,它会将多个空格转换为一个空格,将换行符转换为空格,并忽略前导和尾随空格。
类型为 button
和 submit
的输入元素通过其 value
而不是文本内容进行匹配。例如,通过文本 "登录"
定位匹配 <input type=button value="登录">
。
getByTitle
新增于:v1.27允许通过元素的 title 属性定位元素。
用法
考虑以下 DOM 结构。
<span title='Issues count'>25 issues</span>
您可以通过 title 文本定位它后检查问题数量
assertThat(page.getByTitle("Issues count")).hasText("25 issues");
参数
-
用于定位元素的文本。
-
options
Frame.GetByTitleOptions
(可选)
返回
isDetached
v1.9 之前添加如果框架已分离,则返回 true
,否则返回 false
。
用法
Frame.isDetached();
返回
isEnabled
v1.9 之前添加返回元素是否 启用。
用法
Frame.isEnabled(selector);
Frame.isEnabled(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.IsEnabledOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
locator
新增于:v1.14该方法返回一个元素定位器,可用于在此页面/框架上执行操作。定位器在执行操作前立即解析为元素,因此对同一定位器的一系列操作实际上可能在不同的 DOM 元素上执行。如果 DOM 结构在这些操作之间发生变化,就会发生这种情况。
用法
Frame.locator(selector);
Frame.locator(selector, options);
参数
-
用于解析 DOM 元素的选取器。
-
options
Frame.LocatorOptions
(可选)-
将方法的结果缩小到包含与此相对定位器匹配的元素的那些。例如,包含
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
字符串 | 模式 (可选)新增于:v1.33#匹配不包含指定文本(可能在子元素或后代元素中)的元素。当传递 字符串 时,匹配不区分大小写并搜索子字符串。
-
匹配包含指定文本(可能在子元素或后代元素中)的元素。当传递 字符串 时,匹配不区分大小写并搜索子字符串。例如,
"Playwright"
匹配<article><div>Playwright</div></article>
。
-
返回
name
v1.9 之前添加返回标签中指定的框架名称属性。
如果名称为空,则返回 id 属性。
此值在框架创建时计算一次,如果属性稍后更改,则不会更新。
用法
Frame.name();
返回
navigate
v1.9 之前添加返回主资源响应。如果发生多次重定向,导航将解析为最后一次重定向的响应。
此方法将在以下情况下抛出错误
- 存在 SSL 错误(例如自签名证书)。
- 目标 URL 无效。
- 导航期间超出 setTimeout。
- 远程服务器无响应或无法访问。
- 主资源加载失败。
当远程服务器返回任何有效的 HTTP 状态码时,该方法不会抛出错误,包括 404 "Not Found" 和 500 "Internal Server Error"。此类响应的状态码可以通过调用 Response.status() 获取。
该方法要么抛出错误,要么返回主资源响应。唯一的例外是导航到 about:blank
或导航到具有不同哈希的相同 URL,这将成功并返回 null
。
无头模式不支持导航到 PDF 文档。请参阅 上游问题。
用法
Frame.navigate(url);
Frame.navigate(url, options);
参数
-
要导航框架到的 URL。URL 应包含方案,例如
https://
。 -
options
Frame.NavigateOptions
(可选)-
Referer 标头值。如果提供,它将优先于 Page.setExtraHTTPHeaders() 设置的 referer 标头值。
-
最大操作时间,单位为毫秒,默认为 30 秒,传递
0
禁用超时。默认值可以通过 BrowserContext.setDefaultNavigationTimeout()、BrowserContext.setDefaultTimeout()、Page.setDefaultNavigationTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
setWaitUntil
枚举 WaitUntilState { LOAD, DOMCONTENTLOADED, NETWORKIDLE, COMMIT }
(可选)#何时认为操作成功,默认为
load
。事件可以是以下之一'domcontentloaded'
- 当DOMContentLoaded
事件触发时,认为操作完成。'load'
- 当load
事件触发时,认为操作完成。'networkidle'
- 不建议 当至少500
毫秒内没有网络连接时,认为操作完成。不要使用此方法进行测试,请改用 Web 断言来评估准备情况。'commit'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回
page
v1.9 之前添加返回包含此框架的页面。
用法
Frame.page();
返回
parentFrame
v1.9 之前添加父框架,如果有的话。分离的框架和主框架返回 null
。
用法
Frame.parentFrame();
返回
setContent
v1.9 之前添加此方法内部调用 document.write(),继承其所有特定特征和行为。
用法
Frame.setContent(html);
Frame.setContent(html, options);
参数
-
要分配给页面的 HTML 标记。
-
options
Frame.SetContentOptions
(可选)-
最大操作时间,单位为毫秒,默认为 30 秒,传递
0
禁用超时。默认值可以通过 BrowserContext.setDefaultNavigationTimeout()、BrowserContext.setDefaultTimeout()、Page.setDefaultNavigationTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
setWaitUntil
枚举 WaitUntilState { LOAD, DOMCONTENTLOADED, NETWORKIDLE, COMMIT }
(可选)#何时认为操作成功,默认为
load
。事件可以是以下之一'domcontentloaded'
- 当DOMContentLoaded
事件触发时,认为操作完成。'load'
- 当load
事件触发时,认为操作完成。'networkidle'
- 不建议 当至少500
毫秒内没有网络连接时,认为操作完成。不要使用此方法进行测试,请改用 Web 断言来评估准备情况。'commit'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回
title
v1.9 之前添加返回页面标题。
用法
Frame.title();
返回
url
v1.9 之前添加返回框架的 url。
用法
Frame.url();
返回
waitForFunction
v1.9 之前添加当 expression 返回一个真值时返回,并返回该值。
用法
Frame.waitForFunction() 可用于观察视口大小变化
import com.microsoft.playwright.*;
public class Example {
public static void main(String[] args) {
try (Playwright playwright = Playwright.create()) {
BrowserType firefox = playwright.firefox();
Browser browser = firefox.launch();
Page page = browser.newPage();
page.setViewportSize(50, 50);
page.mainFrame().waitForFunction("window.innerWidth < 100");
browser.close();
}
}
}
将参数传递给 frame.waitForFunction
函数的谓词
String selector = ".foo";
frame.waitForFunction("selector => !!document.querySelector(selector)", selector);
参数
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument (可选)#要传递给 expression 的可选参数。
-
options
Frame.WaitForFunctionOptions
(可选)-
setPollingInterval
双精度浮点数 (可选)#如果指定,则将其视为函数执行的毫秒间隔。默认情况下,如果未指定该选项,expression 将在
requestAnimationFrame
回调中执行。 -
最大等待时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
waitForLoadState
v1.9 之前添加等待达到所需的加载状态。
当框架达到所需的加载状态(默认为 load
)时返回。调用此方法时导航必须已提交。如果当前文档已达到所需状态,则立即解析。
大多数情况下,不需要此方法,因为 Playwright 在每次操作前都会自动等待。
用法
frame.click("button"); // Click triggers navigation.
frame.waitForLoadState(); // Waits for "load" state by default.
参数
-
state
枚举 LoadState { LOAD, DOMCONTENTLOADED, NETWORKIDLE }
(可选)#要等待的可选加载状态,默认为
load
。如果当前文档加载期间已达到该状态,则该方法会立即解析。可以是以下之一'load'
- 等待load
事件触发。'domcontentloaded'
- 等待DOMContentLoaded
事件触发。'networkidle'
- **不推荐** 等待至少500
毫秒内没有网络连接。不要将此方法用于测试,而是依赖 Web 断言来评估准备情况。
-
options
Frame.WaitForLoadStateOptions
(可选)-
最大操作时间,单位为毫秒,默认为 30 秒,传递
0
禁用超时。默认值可以通过 BrowserContext.setDefaultNavigationTimeout()、BrowserContext.setDefaultTimeout()、Page.setDefaultNavigationTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
waitForURL
添加于:v1.11等待框架导航到给定 URL。
用法
frame.click("a.delayed-navigation"); // Clicking the link will indirectly cause a navigation
frame.waitForURL("**/target.html");
参数
-
在等待导航时匹配的全局模式、正则表达式模式或接收 [URL] 的断言。请注意,如果参数是没有通配符的字符串,该方法将等待导航到与该字符串完全相同的 URL。
-
options
Frame.WaitForURLOptions
(可选)-
最大操作时间,单位为毫秒,默认为 30 秒,传递
0
禁用超时。默认值可以通过 BrowserContext.setDefaultNavigationTimeout()、BrowserContext.setDefaultTimeout()、Page.setDefaultNavigationTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
setWaitUntil
枚举 WaitUntilState { LOAD, DOMCONTENTLOADED, NETWORKIDLE, COMMIT }
(可选)#何时认为操作成功,默认为
load
。事件可以是以下之一'domcontentloaded'
- 当DOMContentLoaded
事件触发时,认为操作完成。'load'
- 当load
事件触发时,认为操作完成。'networkidle'
- 不建议 当至少500
毫秒内没有网络连接时,认为操作完成。不要使用此方法进行测试,请改用 Web 断言来评估准备情况。'commit'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回
已弃用
check
v1.9 之前添加改用基于定位器的 Locator.check()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤来检查匹配 选择器 的元素
- 查找匹配 选择器 的元素。如果没有,则等待匹配元素附加到 DOM。
- 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出。如果元素已被选中,此方法将立即返回。
- 等待对匹配元素进行 可操作性 检查,除非设置了 setForce 选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.mouse() 点击元素中心。
- 确保元素现在已选中。如果不是,此方法将抛出异常。
当所有步骤在指定的 setTimeout 内未完成时,此方法会抛出 TimeoutError。传递零超时会禁用此功能。
用法
Frame.check(selector);
Frame.check(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.CheckOptions
(可选)-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
setPosition
Position (可选)添加于:v1.11#相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
setTrial
boolean (可选)添加于:v1.11#设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。用于等待元素准备好执行操作而无需实际执行。
-
返回
click
v1.9 之前添加改用基于定位器的 Locator.click()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤来点击匹配 选择器 的元素
- 查找匹配 选择器 的元素。如果没有,则等待匹配元素附加到 DOM。
- 等待对匹配元素进行 可操作性 检查,除非设置了 setForce 选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.mouse() 点击元素的中心,或指定的 setPosition。
- 等待已启动的导航成功或失败,除非设置了 setNoWaitAfter 选项。
当所有步骤在指定的 setTimeout 内未完成时,此方法会抛出 TimeoutError。传递零超时会禁用此功能。
用法
Frame.click(selector);
Frame.click(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.ClickOptions
(可选)-
setButton
枚举 MouseButton { LEFT, RIGHT, MIDDLE }
(可选)#默认为
left
。 -
默认为 1。参见 UIEvent.detail。
-
mousedown
和mouseup
之间等待的时间(毫秒)。默认为 0。 -
是否绕过 可操作性 检查。默认为
false
。 -
setModifiers
列表<枚举 KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }
> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
已弃用
此选项将来默认为
true
。启动导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为
false
。 -
setPosition
Position (可选)#相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
setTrial
boolean (可选)添加于:v1.11#设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。用于等待元素准备好进行操作而不执行它。请注意,无论trial
如何,键盘modifiers
都将被按下,以允许测试仅在这些键被按下时才可见的元素。
-
返回
dblclick
v1.9 之前添加改用基于定位器的 Locator.dblclick()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤来双击匹配 选择器 的元素
- 查找匹配 选择器 的元素。如果没有,则等待匹配元素附加到 DOM。
- 等待对匹配元素进行 可操作性 检查,除非设置了 setForce 选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.mouse() 双击元素的中心,或指定的 setPosition。如果
dblclick()
的第一次点击触发导航事件,此方法将抛出错误。
当所有步骤在指定的 setTimeout 内未完成时,此方法会抛出 TimeoutError。传递零超时会禁用此功能。
frame.dblclick()
会分派两个 click
事件和一个 dblclick
事件。
用法
Frame.dblclick(selector);
Frame.dblclick(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.DblclickOptions
(可选)-
setButton
枚举 MouseButton { LEFT, RIGHT, MIDDLE }
(可选)#默认为
left
。 -
mousedown
和mouseup
之间等待的时间(毫秒)。默认为 0。 -
是否绕过 可操作性 检查。默认为
false
。 -
setModifiers
列表<枚举 KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }
> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
已弃用
此选项无效。
此选项无效。
-
setPosition
Position (可选)#相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
setTrial
boolean (可选)添加于:v1.11#设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。用于等待元素准备好进行操作而不执行它。请注意,无论trial
如何,键盘modifiers
都将被按下,以允许测试仅在这些键被按下时才可见的元素。
-
返回
dispatchEvent
v1.9 之前添加改用基于定位器的 Locator.dispatchEvent()。阅读更多关于 定位器 的信息。
以下代码片段在元素上分发 click
事件。无论元素的可见性状态如何,都会分发 click
事件。这等同于调用 element.click()。
用法
frame.dispatchEvent("button#submit", "click");
在底层,它根据给定的 type 创建一个事件实例,使用 eventInit 属性初始化它,并在元素上分发。事件默认是 composed
、cancelable
和冒泡的。
由于 eventInit 是特定于事件的,请参阅事件文档以获取初始属性列表
- DeviceMotionEvent
- DeviceOrientationEvent
- DragEvent
- Event
- FocusEvent
- KeyboardEvent
- MouseEvent
- PointerEvent
- TouchEvent
- WheelEvent
您还可以指定 JSHandle
作为属性值,如果您希望将实时对象传递到事件中
// Note you can only create DataTransfer in Chromium and Firefox
JSHandle dataTransfer = frame.evaluateHandle("() => new DataTransfer()");
Map<String, Object> arg = new HashMap<>();
arg.put("dataTransfer", dataTransfer);
frame.dispatchEvent("#source", "dragstart", arg);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
DOM 事件类型:
"click"
、"dragstart"
等。 -
eventInit
EvaluationArgument (可选)#可选的事件特定初始化属性。
-
options
Frame.DispatchEventOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
evalOnSelector
添加于:v1.9此方法不等待元素通过可操作性检查,因此可能导致测试不稳定。请使用 Locator.evaluate()、其他 Locator 辅助方法或优先于 Web 的断言。
返回 expression 的返回值。
此方法在框架内查找匹配指定选择器的元素,并将其作为第一个参数传递给 expression。如果没有元素匹配选择器,该方法将抛出错误。
如果 expression 返回一个 Promise,那么 Frame.evalOnSelector() 将等待该 Promise 解析并返回其值。
用法
String searchValue = (String) frame.evalOnSelector("#search", "el => el.value");
String preloadHref = (String) frame.evalOnSelector("link[rel=preload]", "el => el.href");
String html = (String) frame.evalOnSelector(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello");
参数
-
要查询的选择器。
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument (可选)#要传递给 expression 的可选参数。
-
options
Frame.EvalOnSelectorOptions
(可选)
返回
evalOnSelectorAll
添加于:v1.9在大多数情况下,Locator.evaluateAll()、其他 Locator 辅助方法和 web-first 断言做得更好。
返回 expression 的返回值。
此方法在框架内查找所有匹配指定选择器的元素,并将匹配元素的数组作为第一个参数传递给 expression。
如果 expression 返回一个 Promise,那么 Frame.evalOnSelectorAll() 将等待该 Promise 解析并返回其值。
用法
boolean divsCounts = (boolean) page.evalOnSelectorAll("div", "(divs, min) => divs.length >= min", 10);
参数
-
要查询的选择器。
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument (可选)#要传递给 expression 的可选参数。
返回
fill
v1.9 之前添加改用基于定位器的 Locator.fill()。阅读更多关于 定位器 的信息。
此方法等待匹配 选择器 的元素,等待 可操作性 检查,聚焦元素,填充它,并在填充后触发 input
事件。请注意,您可以传递一个空字符串以清除输入字段。
如果目标元素不是 <input>
、<textarea>
或 [contenteditable]
元素,此方法将抛出错误。但是,如果元素位于具有关联 控件 的 <label>
元素内,则会填充该控件。
要发送细粒度的键盘事件,请使用 Locator.pressSequentially()。
用法
Frame.fill(selector, value);
Frame.fill(selector, value, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要填充
<input>
、<textarea>
或[contenteditable]
元素的值。 -
options
Frame.FillOptions
(可选)-
setForce
boolean (可选)添加于:v1.13#是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
focus
v1.9 之前添加改用基于定位器的 Locator.focus()。阅读更多关于 定位器 的信息。
此方法获取匹配 选择器 的元素并将其聚焦。如果没有元素匹配 选择器,该方法将等待直到匹配元素出现在 DOM 中。
用法
Frame.focus(selector);
Frame.focus(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.FocusOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
getAttribute
v1.9 之前添加改用基于定位器的 Locator.getAttribute()。阅读更多关于 定位器 的信息。
返回元素属性值。
用法
Frame.getAttribute(selector, name);
Frame.getAttribute(selector, name, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要获取值的属性名称。
-
options
Frame.GetAttributeOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
hover
v1.9 之前添加改用基于定位器的 Locator.hover()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤来悬停在匹配 选择器 的元素上
- 查找匹配 选择器 的元素。如果没有,则等待匹配元素附加到 DOM。
- 等待对匹配元素进行 可操作性 检查,除非设置了 setForce 选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.mouse() 悬停在元素的中心,或指定的 setPosition。
当所有步骤在指定的 setTimeout 内未完成时,此方法会抛出 TimeoutError。传递零超时会禁用此功能。
用法
Frame.hover(selector);
Frame.hover(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.HoverOptions
(可选)-
是否绕过 可操作性 检查。默认为
false
。 -
setModifiers
列表<枚举 KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }
> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
setNoWaitAfter
boolean (可选)新增于: v1.28#已弃用此选项无效。
此选项无效。
-
setPosition
Position (可选)#相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
setTrial
boolean (可选)添加于:v1.11#设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。用于等待元素准备好进行操作而不执行它。请注意,无论trial
如何,键盘modifiers
都将被按下,以允许测试仅在这些键被按下时才可见的元素。
-
返回
innerHTML
v1.9 之前添加改用基于定位器的 Locator.innerHTML()。阅读更多关于 定位器 的信息。
返回 element.innerHTML
。
用法
Frame.innerHTML(selector);
Frame.innerHTML(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.InnerHTMLOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
innerText
v1.9 之前添加改用基于定位器的 Locator.innerText()。阅读更多关于 定位器 的信息。
返回 element.innerText
。
用法
Frame.innerText(selector);
Frame.innerText(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.InnerTextOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
inputValue
添加于:v1.13改用基于定位器的 Locator.inputValue()。阅读更多关于 定位器 的信息。
返回选定的 <input>
、<textarea>
或 <select>
元素的 input.value
。
对非输入元素抛出错误。但是,如果元素位于具有关联 控件 的 <label>
元素内,则返回控件的值。
用法
Frame.inputValue(selector);
Frame.inputValue(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.InputValueOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
isChecked
v1.9 之前添加改用基于定位器的 Locator.isChecked()。阅读更多关于 定位器 的信息。
返回元素是否已选中。如果元素不是复选框或单选输入,则抛出异常。
用法
Frame.isChecked(selector);
Frame.isChecked(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.IsCheckedOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
isDisabled
v1.9 之前添加改用基于定位器的 Locator.isDisabled()。阅读更多关于 定位器 的信息。
返回元素是否禁用,与 enabled 相反。
用法
Frame.isDisabled(selector);
Frame.isDisabled(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.IsDisabledOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
isEditable
v1.9 之前添加改用基于定位器的 Locator.isEditable()。阅读更多关于 定位器 的信息。
返回元素是否 可编辑。
用法
Frame.isEditable(selector);
Frame.isEditable(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.IsEditableOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
isHidden
v1.9 之前添加改用基于定位器的 Locator.isHidden()。阅读更多关于 定位器 的信息。
返回元素是否隐藏,与 可见 相反。不匹配任何元素的 选择器 被视为隐藏。
用法
Frame.isHidden(selector);
Frame.isHidden(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.IsHiddenOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
已弃用
此选项被忽略。Frame.isHidden() 不会等待元素变为隐藏并立即返回。
-
返回
isVisible
v1.9 之前添加改用基于定位器的 Locator.isVisible()。阅读更多关于 定位器 的信息。
返回元素是否 可见。不匹配任何元素的 选择器 被视为不可见。
用法
Frame.isVisible(selector);
Frame.isVisible(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.IsVisibleOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
已弃用
此选项被忽略。Frame.isVisible() 不会等待元素变为可见并立即返回。
-
返回
press
v1.9 之前添加改用基于定位器的 Locator.press()。阅读更多关于 定位器 的信息。
键可以指定预期的KeyboardEvent.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
。在 Windows 和 Linux 上,ControlOrMeta
解析为 Control
,在 macOS 上解析为 Meta
。
按住Shift
将输入与键对应的大写文本。
如果键是单个字符,则区分大小写,因此值a
和A
将分别生成不同的文本。
也支持快捷键,例如 key: "Control+o"
、key: "Control++
或 key: "Control+Shift+T"
。当与修饰符一起指定时,修饰符在按下后续键时被按下并保持。
用法
Frame.press(selector, key);
Frame.press(selector, key, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要按下的键的名称或要生成的字符,例如
ArrowLeft
或a
。 -
options
Frame.PressOptions
(可选)-
keydown
和keyup
之间等待的时间(毫秒)。默认为 0。 -
已弃用
此选项将来默认为
true
。启动导航的操作会等待这些导航发生并等待页面开始加载。您可以通过设置此标志来选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为
false
。 -
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
querySelector
添加于:v1.9请改用基于定位符的Frame.locator()。了解更多关于定位符的信息。
返回指向框架元素的 ElementHandle。
不鼓励使用ElementHandle,请改用Locator对象和网页优先断言。
该方法在框架中查找与指定选取器匹配的元素。如果没有元素匹配选取器,则返回 null
。
用法
Frame.querySelector(selector);
Frame.querySelector(selector, options);
参数
-
要查询的选择器。
-
options
Frame.QuerySelectorOptions
(可选)
返回
querySelectorAll
添加于:v1.9请改用基于定位符的Frame.locator()。了解更多关于定位符的信息。
返回指向框架元素的 ElementHandles。
不鼓励使用ElementHandle,请改用Locator对象。
该方法在框架中查找与指定选择器匹配的所有元素。如果没有元素匹配选择器,则返回空数组。
用法
Frame.querySelectorAll(selector);
参数
返回
selectOption
v1.9 之前添加改用基于定位器的 Locator.selectOption()。阅读更多关于 定位器 的信息。
此方法等待匹配选择器的元素,等待可操作性检查,等待所有指定的选项出现在`<select>`元素中并选择这些选项。
如果目标元素不是`<select>`元素,此方法将抛出错误。但是,如果元素位于具有关联控件的`<label>`元素内,则将改用该控件。
返回已成功选择的选项值数组。
一旦所有提供的选项都已选中,将触发 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", new SelectOption().setLabel("Blue"));
// multiple selection
frame.selectOption("select#colors", new String[] {"red", "green", "blue"});
参数
-
要查询的选择器。
-
values
空 | 字符串 | ElementHandle | 字符串[] |SelectOption
| ElementHandle[] |SelectOption
[]#-
setValue
String (可选)按
option.value
匹配。可选。 -
setLabel
String (可选)按
option.label
匹配。可选。 -
setIndex
int (可选)按索引匹配。可选。
要选择的选项。如果`<select>`具有`multiple`属性,则选择所有匹配的选项,否则仅选择第一个匹配传入选项之一的选项。字符串值匹配值和标签。如果所有指定的属性都匹配,则选项被视为匹配。
-
-
options
Frame.SelectOptionOptions
(可选)-
setForce
boolean (可选)添加于:v1.13#是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
setChecked
新增于: v1.15改用基于定位器的 Locator.setChecked()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤来选中或取消选中匹配选择器的元素
- 查找与选择器匹配的元素。如果不存在,则等待直到匹配的元素附加到DOM。
- 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出错误。
- 如果元素已经处于正确的选中状态,此方法将立即返回。
- 对匹配的元素执行可操作性检查,除非设置了setForce选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.mouse() 点击元素中心。
- 确保元素现在已选中或未选中。如果不是,此方法将抛出异常。
如果在指定的setTimeout期间所有步骤都没有完成,此方法将抛出TimeoutError。传递零超时将禁用此功能。
用法
Frame.setChecked(selector, checked);
Frame.setChecked(selector, checked, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
是否选中或取消选中复选框。
-
options
Frame.SetCheckedOptions
(可选)-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
setPosition
位置 (可选)#相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。用于等待元素准备好执行操作而无需实际执行。
-
返回
setInputFiles
v1.9 之前添加改用基于定位器的 Locator.setInputFiles()。阅读更多关于 定位器 的信息。
将文件输入的值设置为这些文件路径或文件。如果某些 filePaths
是相对路径,则它们相对于当前工作目录解析。对于空数组,清除选定的文件。
此方法要求选择器指向输入元素。但是,如果元素位于具有关联控件的`<label>`元素内,则会改为针对该控件。
用法
Frame.setInputFiles(selector, files);
Frame.setInputFiles(selector, files, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.SetInputFilesOptions
(可选)-
已弃用
此选项无效。
此选项无效。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
tap
v1.9 之前添加改用基于定位器的 Locator.tap()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤轻触与选择器匹配的元素
- 查找与选择器匹配的元素。如果不存在,则等待直到匹配的元素附加到DOM。
- 对匹配的元素执行可操作性检查,除非设置了setForce选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用Page.touchscreen()轻触元素的中心,或指定的setPosition。
如果在指定的setTimeout期间所有步骤都没有完成,此方法将抛出TimeoutError。传递零超时将禁用此功能。
frame.tap()
要求浏览器上下文的 hasTouch
选项设置为 true。
用法
Frame.tap(selector);
Frame.tap(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.TapOptions
(可选)-
是否绕过 可操作性 检查。默认为
false
。 -
setModifiers
列表<枚举 KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }
> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后将当前修饰键恢复。如果未指定,则使用当前按下的修饰键。"ControlOrMeta" 在 Windows 和 Linux 上解析为 "Control",在 macOS 上解析为 "Meta"。
-
已弃用
此选项无效。
此选项无效。
-
setPosition
位置 (可选)#相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
setTrial
boolean (可选)添加于:v1.11#设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。用于等待元素准备好进行操作而不执行它。请注意,无论trial
如何,键盘modifiers
都将被按下,以允许测试仅在这些键被按下时才可见的元素。
-
返回
textContent
v1.9 之前添加改用基于定位器的 Locator.textContent()。阅读更多关于 定位器 的信息。
返回 element.textContent
。
用法
Frame.textContent(selector);
Frame.textContent(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.TextContentOptions
(可选)-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
type
v1.9 之前添加在大多数情况下,您应该使用Locator.fill()。只有当页面上有特殊的键盘处理时,您才需要逐个按下按键——在这种情况下,请使用Locator.pressSequentially()。
为文本中的每个字符发送`keydown`、`keypress`/`input`和`keyup`事件。`frame.type`可用于发送细粒度的键盘事件。要填充表单字段中的值,请使用Frame.fill()。
要按下特殊键,例如 Control
或 ArrowDown
,请使用 Keyboard.press()。
用法
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要输入到聚焦元素的文本。
-
options
Frame.TypeOptions
(可选)-
按键之间等待的时间,以毫秒为单位。默认为 0。
-
已弃用
此选项无效。
此选项无效。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
uncheck
v1.9 之前添加改用基于定位器的 Locator.uncheck()。阅读更多关于 定位器 的信息。
此方法通过执行以下步骤取消选中与选择器匹配的元素
- 查找与选择器匹配的元素。如果不存在,则等待直到匹配的元素附加到DOM。
- 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出错误。如果元素已取消选中,此方法会立即返回。
- 对匹配的元素执行可操作性检查,除非设置了setForce选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.mouse() 点击元素中心。
- 确保元素现在未选中。如果不是,此方法将抛出异常。
如果在指定的setTimeout期间所有步骤都没有完成,此方法将抛出TimeoutError。传递零超时将禁用此功能。
用法
Frame.uncheck(selector);
Frame.uncheck(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
Frame.UncheckOptions
(可选)-
是否绕过 可操作性 检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
setPosition
Position (可选)添加于:v1.11#相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
setTrial
boolean (可选)添加于:v1.11#设置后,此方法仅执行 可操作性 检查并跳过操作。默认为
false
。用于等待元素准备好执行操作而无需实际执行。
-
返回
waitForNavigation
v1.9 之前添加此方法本身具有竞态条件,请改用Frame.waitForURL()。
等待帧导航并返回主资源响应。在多次重定向的情况下,导航将使用最后一次重定向的响应来解决。在导航到不同锚点或由于历史 API 使用而进行导航的情况下,导航将解析为`null`。
用法
此方法等待帧导航到新 URL。当您运行间接导致帧导航的代码时,此方法非常有用。请考虑以下示例:
// The method returns after navigation has finished
frame.waitForNavigation(() -> {
// Clicking the link will indirectly cause a navigation
frame.click("a.delayed-navigation");
});
使用 History API 更改 URL 被视为导航。
参数
-
options
Frame.WaitForNavigationOptions
(可选)-
最大操作时间,单位为毫秒,默认为 30 秒,传递
0
禁用超时。默认值可以通过 BrowserContext.setDefaultNavigationTimeout()、BrowserContext.setDefaultTimeout()、Page.setDefaultNavigationTimeout() 或 Page.setDefaultTimeout() 方法更改。 -
setUrl
字符串 | Pattern | Predicate<字符串> (可选)#在等待导航时匹配的全局模式、正则表达式模式或接收 [URL] 的断言。请注意,如果参数是没有通配符的字符串,该方法将等待导航到与该字符串完全相同的 URL。
-
setWaitUntil
枚举 WaitUntilState { LOAD, DOMCONTENTLOADED, NETWORKIDLE, COMMIT }
(可选)#何时认为操作成功,默认为
load
。事件可以是以下之一'domcontentloaded'
- 当DOMContentLoaded
事件触发时,认为操作完成。'load'
- 当load
事件触发时,认为操作完成。'networkidle'
- 不建议 当至少500
毫秒内没有网络连接时,认为操作完成。不要使用此方法进行测试,请改用 Web 断言来评估准备情况。'commit'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
-
执行触发事件的操作的回调。
返回
waitForSelector
v1.9 之前添加请改用断言可见性的网页断言或基于定位符的Locator.waitFor()。了解更多关于定位符的信息。
当由选择器指定的元素满足setState选项时返回。如果等待`hidden`或`detached`,则返回`null`。
Playwright 会在执行操作之前自动等待元素准备就绪。使用Locator对象和网页优先断言可以使代码免于等待选择器。
等待选择器满足setState选项(从DOM出现/消失,或变为可见/隐藏)。如果调用方法时选择器已经满足条件,则方法将立即返回。如果选择器在setTimeout毫秒内不满足条件,则函数将抛出异常。
用法
此方法适用于跨导航
import com.microsoft.playwright.*;
public class Example {
public static void main(String[] args) {
try (Playwright playwright = Playwright.create()) {
BrowserType chromium = playwright.chromium();
Browser browser = chromium.launch();
Page page = browser.newPage();
for (String currentURL : Arrays.asList("https://google.com", "https://bbc.com")) {
page.navigate(currentURL);
ElementHandle element = page.mainFrame().waitForSelector("img");
System.out.println("Loaded image: " + element.getAttribute("src"));
}
browser.close();
}
}
}
参数
-
要查询的选择器。
-
options
Frame.WaitForSelectorOptions
(可选)-
setState
枚举 WaitForSelectorState { ATTACHED, DETACHED, VISIBLE, HIDDEN }
(可选)#默认为
'visible'
。可以是以下之一:'attached'
- 等待元素出现在 DOM 中。'detached'
- 等待元素不在 DOM 中。'visible'
- 等待元素具有非空的边界框且没有visibility:hidden
。请注意,没有任何内容或具有display:none
的元素具有空的边界框,不被视为可见。'hidden'
- 等待元素从 DOM 中分离,或具有空的边界框或visibility:hidden
。这与'visible'
选项相反。
-
setStrict
boolean (可选)新增于:v1.14#如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
最大超时时间,单位为毫秒。默认为
30000
(30 秒)。传递0
禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
-
返回
waitForTimeout
v1.9 之前添加切勿在生产环境中等待超时。等待时间的测试本身就不可靠。请使用会自动等待的Locator操作和网页断言。
等待给定的timeout毫秒。
请注意,frame.waitForTimeout()
只能用于调试。在生产环境中使用计时器的测试将会不稳定。请改用网络事件、选择器变为可见等信号。
用法
Frame.waitForTimeout(timeout);
参数
返回