Frame
在任何时候,页面都会通过 Page.MainFrame 和 Frame.ChildFrames 方法公开其当前框架树。
Frame 对象的生命周期由页面对象上分派的三个事件控制
- Page.FrameAttached - 当框架附加到页面时触发。一个框架只能附加到页面一次。
- Page.FrameNavigated - 当框架提交导航到不同 URL 时触发。
- Page.FrameDetached - 当框架从页面分离时触发。一个框架只能从页面分离一次。
转储框架树的示例
using Microsoft.Playwright;
using System;
using System.Threading.Tasks;
class FrameExamples
{
public static async Task Main()
{
using var playwright = await Playwright.CreateAsync();
await using var browser = await playwright.Firefox.LaunchAsync();
var page = await browser.NewPageAsync();
await page.GotoAsync("https://www.bing.com");
DumpFrameTree(page.MainFrame, string.Empty);
}
private static void DumpFrameTree(IFrame frame, string indent)
{
Console.WriteLine($"{indent}{frame.Url}");
foreach (var child in frame.ChildFrames)
DumpFrameTree(child, indent + " ");
}
}
方法
AddScriptTagAsync
v1.9 之前添加当脚本的 onload 事件触发或脚本内容注入到框架中时,返回添加的标签。
将带有所需 url 或内容的 <script>
标签添加到页面中。
用法
await Frame.AddScriptTagAsync(options);
参数
options
FrameAddScriptTagOptions?
(可选)
返回
AddStyleTagAsync
v1.9 之前添加当样式表的 onload 事件触发或 CSS 内容注入到框架中时,返回添加的标签。
将带有所需 url 的 <link rel="stylesheet">
标签或带有内容的 <style type="text/css">
标签添加到页面中。
用法
await Frame.AddStyleTagAsync(options);
参数
options
FrameAddStyleTagOptions?
(可选)
返回
ChildFrames
v1.9 之前添加用法
Frame.ChildFrames
返回
ContentAsync
v1.9 之前添加获取框架的完整 HTML 内容,包括 doctype。
用法
await Frame.ContentAsync();
返回
DragAndDropAsync
添加于:v1.13用法
await Frame.DragAndDropAsync(source, target, options);
参数
-
用于搜索要拖动的元素的选择器。如果有多个元素满足选择器,将使用第一个。
-
用于搜索要拖放到的元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameDragAndDropOptions?
(可选)-
是否绕过可操作性检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
SourcePosition
SourcePosition? (可选)新增于:v1.14#-
X
[float] -
Y
[float]
在此点(相对于元素内边距框的左上角)点击源元素。如果未指定,则使用元素的某个可见点。
-
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
TargetPosition
TargetPosition? (可选)新增于:v1.14#-
X
[float] -
Y
[float]
在此点(相对于元素内边距框的左上角)拖放到目标元素。如果未指定,则使用元素的某个可见点。
-
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
设置后,此方法仅执行可操作性检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。
-
返回
EvaluateAsync
v1.9 之前添加返回 expression 的返回值。
如果传递给 Frame.EvaluateAsync() 的函数返回一个 Promise,则 Frame.EvaluateAsync() 将等待 Promise 解析并返回其值。
如果传递给 Frame.EvaluateAsync() 的函数返回一个不可 序列化 的值,则 Frame.EvaluateAsync() 返回 undefined
。Playwright 还支持传输一些不可被 JSON
序列化的额外值:-0
、NaN
、Infinity
、-Infinity
。
用法
var result = await frame.EvaluateAsync<int>("([x, y]) => Promise.resolve(x * y)", new[] { 7, 8 });
Console.WriteLine(result);
也可以传入字符串而不是函数。
Console.WriteLine(await frame.EvaluateAsync<int>("1 + 2")); // prints "3"
ElementHandle 实例可以作为参数传递给 Frame.EvaluateAsync()
var bodyHandle = await frame.EvaluateAsync("document.body");
var html = await frame.EvaluateAsync<string>("([body, suffix]) => body.innerHTML + suffix", new object [] { bodyHandle, "hello" });
await bodyHandle.DisposeAsync();
参数
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument? (可选)#要传递给 expression 的可选参数。
返回
- [object]#
EvaluateHandleAsync
v1.9 之前添加返回 expression 的返回值作为 JSHandle。
Frame.EvaluateAsync() 和 Frame.EvaluateHandleAsync() 之间唯一的区别是 Frame.EvaluateHandleAsync() 返回 JSHandle。
如果传递给 Frame.EvaluateHandleAsync() 的函数返回一个 Promise,则 Frame.EvaluateHandleAsync() 将等待 Promise 解析并返回其值。
用法
// Handle for the window object.
var aWindowHandle = await frame.EvaluateHandleAsync("() => Promise.resolve(window)");
也可以传入字符串而不是函数。
var docHandle = await frame.EvaluateHandleAsync("document"); // Handle for the `document`
JSHandle 实例可以作为参数传递给 Frame.EvaluateHandleAsync()
var handle = await frame.EvaluateHandleAsync("() => document.body");
var resultHandle = await frame.EvaluateHandleAsync("([body, suffix]) => body.innerHTML + suffix", new object[] { handle, "hello" });
Console.WriteLine(await resultHandle.JsonValueAsync<string>());
await resultHandle.DisposeAsync();
参数
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument? (可选)#要传递给 expression 的可选参数。
返回
FrameElementAsync
v1.9 之前添加返回与此框架对应的 frame
或 iframe
元素句柄。
这是 ElementHandle.ContentFrameAsync() 的逆操作。请注意,返回的句柄实际上属于父框架。
如果框架在 frameElement()
返回之前已分离,则此方法会抛出错误。
用法
var frameElement = await frame.FrameElementAsync();
var contentFrame = await frameElement.ContentFrameAsync();
Console.WriteLine(frame == contentFrame); // -> True
返回
FrameLocator
新增于: v1.17使用 iframe 时,您可以创建一个框架定位器,它将进入 iframe 并允许选择 iframe 中的元素。
用法
以下代码片段在 id 为 my-frame
的 iframe 中查找文本为“提交”的元素,例如 <iframe id="my-frame">
var locator = frame.FrameLocator("#my-iframe").GetByText("Submit");
await locator.ClickAsync();
参数
返回
GetByAltText
新增于:v1.27允许根据元素的 alt 文本定位元素。
用法
例如,此方法将通过 alt 文本“Playwright logo”找到图像
<img alt='Playwright logo'>
await page.GetByAltText("Playwright logo").ClickAsync();
参数
-
用于定位元素的文本。
-
options
FrameGetByAltTextOptions?
(可选)
返回
GetByLabel
新增于:v1.27允许通过关联的 <label>
或 aria-labelledby
元素的文本或 aria-label
属性来定位输入元素。
用法
例如,此方法将在以下 DOM 中通过标签“用户名”和“密码”找到输入
<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">
await page.GetByLabel("Username").FillAsync("john");
await page.GetByLabel("Password").FillAsync("secret");
参数
-
用于定位元素的文本。
-
options
FrameGetByLabelOptions?
(可选)
返回
GetByPlaceholder
新增于:v1.27允许通过占位符文本定位输入元素。
用法
例如,考虑以下 DOM 结构。
<input type="email" placeholder="name@example.com" />
您可以按占位符文本定位输入框后填充它
await page
.GetByPlaceholder("name@example.com")
.FillAsync("playwright@microsoft.com");
参数
-
用于定位元素的文本。
-
options
FrameGetByPlaceholderOptions?
(可选)
返回
GetByRole
新增于:v1.27允许通过元素的 ARIA 角色、ARIA 属性 和 可访问名称 进行定位。
用法
考虑以下 DOM 结构。
<h3>Sign up</h3>
<label>
<input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>
您可以通过其隐式角色定位每个元素
await Expect(Page
.GetByRole(AriaRole.Heading, new() { Name = "Sign up" }))
.ToBeVisibleAsync();
await page
.GetByRole(AriaRole.Checkbox, new() { Name = "Subscribe" })
.CheckAsync();
await page
.GetByRole(AriaRole.Button, new() {
NameRegex = new Regex("submit", RegexOptions.IgnoreCase)
})
.ClickAsync();
参数
-
role
enum AriaRole { Alert, Alertdialog, Application, Article, Banner, Blockquote, Button, Caption, Cell, Checkbox, Code, Columnheader, Combobox, Complementary, Contentinfo, Definition, Deletion, Dialog, Directory, Document, Emphasis, Feed, Figure, Form, Generic, Grid, Gridcell, Group, Heading, Img, Insertion, Link, List, Listbox, Listitem, Log, Main, Marquee, Math, Meter, Menu, Menubar, Menuitem, Menuitemcheckbox, Menuitemradio, Navigation, None, Note, Option, Paragraph, Presentation, Progressbar, Radio, Radiogroup, Region, Row, Rowgroup, Rowheader, Scrollbar, Search, Searchbox, Separator, Slider, Spinbutton, Status, Strong, Subscript, Superscript, Switch, Tab, Table, Tablist, Tabpanel, Term, Textbox, Time, Timer, Toolbar, Tooltip, Tree, Treegrid, Treeitem }
#所需的 aria 角色。
-
options
FrameGetByRoleOptions?
(可选)-
通常由
aria-checked
或原生<input type=checkbox>
控件设置的属性。了解更多关于
aria-checked
的信息。 -
通常由
aria-disabled
或disabled
设置的属性。注意与大多数其他属性不同,
disabled
在 DOM 层次结构中是继承的。了解更多关于aria-disabled
的信息。 -
是否精确匹配 Name|NameRegex:区分大小写和全字符串匹配。默认为 false。当 Name|NameRegex 是正则表达式时忽略。请注意,精确匹配仍会修剪空白字符。
-
通常由
aria-expanded
设置的属性。了解更多关于
aria-expanded
的信息。 -
控制是否匹配隐藏元素的选项。默认情况下,只有非隐藏元素(由 ARIA 定义)由角色选择器匹配。
了解更多关于
aria-hidden
的信息。 -
通常用于角色
heading
、listitem
、row
、treeitem
的数字属性,<h1>-<h6>
元素具有默认值。了解更多关于
aria-level
的信息。 -
Name|NameRegex
string? | Regex? (可选)#匹配 可访问名称 的选项。默认情况下,匹配不区分大小写,并搜索子字符串,使用 Exact 来控制此行为。
了解更多关于 可访问名称 的信息。
-
通常由
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 定位元素
await page.GetByTestId("directions").ClickAsync();
参数
返回
详情
默认情况下,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() { Exact = true });
// Matches both <div>s
page.GetByText(new Regex("Hello"));
// Matches second <div>
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase));
参数
-
用于定位元素的文本。
-
options
FrameGetByTextOptions?
(可选)
返回
详情
按文本匹配始终会规范化空格,即使是精确匹配也是如此。例如,它会将多个空格转换为一个空格,将换行符转换为空格,并忽略前导和尾随空格。
类型为 button
和 submit
的输入元素通过其 value
而不是文本内容进行匹配。例如,通过文本 "登录"
定位匹配 <input type=button value="登录">
。
GetByTitle
新增于:v1.27允许通过元素的 title 属性定位元素。
用法
考虑以下 DOM 结构。
<span title='Issues count'>25 issues</span>
您可以通过 title 文本定位它后检查问题数量
await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");
参数
-
用于定位元素的文本。
-
options
FrameGetByTitleOptions?
(可选)
返回
GotoAsync
v1.9 之前添加返回主资源响应。如果发生多次重定向,导航将解析为最后一次重定向的响应。
此方法将在以下情况下抛出错误
- 存在 SSL 错误(例如自签名证书)。
- 目标 URL 无效。
- 超时 已超过导航期间。
- 远程服务器无响应或无法访问。
- 主资源加载失败。
当远程服务器返回任何有效的 HTTP 状态码时,包括 404 "未找到" 和 500 "内部服务器错误",该方法不会抛出错误。此类响应的状态码可以通过调用 Response.Status 检索。
该方法要么抛出错误,要么返回主资源响应。唯一的例外是导航到 about:blank
或导航到具有不同哈希的相同 URL,这将成功并返回 null
。
无头模式不支持导航到 PDF 文档。请参阅 上游问题。
用法
await Frame.GotoAsync(url, options);
参数
-
要导航框架到的 URL。URL 应包含方案,例如
https://
。 -
options
FrameGotoOptions?
(可选)-
Referer 标头值。如果提供,它将优先于 Page.SetExtraHTTPHeadersAsync() 设置的 referer 标头值。
-
Timeout
[float]? (可选)#最大操作时间(毫秒),默认为 30 秒,传递
0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
WaitUntil
enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }?
(可选)#何时认为操作成功,默认为
load
。事件可以是以下之一'domcontentloaded'
- 当DOMContentLoaded
事件触发时,认为操作完成。'load'
- 当load
事件触发时,认为操作完成。'networkidle'
- 不建议 当至少500
毫秒内没有网络连接时,认为操作完成。不要使用此方法进行测试,请改用 Web 断言来评估准备情况。'commit'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回
IsDetached
v1.9 之前添加如果框架已分离,则返回 true
,否则返回 false
。
用法
Frame.IsDetached
返回
IsEnabledAsync
v1.9 之前添加返回元素是否 已启用。
用法
await Frame.IsEnabledAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameIsEnabledOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
Locator
新增于:v1.14该方法返回一个元素定位器,可用于在此页面/框架上执行操作。定位器在执行操作之前立即解析为元素,因此对同一定位器执行一系列操作实际上可以在不同的 DOM 元素上执行。如果这些操作之间的 DOM 结构发生变化,就会发生这种情况。
用法
Frame.Locator(selector, options);
参数
-
用于解析 DOM 元素的选取器。
-
options
FrameLocatorOptions?
(可选)-
将方法结果缩小到包含与此相对定位器匹配的元素的那些结果。例如,包含 `text=Playwright` 的 `article` 匹配 `<article><div>Playwright</div></article>`。
内部定位器 **必须相对于** 外部定位器,并且从外部定位器匹配开始查询,而不是文档根目录。例如,您可以在 `<article><content><div>Playwright</div></content></article>` 中找到包含 `div` 的 `content`。但是,查找包含 `article div` 的 `content` 将失败,因为内部定位器必须是相对的,并且不应使用 `content` 之外的任何元素。
请注意,外部和内部定位器必须属于同一个框架。内部定位器不能包含 FrameLocator。
-
匹配不包含与内部定位器匹配的元素的元素。内部定位器针对外部定位器进行查询。例如,不包含 `div` 的 `article` 匹配 `<article><span>Playwright</span></article>`。
请注意,外部和内部定位器必须属于同一个框架。内部定位器不能包含 FrameLocator。
-
HasNotText|HasNotTextRegex
string? | Regex? (可选)新增于:v1.33#匹配不包含指定文本(可能在子元素或后代元素中)的元素。当传入 string 时,匹配不区分大小写,并搜索子字符串。
-
HasText|HasTextRegex
string? | Regex? (可选)#匹配包含指定文本(可能在子元素或后代元素中)的元素。当传入 string 时,匹配不区分大小写,并搜索子字符串。例如,`"Playwright"` 匹配 `<article><div>Playwright</div></article>`。
-
返回
Name
v1.9 之前添加返回标签中指定的框架名称属性。
如果名称为空,则返回 id 属性。
此值在框架创建时计算一次,如果属性稍后更改,则不会更新。
用法
Frame.Name
返回
Page
v1.9 之前添加返回包含此框架的页面。
用法
Frame.Page
返回
ParentFrame
v1.9 之前添加父框架,如果有的话。分离的框架和主框架返回 null
。
用法
Frame.ParentFrame
返回
SetContentAsync
v1.9 之前添加此方法内部调用 document.write(),继承其所有特定特征和行为。
用法
await Frame.SetContentAsync(html, options);
参数
-
要分配给页面的 HTML 标记。
-
options
FrameSetContentOptions?
(可选)-
Timeout
[float]? (可选)#最大操作时间(毫秒),默认为 30 秒,传递
0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
WaitUntil
enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }?
(可选)#何时认为操作成功,默认为
load
。事件可以是以下之一'domcontentloaded'
- 当DOMContentLoaded
事件触发时,认为操作完成。'load'
- 当load
事件触发时,认为操作完成。'networkidle'
- 不建议 当至少500
毫秒内没有网络连接时,认为操作完成。不要使用此方法进行测试,请改用 Web 断言来评估准备情况。'commit'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回
TitleAsync
v1.9 之前添加返回页面标题。
用法
await Frame.TitleAsync();
返回
Url
v1.9 之前添加返回框架的 url。
用法
Frame.Url
返回
WaitForFunctionAsync
v1.9 之前添加当 expression 返回一个真值时返回,并返回该值。
用法
Frame.WaitForFunctionAsync() 可用于观察视口大小变化
using Microsoft.Playwright;
using System.Threading.Tasks;
class FrameExamples
{
public static async Task Main()
{
using var playwright = await Playwright.CreateAsync();
await using var browser = await playwright.Firefox.LaunchAsync();
var page = await browser.NewPageAsync();
await page.SetViewportSizeAsync(50, 50);
await page.MainFrame.WaitForFunctionAsync("window.innerWidth < 100");
}
}
将参数传递给 frame.waitForFunction
函数的谓词
var selector = ".foo";
await page.MainFrame.WaitForFunctionAsync("selector => !!document.querySelector(selector)", selector);
参数
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument? (可选)#要传递给 expression 的可选参数。
-
options
FrameWaitForFunctionOptions?
(可选)-
PollingInterval
[float]? (可选)#如果指定,则将其视为函数执行的毫秒间隔。默认情况下,如果未指定此选项,expression 在 `requestAnimationFrame` 回调中执行。
-
Timeout
[float]? (可选)#最大等待时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
WaitForLoadStateAsync
v1.9 之前添加等待达到所需的加载状态。
当框架达到所需的加载状态(默认为 load
)时返回。调用此方法时导航必须已提交。如果当前文档已达到所需状态,则立即解析。
大多数情况下,不需要此方法,因为 Playwright 在每次操作前自动等待。
用法
await frame.ClickAsync("button");
await frame.WaitForLoadStateAsync(); // Defaults to LoadState.Load
参数
-
state
enum LoadState { Load, DOMContentLoaded, NetworkIdle }?
(可选)#要等待的可选加载状态,默认为
load
。如果当前文档加载期间已达到该状态,则该方法会立即解析。可以是以下之一'load'
- 等待load
事件触发。'domcontentloaded'
- 等待DOMContentLoaded
事件触发。'networkidle'
- **不推荐** 等待至少500
毫秒内没有网络连接。不要将此方法用于测试,而是依赖 Web 断言来评估准备情况。
-
options
FrameWaitForLoadStateOptions?
(可选)-
Timeout
[float]? (可选)#最大操作时间(毫秒),默认为 30 秒,传递
0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
WaitForURLAsync
添加于:v1.11等待框架导航到给定 URL。
用法
await frame.ClickAsync("a.delayed-navigation"); // clicking the link will indirectly cause a navigation
await frame.WaitForURLAsync("**/target.html");
参数
-
url
string | Regex | Func<string, bool>#一个 glob 模式、正则表达式模式或接收 URL 的谓词,用于在等待导航时进行匹配。请注意,如果参数是没有通配符的字符串,则该方法将等待导航到与该字符串完全相等的 URL。
-
options
FrameWaitForURLOptions?
(可选)-
Timeout
[float]? (可选)#最大操作时间(毫秒),默认为 30 秒,传递
0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
WaitUntil
enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }?
(可选)#何时认为操作成功,默认为
load
。事件可以是以下之一'domcontentloaded'
- 当DOMContentLoaded
事件触发时,认为操作完成。'load'
- 当load
事件触发时,认为操作完成。'networkidle'
- 不建议 当至少500
毫秒内没有网络连接时,认为操作完成。不要使用此方法进行测试,请改用 Web 断言来评估准备情况。'commit'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回
已弃用
CheckAsync
v1.9 之前添加请改用基于定位器的 Locator.CheckAsync()。阅读有关 定位器 的更多信息。
此方法通过执行以下步骤来检查与 selector 匹配的元素
- 查找与 selector 匹配的元素。如果没有,则等待直到匹配的元素附加到 DOM。
- 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出。如果元素已被选中,此方法将立即返回。
- 在匹配元素上等待 可操作性 检查,除非设置了 Force 选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 点击元素的中心。
- 确保元素现在已选中。如果不是,此方法将抛出异常。
当所有步骤在指定的 Timeout 内未完成时,此方法会抛出 TimeoutError。传递零超时将禁用此功能。
用法
await Frame.CheckAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameCheckOptions?
(可选)-
是否绕过可操作性检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
Position
Position? (可选)添加于:v1.11#-
X
[float] -
Y
[float]
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
设置后,此方法仅执行可操作性检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。
-
返回
ClickAsync
v1.9 之前添加请改用基于定位器的 Locator.ClickAsync()。阅读有关 定位器 的更多信息。
此方法通过执行以下步骤来单击与 selector 匹配的元素
- 查找与 selector 匹配的元素。如果没有,则等待直到匹配的元素附加到 DOM。
- 在匹配元素上等待 可操作性 检查,除非设置了 Force 选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 单击元素的中心,或指定的 Position。
- 等待已启动的导航成功或失败,除非设置了 NoWaitAfter 选项。
当所有步骤在指定的 Timeout 内未完成时,此方法会抛出 TimeoutError。传递零超时将禁用此功能。
用法
await Frame.ClickAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameClickOptions?
(可选)-
Button
enum MouseButton { Left, Right, Middle }?
(可选)#默认为
left
。 -
默认为 1。参见 UIEvent.detail。
-
Delay
[float]? (可选)#mousedown
和mouseup
之间等待的时间(毫秒)。默认为 0。 -
是否绕过可操作性检查。默认为
false
。 -
Modifiers
IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }
> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后恢复当前修饰键。如果未指定,则使用当前按下的修饰键。“ControlOrMeta”在 Windows 和 Linux 上解析为“Control”,在 macOS 上解析为“Meta”。
-
已弃用
此选项将来默认为
true
。启动导航的操作正在等待这些导航发生并且页面开始加载。您可以通过设置此标志选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 `false`。
-
Position
Position? (可选)#-
X
[float] -
Y
[float]
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
设置后,此方法只执行 可操作性 检查并跳过操作。默认为 `false`。用于等待元素准备好执行操作而不执行它。请注意,无论 `trial` 如何,键盘 `modifiers` 都将被按下,以允许测试仅在这些键被按下时才可见的元素。
-
返回
DblClickAsync
v1.9 之前添加请改用基于定位器的 Locator.DblClickAsync()。阅读有关 定位器 的更多信息。
此方法通过执行以下步骤双击与 selector 匹配的元素
- 查找与 selector 匹配的元素。如果没有,则等待直到匹配的元素附加到 DOM。
- 在匹配元素上等待 可操作性 检查,除非设置了 Force 选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 双击元素的中心,或指定的 Position。如果 `dblclick()` 的第一次点击触发导航事件,此方法将抛出。
当所有步骤在指定的 Timeout 内未完成时,此方法会抛出 TimeoutError。传递零超时将禁用此功能。
frame.dblclick()
会分派两个 click
事件和一个 dblclick
事件。
用法
await Frame.DblClickAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameDblClickOptions?
(可选)-
Button
enum MouseButton { Left, Right, Middle }?
(可选)#默认为
left
。 -
Delay
[float]? (可选)#mousedown
和mouseup
之间等待的时间(毫秒)。默认为 0。 -
是否绕过可操作性检查。默认为
false
。 -
Modifiers
IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }
> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后恢复当前修饰键。如果未指定,则使用当前按下的修饰键。“ControlOrMeta”在 Windows 和 Linux 上解析为“Control”,在 macOS 上解析为“Meta”。
-
已弃用
此选项无效。
此选项无效。
-
Position
Position? (可选)#-
X
[float] -
Y
[float]
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
设置后,此方法只执行 可操作性 检查并跳过操作。默认为 `false`。用于等待元素准备好执行操作而不执行它。请注意,无论 `trial` 如何,键盘 `modifiers` 都将被按下,以允许测试仅在这些键被按下时才可见的元素。
-
返回
DispatchEventAsync
v1.9 之前添加请改用基于定位器的 Locator.DispatchEventAsync()。阅读有关 定位器 的更多信息。
下面的代码片段在元素上分派 `click` 事件。无论元素的可见性状态如何,都会分派 `click` 事件。这等同于调用 element.click()。
用法
await frame.DispatchEventAsync("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
var dataTransfer = await frame.EvaluateHandleAsync("() => new DataTransfer()");
await frame.DispatchEventAsync("#source", "dragstart", new { dataTransfer });
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
DOM 事件类型:
"click"
、"dragstart"
等。 -
eventInit
EvaluationArgument? (可选)#可选的事件特定初始化属性。
-
options
FrameDispatchEventOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
EvalOnSelectorAsync
添加于:v1.9此方法不会等待元素通过可操作性检查,因此可能导致测试不稳定。请改用 Locator.EvaluateAsync()、其他 Locator 辅助方法或 Web 优先断言。
返回 expression 的返回值。
该方法在框架中查找与指定选择器匹配的元素,并将其作为第一个参数传递给 expression。如果没有元素与选择器匹配,该方法会抛出错误。
如果 expression 返回一个 Promise,则 Frame.EvalOnSelectorAsync() 将等待 Promise 解析并返回其值。
用法
var searchValue = await frame.EvalOnSelectorAsync<string>("#search", "el => el.value");
var preloadHref = await frame.EvalOnSelectorAsync<string>("link[rel=preload]", "el => el.href");
var html = await frame.EvalOnSelectorAsync(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello");
参数
-
要查询的选择器。
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument? (可选)#要传递给 expression 的可选参数。
-
options
FrameEvalOnSelectorOptions?
(可选)
返回
- [object]#
EvalOnSelectorAllAsync
添加于:v1.9在大多数情况下,Locator.EvaluateAllAsync()、其他 Locator 辅助方法和 web-first 断言做得更好。
返回 expression 的返回值。
此方法在框架中查找与指定选择器匹配的所有元素,并将匹配元素的数组作为第一个参数传递给 expression。
如果 expression 返回一个 Promise,则 Frame.EvalOnSelectorAllAsync() 将等待 Promise 解析并返回其值。
用法
var divsCount = await frame.EvalOnSelectorAllAsync<bool>("div", "(divs, min) => divs.length >= min", 10);
参数
-
要查询的选择器。
-
要在浏览器上下文中计算的 JavaScript 表达式。如果表达式计算为函数,则该函数会自动调用。
-
arg
EvaluationArgument? (可选)#要传递给 expression 的可选参数。
返回
- [object]#
FillAsync
v1.9 之前添加请改用基于定位器的 Locator.FillAsync()。阅读有关 定位器 的更多信息。
此方法等待与 selector 匹配的元素,等待 可操作性 检查,聚焦元素,填充它,并在填充后触发 `input` 事件。请注意,您可以传入空字符串来清除输入字段。
如果目标元素不是 `<input>`、`<textarea>` 或 `[contenteditable]` 元素,此方法将抛出错误。但是,如果元素位于具有关联 control 的 `<label>` 元素内,则将填充该控件。
要发送细粒度的键盘事件,请使用 Locator.PressSequentiallyAsync()。
用法
await Frame.FillAsync(selector, value, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要填充
<input>
、<textarea>
或[contenteditable]
元素的值。 -
options
FrameFillOptions?
(可选)-
是否绕过可操作性检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
FocusAsync
v1.9 之前添加请改用基于定位器的 Locator.FocusAsync()。阅读有关 定位器 的更多信息。
此方法使用 selector 获取元素并聚焦它。如果没有元素与 selector 匹配,该方法会等待直到匹配的元素出现在 DOM 中。
用法
await Frame.FocusAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameFocusOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
GetAttributeAsync
v1.9 之前添加请改用基于定位器的 Locator.GetAttributeAsync()。阅读有关 定位器 的更多信息。
返回元素属性值。
用法
await Frame.GetAttributeAsync(selector, name, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要获取值的属性名称。
-
options
FrameGetAttributeOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
HoverAsync
v1.9 之前添加请改用基于定位器的 Locator.HoverAsync()。阅读有关 定位器 的更多信息。
此方法通过执行以下步骤悬停在与 selector 匹配的元素上
- 查找与 selector 匹配的元素。如果没有,则等待直到匹配的元素附加到 DOM。
- 在匹配元素上等待 可操作性 检查,除非设置了 Force 选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 悬停在元素的中心,或指定的 Position。
当所有步骤在指定的 Timeout 内未完成时,此方法会抛出 TimeoutError。传递零超时将禁用此功能。
用法
await Frame.HoverAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameHoverOptions?
(可选)-
是否绕过可操作性检查。默认为
false
。 -
Modifiers
IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }
> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后恢复当前修饰键。如果未指定,则使用当前按下的修饰键。“ControlOrMeta”在 Windows 和 Linux 上解析为“Control”,在 macOS 上解析为“Meta”。
-
NoWaitAfter
bool? (可选)新增于: v1.28#已弃用此选项无效。
此选项无效。
-
Position
Position? (可选)#-
X
[float] -
Y
[float]
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
设置后,此方法只执行 可操作性 检查并跳过操作。默认为 `false`。用于等待元素准备好执行操作而不执行它。请注意,无论 `trial` 如何,键盘 `modifiers` 都将被按下,以允许测试仅在这些键被按下时才可见的元素。
-
返回
InnerHTMLAsync
v1.9 之前添加请改用基于定位器的 Locator.InnerHTMLAsync()。阅读有关 定位器 的更多信息。
返回 element.innerHTML
。
用法
await Frame.InnerHTMLAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameInnerHTMLOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
InnerTextAsync
v1.9 之前添加请改用基于定位器的 Locator.InnerTextAsync()。阅读有关 定位器 的更多信息。
返回 element.innerText
。
用法
await Frame.InnerTextAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameInnerTextOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
InputValueAsync
添加于:v1.13请改用基于定位器的 Locator.InputValueAsync()。阅读有关 定位器 的更多信息。
返回选定的 <input>
、<textarea>
或 <select>
元素的 input.value
。
对于非输入元素,将抛出错误。但是,如果元素位于具有关联 控制 的 `<label>` 元素内,则返回控制的值。
用法
await Frame.InputValueAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameInputValueOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
IsCheckedAsync
v1.9 之前添加请改用基于定位器的 Locator.IsCheckedAsync()。阅读有关 定位器 的更多信息。
返回元素是否已选中。如果元素不是复选框或单选输入,则抛出异常。
用法
await Frame.IsCheckedAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameIsCheckedOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
IsDisabledAsync
v1.9 之前添加请改用基于定位器的 Locator.IsDisabledAsync()。阅读有关 定位器 的更多信息。
返回元素是否已禁用,与 enabled 相反。
用法
await Frame.IsDisabledAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameIsDisabledOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
IsEditableAsync
v1.9 之前添加请改用基于定位器的 Locator.IsEditableAsync()。阅读有关 定位器 的更多信息。
返回元素是否 可编辑。
用法
await Frame.IsEditableAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameIsEditableOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
IsHiddenAsync
v1.9 之前添加请改用基于定位器的 Locator.IsHiddenAsync()。阅读有关 定位器 的更多信息。
返回元素是否隐藏,与 可见 相反。不匹配任何元素的 selector 被认为是隐藏的。
用法
await Frame.IsHiddenAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameIsHiddenOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#已弃用此选项被忽略。Frame.IsHiddenAsync() 不会等待元素变为隐藏,并立即返回。
-
返回
IsVisibleAsync
v1.9 之前添加请改用基于定位符的 Locator.IsVisibleAsync()。了解更多关于定位符的信息。
返回元素是否 可见。不匹配任何元素的 selector 被认为不可见。
用法
await Frame.IsVisibleAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameIsVisibleOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#已弃用此选项被忽略。Frame.IsVisibleAsync() 不会等待元素变为可见,并立即返回。
-
返回
PressAsync
v1.9 之前添加请改用基于定位符的 Locator.PressAsync()。了解更多关于定位符的信息。
keyboardEvent.key 可以指定预期的 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.PressAsync(selector, key, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要按下的键的名称或要生成的字符,例如
ArrowLeft
或a
。 -
options
FramePressOptions?
(可选)-
Delay
[float]? (可选)#keydown
和keyup
之间等待的时间(毫秒)。默认为 0。 -
已弃用
此选项将来默认为
true
。启动导航的操作正在等待这些导航发生并且页面开始加载。您可以通过设置此标志选择不等待。只有在导航到无法访问的页面等特殊情况下才需要此选项。默认为 `false`。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
QuerySelectorAsync
添加于:v1.9请改用基于定位器的 Frame.Locator()。阅读更多关于 定位器 的信息。
返回指向框架元素的 ElementHandle。
不推荐使用 ElementHandle,请改用 Locator 对象和 Web 优先断言。
该方法在框架中查找与指定选取器匹配的元素。如果没有元素匹配选取器,则返回 null
。
用法
await Frame.QuerySelectorAsync(selector, options);
参数
-
要查询的选择器。
-
options
FrameQuerySelectorOptions?
(可选)
返回
QuerySelectorAllAsync
添加于:v1.9请改用基于定位器的 Frame.Locator()。阅读更多关于 定位器 的信息。
返回指向框架元素的 ElementHandles。
不推荐使用 ElementHandle,请改用 Locator 对象。
该方法在框架中查找与指定选择器匹配的所有元素。如果没有元素匹配选择器,则返回空数组。
用法
await Frame.QuerySelectorAllAsync(selector);
参数
返回
RunAndWaitForNavigationAsync
v1.9 之前添加此方法本身存在竞态条件,请改用Frame.WaitForURLAsync()。
等待框架导航并返回主资源响应。如果存在多次重定向,导航将解析为最后一次重定向的响应。如果导航到不同的锚点或由于历史记录API使用而导航,则导航将解析为null
。
用法
此方法等待帧导航到新 URL。当您运行间接导致帧导航的代码时,此方法非常有用。请考虑以下示例:
await frame.RunAndWaitForNavigationAsync(async () =>
{
// Clicking the link will indirectly cause a navigation.
await frame.ClickAsync("a.delayed-navigation");
});
// Resolves after navigation has finished
使用 History API 更改 URL 被视为导航。
参数
-
触发事件的操作。
-
options
FrameRunAndWaitForNavigationOptions?
(可选)-
Timeout
[float]? (可选)#最大操作时间(毫秒),默认为 30 秒,传递
0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
Url|UrlRegex|UrlFunc
string? | Regex? | Func<string?, bool> (可选)#一个 glob 模式、正则表达式模式或接收 URL 的谓词,用于在等待导航时进行匹配。请注意,如果参数是没有通配符的字符串,则该方法将等待导航到与该字符串完全相等的 URL。
-
WaitUntil
enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }?
(可选)#何时认为操作成功,默认为
load
。事件可以是以下之一'domcontentloaded'
- 当DOMContentLoaded
事件触发时,认为操作完成。'load'
- 当load
事件触发时,认为操作完成。'networkidle'
- 不建议 当至少500
毫秒内没有网络连接时,认为操作完成。不要使用此方法进行测试,请改用 Web 断言来评估准备情况。'commit'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回
WaitForNavigationAsync
v1.9 之前添加此方法本身存在竞态条件,请改用Frame.WaitForURLAsync()。
等待框架导航并返回主资源响应。如果存在多次重定向,导航将解析为最后一次重定向的响应。如果导航到不同的锚点或由于历史记录API使用而导航,则导航将解析为null
。
用法
此方法等待帧导航到新 URL。当您运行间接导致帧导航的代码时,此方法非常有用。请考虑以下示例:
await frame.RunAndWaitForNavigationAsync(async () =>
{
// Clicking the link will indirectly cause a navigation.
await frame.ClickAsync("a.delayed-navigation");
});
// Resolves after navigation has finished
使用 History API 更改 URL 被视为导航。
参数
options
FrameRunAndWaitForNavigationOptions?
(可选)-
Timeout
[float]? (可选)#最大操作时间(毫秒),默认为 30 秒,传递
0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
Url|UrlRegex|UrlFunc
string? | Regex? | Func<string?, bool> (可选)#一个 glob 模式、正则表达式模式或接收 URL 的谓词,用于在等待导航时进行匹配。请注意,如果参数是没有通配符的字符串,则该方法将等待导航到与该字符串完全相等的 URL。
-
WaitUntil
enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }?
(可选)#何时认为操作成功,默认为
load
。事件可以是以下之一'domcontentloaded'
- 当DOMContentLoaded
事件触发时,认为操作完成。'load'
- 当load
事件触发时,认为操作完成。'networkidle'
- 不建议 当至少500
毫秒内没有网络连接时,认为操作完成。不要使用此方法进行测试,请改用 Web 断言来评估准备情况。'commit'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回
SelectOptionAsync
v1.9 之前添加请改用基于定位符的 Locator.SelectOptionAsync()。了解更多关于定位符的信息。
此方法等待与选择器匹配的元素,等待可操作性检查,等待所有指定的选项都存在于<select>
元素中,然后选择这些选项。
如果目标元素不是<select>
元素,则此方法会抛出错误。但是,如果该元素位于具有关联控件的<label>
元素内部,则将改用该控件。
返回已成功选择的选项值数组。
一旦所有提供的选项都已选中,将触发 change
和 input
事件。
用法
// Single selection matching the value or label
await frame.SelectOptionAsync("select#colors", new[] { "blue" });
// single selection matching both the value and the label
await frame.SelectOptionAsync("select#colors", new[] { new SelectOptionValue() { Label = "blue" } });
// multiple selection
await frame.SelectOptionAsync("select#colors", new[] { "red", "green", "blue" });
参数
-
要查询的选择器。
-
values
string | ElementHandle | IEnumerable |SelectOption
| IEnumerable | IEnumerable?#-
Value
string? (可选)按
option.value
匹配。可选。 -
Label
string? (可选)按
option.label
匹配。可选。 -
Index
int? (可选)按索引匹配。可选。
要选择的选项。如果
<select>
具有multiple
属性,则选择所有匹配的选项,否则只选择与传入选项之一匹配的第一个选项。字符串值同时匹配值和标签。如果所有指定属性都匹配,则认为选项匹配。 -
-
options
FrameSelectOptionOptions?
(可选)-
是否绕过可操作性检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
SetCheckedAsync
新增于: v1.15请改用基于定位符的 Locator.SetCheckedAsync()。了解更多关于定位符的信息。
此方法通过执行以下步骤来选中或取消选中与选择器匹配的元素
- 查找与选择器匹配的元素。如果没有,则等待匹配的元素附加到DOM。
- 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出错误。
- 如果元素已经处于正确的选中状态,此方法将立即返回。
- 对匹配的元素执行可操作性检查,除非设置了Force选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 点击元素的中心。
- 确保元素现在已选中或未选中。如果不是,此方法将抛出异常。
当所有步骤在指定的超时时间内未完成时,此方法将抛出TimeoutError。传递零超时会禁用此功能。
用法
await Frame.SetCheckedAsync(selector, checked, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
是否选中或取消选中复选框。
-
options
FrameSetCheckedOptions?
(可选)-
是否绕过可操作性检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
Position
Position? (可选)#-
X
[float] -
Y
[float]
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
设置后,此方法仅执行可操作性检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。
-
返回
SetInputFilesAsync
v1.9 之前添加请改用基于定位符的 Locator.SetInputFilesAsync()。了解更多关于定位符的信息。
将文件输入的值设置为这些文件路径或文件。如果某些 filePaths
是相对路径,则它们相对于当前工作目录解析。对于空数组,清除选定的文件。
此方法期望选择器指向输入元素。但是,如果该元素位于具有关联控件的<label>
元素内部,则改为指向该控件。
用法
await Frame.SetInputFilesAsync(selector, files, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
files
string | IEnumerable<string> |FilePayload
| IEnumerable<FilePayload
># -
options
FrameSetInputFilesOptions?
(可选)-
已弃用
此选项无效。
此选项无效。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
TapAsync
v1.9 之前添加请改用基于定位符的 Locator.TapAsync()。了解更多关于定位符的信息。
此方法通过执行以下步骤来点击与选择器匹配的元素
- 查找与选择器匹配的元素。如果没有,则等待匹配的元素附加到DOM。
- 对匹配的元素执行可操作性检查,除非设置了Force选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用Page.Touchscreen点击元素的中心,或指定的Position。
当所有步骤在指定的超时时间内未完成时,此方法将抛出TimeoutError。传递零超时会禁用此功能。
frame.tap()
要求浏览器上下文的 hasTouch
选项设置为 true。
用法
await Frame.TapAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameTapOptions?
(可选)-
是否绕过可操作性检查。默认为
false
。 -
Modifiers
IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }
> (可选)#要按下的修饰键。确保在操作期间只按下这些修饰键,然后恢复当前修饰键。如果未指定,则使用当前按下的修饰键。“ControlOrMeta”在 Windows 和 Linux 上解析为“Control”,在 macOS 上解析为“Meta”。
-
已弃用
此选项无效。
此选项无效。
-
Position
Position? (可选)#-
X
[float] -
Y
[float]
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
设置后,此方法只执行 可操作性 检查并跳过操作。默认为 `false`。用于等待元素准备好执行操作而不执行它。请注意,无论 `trial` 如何,键盘 `modifiers` 都将被按下,以允许测试仅在这些键被按下时才可见的元素。
-
返回
TextContentAsync
v1.9 之前添加请改用基于定位符的 Locator.TextContentAsync()。了解更多关于定位符的信息。
返回 element.textContent
。
用法
await Frame.TextContentAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameTextContentOptions?
(可选)-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
TypeAsync
v1.9 之前添加在大多数情况下,您应该使用Locator.FillAsync()。只有当页面上有特殊的键盘处理时,您才需要一个一个地按下键 - 在这种情况下,请使用Locator.PressSequentiallyAsync()。
为文本中的每个字符发送一个keydown
、keypress
/input
和keyup
事件。frame.type
可用于发送细粒度的键盘事件。要在表单字段中填充值,请使用Frame.FillAsync()。
要按特殊键,例如 Control
或 ArrowDown
,请使用 Keyboard.PressAsync()。
用法
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
要输入到聚焦元素的文本。
-
options
FrameTypeOptions?
(可选)-
Delay
[float]? (可选)#按键之间等待的时间,以毫秒为单位。默认为 0。
-
已弃用
此选项无效。
此选项无效。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
UncheckAsync
v1.9 之前添加请改用基于定位符的 Locator.UncheckAsync()。了解更多关于定位符的信息。
此方法通过执行以下步骤来取消选中与选择器匹配的元素
- 查找与选择器匹配的元素。如果没有,则等待匹配的元素附加到DOM。
- 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出错误。如果元素已取消选中,此方法会立即返回。
- 对匹配的元素执行可操作性检查,除非设置了Force选项。如果在检查期间元素被分离,则整个操作将重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 点击元素的中心。
- 确保元素现在未选中。如果不是,此方法将抛出异常。
当所有步骤在指定的超时时间内未完成时,此方法将抛出TimeoutError。传递零超时会禁用此功能。
用法
await Frame.UncheckAsync(selector, options);
参数
-
用于搜索元素的选取器。如果有多个元素满足选取器,则使用第一个。
-
options
FrameUncheckOptions?
(可选)-
是否绕过可操作性检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
Position
Position? (可选)添加于:v1.11#-
X
[float] -
Y
[float]
相对于元素填充框左上角的点。如果未指定,则使用元素的某个可见点。
-
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
设置后,此方法仅执行可操作性检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备好进行操作很有用。
-
返回
WaitForSelectorAsync
v1.9 之前添加请改用断言可见性的 Web 断言或基于定位符的 Locator.WaitForAsync()。了解更多关于定位符的信息。
当由选择器指定的元素满足State选项时返回。如果等待hidden
或detached
,则返回null
。
Playwright 会在执行操作前自动等待元素准备就绪。使用Locator对象和 Web-first 断言可以使代码无需等待选择器。
等待选择器满足状态选项(从DOM中出现/消失,或变为可见/隐藏)。如果在调用方法时选择器已满足条件,则方法将立即返回。如果选择器在超时毫秒内不满足条件,则函数将抛出错误。
用法
此方法适用于跨导航
using Microsoft.Playwright;
using System;
using System.Threading.Tasks;
class FrameExamples
{
public static async Task Main()
{
using var playwright = await Playwright.CreateAsync();
await using var browser = await playwright.Chromium.LaunchAsync();
var page = await browser.NewPageAsync();
foreach (var currentUrl in new[] { "https://www.google.com", "https://bbc.com" })
{
await page.GotoAsync(currentUrl);
element = await page.MainFrame.WaitForSelectorAsync("img");
Console.WriteLine($"Loaded image: {await element.GetAttributeAsync("src")}");
}
}
}
参数
-
要查询的选择器。
-
options
FrameWaitForSelectorOptions?
(可选)-
State
enum WaitForSelectorState { Attached, Detached, Visible, Hidden }?
(可选)#默认为
'visible'
。可以是以下之一:'attached'
- 等待元素出现在 DOM 中。'detached'
- 等待元素不在 DOM 中。'visible'
- 等待元素具有非空的边界框且没有visibility:hidden
。请注意,没有任何内容或具有display:none
的元素具有空的边界框,不被视为可见。'hidden'
- 等待元素从 DOM 中分离,或具有空的边界框或visibility:hidden
。这与'visible'
选项相反。
-
如果为 true,则调用要求选择器解析为单个元素。如果给定选择器解析为多个元素,则调用会抛出异常。
-
Timeout
[float]? (可选)#最大时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回
WaitForTimeoutAsync
v1.9 之前添加在生产环境中切勿等待超时。等待时间的测试本身就不可靠。使用会自动等待的Locator操作和 Web 断言。
等待给定的超时(毫秒)。
请注意,frame.waitForTimeout()
只能用于调试。在生产环境中使用计时器的测试将会不稳定。请改用网络事件、选择器变为可见等信号。
用法
await Frame.WaitForTimeoutAsync(timeout);
参数
-
timeout
[float]#要等待的超时时间。
返回