Page
Page 提供了与 Browser 中的单个标签页或 Chromium 中的 扩展程序后台页面 进行交互的方法。一个 Browser 实例可以有多个 Page 实例。
此示例创建一个页面,导航到 URL,然后保存屏幕截图
using Microsoft.Playwright;
using System.Threading.Tasks;
class PageExamples
{
public static async Task Run()
{
using var playwright = await Playwright.CreateAsync();
await using var browser = await playwright.Webkit.LaunchAsync();
var page = await browser.NewPageAsync();
await page.GotoAsync("https://www.theverge.com");
await page.ScreenshotAsync(new() { Path = "theverge.png" });
}
}
Page 类会发出各种事件(如下所述),可以使用 Node 的任何原生 EventEmitter
方法来处理,例如 on
、once
或 removeListener
。
此示例为单个页面 load
事件记录一条消息
page.Load += (_, _) => Console.WriteLine("Page loaded!");
要取消订阅事件,请使用 removeListener
方法
void PageLoadHandler(object _, IPage p) {
Console.WriteLine("Page loaded!");
};
page.Load += PageLoadHandler;
// Do some work...
page.Load -= PageLoadHandler;
方法
AddInitScriptAsync
在 v1.9 之前添加添加一个脚本,该脚本将在以下场景之一中执行
- 每次导航到页面时。
- 每次附加或导航子框架时。在这种情况下,脚本将在新附加的框架上下文中执行。
脚本在文档创建后但在任何其他脚本运行前执行。这对于修改 JavaScript 环境很有用,例如为 Math.random
设置种子。
用法
在页面加载前覆盖 Math.random
的示例
// preload.js
Math.random = () => 42;
await Page.AddInitScriptAsync(scriptPath: "./preload.js");
通过 BrowserContext.AddInitScriptAsync() 和 Page.AddInitScriptAsync() 安装的多个脚本的执行顺序未定义。
参数
返回值
AddLocatorHandlerAsync
添加于:v1.42测试网页时,有时会出现意料之外的覆盖层,如“注册”对话框,它们会阻止您想要自动化的操作,例如点击按钮。这些覆盖层不会总是以相同的方式或在同一时间出现,这使得它们在自动化测试中难以处理。
此方法允许您设置一个特殊函数(称为处理程序),当检测到覆盖层可见时,它会被激活。处理程序的任务是移除覆盖层,让您的测试可以继续进行,就像覆盖层不存在一样。
注意事项
- 当覆盖层可预测地出现时,我们建议在测试中显式等待并将其作为常规测试流程的一部分进行关闭,而不是使用 Page.AddLocatorHandlerAsync()。
- Playwright 在每次执行或重试需要进行可操作性检查的操作之前,或在执行自动等待断言检查之前,都会检查覆盖层。当覆盖层可见时,Playwright 会首先调用处理程序,然后继续执行操作/断言。请注意,处理程序仅在您执行操作/断言时调用 - 如果覆盖层可见但您不执行任何操作,则不会触发处理程序。
- 执行处理程序后,Playwright 会确保触发处理程序的覆盖层不再可见。您可以使用 NoWaitAfter 选项取消此行为。
- 处理程序的执行时间会计入执行处理程序的操作/断言的超时时间。如果您的处理程序耗时过长,可能会导致超时。
- 您可以注册多个处理程序。但是,一次只能运行一个处理程序。请确保处理程序中的操作不依赖于其他处理程序。
运行处理程序会改变您的页面状态(测试中途)。例如,它会改变当前聚焦的元素并移动鼠标。请确保处理程序之后运行的操作是独立的,并且不依赖于焦点和鼠标状态未改变。
例如,考虑一个测试,它先调用 Locator.FocusAsync(),然后调用 Keyboard.PressAsync()。如果您的处理程序在两次操作之间点击了一个按钮,那么聚焦的元素很可能是不正确的,并且按键操作将发生在意外的元素上。建议改用 Locator.PressAsync() 来避免此问题。
另一个示例是鼠标操作系列,其中 Mouse.MoveAsync() 之后是 Mouse.DownAsync()。同样,当处理程序在这两个操作之间运行时,鼠标在按下期间的位置将是错误的。更倾向于使用 Locator.ClickAsync() 等独立的动作,这些动作不依赖于处理程序不改变状态。
用法
出现“订阅时事通讯”对话框时关闭它的示例
// Setup the handler.
await page.AddLocatorHandlerAsync(page.GetByText("Sign up to the newsletter"), async () => {
await page.GetByRole(AriaRole.Button, new() { Name = "No thanks" }).ClickAsync();
});
// Write the test as usual.
await page.GotoAsync("https://example.com");
await page.GetByRole("button", new() { Name = "Start here" }).ClickAsync();
显示“确认您的安全详细信息”页面时跳过它的示例
// Setup the handler.
await page.AddLocatorHandlerAsync(page.GetByText("Confirm your security details"), async () => {
await page.GetByRole(AriaRole.Button, new() { Name = "Remind me later" }).ClickAsync();
});
// Write the test as usual.
await page.GotoAsync("https://example.com");
await page.GetByRole("button", new() { Name = "Start here" }).ClickAsync();
一个示例,其中在每次可操作性检查时都有一个自定义回调。它使用始终可见的 <body>
定位符,因此在每次可操作性检查之前都会调用处理程序。指定 NoWaitAfter 很重要,因为处理程序不会隐藏 <body>
元素。
// Setup the handler.
await page.AddLocatorHandlerAsync(page.Locator("body"), async () => {
await page.EvaluateAsync("window.removeObstructionsForTestIfNeeded()");
}, new() { NoWaitAfter = true });
// Write the test as usual.
await page.GotoAsync("https://example.com");
await page.GetByRole("button", new() { Name = "Start here" }).ClickAsync();
处理程序将原始定位符作为参数。您还可以通过设置 Times 选项在一定次数的调用后自动移除处理程序。
await page.AddLocatorHandlerAsync(page.GetByText("Sign up to the newsletter"), async locator => {
await locator.ClickAsync();
}, new() { Times = 1 });
参数
-
触发处理程序的定位符。
-
当 locator 出现时应运行的函数。此函数应移除阻止点击等操作的元素。
-
options
PageAddLocatorHandlerOptions?
(可选)
返回值
AddScriptTagAsync
在 v1.9 之前添加将一个 <script>
标签添加到页面中,其中包含所需的 URL 或内容。当脚本的 onload 事件触发或脚本内容被注入到框架中时,返回添加的标签。
用法
await Page.AddScriptTagAsync(options);
参数
options
PageAddScriptTagOptions?
(可选)
返回值
AddStyleTagAsync
在 v1.9 之前添加将一个 <link rel="stylesheet">
标签(包含所需 URL)或一个 <style type="text/css">
标签(包含内容)添加到页面中。当样式表的 onload 事件触发或 CSS 内容被注入到框架中时,返回添加的标签。
用法
await Page.AddStyleTagAsync(options);
参数
options
PageAddStyleTagOptions?
(可选)
返回值
BringToFrontAsync
在 v1.9 之前添加将页面带到最前面(激活标签页)。
用法
await Page.BringToFrontAsync();
返回值
CloseAsync
在 v1.9 之前添加如果 RunBeforeUnload 为 false
,则不运行任何 unload 处理程序并等待页面关闭。如果 RunBeforeUnload 为 true
,该方法将运行 unload 处理程序,但**不会**等待页面关闭。
默认情况下,page.close()
**不会**运行 beforeunload
处理程序。
如果 RunBeforeUnload 传递为 true,可能会触发 beforeunload 对话框,应通过 Page.Dialog 事件手动处理。
用法
await Page.CloseAsync(options);
参数
options
PageCloseOptions?
(可选)-
报告给因页面关闭而中断的操作的原因。
-
默认为
false
。是否运行 before unload 页面处理程序。
-
返回值
ContentAsync
在 v1.9 之前添加获取页面的完整 HTML 内容,包括 doctype。
用法
await Page.ContentAsync();
返回值
Context
在 v1.9 之前添加获取页面所属的浏览器上下文。
用法
Page.Context
返回值
DragAndDropAsync
添加于:v1.13此方法将源元素拖动到目标元素。它将首先移动到源元素,执行 mousedown
操作,然后移动到目标元素并执行 mouseup
操作。
用法
await Page.DragAndDropAsync("#source", "#target");
// or specify exact positions relative to the top-left corners of the elements:
await Page.DragAndDropAsync("#source", "#target", new()
{
SourcePosition = new() { X = 34, Y = 7 },
TargetPosition = new() { X = 10, Y = 20 },
});
参数
-
用于搜索要拖动的元素的 CSS 选择器。如果存在多个符合选择器的元素,将使用第一个。
-
用于搜索要放置元素的 CSS 选择器。如果存在多个符合选择器的元素,将使用第一个。
-
options
PageDragAndDropOptions?
(可选)-
是否绕过可操作性检查。默认为
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
。这对于等待元素准备好进行操作而无需实际执行操作很有用。
-
返回值
EmulateMediaAsync
在 v1.9 之前添加此方法通过 media
参数更改 CSS 媒体类型
,并/或使用 colorScheme
参数更改“prefers-colors-scheme
”媒体特性。
用法
await page.EvaluateAsync("() => matchMedia('screen').matches");
// → true
await page.EvaluateAsync("() => matchMedia('print').matches");
// → false
await page.EmulateMediaAsync(new() { Media = Media.Print });
await page.EvaluateAsync("() => matchMedia('screen').matches");
// → false
await page.EvaluateAsync("() => matchMedia('print').matches");
// → true
await page.EmulateMediaAsync(new() { Media = Media.Screen });
await page.EvaluateAsync("() => matchMedia('screen').matches");
// → true
await page.EvaluateAsync("() => matchMedia('print').matches");
// → false
await page.EmulateMediaAsync(new() { ColorScheme = ColorScheme.Dark });
await page.EvaluateAsync("matchMedia('(prefers-color-scheme: dark)').matches");
// → true
await page.EvaluateAsync("matchMedia('(prefers-color-scheme: light)').matches");
// → false
参数
options
PageEmulateMediaOptions?
(可选)-
ColorScheme
enum ColorScheme { Light, Dark, NoPreference, Null }?
(可选)添加于:v1.9#模拟 prefers-colors-scheme 媒体特性,支持的值为
'light'
和'dark'
。传递'Null'
会禁用颜色方案模拟。'no-preference'
已弃用。 -
Contrast
enum Contrast { NoPreference, More, Null }?
(可选)添加于:v1.51# -
ForcedColors
enum ForcedColors { Active, None, Null }?
(可选)添加于:v1.15# -
Media
enum Media { Screen, Print, Null }?
(可选)添加于:v1.9#更改页面的 CSS 媒体类型。唯一允许的值是
'Screen'
、'Print'
和'Null'
。传递'Null'
会禁用 CSS 媒体模拟。 -
ReducedMotion
enum ReducedMotion { Reduce, NoPreference, Null }?
(可选)添加于:v1.12#模拟
'prefers-reduced-motion'
媒体特性,支持的值为'reduce'
、'no-preference'
。传递 null 会禁用减少动画模拟。
-
返回值
EvaluateAsync
在 v1.9 之前添加返回 expression 调用的值。
如果传递给 Page.EvaluateAsync() 的函数返回一个 Promise,则 Page.EvaluateAsync() 将等待 Promise 解析并返回其值。
如果传递给 Page.EvaluateAsync() 的函数返回一个不可Serializable 值,则 Page.EvaluateAsync() 将解析为 undefined
。Playwright 还支持传输一些 JSON 无法序列化的额外值:-0
、NaN
、Infinity
、-Infinity
。
用法
将参数传递给 expression
var result = await page.EvaluateAsync<int>("([x, y]) => Promise.resolve(x * y)", new[] { 7, 8 });
Console.WriteLine(result);
也可以传入字符串而不是函数
Console.WriteLine(await page.EvaluateAsync<int>("1 + 2")); // prints "3"
ElementHandle 实例可以作为参数传递给 Page.EvaluateAsync()
var bodyHandle = await page.EvaluateAsync("document.body");
var html = await page.EvaluateAsync<string>("([body, suffix]) => body.innerHTML + suffix", new object [] { bodyHandle, "hello" });
await bodyHandle.DisposeAsync();
参数
-
要在浏览器上下文中执行的 JavaScript 表达式。如果 expression 解析为函数,则该函数将自动调用。
-
arg
EvaluationArgument? (可选)#要传递给 expression 的可选参数。
返回值
- [object]#
EvaluateHandleAsync
在 v1.9 之前添加返回 expression 调用的值作为 JSHandle。
Page.EvaluateAsync() 和 Page.EvaluateHandleAsync() 之间的唯一区别是 Page.EvaluateHandleAsync() 返回 JSHandle。
如果传递给 Page.EvaluateHandleAsync() 的函数返回一个 Promise,则 Page.EvaluateHandleAsync() 将等待 Promise 解析并返回其值。
用法
// Handle for the window object.
var aWindowHandle = await page.EvaluateHandleAsync("() => Promise.resolve(window)");
也可以传入字符串而不是函数
var docHandle = await page.EvaluateHandleAsync("document"); // Handle for the `document`
JSHandle 实例可以作为参数传递给 Page.EvaluateHandleAsync()
var handle = await page.EvaluateHandleAsync("() => document.body");
var resultHandle = await page.EvaluateHandleAsync("([body, suffix]) => body.innerHTML + suffix", new object[] { handle, "hello" });
Console.WriteLine(await resultHandle.JsonValueAsync<string>());
await resultHandle.DisposeAsync();
参数
-
要在浏览器上下文中执行的 JavaScript 表达式。如果 expression 解析为函数,则该函数将自动调用。
-
arg
EvaluationArgument? (可选)#要传递给 expression 的可选参数。
返回值
ExposeBindingAsync
在 v1.9 之前添加此方法在页面中每个框架的 window
对象上添加一个名为 name 的函数。调用时,该函数将执行 callback 并返回一个 Promise,该 Promise 将解析为 callback 的返回值。如果 callback 返回一个 Promise,它将被等待。
callback 函数的第一个参数包含调用者的信息:{ browserContext: BrowserContext, page: Page, frame: Frame }
。
有关上下文范围的版本,请参阅 BrowserContext.ExposeBindingAsync()。
通过 Page.ExposeBindingAsync() 安装的函数在导航后仍然有效。
用法
将页面 URL 暴露给页面中所有框架的示例
using Microsoft.Playwright;
using System.Threading.Tasks;
class PageExamples
{
public static async Task Main()
{
using var playwright = await Playwright.CreateAsync();
await using var browser = await playwright.Webkit.LaunchAsync(new()
{
Headless = false,
});
var page = await browser.NewPageAsync();
await page.ExposeBindingAsync("pageUrl", (source) => source.Page.Url);
await page.SetContentAsync("<script>\n" +
" async function onClick() {\n" +
" document.querySelector('div').textContent = await window.pageURL();\n" +
" }\n" +
"</script>\n" +
"<button onclick=\"onClick()\">Click me</button>\n" +
"<div></div>");
await page.ClickAsync("button");
}
}
参数
-
window 对象上的函数名称。
-
callback
Action<BindingSource, T, [TResult]>#将在 Playwright 上下文中调用的回调函数。
-
options
PageExposeBindingOptions?
(可选)
返回值
ExposeFunctionAsync
在 v1.9 之前添加此方法在页面的每个框架的 window
对象上添加一个名为 name 的函数。调用时,该函数将执行 callback 并返回一个 Promise,该 Promise 将解析为 callback 的返回值。
如果 callback 返回一个 Promise,它将被等待。
有关上下文范围的暴露函数,请参阅 BrowserContext.ExposeFunctionAsync()。
通过 Page.ExposeFunctionAsync() 安装的函数在导航后仍然有效。
用法
向页面添加 sha256 函数的示例
using Microsoft.Playwright;
using System;
using System.Security.Cryptography;
using System.Threading.Tasks;
class PageExamples
{
public static async Task Main()
{
using var playwright = await Playwright.CreateAsync();
await using var browser = await playwright.Webkit.LaunchAsync(new()
{
Headless = false
});
var page = await browser.NewPageAsync();
await page.ExposeFunctionAsync("sha256", (string input) =>
{
return Convert.ToBase64String(
SHA256.Create().ComputeHash(System.Text.Encoding.UTF8.GetBytes(input)));
});
await page.SetContentAsync("<script>\n" +
" async function onClick() {\n" +
" document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');\n" +
" }\n" +
"</script>\n" +
"<button onclick=\"onClick()\">Click me</button>\n" +
"<div></div>");
await page.ClickAsync("button");
Console.WriteLine(await page.TextContentAsync("div"));
}
}
参数
返回值
Frame
在 v1.9 之前添加返回与指定条件匹配的框架。必须指定 name 或 url。
用法
var frame = page.Frame("frame-name");
var frame = page.FrameByUrl(".*domain.*");
参数
返回值
FrameByUrl
添加于:v1.9返回具有匹配 URL 的框架。
用法
Page.FrameByUrl(url);
参数
返回值
FrameLocator
添加于: v1.17使用 iframe 时,可以创建一个框架定位器,该定位器将进入 iframe 并允许在该 iframe 中选择元素。
用法
以下代码片段将在 id 为 my-frame
的 iframe 中定位文本为 "Submit" 的元素,例如 <iframe id="my-frame">
var locator = page.FrameLocator("#my-iframe").GetByText("Submit");
await locator.ClickAsync();
参数
返回值
Frames
在 v1.9 之前添加附加到页面的所有框架的数组。
用法
Page.Frames
返回值
GetByAltText
添加于: v1.27允许通过元素的 alt 文本定位元素。
用法
例如,此方法将通过 alt 文本 "Playwright logo" 查找图像。
<img alt='Playwright logo'>
await page.GetByAltText("Playwright logo").ClickAsync();
参数
-
用于定位元素的文本。
-
options
PageGetByAltTextOptions?
(可选)
返回值
GetByLabel
添加于: v1.27允许通过关联的 <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").FillAsync("john");
await page.GetByLabel("Password").FillAsync("secret");
参数
-
用于定位元素的文本。
-
options
PageGetByLabelOptions?
(可选)
返回值
GetByPlaceholder
添加于: v1.27允许通过占位符文本定位输入元素。
用法
例如,考虑以下 DOM 结构。
<input type="email" placeholder="name@example.com" />
在通过占位符文本定位输入框后,可以填充它。
await page
.GetByPlaceholder("name@example.com")
.FillAsync("playwright@microsoft.com");
参数
-
用于定位元素的文本。
-
options
PageGetByPlaceholderOptions?
(可选)
返回值
GetByRole
添加于: v1.27允许通过元素的 ARIA role、ARIA attribute 和 可访问名称定位元素。
用法
考虑以下 DOM 结构。
<h3>Sign up</h3>
<label>
<input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>
可以通过元素的隐式 role 定位每个元素。
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 role。
-
options
PageGetByRoleOptions?
(可选)-
通常由
aria-checked
或原生<input type=checkbox>
控件设置的属性。了解更多关于
aria-checked
。 -
通常由
aria-disabled
或disabled
设置的属性。注意与大多数其他属性不同,
disabled
通过 DOM 层级结构继承。了解更多关于aria-disabled
。 -
是否 Name|NameRegex 精确匹配:区分大小写且匹配整个字符串。默认为 false。当 Name|NameRegex 是正则表达式时忽略。请注意,精确匹配仍会修剪空白字符。
-
通常由
aria-expanded
设置的属性。了解更多关于
aria-expanded
。 -
控制是否匹配隐藏元素的选项。默认情况下,只有根据 ARIA 定义的非隐藏元素会由 role 选择器匹配。
了解更多关于
aria-hidden
。 -
通常存在于 role
heading
、listitem
、row
、treeitem
的数值属性,对于<h1>-<h6>
元素具有默认值。了解更多关于
aria-level
。 -
Name|NameRegex
string? | Regex? (可选)#匹配可访问名称的选项。默认情况下,匹配不区分大小写并搜索子字符串,使用Exact来控制此行为。
了解更多关于可访问名称。
-
通常由
aria-pressed
设置的属性。了解更多关于
aria-pressed
。 -
通常由
aria-selected
设置的属性。了解更多关于
aria-selected
。
-
返回值
详情
Role 选择器不能替代可访问性审计和一致性测试,但可以为 ARIA 指南提供早期反馈。
许多 HTML 元素具有隐式定义的 role,role 选择器可以识别这些 role。可以在此处找到所有支持的 role。ARIA 指南不建议通过将 role
和/或 aria-*
属性设置为默认值来重复隐式 role 和属性。
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(),它允许按其他条件(例如可访问 role)匹配,然后按文本内容进行筛选。
用法
考虑以下 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
PageGetByTextOptions?
(可选)
返回值
详情
按文本匹配总是会规范化空白字符,即使是精确匹配。例如,它将多个空格变成一个,将换行符变成空格,并忽略前导和尾随空白字符。
类型为 button
和 submit
的输入元素是按其 value
匹配,而不是按文本内容。例如,按文本 "Log in"
定位会匹配 <input type=button value="Log in">
。
GetByTitle
添加于: v1.27允许通过元素的 title 属性定位元素。
用法
考虑以下 DOM 结构。
<span title='Issues count'>25 issues</span>
在通过 title 文本定位它之后,可以检查问题计数。
await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");
参数
-
用于定位元素的文本。
-
options
PageGetByTitleOptions?
(可选)
返回值
GoBackAsync
在 v1.9 之前添加返回主资源响应。在多次重定向的情况下,导航将解析为最后一次重定向的响应。如果无法后退,则返回 null
。
导航到历史记录中的上一页。
用法
await Page.GoBackAsync(options);
参数
options
PageGoBackOptions?
(可选)-
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'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回值
GoForwardAsync
在 v1.9 之前添加返回主资源响应。在多次重定向的情况下,导航将解析为最后一次重定向的响应。如果无法前进,则返回 null
。
导航到历史记录中的下一页。
用法
await Page.GoForwardAsync(options);
参数
options
PageGoForwardOptions?
(可选)-
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'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回值
GotoAsync
在 v1.9 之前添加返回主资源响应。在多次重定向的情况下,导航将解析为第一个非重定向响应。
如果出现以下情况,该方法将抛出错误:
- 出现 SSL 错误 (例如,自签名证书的情况)。
- 目标 URL 无效。
- 在导航期间 Timeout 超时。
- 远程服务器无响应或不可访问。
- 主资源加载失败。
当远程服务器返回任何有效的 HTTP 状态码时,该方法不会抛出错误,包括 404 "Not Found" 和 500 "Internal Server Error"。可以通过调用Response.Status获取此类响应的状态码。
该方法要么抛出错误,要么返回主资源响应。唯一的例外是导航到 about:blank
或导航到具有不同 hash 的相同 URL,这将成功并返回 null
。
Headless 模式不支持导航到 PDF 文档。请参阅上游问题。
用法
await Page.GotoAsync(url, options);
参数
-
用于导航页面的 URL。URL 应包含 scheme,例如
https://
。当通过上下文选项提供了 BaseURL 且传递的 URL 是路径时,它将通过new URL()
构造函数合并。 -
options
PageGotoOptions?
(可选)-
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'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回值
IsClosed
在 v1.9 之前添加指示页面已关闭。
用法
Page.IsClosed
返回值
Locator
添加于:v1.14该方法返回一个元素定位器,可用于在此页面/框架上执行操作。定位器在执行操作之前立即解析到元素,因此在同一个定位器上的一系列操作实际上可以作用于不同的 DOM 元素。如果这些操作之间 DOM 结构发生变化,就会发生这种情况。
用法
Page.Locator(selector, options);
参数
-
解析 DOM 元素时要使用的选择器。
-
options
PageLocatorOptions?
(可选)-
将方法结果缩小到包含与此相对定位器匹配的元素的那些结果。例如,包含
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|HasNotTextRegex
string? | Regex? (可选)添加于: v1.33#匹配内部不包含指定文本(可能在子元素或后代元素中)的元素。传递string时,匹配不区分大小写并搜索子字符串。
-
HasText|HasTextRegex
string? | Regex? (可选)#匹配内部包含指定文本(可能在子元素或后代元素中)的元素。传递string时,匹配不区分大小写并搜索子字符串。例如,
"Playwright"
匹配<article><div>Playwright</div></article>
。
-
返回值
MainFrame
在 v1.9 之前添加页面的主框架。页面保证有一个在导航期间持久存在的主框架。
用法
Page.MainFrame
返回值
OpenerAsync
在 v1.9 之前添加返回弹出页面的 opener,对于其他页面返回 null
。如果 opener 已经被关闭,则返回 null
。
用法
await Page.OpenerAsync();
返回值
PauseAsync
添加于:v1.9暂停脚本执行。Playwright 将停止执行脚本,并等待用户在页面叠加层中按下 'Resume' 按钮,或在 DevTools 控制台中调用 playwright.resume()
。
用户可以在暂停时检查选择器或执行手动步骤。Resume 将从暂停的位置继续运行原始脚本。
此方法需要 Playwright 在有头模式下启动,且 Headless 选项为 false。
用法
await Page.PauseAsync();
返回值
PdfAsync
在 v1.9 之前添加返回 PDF 缓冲区。
page.pdf()
使用 print
CSS 媒体生成页面的 pdf。要使用 screen
媒体生成 pdf,请在调用 page.pdf()
之前调用 Page.EmulateMediaAsync()。
默认情况下,page.pdf()
生成具有修改打印颜色的 pdf。使用 -webkit-print-color-adjust
属性强制渲染精确颜色。
用法
// Generates a PDF with 'screen' media type
await page.EmulateMediaAsync(new() { Media = Media.Screen });
await page.PdfAsync(new() { Path = "page.pdf" });
Width、Height 和 Margin 选项接受带有单位标记的值。未标记的值视为像素。
一些示例
page.pdf({width: 100})
- 打印时宽度设置为 100 像素page.pdf({width: '100px'})
- 打印时宽度设置为 100 像素page.pdf({width: '10cm'})
- 打印时宽度设置为 10 厘米。
所有可能的单位是
px
- 像素in
- 英寸cm
- 厘米mm
- 毫米
Format 选项有
Letter
:8.5in x 11inLegal
:8.5in x 14inTabloid
:11in x 17inLedger
:17in x 11inA0
:33.1in x 46.8inA1
:23.4in x 33.1inA2
:16.54in x 23.4inA3
:11.7in x 16.54inA4
:8.27in x 11.7inA5
:5.83in x 8.27inA6
:4.13in x 5.83in
HeaderTemplate 和 FooterTemplate 标记具有以下限制:> 1. 模板中的 Script 标签不会被评估。> 2. 页面样式在模板中不可见。
参数
options
PagePdfOptions?
(可选)-
DisplayHeaderFooter
bool? (可选)#显示页眉和页脚。默认为
false
。 -
打印页脚的 HTML 模板。应使用与 HeaderTemplate 相同的格式。
-
打印页眉的 HTML 模板。应为有效的 HTML 标记,并使用以下类将打印值注入其中:
'date'
格式化后的打印日期'title'
文档标题'url'
文档位置'pageNumber'
当前页码'totalPages'
文档总页数
-
纸张高度,接受带有单位的值。
-
纸张方向。默认为
false
。 -
Margin
Margin? (可选)#-
Top
string? (可选)上边距,接受带有单位的值。默认为
0
。 -
Right
string? (可选)右边距,接受带有单位的值。默认为
0
。 -
Bottom
string? (可选)下边距,接受带有单位的值。默认为
0
。 -
Left
string? (可选)左边距,接受带有单位的值。默认为
0
。
纸张边距,默认为无。
-
-
是否将文档大纲嵌入到 PDF 中。默认为
false
。 -
要打印的页范围,例如 '1-5, 8, 11-13'。默认为空字符串,表示打印所有页。
-
保存 PDF 的文件路径。如果 Path 是相对路径,则它相对于当前工作目录解析。如果未提供路径,则 PDF 不会保存到磁盘。
-
使页面中声明的任何 CSS
@page
大小优先于 Width 和 Height 或 Format 选项中声明的大小。默认为false
,此时内容将缩放以适应纸张大小。 -
打印背景图形。默认为
false
。 -
Scale
[float]? (可选)#网页渲染的缩放比例。默认为
1
。缩放比例必须在 0.1 到 2 之间。 -
是否生成带有标签(可访问)的 PDF。默认为
false
。 -
纸张宽度,接受带有单位的值。
-
返回值
ReloadAsync
在 v1.9 之前添加此方法重新加载当前页,就像用户触发了浏览器刷新一样。返回主资源响应。如果发生多次重定向,导航将解析为最后一次重定向的响应。
用法
await Page.ReloadAsync(options);
参数
options
PageReloadOptions?
(可选)-
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'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回值
RemoveLocatorHandlerAsync
添加于:v1.44移除由 Page.AddLocatorHandlerAsync() 为特定定位器添加的所有定位器处理程序。
用法
await Page.RemoveLocatorHandlerAsync(locator);
参数
-
传递给 Page.AddLocatorHandlerAsync() 的定位器。
返回值
RequestGCAsync
添加于: v1.48请求页面执行垃圾回收。请注意,不能保证所有不可达对象都将被回收。
这有助于检测内存泄漏。例如,如果您的页面有一个可能泄漏的大对象 'suspect'
,您可以使用 WeakRef
检查它是否泄漏。
// 1. In your page, save a WeakRef for the "suspect".
await Page.EvaluateAsync("globalThis.suspectWeakRef = new WeakRef(suspect)");
// 2. Request garbage collection.
await Page.RequestGCAsync();
// 3. Check that weak ref does not deref to the original object.
Assert.True(await Page.EvaluateAsync("!globalThis.suspectWeakRef.deref()"));
用法
await Page.RequestGCAsync();
返回值
RouteAsync
在 v1.9 之前添加路由提供修改页面发起的网络请求的能力。
一旦启用路由,每个匹配 URL 模式的请求都将暂停,除非它被继续、满足或中止。
如果响应是重定向,处理程序将仅对第一个 URL 调用。
Page.RouteAsync() 将不会拦截被 Service Worker 拦截的请求。请参阅 此 issue。我们建议在使用请求拦截时通过将 ServiceWorkers 设置为 'block'
来禁用 Service Workers。
Page.RouteAsync() 将不会拦截弹出页面的第一个请求。请改用 BrowserContext.RouteAsync()。
用法
一个简单的处理程序示例,它中止所有图片请求:
var page = await browser.NewPageAsync();
await page.RouteAsync("**/*.{png,jpg,jpeg}", async r => await r.AbortAsync());
await page.GotoAsync("https://www.microsoft.com");
或使用正则表达式模式的相同代码片段:
var page = await browser.NewPageAsync();
await page.RouteAsync(new Regex("(\\.png$)|(\\.jpg$)"), async r => await r.AbortAsync());
await page.GotoAsync("https://www.microsoft.com");
可以检查请求以决定路由操作。例如,模拟包含某些 POST 数据的所有请求,并保持其他请求不变:
await page.RouteAsync("/api/**", async r =>
{
if (r.Request.PostData.Contains("my-string"))
await r.FulfillAsync(new() { Body = "mocked-data" });
else
await r.ContinueAsync();
});
当请求同时匹配页面路由和浏览器上下文路由(使用 BrowserContext.RouteAsync() 设置)时,页面路由优先。
要移除路由及其处理程序,可以使用 Page.UnrouteAsync()。
启用路由会禁用 HTTP 缓存。
参数
-
url
string | Regex | Func<string, bool>#用于在路由期间匹配的 glob 模式、正则表达式模式或接收 URL 的谓词。如果在上下文选项中设置了 BaseURL 并且提供的 URL 是不以
*
开头的字符串,则使用new URL()
构造函数解析它。 -
路由请求的处理程序函数。
-
options
PageRouteOptions?
(可选)
返回值
RouteFromHARAsync
添加于: v1.23如果指定,页面中发起的网络请求将从 HAR 文件提供服务。阅读有关 从 HAR 回放 的更多信息。
Playwright 不会从 HAR 文件为 Service Worker 拦截的请求提供服务。请参阅 此 issue。我们建议在使用请求拦截时通过将 ServiceWorkers 设置为 'block'
来禁用 Service Workers。
用法
await Page.RouteFromHARAsync(har, options);
参数
-
带有预先录制的网络数据的 HAR 文件路径。如果
path
是相对路径,则它相对于当前工作目录解析。 -
options
PageRouteFromHAROptions?
(可选)-
NotFound
enum HarNotFound { Abort, Fallback }?
(可选)#- 如果设置为 'abort',则 HAR 文件中未找到的任何请求都将被中止。
- 如果设置为 'fallback',则缺失的请求将被发送到网络。
默认为 abort。
-
如果指定,将使用实际的网络信息更新给定的 HAR,而不是从文件提供服务。文件在调用 BrowserContext.CloseAsync() 时写入磁盘。
-
UpdateContent
enum RouteFromHarUpdateContentPolicy { Embed, Attach }?
(可选)添加于: v1.32#控制资源内容管理的可选设置。如果指定
attach
,资源将作为独立文件或条目保留在 ZIP 存档中。如果指定embed
,内容将以内联方式存储在 HAR 文件中。 -
UpdateMode
enum HarMode { Full, Minimal }?
(可选)添加于: v1.32#当设置为
minimal
时,仅记录从 HAR 路由所需的信息。这将省略大小、时间、页面、Cookie、安全性和其他在从 HAR 回放时不使用的 HAR 信息类型。默认为minimal
。 -
Url|UrlRegex
string? | Regex? (可选)#用于匹配请求 URL 的 glob 模式、正则表达式或谓词。只有 URL 匹配模式的请求才会从 HAR 文件提供服务。如果未指定,所有请求都将从 HAR 文件提供服务。
-
返回值
RouteWebSocketAsync
添加于: v1.48此方法允许修改页面创建的 websocket 连接。
请注意,只有在此方法调用后创建的 WebSocket
才会被路由。建议在导航页面之前调用此方法。
用法
下面是一个简单的模拟示例,它响应一条消息。有关更多详细信息和示例,请参阅 WebSocketRoute。
await page.RouteWebSocketAsync("/ws", ws => {
ws.OnMessage(frame => {
if (frame.Text == "request")
ws.Send("response");
});
});
参数
-
url
string | Regex | Func<string, bool>#只有 URL 匹配此模式的 WebSocket 才会被路由。字符串模式可以相对于 BaseURL 上下文选项。
-
handler
Action<WebSocketRoute>#路由 WebSocket 的处理程序函数。
返回值
RunAndWaitForConsoleMessageAsync
添加于:v1.9执行操作并等待页面中记录 ConsoleMessage。如果提供了谓词,它将 ConsoleMessage 值传递给 predicate
函数,并等待 predicate(message)
返回真值。如果在 Page.Console 事件触发之前页面关闭,将抛出错误。
用法
await Page.RunAndWaitForConsoleMessageAsync(action, options);
参数
-
触发事件的操作。
-
options
PageRunAndWaitForConsoleMessageOptions?
(可选)-
Predicate
Func<ConsoleMessage?, bool> (可选)#接收 ConsoleMessage 对象,并在等待应该解决时解析为真值。
-
Timeout
[float]? (可选)#最大等待时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 BrowserContext.SetDefaultTimeout() 更改默认值。
-
返回值
WaitForConsoleMessageAsync
添加于:v1.9执行操作并等待页面中记录 ConsoleMessage。如果提供了谓词,它将 ConsoleMessage 值传递给 predicate
函数,并等待 predicate(message)
返回真值。如果在 Page.Console 事件触发之前页面关闭,将抛出错误。
用法
await Page.WaitForConsoleMessageAsync(action, options);
参数
options
PageRunAndWaitForConsoleMessageOptions?
(可选)-
Predicate
Func<ConsoleMessage?, bool> (可选)#接收 ConsoleMessage 对象,并在等待应该解决时解析为真值。
-
Timeout
[float]? (可选)#最大等待时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 BrowserContext.SetDefaultTimeout() 更改默认值。
-
返回值
RunAndWaitForDownloadAsync
添加于:v1.9执行操作并等待新的 Download。如果提供了谓词,它将 Download 值传递给 predicate
函数,并等待 predicate(download)
返回真值。如果在下载事件触发之前页面关闭,将抛出错误。
用法
await Page.RunAndWaitForDownloadAsync(action, options);
参数
-
触发事件的操作。
-
options
PageRunAndWaitForDownloadOptions?
(可选)
返回值
WaitForDownloadAsync
添加于:v1.9执行操作并等待新的 Download。如果提供了谓词,它将 Download 值传递给 predicate
函数,并等待 predicate(download)
返回真值。如果在下载事件触发之前页面关闭,将抛出错误。
用法
await Page.WaitForDownloadAsync(action, options);
参数
options
PageRunAndWaitForDownloadOptions?
(可选)
返回值
RunAndWaitForFileChooserAsync
添加于:v1.9执行操作并等待创建新的 FileChooser。如果提供了谓词,它将 FileChooser 值传递给 predicate
函数,并等待 predicate(fileChooser)
返回真值。如果在文件选择器打开之前页面关闭,将抛出错误。
用法
await Page.RunAndWaitForFileChooserAsync(action, options);
参数
-
触发事件的操作。
-
options
PageRunAndWaitForFileChooserOptions?
(可选)-
Predicate
Func<FileChooser?, bool> (可选)#接收 FileChooser 对象,并在等待应该解决时解析为真值。
-
Timeout
[float]? (可选)#最大等待时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 BrowserContext.SetDefaultTimeout() 更改默认值。
-
返回值
WaitForFileChooserAsync
添加于:v1.9执行操作并等待创建新的 FileChooser。如果提供了谓词,它将 FileChooser 值传递给 predicate
函数,并等待 predicate(fileChooser)
返回真值。如果在文件选择器打开之前页面关闭,将抛出错误。
用法
await Page.WaitForFileChooserAsync(action, options);
参数
options
PageRunAndWaitForFileChooserOptions?
(可选)-
Predicate
Func<FileChooser?, bool> (可选)#接收 FileChooser 对象,并在等待应该解决时解析为真值。
-
Timeout
[float]? (可选)#最大等待时间,单位为毫秒。默认为
30000
(30 秒)。传递0
以禁用超时。可以使用 BrowserContext.SetDefaultTimeout() 更改默认值。
-
返回值
RunAndWaitForPopupAsync
添加于:v1.9执行操作并等待弹出 Page。如果提供了谓词,它将 [Popup] 值传递给 predicate
函数,并等待 predicate(page)
返回真值。如果在弹出事件触发之前页面关闭,将抛出错误。
用法
await Page.RunAndWaitForPopupAsync(action, options);
参数
-
触发事件的操作。
-
options
PageRunAndWaitForPopupOptions?
(可选)
返回值
WaitForPopupAsync
添加于:v1.9执行操作并等待弹出 Page。如果提供了谓词,它将 [Popup] 值传递给 predicate
函数,并等待 predicate(page)
返回真值。如果在弹出事件触发之前页面关闭,将抛出错误。
用法
await Page.WaitForPopupAsync(action, options);
参数
options
PageRunAndWaitForPopupOptions?
(可选)
返回值
RunAndWaitForRequestAsync
在 v1.9 之前添加等待匹配的请求并返回它。有关事件的更多详细信息,请参阅 等待事件。
用法
// Waits for the next request with the specified url.
await page.RunAndWaitForRequestAsync(async () =>
{
await page.GetByText("trigger request").ClickAsync();
}, "http://example.com/resource");
// Alternative way with a predicate.
await page.RunAndWaitForRequestAsync(async () =>
{
await page.GetByText("trigger request").ClickAsync();
}, request => request.Url == "https://example.com" && request.Method == "GET");
参数
-
触发事件的操作。
-
urlOrPredicate
string | Regex | Func<Request, bool>#请求 URL 字符串、正则表达式或接收 Request 对象的谓词。当通过上下文选项提供了 BaseURL 并且传递的 URL 是路径时,它将通过
new URL()
构造函数进行合并。 -
options
PageRunAndWaitForRequestOptions?
(可选)-
Timeout
[float]? (可选)#最大等待时间,单位为毫秒,默认为 30 秒,传递
0
以禁用超时。可以使用 Page.SetDefaultTimeout() 方法更改默认值。
-
返回值
WaitForRequestAsync
在 v1.9 之前添加等待匹配的请求并返回它。有关事件的更多详细信息,请参阅 等待事件。
用法
// Waits for the next request with the specified url.
await page.RunAndWaitForRequestAsync(async () =>
{
await page.GetByText("trigger request").ClickAsync();
}, "http://example.com/resource");
// Alternative way with a predicate.
await page.RunAndWaitForRequestAsync(async () =>
{
await page.GetByText("trigger request").ClickAsync();
}, request => request.Url == "https://example.com" && request.Method == "GET");
参数
-
urlOrPredicate
string | Regex | Func<Request, bool>#请求 URL 字符串、正则表达式或接收 Request 对象的谓词。当通过上下文选项提供了 BaseURL 并且传递的 URL 是路径时,它将通过
new URL()
构造函数进行合并。 -
options
PageRunAndWaitForRequestOptions?
(可选)-
Timeout
[float]? (可选)#最大等待时间,单位为毫秒,默认为 30 秒,传递
0
以禁用超时。可以使用 Page.SetDefaultTimeout() 方法更改默认值。
-
返回值
RunAndWaitForRequestFinishedAsync
添加于:v1.12执行操作并等待 Request 加载完成。如果提供了谓词,它将 Request 值传递给 predicate
函数,并等待 predicate(request)
返回真值。如果在 Page.RequestFinished 事件触发之前页面关闭,将抛出错误。
用法
await Page.RunAndWaitForRequestFinishedAsync(action, options);
参数
-
触发事件的操作。
-
options
PageRunAndWaitForRequestFinishedOptions?
(可选)
返回值
WaitForRequestFinishedAsync
添加于:v1.12执行操作并等待 Request 加载完成。如果提供了谓词,它将 Request 值传递给 predicate
函数,并等待 predicate(request)
返回真值。如果在 Page.RequestFinished 事件触发之前页面关闭,将抛出错误。
用法
await Page.WaitForRequestFinishedAsync(action, options);
参数
options
PageRunAndWaitForRequestFinishedOptions?
(可选)
返回值
RunAndWaitForResponseAsync
在 v1.9 之前添加返回匹配的响应。有关事件的更多详细信息,请参阅 等待事件。
用法
// Waits for the next response with the specified url.
await page.RunAndWaitForResponseAsync(async () =>
{
await page.GetByText("trigger response").ClickAsync();
}, "http://example.com/resource");
// Alternative way with a predicate.
await page.RunAndWaitForResponseAsync(async () =>
{
await page.GetByText("trigger response").ClickAsync();
}, response => response.Url == "https://example.com" && response.Status == 200 && response.Request.Method == "GET");
参数
-
触发事件的操作。
-
urlOrPredicate
string | Regex | Func<Response, bool>#请求 URL 字符串、正则表达式或接收 Response 对象的谓词。当通过上下文选项提供了 BaseURL 并且传递的 URL 是路径时,它将通过
new URL()
构造函数进行合并。 -
options
PageRunAndWaitForResponseOptions?
(可选)-
Timeout
[float]? (可选)#最大等待时间,单位为毫秒,默认为 30 秒,传递
0
以禁用超时。可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改默认值。
-
返回值
WaitForResponseAsync
在 v1.9 之前添加返回匹配的响应。有关事件的更多详细信息,请参阅 等待事件。
用法
// Waits for the next response with the specified url.
await page.RunAndWaitForResponseAsync(async () =>
{
await page.GetByText("trigger response").ClickAsync();
}, "http://example.com/resource");
// Alternative way with a predicate.
await page.RunAndWaitForResponseAsync(async () =>
{
await page.GetByText("trigger response").ClickAsync();
}, response => response.Url == "https://example.com" && response.Status == 200 && response.Request.Method == "GET");
参数
-
urlOrPredicate
string | Regex | Func<Response, bool>#请求 URL 字符串、正则表达式或接收 Response 对象的谓词。当通过上下文选项提供了 BaseURL 并且传递的 URL 是路径时,它将通过
new URL()
构造函数进行合并。 -
options
PageRunAndWaitForResponseOptions?
(可选)-
Timeout
[float]? (可选)#最大等待时间,单位为毫秒,默认为 30 秒,传递
0
以禁用超时。可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改默认值。
-
返回值
RunAndWaitForWebSocketAsync
添加于:v1.9执行操作并等待新的 WebSocket。如果提供了 predicate,则将 WebSocket 值传递给 predicate
函数,并等待 predicate(webSocket)
返回一个真值。如果在 WebSocket 事件触发之前页面关闭,则会抛出错误。
用法
await Page.RunAndWaitForWebSocketAsync(action, options);
参数
-
触发事件的操作。
-
options
PageRunAndWaitForWebSocketOptions?
(可选)
返回值
WaitForWebSocketAsync
添加于:v1.9执行操作并等待新的 WebSocket。如果提供了 predicate,则将 WebSocket 值传递给 predicate
函数,并等待 predicate(webSocket)
返回一个真值。如果在 WebSocket 事件触发之前页面关闭,则会抛出错误。
用法
await Page.WaitForWebSocketAsync(action, options);
参数
options
PageRunAndWaitForWebSocketOptions?
(可选)
返回值
RunAndWaitForWorkerAsync
添加于:v1.9执行操作并等待新的 Worker。如果提供了 predicate,则将 Worker 值传递给 predicate
函数,并等待 predicate(worker)
返回一个真值。如果在 Worker 事件触发之前页面关闭,则会抛出错误。
用法
await Page.RunAndWaitForWorkerAsync(action, options);
参数
-
触发事件的操作。
-
options
PageRunAndWaitForWorkerOptions?
(可选)
返回值
WaitForWorkerAsync
添加于:v1.9执行操作并等待新的 Worker。如果提供了 predicate,则将 Worker 值传递给 predicate
函数,并等待 predicate(worker)
返回一个真值。如果在 Worker 事件触发之前页面关闭,则会抛出错误。
用法
await Page.WaitForWorkerAsync(action, options);
参数
options
PageRunAndWaitForWorkerOptions?
(可选)
返回值
ScreenshotAsync
在 v1.9 之前添加返回捕获的屏幕截图的缓冲区。
用法
await Page.ScreenshotAsync(options);
参数
options
PageScreenshotOptions?
(可选)-
Animations
enum ScreenshotAnimations { Disabled, Allow }?
(可选)#设置为
"disabled"
时,停止 CSS 动画、CSS 过渡和 Web Animations。动画根据其持续时间获得不同的处理方式:- 有限动画快进到完成,因此它们将触发
transitionend
事件。 - 无限动画被取消到初始状态,然后在截图后重新播放。
默认为
"allow"
,它保留动画不变。 - 有限动画快进到完成,因此它们将触发
-
Caret
enum ScreenshotCaret { Hide, Initial }?
(可选)#设置为
"hide"
时,截图将隐藏文本光标。设置为"initial"
时,文本光标行为将不会改变。默认为"hide"
。 -
Clip
Clip? (可选)#-
X
[float]裁剪区域左上角的 x 坐标
-
Y
[float]裁剪区域左上角的 y 坐标
-
Width
[float]裁剪区域的宽度
-
Height
[float]裁剪区域的高度
一个指定结果图像裁剪的对象。
-
-
为 true 时,截取整个可滚动页面的屏幕截图,而不是当前可见视口。默认为
false
。 -
Mask
IEnumerable?<Locator> (可选)#指定在截取屏幕截图时应被遮罩的定位器。被遮罩的元素将叠加一个粉色框
#FF00FF
(由 MaskColor 定制),该框完全覆盖其边界框。遮罩也适用于不可见元素,请参阅 仅匹配可见元素 以禁用此行为。 -
MaskColor
string? (可选)添加于: v1.35#指定被遮罩元素的叠加框颜色,格式为 CSS 颜色。默认颜色为粉色
#FF00FF
。 -
隐藏默认的白色背景,并允许截取带有透明度的屏幕截图。不适用于
jpeg
图像。默认为false
。 -
保存图像的文件路径。屏幕截图类型将根据文件扩展名推断。如果 Path 是相对路径,则相对于当前工作目录解析。如果未提供路径,则图像不会保存到磁盘。
-
图像质量,介于 0-100 之间。不适用于
png
图像。 -
Scale
enum ScreenshotScale { Css, Device }?
(可选)#设置为
"css"
时,截图将按页面上每个 CSS 像素生成一个像素。对于高分辨率设备,这将使截图保持较小。使用"device"
选项将按每个设备像素生成一个像素,因此高分辨率设备的截图将是两倍大或更大。默认为
"device"
。 -
截取屏幕截图时应用的样式表文本。您可以在此处隐藏动态元素、使元素不可见或更改其属性,以帮助您创建可重复的屏幕截图。此样式表穿透 Shadow DOM 并应用于内部框架。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
Type
enum ScreenshotType { Png, Jpeg }?
(可选)#指定屏幕截图类型,默认为
png
。
-
返回值
SetContentAsync
在 v1.9 之前添加此方法内部调用 document.write(),继承其所有特定特性和行为。
用法
await Page.SetContentAsync(html, options);
参数
-
要分配给页面的 HTML 标记。
-
options
PageSetContentOptions?
(可选)-
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'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回值
SetDefaultNavigationTimeout
在 v1.9 之前添加此设置将更改以下方法和相关快捷方式的默认最大导航时间:
- Page.GoBackAsync()
- Page.GoForwardAsync()
- Page.GotoAsync()
- Page.ReloadAsync()
- Page.SetContentAsync()
- Page.RunAndWaitForNavigationAsync()
- Page.WaitForURLAsync()
用法
Page.SetDefaultNavigationTimeout(timeout);
参数
-
timeout
[float]#最大导航时间,单位为毫秒
SetDefaultTimeout
在 v1.9 之前添加此设置将更改所有接受 timeout
选项的方法的默认最长时间。
用法
Page.SetDefaultTimeout(timeout);
参数
-
timeout
[float]#最大时间,单位为毫秒。传入
0
可禁用超时。
SetExtraHTTPHeadersAsync
在 v1.9 之前添加额外的 HTTP 头部将随页面发起的每个请求发送。
Page.SetExtraHTTPHeadersAsync() 不保证 outgoing requests 中头部字段的顺序。
用法
await Page.SetExtraHTTPHeadersAsync(headers);
参数
-
headers
IDictionary<string, string>#一个包含要随每个请求发送的额外 HTTP 头部的对象。所有头部值必须是字符串。
返回值
SetViewportSizeAsync
在 v1.9 之前添加在单个浏览器中有多个页面的情况下,每个页面都可以有自己的视口大小。然而,Browser.NewContextAsync() 允许一次性设置上下文中所有页面的视口大小(以及更多设置)。
Page.SetViewportSizeAsync() 将调整页面大小。许多网站不期望手机改变大小,因此您应该在导航到页面之前设置视口大小。Page.SetViewportSizeAsync() 也会重置 screen
大小,如果您需要更好地控制这些属性,请使用带有 screen
和 viewport
参数的 Browser.NewContextAsync()。
用法
var page = await browser.NewPageAsync();
await page.SetViewportSizeAsync(640, 480);
await page.GotoAsync("https://www.microsoft.com");
参数
返回值
TitleAsync
在 v1.9 之前添加返回页面的标题。
用法
await Page.TitleAsync();
返回值
UnrouteAsync
在 v1.9 之前添加移除使用 Page.RouteAsync() 创建的路由。如果未指定 handler,则移除给定 url 的所有路由。
用法
await Page.UnrouteAsync(url, handler);
参数
返回值
UnrouteAllAsync
添加于: v1.41移除使用 Page.RouteAsync() 和 Page.RouteFromHARAsync() 创建的所有路由。
用法
await Page.UnrouteAllAsync(options);
参数
options
PageUnrouteAllOptions?
(可选)-
Behavior
enum UnrouteBehavior { Wait, IgnoreErrors, Default }?
(可选)#指定是否等待已在运行的处理程序以及它们抛出错误时如何处理:
'default'
- 不等待当前处理程序调用(如果有)完成,如果未路由的处理程序抛出异常,可能导致未处理的错误。'wait'
- 等待当前处理程序调用(如果有)完成。'ignoreErrors'
- 不等待当前处理程序调用(如果有)完成,未路由后处理程序抛出的所有错误都将被静默捕获。
-
返回值
Url
在 v1.9 之前添加用法
Page.Url
返回值
Video
在 v1.9 之前添加与此页面关联的 Video 对象。
用法
Page.Video
返回值
ViewportSize
在 v1.9 之前添加用法
Page.ViewportSize
返回值
WaitForFunctionAsync
在 v1.9 之前添加当 expression 返回真值时返回。它解析为该真值的 JSHandle。
用法
可以使用 Page.WaitForFunctionAsync() 来观察视口大小变化:
using Microsoft.Playwright;
using System.Threading.Tasks;
class FrameExamples
{
public static async Task WaitForFunction()
{
using var playwright = await Playwright.CreateAsync();
await using var browser = await playwright.Webkit.LaunchAsync();
var page = await browser.NewPageAsync();
await page.SetViewportSizeAsync(50, 50);
await page.MainFrame.WaitForFunctionAsync("window.innerWidth < 100");
}
}
将参数传递给 Page.WaitForFunctionAsync() 函数的谓词:
var selector = ".foo";
await page.WaitForFunctionAsync("selector => !!document.querySelector(selector)", selector);
参数
-
要在浏览器上下文中执行的 JavaScript 表达式。如果 expression 解析为函数,则该函数将自动调用。
-
arg
EvaluationArgument? (可选)#可选参数,传递给 expression。
-
options
PageWaitForFunctionOptions?
(可选)-
PollingInterval
[float]? (可选)#如果指定,则将其视为执行函数的间隔,单位为毫秒。默认情况下,如果未指定此选项,expression 会在
requestAnimationFrame
回调中执行。 -
Timeout
[float]? (可选)#最大等待时间,单位为毫秒。默认为
30000
(30 秒)。传入0
可禁用超时。可以通过 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改默认值。
-
返回值
WaitForLoadStateAsync
在 v1.9 之前添加当达到所需的加载状态时返回。
当页面达到所需的加载状态时(默认为 load
)解析。调用此方法时,导航必须已经提交。如果当前文档已达到所需状态,则立即解析。
大多数情况下,不需要此方法,因为 Playwright 在执行每个操作之前都会自动等待。
用法
await page.GetByRole(AriaRole.Button).ClickAsync(); // Click triggers navigation.
await page.WaitForLoadStateAsync(); // The promise resolves after 'load' event.
var popup = await page.RunAndWaitForPopupAsync(async () =>
{
await page.GetByRole(AriaRole.Button).ClickAsync(); // click triggers the popup
});
// Wait for the "DOMContentLoaded" event.
await popup.WaitForLoadStateAsync(LoadState.DOMContentLoaded);
Console.WriteLine(await popup.TitleAsync()); // popup is ready to use.
参数
-
state
enum LoadState { Load, DOMContentLoaded, NetworkIdle }?
(可选)#可选的要等待的加载状态,默认为
load
。如果加载当前文档时已达到该状态,则方法立即解析。可以是以下之一:'load'
- 等待load
事件触发。'domcontentloaded'
- 等待DOMContentLoaded
事件触发。'networkidle'
- **不建议使用** 等待直到网络连接至少500
毫秒内没有活动。不要将此方法用于测试,请依靠 Web 断言来评估就绪状态。
-
options
PageWaitForLoadStateOptions?
(可选)-
Timeout
[float]? (可选)#操作的最大时间(以毫秒为单位),默认为 30 秒,传递
0
可禁用超时。默认值可以通过使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
WaitForURLAsync
添加于: v1.11等待主框架导航到给定 URL。
用法
await page.ClickAsync("a.delayed-navigation"); // clicking the link will indirectly cause a navigation
await page.WaitForURLAsync("**/target.html");
参数
-
url
string | Regex | Func<string, bool>#等待导航时用于匹配 URL 的 glob 模式、正则表达式模式或接收 URL 的谓词。请注意,如果参数是不带通配符的字符串,则该方法将等待导航到与该字符串完全相等的 URL。
-
options
PageWaitForURLOptions?
(可选)-
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'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回值
Workers
在 v1.9 之前添加此方法返回与页面关联的所有专用 WebWorkers。
此列表不包含 ServiceWorkers
用法
Page.Workers
返回值
属性
APIRequest
添加于: v1.16与此页面关联的 API 测试助手。此方法返回与页面上下文中的 BrowserContext.APIRequest 相同的实例。有关更多详细信息,请参阅 BrowserContext.APIRequest。
用法
Page.APIRequest
类型
Clock
添加于: v1.45Playwright 具有模拟时钟和时间流逝的能力。
用法
Page.Clock
类型
Keyboard
在 v1.9 之前添加用法
Page.Keyboard
类型
Mouse
在 v1.9 之前添加用法
Page.Mouse
类型
Touchscreen
在 v1.9 之前添加用法
Page.Touchscreen
类型
事件
事件 Close
在 v1.9 之前添加页面关闭时触发。
用法
Page.Close += async (_, page) => {};
事件数据
事件 Console
在 v1.9 之前添加当页面中的 JavaScript 调用控制台 API 方法时触发,例如 console.log
或 console.dir
。
传递给 console.log
的参数可在 ConsoleMessage 事件处理程序参数中获取。
用法
page.Console += async (_, msg) =>
{
foreach (var arg in msg.Args)
Console.WriteLine(await arg.JsonValueAsync<object>());
};
await page.EvaluateAsync("console.log('hello', 5, { foo: 'bar' })");
事件数据
事件 Crash
在 v1.9 之前添加页面崩溃时触发。如果浏览器页面尝试分配过多内存,可能会崩溃。页面崩溃时,正在进行和后续的操作将抛出异常。
处理崩溃的最常见方法是捕获异常:
try {
// Crash might happen during a click.
await page.ClickAsync("button");
// Or while waiting for an event.
await page.WaitForPopup();
} catch (PlaywrightException e) {
// When the page crashes, exception message contains "crash".
}
用法
Page.Crash += async (_, page) => {};
事件数据
事件 Dialog
在 v1.9 之前添加当出现 JavaScript 对话框时触发,例如 alert
、prompt
、confirm
或 beforeunload
。监听器**必须**接受 Dialog.AcceptAsync() 或关闭 Dialog.DismissAsync() 对话框 - 否则页面将冻结等待对话框,并且诸如 click 之类的操作永远无法完成。
用法
page.RequestFailed += (_, request) =>
{
Console.WriteLine(request.Url + " " + request.Failure);
};
如果没有 Page.Dialog 或 BrowserContext.Dialog 监听器,所有对话框都会自动关闭。
事件数据
事件 DOMContentLoaded
添加于:v1.9JavaScript DOMContentLoaded
事件分发时触发。
用法
Page.DOMContentLoaded += async (_, page) => {};
事件数据
事件 Download
在 v1.9 之前添加附件下载开始时触发。用户可以通过传递的 Download 实例访问下载内容的基本文件操作。
用法
Page.Download += async (_, download) => {};
事件数据
事件 FileChooser
添加于:v1.9当应出现文件选择器时触发,例如点击 <input type=file>
后。Playwright 可以通过使用 FileChooser.SetFilesAsync() 设置输入文件来响应,之后即可上传。
page.FileChooser += (_, fileChooser) =>
{
fileChooser.SetFilesAsync(@"C:\temp\myfile.pdf");
};
用法
Page.FileChooser += async (_, fileChooser) => {};
事件数据
事件 FrameAttached
添加于:v1.9附加框架时触发。
用法
Page.FrameAttached += async (_, frame) => {};
事件数据
事件 FrameDetached
添加于:v1.9分离框架时触发。
用法
Page.FrameDetached += async (_, frame) => {};
事件数据
事件 FrameNavigated
添加于:v1.9框架导航到新 URL 时触发。
用法
Page.FrameNavigated += async (_, frame) => {};
事件数据
事件 Load
在 v1.9 之前添加JavaScript load
事件分发时触发。
用法
Page.Load += async (_, page) => {};
事件数据
事件 PageError
添加于:v1.9页面中发生未捕获异常时触发。
// Log all uncaught errors to the terminal
page.PageError += (_, exception) =>
{
Console.WriteLine("Uncaught exception: " + exception);
};
用法
Page.PageError += async (_, value) => {};
事件数据
事件 Popup
在 v1.9 之前添加页面打开新标签页或窗口时触发。此事件除了 BrowserContext.Page 事件外还会触发,但仅针对与此页面相关的弹出窗口。
页面可用的最早时刻是当它已导航到初始 URL 时。例如,当使用 window.open('http://example.com')
打开弹出窗口时,当对 "http://example.com" 的网络请求完成并且其响应已开始在弹出窗口中加载时,将触发此事件。如果你想路由/监听此网络请求,请分别使用 BrowserContext.RouteAsync() 和 BrowserContext.Request,而不是 Page 上的类似方法。
var popup = await page.RunAndWaitForPopupAsync(async () =>
{
await page.GetByText("open the popup").ClickAsync();
});
Console.WriteLine(await popup.EvaluateAsync<string>("location.href"));
使用 Page.WaitForLoadStateAsync() 等待页面达到特定状态(大多数情况下不需要)。
用法
Page.Popup += async (_, page) => {};
事件数据
event Request
在 v1.9 之前添加当页面发出请求时触发。 request 对象是只读的。要拦截和修改请求,请参阅 Page.RouteAsync() 或 BrowserContext.RouteAsync()。
用法
Page.Request += async (_, request) => {};
事件数据
event RequestFailed
添加于:v1.9当请求失败时触发,例如由于超时。
HTTP 错误响应(例如 404 或 503)从 HTTP 的角度来看仍然是成功响应,因此请求将通过 Page.RequestFinished 事件完成,而不是通过 Page.RequestFailed。只有当客户端无法从服务器获取 HTTP 响应时(例如由于网络错误 net::ERR_FAILED),请求才会被视为失败。
用法
Page.RequestFailed += async (_, request) => {};
事件数据
event RequestFinished
添加于:v1.9当请求成功下载响应体后完成时触发。对于成功的响应,事件序列是 request
、response
和 requestfinished
。
用法
Page.RequestFinished += async (_, request) => {};
事件数据
event Response
在 v1.9 之前添加当请求收到 response 状态和头时触发。对于成功的响应,事件序列是 request
、response
和 requestfinished
。
用法
Page.Response += async (_, response) => {};
事件数据
event WebSocket
添加于:v1.9当发送 WebSocket 请求时触发。
用法
Page.WebSocket += async (_, webSocket) => {};
事件数据
event Worker
在 v1.9 之前添加当页面派生出专用的 WebWorker 时触发。
用法
Page.Worker += async (_, worker) => {};
事件数据
已废弃
可访问性
在 v1.9 之前添加用法
Page.Accessibility
类型
CheckAsync
在 v1.9 之前添加请改用基于定位器的 Locator.CheckAsync()。了解有关 定位器 的更多信息。
此方法通过执行以下步骤来检查匹配 selector 的元素
- 查找匹配 selector 的元素。如果没有,等待直到匹配的元素附加到 DOM。
- 确保匹配的元素是复选框或单选输入框。如果不是,此方法将抛出异常。如果元素已选中,此方法会立即返回。
- 等待对匹配元素的可操作性 (actionability) 检查,除非设置了 Force 选项。如果在检查期间元素被分离,则整个操作会重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 在元素的中心点击。
- 确保元素现在已被选中。如果不是,此方法将抛出异常。
当所有步骤在指定的 Timeout 期间未完成时,此方法将抛出 TimeoutError。传入零超时会禁用此功能。
用法
await Page.CheckAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageCheckOptions?
(可选)-
是否绕过可操作性检查。默认为
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。
- 等待对匹配元素的可操作性 (actionability) 检查,除非设置了 Force 选项。如果在检查期间元素被分离,则整个操作会重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 在元素的中心或指定的 Position 点击。
- 等待已启动的导航成功或失败,除非设置了 NoWaitAfter 选项。
当所有步骤在指定的 Timeout 期间未完成时,此方法将抛出 TimeoutError。传入零超时会禁用此功能。
用法
await Page.ClickAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageClickOptions?
(可选)-
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() 方法更改。 -
设置后,此方法仅执行可操作性 (actionability) 检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备就绪时很有用。请注意,无论是否进行trial
尝试,都会按下键盘modifiers
,以允许测试只有在按下这些键时才可见的元素。
-
返回值
DblClickAsync
在 v1.9 之前添加请改用基于定位器的 Locator.DblClickAsync()。了解有关 定位器 的更多信息。
此方法通过执行以下步骤来双击匹配 selector 的元素
- 查找匹配 selector 的元素。如果没有,等待直到匹配的元素附加到 DOM。
- 等待对匹配元素的可操作性 (actionability) 检查,除非设置了 Force 选项。如果在检查期间元素被分离,则整个操作会重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 在元素的中心或指定的 Position 双击。
当所有步骤在指定的 Timeout 期间未完成时,此方法将抛出 TimeoutError。传入零超时会禁用此功能。
page.dblclick()
会派发两个 click
事件和一个 dblclick
事件。
用法
await Page.DblClickAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageDblClickOptions?
(可选)-
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() 方法更改。 -
设置后,此方法仅执行可操作性 (actionability) 检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备就绪时很有用。请注意,无论是否进行trial
尝试,都会按下键盘modifiers
,以允许测试只有在按下这些键时才可见的元素。
-
返回值
DispatchEventAsync
在 v1.9 之前添加请改用基于定位器的 Locator.DispatchEventAsync()。了解有关 定位器 的更多信息。
以下代码片段在元素上派发 click
事件。无论元素的可见性状态如何,都会派发 click
事件。这等同于调用 element.click()。
用法
await page.DispatchEventAsync("button#submit", "click");
底层实现是根据给定的 type 创建一个事件实例,使用 eventInit 属性初始化它,并在元素上派发。事件默认是 composed
, cancelable
和冒泡 (bubble) 的。
由于 eventInit 特定于事件,请参考事件文档以获取初始属性列表
- DeviceMotionEvent
- DeviceOrientationEvent
- DragEvent
- Event
- FocusEvent
- KeyboardEvent
- MouseEvent
- PointerEvent
- TouchEvent
- WheelEvent
如果您希望将实时对象传递到事件中,也可以将 JSHandle
指定为属性值
var dataTransfer = await page.EvaluateHandleAsync("() => new DataTransfer()");
await page.DispatchEventAsync("#source", "dragstart", new { dataTransfer });
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
DOM 事件类型:
"click"
,"dragstart"
等。 -
eventInit
EvaluationArgument? (可选)#可选的事件特定初始化属性。
-
options
PageDispatchEventOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
EvalOnSelectorAsync
添加于:v1.9此方法不会等待元素通过可操作性 (actionability) 检查,因此可能导致测试不稳定。请改用 Locator.EvaluateAsync()、其他 Locator 辅助方法或 web-first 断言。
此方法在页面内查找匹配指定 selector 的元素,并将其作为第一个参数传递给 expression。如果没有元素匹配 selector,此方法将抛出异常。返回 expression 的值。
如果 expression 返回一个 Promise,则 Page.EvalOnSelectorAsync() 将等待 promise 解析并返回其值。
用法
var searchValue = await page.EvalOnSelectorAsync<string>("#search", "el => el.value");
var preloadHref = await page.EvalOnSelectorAsync<string>("link[rel=preload]", "el => el.href");
var html = await page.EvalOnSelectorAsync(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello");
参数
-
用于查询的 selector。
-
要在浏览器上下文中执行的 JavaScript 表达式。如果 expression 解析为函数,则该函数将自动调用。
-
arg
EvaluationArgument? (可选)#要传递给 expression 的可选参数。
-
options
PageEvalOnSelectorOptions?
(可选)
返回值
- [object]#
EvalOnSelectorAllAsync
添加于:v1.9在大多数情况下,Locator.EvaluateAllAsync()、其他 Locator 辅助方法和 web-first 断言效果更好。
此方法在页面内查找所有匹配指定 selector 的元素,并将其匹配元素的数组作为第一个参数传递给 expression。返回 expression 调用的结果。
如果 expression 返回一个 Promise,则 Page.EvalOnSelectorAllAsync() 将等待 promise 解析并返回其值。
用法
var divsCount = await page.EvalOnSelectorAllAsync<bool>("div", "(divs, min) => divs.length >= min", 10);
参数
-
用于查询的 selector。
-
要在浏览器上下文中执行的 JavaScript 表达式。如果 expression 解析为函数,则该函数将自动调用。
-
arg
EvaluationArgument? (可选)#要传递给 expression 的可选参数。
返回值
- [object]#
FillAsync
在 v1.9 之前添加请改用基于定位器的 Locator.FillAsync()。了解有关 定位器 的更多信息。
此方法会等待匹配 selector 的元素,等待可操作性 (actionability) 检查,聚焦元素,填充内容并在填充后触发 input
事件。请注意,您可以传入空字符串来清空输入字段。
如果目标元素不是 <input>
、<textarea>
或 [contenteditable]
元素,此方法将抛出异常。但是,如果元素在具有关联 control 的 <label>
元素内,则会填充该 control。
要发送细粒度的键盘事件,请使用 Locator.PressSequentiallyAsync()。
用法
await Page.FillAsync(selector, value, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
要为
<input>
、<textarea>
或[contenteditable]
元素填充的值。 -
options
PageFillOptions?
(可选)-
是否绕过可操作性检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
FocusAsync
在 v1.9 之前添加请改用基于定位器的 Locator.FocusAsync()。了解有关 定位器 的更多信息。
此方法获取具有 selector 的元素并聚焦它。如果没有元素匹配 selector,此方法会等待直到匹配的元素出现在 DOM 中。
用法
await Page.FocusAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageFocusOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
GetAttributeAsync
在 v1.9 之前添加请改用基于定位器的 Locator.GetAttributeAsync()。了解有关 定位器 的更多信息。
返回元素的属性值。
用法
await Page.GetAttributeAsync(selector, name, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
要获取值的属性名称。
-
options
PageGetAttributeOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
HoverAsync
在 v1.9 之前添加请改用基于定位器的 Locator.HoverAsync()。了解有关 定位器 的更多信息。
此方法通过执行以下步骤将鼠标悬停在匹配 selector 的元素上
- 查找匹配 selector 的元素。如果没有,等待直到匹配的元素附加到 DOM。
- 等待对匹配元素的可操作性 (actionability) 检查,除非设置了 Force 选项。如果在检查期间元素被分离,则整个操作会重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 将鼠标悬停在元素的中心或指定的 Position 上。
当所有步骤在指定的 Timeout 期间未完成时,此方法将抛出 TimeoutError。传入零超时会禁用此功能。
用法
await Page.HoverAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageHoverOptions?
(可选)-
是否绕过可操作性检查。默认为
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() 方法更改。 -
设置后,此方法仅执行可操作性 (actionability) 检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备就绪时很有用。请注意,无论是否进行trial
尝试,都会按下键盘modifiers
,以允许测试只有在按下这些键时才可见的元素。
-
返回值
InnerHTMLAsync
在 v1.9 之前添加请改用基于定位器的 Locator.InnerHTMLAsync()。了解有关 定位器 的更多信息。
返回 element.innerHTML
。
用法
await Page.InnerHTMLAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageInnerHTMLOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
InnerTextAsync
在 v1.9 之前添加请改用基于定位器的 Locator.InnerTextAsync()。了解有关 定位器 的更多信息。
返回 element.innerText
。
用法
await Page.InnerTextAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageInnerTextOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
InputValueAsync
添加于:v1.13请改用基于定位器的 Locator.InputValueAsync()。了解有关 定位器 的更多信息。
返回所选 <input>
、<textarea>
或 <select>
元素的 input.value
。
对于非输入元素抛出异常。但是,如果元素在具有关联 control 的 <label>
元素内,则返回该 control 的值。
用法
await Page.InputValueAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageInputValueOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
IsCheckedAsync
在 v1.9 之前添加建议改用基于 locators 的 Locator.IsCheckedAsync()。阅读有关 locators 的更多信息。
返回元素是否已选中。如果元素不是复选框或单选输入,则抛出错误。
用法
await Page.IsCheckedAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageIsCheckedOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
IsDisabledAsync
在 v1.9 之前添加建议改用基于 locators 的 Locator.IsDisabledAsync()。阅读有关 locators 的更多信息。
返回元素是否已禁用,与 enabled 相反。
用法
await Page.IsDisabledAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageIsDisabledOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
IsEditableAsync
在 v1.9 之前添加建议改用基于 locators 的 Locator.IsEditableAsync()。阅读有关 locators 的更多信息。
返回元素是否可 编辑。
用法
await Page.IsEditableAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageIsEditableOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
IsEnabledAsync
在 v1.9 之前添加建议改用基于 locators 的 Locator.IsEnabledAsync()。阅读有关 locators 的更多信息。
返回元素是否 enabled。
用法
await Page.IsEnabledAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageIsEnabledOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
IsHiddenAsync
在 v1.9 之前添加建议改用基于 locators 的 Locator.IsHiddenAsync()。阅读有关 locators 的更多信息。
返回元素是否隐藏,与 visible 相反。不匹配任何元素的 选择器 被视为隐藏。
用法
await Page.IsHiddenAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageIsHiddenOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#已弃用此选项将被忽略。Page.IsHiddenAsync() 不会等待元素变为隐藏,而是立即返回。
-
返回值
IsVisibleAsync
在 v1.9 之前添加建议改用基于 locators 的 Locator.IsVisibleAsync()。阅读有关 locators 的更多信息。
返回元素是否 visible。不匹配任何元素的 选择器 被视为不可见。
用法
await Page.IsVisibleAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageIsVisibleOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#已弃用此选项将被忽略。Page.IsVisibleAsync() 不会等待元素变为可见,而是立即返回。
-
返回值
PressAsync
在 v1.9 之前添加建议改用基于 locators 的 Locator.PressAsync()。阅读有关 locators 的更多信息。
聚焦元素,然后使用 Keyboard.DownAsync() 和 Keyboard.UpAsync()。
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"
的快捷方式。与修饰符一起指定时,修饰符会被按下并保持,同时按下后续键。
用法
var page = await browser.NewPageAsync();
await page.GotoAsync("https://keycode.info");
await page.PressAsync("body", "A");
await page.ScreenshotAsync(new() { Path = "A.png" });
await page.PressAsync("body", "ArrowLeft");
await page.ScreenshotAsync(new() { Path = "ArrowLeft.png" });
await page.PressAsync("body", "Shift+O");
await page.ScreenshotAsync(new() { Path = "O.png" });
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
要按下的键名或要生成的字符,例如
ArrowLeft
或a
。 -
options
PagePressOptions?
(可选)-
Delay
[float]? (可选)#keydown
和keyup
之间等待的时间,单位为毫秒。默认为 0。 -
已弃用
此选项将来会默认为
true
。启动导航的操作会等待这些导航发生以及页面开始加载。您可以通过设置此标志来选择不等待。仅在特殊情况下才需要此选项,例如导航到无法访问的页面。默认为
false
。 -
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
QuerySelectorAsync
添加于:v1.9建议改用基于 locators 的 Page.Locator()。阅读有关 locators 的更多信息。
该方法在页面中查找与指定选择器匹配的元素。如果没有元素与选择器匹配,则返回值解析为 null
。要在页面上等待元素,请使用 Locator.WaitForAsync()。
用法
await Page.QuerySelectorAsync(selector, options);
参数
-
用于查询的 selector。
-
options
PageQuerySelectorOptions?
(可选)
返回值
QuerySelectorAllAsync
添加于:v1.9建议改用基于 locators 的 Page.Locator()。阅读有关 locators 的更多信息。
该方法在页面中查找与指定选择器匹配的所有元素。如果没有元素与选择器匹配,则返回值解析为 []
。
用法
await Page.QuerySelectorAllAsync(selector);
参数
返回值
RunAndWaitForNavigationAsync
在 v1.9 之前添加此方法本身存在竞态条件,请改用 Page.WaitForURLAsync()。
等待主框架导航并返回主资源响应。如果发生多次重定向,导航将以最后一次重定向的响应结束。如果导航到不同的锚点或由于 History API 的使用而发生导航,则导航将以 null
结束。
用法
当页面导航到新的 URL 或重新加载时,此方法结束。当您运行可能间接导致页面导航的代码时,此方法很有用。例如,点击目标具有一个 onclick
处理程序,该处理程序通过 setTimeout
触发导航。请考虑以下示例:
await page.RunAndWaitForNavigationAsync(async () =>
{
// This action triggers the navigation after a timeout.
await page.GetByText("Navigate after timeout").ClickAsync();
});
// The method continues after navigation has finished
使用 History API 更改 URL 被视为导航。
参数
-
触发事件的操作。
-
options
PageRunAndWaitForNavigationOptions?
(可选)-
Timeout
[float]? (可选)#操作的最大时间(以毫秒为单位),默认为 30 秒,传递
0
可禁用超时。默认值可以通过使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
Url|UrlRegex|UrlFunc
string? | Regex? | Func<string?, bool> (可选)#等待导航时用于匹配 URL 的 glob 模式、正则表达式模式或接收 URL 的谓词。请注意,如果参数是不带通配符的字符串,则该方法将等待导航到与该字符串完全相等的 URL。
-
WaitUntil
enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }?
(可选)#何时认为操作成功,默认为
load
。事件可以是以下之一:'domcontentloaded'
- 当DOMContentLoaded
事件触发时,认为操作完成。'load'
- 当load
事件触发时,认为操作完成。'networkidle'
- 不建议使用 当至少500
毫秒内没有网络连接时,认为操作完成。请勿将此方法用于测试,而应依靠 web 断言来评估就绪状态。'commit'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回值
WaitForNavigationAsync
在 v1.9 之前添加此方法本身存在竞态条件,请改用 Page.WaitForURLAsync()。
等待主框架导航并返回主资源响应。如果发生多次重定向,导航将以最后一次重定向的响应结束。如果导航到不同的锚点或由于 History API 的使用而发生导航,则导航将以 null
结束。
用法
当页面导航到新的 URL 或重新加载时,此方法结束。当您运行可能间接导致页面导航的代码时,此方法很有用。例如,点击目标具有一个 onclick
处理程序,该处理程序通过 setTimeout
触发导航。请考虑以下示例:
await page.RunAndWaitForNavigationAsync(async () =>
{
// This action triggers the navigation after a timeout.
await page.GetByText("Navigate after timeout").ClickAsync();
});
// The method continues after navigation has finished
使用 History API 更改 URL 被视为导航。
参数
options
PageRunAndWaitForNavigationOptions?
(可选)-
Timeout
[float]? (可选)#操作的最大时间(以毫秒为单位),默认为 30 秒,传递
0
可禁用超时。默认值可以通过使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
Url|UrlRegex|UrlFunc
string? | Regex? | Func<string?, bool> (可选)#等待导航时用于匹配 URL 的 glob 模式、正则表达式模式或接收 URL 的谓词。请注意,如果参数是不带通配符的字符串,则该方法将等待导航到与该字符串完全相等的 URL。
-
WaitUntil
enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }?
(可选)#何时认为操作成功,默认为
load
。事件可以是以下之一:'domcontentloaded'
- 当DOMContentLoaded
事件触发时,认为操作完成。'load'
- 当load
事件触发时,认为操作完成。'networkidle'
- 不建议使用 当至少500
毫秒内没有网络连接时,认为操作完成。请勿将此方法用于测试,而应依靠 web 断言来评估就绪状态。'commit'
- 当收到网络响应且文档开始加载时,认为操作完成。
-
返回值
SelectOptionAsync
在 v1.9 之前添加建议改用基于 locators 的 Locator.SelectOptionAsync()。阅读有关 locators 的更多信息。
此方法等待匹配 选择器 的元素出现,等待 可操作性 检查完成,等待 `<select>` 元素中存在所有指定选项,然后选择这些选项。
如果目标元素不是 `<select>` 元素,此方法将抛出错误。但是,如果该元素位于具有关联 control 的 `<label>` 元素内,则将改用该 control。
返回已成功选择的选项值数组。
在所有提供的选项都已选择后,触发 change
和 input
事件。
用法
// Single selection matching the value or label
await page.SelectOptionAsync("select#colors", new[] { "blue" });
// single selection matching both the value and the label
await page.SelectOptionAsync("select#colors", new[] { new SelectOptionValue() { Label = "blue" } });
// multiple
await page.SelectOptionAsync("select#colors", new[] { "red", "green", "blue" });
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
values
string | ElementHandle | IEnumerable |SelectOption
| IEnumerable | IEnumerable?#-
Value
string? (可选)按
option.value
匹配。可选。 -
Label
string? (可选)按
option.label
匹配。可选。 -
Index
int? (可选)按索引匹配。可选。
要选择的选项。如果 `<select>` 元素具有
multiple
属性,则选择所有匹配的选项;否则,仅选择与所传递的任一选项匹配的第一个选项。字符串值匹配值和标签。如果所有指定属性都匹配,则认为选项匹配。 -
-
options
PageSelectOptionOptions?
(可选)-
是否绕过可操作性检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
SetCheckedAsync
添加于:v1.15建议改用基于 locators 的 Locator.SetCheckedAsync()。阅读有关 locators 的更多信息。
此方法通过执行以下步骤来选中或取消选中匹配 选择器 的元素:
- 查找匹配 选择器 的元素。如果不存在,则等待直到匹配的元素附加到 DOM。
- 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出错误。
- 如果元素已经处于正确的选中状态,此方法将立即返回。
- 等待对匹配元素进行 可操作性 检查,除非设置了 Force 选项。如果在检查期间元素被分离,则整个操作会重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 在元素的中心点击。
- 确保元素现在处于选中或未选中状态。如果不是,此方法将抛出错误。
如果在指定的 Timeout 期间所有步骤都没有完成,此方法将抛出 TimeoutError。传递零超时将禁用此功能。
用法
await Page.SetCheckedAsync(selector, checked, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
是否选中或取消选中复选框。
-
options
PageSetCheckedOptions?
(可选)-
是否绕过可操作性检查。默认为
false
。 -
已弃用
此选项无效。
此选项无效。
-
Position
Position? (可选)#-
X
[float] -
Y
[float]
相对于元素内边距框左上角的点。如果未指定,则使用元素的某个可见点。
-
-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。 -
设置后,此方法仅执行可操作性检查并跳过实际操作。默认为
false
。这对于等待元素准备好进行操作而无需实际执行操作很有用。
-
返回值
SetInputFilesAsync
在 v1.9 之前添加建议改用基于 locators 的 Locator.SetInputFilesAsync()。阅读有关 locators 的更多信息。
将文件输入的值设置为这些文件路径或文件。如果某些 filePaths
是相对路径,则它们将相对于当前工作目录解析。对于空数组,清除选定的文件。对于具有 [webkitdirectory]
属性的输入,仅支持单个目录路径。
此方法要求 选择器 指向一个 input 元素。但是,如果元素位于具有关联 control 的 `<label>` 元素内,则将改为定位该 control。
用法
await Page.SetInputFilesAsync(selector, files, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
files
string | IEnumerable<string> |FilePayload
| IEnumerable<FilePayload
># -
options
PageSetInputFilesOptions?
(可选)-
已弃用
此选项无效。
此选项无效。
-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
TapAsync
在 v1.9 之前添加建议改用基于 locators 的 Locator.TapAsync()。阅读有关 locators 的更多信息。
此方法通过执行以下步骤来点击匹配 选择器 的元素:
- 查找匹配 选择器 的元素。如果不存在,则等待直到匹配的元素附加到 DOM。
- 等待对匹配元素进行 可操作性 检查,除非设置了 Force 选项。如果在检查期间元素被分离,则整个操作会重试。
- 如果需要,将元素滚动到视图中。
- 使用 Page.Touchscreen 点击元素的中心,或指定的 Position。
如果在指定的 Timeout 期间所有步骤都没有完成,此方法将抛出 TimeoutError。传递零超时将禁用此功能。
Page.TapAsync() 方法在浏览器上下文的 HasTouch 选项为 false 时将抛出错误。
用法
await Page.TapAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageTapOptions?
(可选)-
是否绕过可操作性检查。默认为
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() 方法更改。 -
设置后,此方法仅执行可操作性 (actionability) 检查并跳过操作。默认为
false
。在不执行操作的情况下等待元素准备就绪时很有用。请注意,无论是否进行trial
尝试,都会按下键盘modifiers
,以允许测试只有在按下这些键时才可见的元素。
-
返回值
TextContentAsync
在 v1.9 之前添加建议改用基于 locators 的 Locator.TextContentAsync()。阅读有关 locators 的更多信息。
返回 element.textContent
。
用法
await Page.TextContentAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageTextContentOptions?
(可选)-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
TypeAsync
在 v1.9 之前添加在大多数情况下,您应该使用 Locator.FillAsync()
。只有当页面有特殊的键盘处理时,才需要一个一个地按下按键——在这种情况下使用 Locator.PressSequentiallyAsync()
。
为文本中的每个字符发送一个 keydown
、keypress
/input
和 keyup
事件。page.type
可用于发送细粒度的键盘事件。要在表单字段中填充值,请使用 Page.FillAsync()
。
要按下特殊键,如 Control
或 ArrowDown
,请使用 Keyboard.PressAsync()
。
用法
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
要输入到获得焦点元素的文本。
-
options
PageTypeOptions?
(可选)-
Delay
[float]? (可选)#按键之间的等待时间(以毫秒为单位)。默认为 0。
-
已弃用
此选项无效。
此选项无效。
-
为 true 时,要求选择器解析为单个元素。如果给定的选择器解析到多个元素,调用将抛出异常。
-
Timeout
[float]? (可选)#最大时间(毫秒)。默认为
30000
(30 秒)。传递0
以禁用超时。默认值可以通过使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法更改。
-
返回值
UncheckAsync
在 v1.9 之前添加请使用基于定位符的 Locator.UncheckAsync()
。阅读更多关于定位符的内容。
此方法通过执行以下步骤取消选中与 selector
匹配的元素
- 查找与
selector
匹配的元素。如果没有找到,则等待直到匹配的元素附加到 DOM。 - 确保匹配的元素是复选框或单选输入。如果不是,此方法将抛出错误。如果元素已经被取消选中,此方法将立即返回。
- 等待对匹配的元素进行 可操作性 (actionability) 检查,除非设置了
Force
选项。如果在检查期间元素被分离,整个操作将重试。 - 如果需要,将元素滚动到视图中。
- 使用 Page.Mouse 在元素的中心点击。
- 确保元素现在未被选中。如果不是,此方法将抛出错误。
如果在指定的 Timeout
期间所有步骤总计未完成,此方法将抛出 TimeoutError
。将超时设置为零会禁用此功能。
用法
await Page.UncheckAsync(selector, options);
参数
-
用于搜索元素的 selector。如果存在多个满足 selector 的元素,将使用第一个。
-
options
PageUncheckOptions?
(可选)-
是否绕过可操作性检查。默认为
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()
。阅读更多关于定位符的内容。
当由 selector
指定的元素满足 State
选项时返回。如果等待 hidden
或 detached
,则返回 null
。
Playwright 在执行操作之前会自动等待元素就绪。使用 Locator
对象和 web-first 断言使代码无需等待选择器。
等待 selector
满足 State
选项(从 DOM 出现/消失,或变得可见/隐藏)。如果在调用方法时 selector
已经满足条件,该方法将立即返回。如果选择器在 Timeout
毫秒内不满足条件,函数将抛出错误。
用法
此方法适用于跨导航
using Microsoft.Playwright;
using System;
using System.Threading.Tasks;
class FrameExamples
{
public static async Task Images()
{
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);
var element = await page.WaitForSelectorAsync("img");
Console.WriteLine($"Loaded image: {await element.GetAttributeAsync("src")}");
}
await browser.CloseAsync();
}
}
参数
-
用于查询的 selector。
-
options
PageWaitForSelectorOptions?
(可选)-
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 断言。
等待给定的 timeout
毫秒。
请注意,page.waitForTimeout()
只应用于调试。在生产中使用计时器的测试将会不稳定。请改用网络事件、选择器可见等信号。
用法
// Wait for 1 second
await page.WaitForTimeoutAsync(1000);
参数
-
timeout
[float]#要等待的超时时间
返回值