BrowserContext
BrowserContexts 提供了一种操作多个独立浏览器会话的方式。
如果一个页面打开了另一个页面,例如通过window.open
调用,弹出窗口将属于父页面的浏览器上下文。
Playwright允许通过Browser.NewContextAsync()方法创建隔离的非持久性浏览器上下文。非持久性浏览器上下文不会向磁盘写入任何浏览数据。
using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Firefox.LaunchAsync(new() { Headless = false });
// Create a new incognito browser context
var context = await browser.NewContextAsync();
// Create a new page inside context.
var page = await context.NewPageAsync();
await page.GotoAsync("https://bing.com");
// Dispose context once it is no longer needed.
await context.CloseAsync();
方法
AddCookiesAsync
Added before v1.9将cookies添加到此浏览器上下文中。该上下文内的所有页面都将安装这些cookies。可以通过BrowserContext.CookiesAsync()获取cookies。
用法
await context.AddCookiesAsync(new[] { cookie1, cookie2 });
参数
cookies
IEnumerable<Cookie
>#-
Name
string -
Value
string -
Url
string? (可选)url 或 domain / path 必须提供其中一项。可选参数。
-
Domain
string? (可选)要使cookie适用于所有子域名,请在域名前加上点号,例如:".example.com"。必须提供url或domain/path。可选参数。
-
Path
string? (可选)必须提供url或domain/path中的任意一个 可选。
-
Expires
[float]? (可选)Unix时间,单位为秒。可选参数。
-
HttpOnly
bool? (可选)可选项。
-
Secure
bool? (可选)可选参数。
-
SameSite
enum SameSiteAttribute { Strict, Lax, None }?
(可选)可选项。
-
返回
AddInitScriptAsync
Added before v1.9添加一个脚本,该脚本将在以下任一场景中被执行:
- 每当在浏览器上下文中创建页面或进行导航时。
- 每当浏览器上下文中任何页面的子框架被附加或导航时。在这种情况下,脚本会在新附加框架的上下文中进行评估。
脚本会在文档创建后但在其任何脚本运行前被评估。这对于修改JavaScript环境非常有用,例如用于初始化Math.random
。
用法
在页面加载前覆盖Math.random
的示例:
// preload.js
Math.random = () => 42;
await Context.AddInitScriptAsync(scriptPath: "preload.js");
通过BrowserContext.AddInitScriptAsync()和Page.AddInitScriptAsync()安装的多个脚本的执行顺序是未定义的。
参数
返回
后台页面
Added in: v1.11后台页面仅在基于Chromium的浏览器中受支持。
上下文中的所有现有后台页面。
用法
BrowserContext.BackgroundPages
返回
浏览器
Added before v1.9返回上下文的浏览器实例。如果是作为持久化上下文启动的,则返回null。
用法
BrowserContext.Browser
返回
ClearCookiesAsync
Added before v1.9从上下文中移除cookies。接受可选过滤器。
用法
await context.ClearCookiesAsync();
await context.ClearCookiesAsync(new() { Name = "session-id" });
await context.ClearCookiesAsync(new() { Domain = "my-origin.com" });
await context.ClearCookiesAsync(new() { Path = "/api/v1" });
await context.ClearCookiesAsync(new() { Name = "session-id", Domain = "my-origin.com" });
参数
options
BrowserContextClearCookiesOptions?
(optional)
返回
ClearPermissionsAsync
Added before v1.9清除浏览器上下文的所有权限覆盖设置。
用法
var context = await browser.NewContextAsync();
await context.GrantPermissionsAsync(new[] { "clipboard-read" });
// Alternatively, you can use the helper class ContextPermissions
// to specify the permissions...
// do stuff ...
await context.ClearPermissionsAsync();
返回
CloseAsync
Added before v1.9关闭浏览器上下文。属于该浏览器上下文的所有页面都将被关闭。
默认浏览器上下文无法关闭。
用法
await BrowserContext.CloseAsync(options);
参数
options
BrowserContextCloseOptions?
(optional)
返回
CookiesAsync
Added before v1.9如果未指定URL,此方法将返回所有cookie。如果指定了URL,则仅返回影响这些URL的cookie。
用法
await BrowserContext.CookiesAsync(urls);
参数
-
urls
string? | IEnumerable?<string> (可选)#可选的URL列表。
返回
- IEnumerable<
Cookie
>#
ExposeBindingAsync
Added before v1.9该方法在上下文中每个页面的每个框架的window
对象上添加一个名为name的函数。当被调用时,该函数执行callback并返回一个Promise,该Promise会解析为callback的返回值。如果callback返回一个Promise,它将被等待。
callback函数的第一个参数包含调用者的信息:{ browserContext: BrowserContext, page: Page, frame: Frame }
。
查看Page.ExposeBindingAsync()获取仅限页面的版本。
用法
一个示例,展示如何在上下文中向所有页面中的所有框架公开页面URL:
using Microsoft.Playwright;
using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Webkit.LaunchAsync(new() { Headless = false });
var context = await browser.NewContextAsync();
await context.ExposeBindingAsync("pageURL", source => source.Page.Url);
var page = await context.NewPageAsync();
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.GetByRole(AriaRole.Button).ClickAsync();
参数
-
窗口对象上的函数名称。
-
将在Playwright上下文中调用的回调函数。
-
options
BrowserContextExposeBindingOptions?
(可选)
返回
ExposeFunctionAsync
Added before v1.9该方法在上下文环境中每个页面的每个框架的window
对象上添加一个名为name的函数。当调用时,该函数执行callback并返回一个Promise,该Promise会解析为callback的返回值。
查看Page.ExposeFunctionAsync()获取仅限页面的版本。
用法
一个在上下文中为所有页面添加sha256
函数的示例:
using Microsoft.Playwright;
using System;
using System.Security.Cryptography;
using System.Threading.Tasks;
class BrowserContextExamples
{
public static async Task Main()
{
using var playwright = await Playwright.CreateAsync();
var browser = await playwright.Webkit.LaunchAsync(new() { Headless = false });
var context = await browser.NewContextAsync();
await context.ExposeFunctionAsync("sha256", (string input) =>
{
return Convert.ToBase64String(
SHA256.Create().ComputeHash(System.Text.Encoding.UTF8.GetBytes(input)));
});
var page = await context.NewPageAsync();
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.GetByRole(AriaRole.Button).ClickAsync();
Console.WriteLine(await page.TextContentAsync("div"));
}
}
参数
返回
GrantPermissionsAsync
Added before v1.9授予浏览器上下文指定的权限。如果指定了来源,则仅授予该来源相应的权限。
用法
await BrowserContext.GrantPermissionsAsync(permissions, options);
参数
-
permissions
IEnumerable<string>#授予的权限列表。
danger不同浏览器之间支持的权限有所不同,即使是同一浏览器的不同版本之间也可能存在差异。任何权限在更新后都可能停止工作。
以下是一些可能被某些浏览器支持的权限:
'accelerometer'
'ambient-light-sensor'
'background-sync'
'camera'
'clipboard-read'
'clipboard-write'
'geolocation'
'gyroscope'
'magnetometer'
'microphone'
'midi-sysex'
(系统专用MIDI)'midi'
'notifications'
'payment-handler'
'storage-access'
-
options
BrowserContextGrantPermissionsOptions?
(可选)-
要授予权限的来源,例如"https://example.com"。
-
返回
NewCDPSessionAsync
Added in: v1.11CDP会话仅在基于Chromium的浏览器中受支持。
返回新创建的会话。
用法
await BrowserContext.NewCDPSessionAsync(page);
参数
返回
NewPageAsync
Added before v1.9在浏览器上下文中创建一个新页面。
用法
await BrowserContext.NewPageAsync();
返回
页面
Added before v1.9返回上下文中所有打开的页面。
用法
BrowserContext.Pages
返回
RouteAsync
Added before v1.9路由功能提供了修改浏览器上下文中任何页面发出的网络请求的能力。一旦启用路由,每个匹配URL模式的请求都将被暂停,除非它被继续、完成或中止。
BrowserContext.RouteAsync() 不会拦截被Service Worker拦截的请求。请参阅此问题。我们建议在使用请求拦截时,通过将ServiceWorkers设置为'block'
来禁用Service Workers。
用法
一个简单的处理程序示例,它会中止所有图片请求:
var context = await browser.NewContextAsync();
var page = await context.NewPageAsync();
await context.RouteAsync("**/*.{png,jpg,jpeg}", r => r.AbortAsync());
await page.GotoAsync("https://theverge.com");
await browser.CloseAsync();
或者使用正则表达式模式替代的相同代码片段:
var context = await browser.NewContextAsync();
var page = await context.NewPageAsync();
await context.RouteAsync(new Regex("(\\.png$)|(\\.jpg$)"), r => r.AbortAsync());
await page.GotoAsync("https://theverge.com");
await browser.CloseAsync();
可以检查请求来决定路由操作。例如,模拟所有包含某些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();
});
当请求同时匹配多个处理器时,页面路由(通过Page.RouteAsync()设置)的优先级高于浏览器上下文路由。
要移除带有处理程序的路由,您可以使用 BrowserContext.UnrouteAsync()。
启用路由会禁用http缓存。
参数
-
url
string | Regex | Func<string, bool>#在路由时用于匹配URL的全局模式、正则表达式模式或接收URL的谓词函数。当通过上下文选项提供了BaseURL且传入的URL是路径时,会通过
new URL()
构造函数进行合并。 -
用于路由请求的处理函数。
-
options
BrowserContextRouteOptions?
(可选)
返回
RouteFromHARAsync
Added in: v1.23如果指定了该选项,上下文中的网络请求将从HAR文件提供。了解更多关于从HAR回放的信息。
Playwright 不会处理由 Service Worker 从 HAR 文件中拦截的请求。请参阅此问题。我们建议在使用请求拦截时,通过将ServiceWorkers设置为'block'
来禁用 Service Workers。
用法
await BrowserContext.RouteFromHARAsync(har, options);
参数
-
指向包含预录制网络数据的HAR文件的路径。如果
path
是相对路径,则会相对于当前工作目录进行解析。 -
options
BrowserContextRouteFromHAROptions?
(可选)-
NotFound
enum HarNotFound { Abort, Fallback }?
(可选)#- 如果设置为'abort',任何在HAR文件中找不到的请求都将被中止。
- 如果设置为'fallback',将回退到处理程序链中的下一个路由处理程序。
默认为中止。
-
如果指定此参数,将使用实际的网络信息更新给定的HAR文件,而不是从文件读取。该文件会在调用BrowserContext.CloseAsync()时写入磁盘。
-
UpdateContent
enum RouteFromHarUpdateContentPolicy { Embed, Attach }?
(可选) 添加于: v1.32#用于控制资源内容管理的可选设置。如果指定了
attach
,资源将作为单独的文件或ZIP存档中的条目持久保存。如果指定了embed
,内容将内联存储在HAR文件中。 -
UpdateMode
enum HarMode { Full, Minimal }?
(可选) 添加于: v1.32#当设置为
minimal
时,仅记录从HAR路由所必需的信息。这会省略大小、时间、页面、cookies、安全和其他类型的HAR信息,这些信息在从HAR回放时不会被使用。默认为minimal
。 -
Url|UrlRegex
string? | Regex? (可选)#用于匹配请求URL的通配符模式、正则表达式或谓词。只有URL匹配该模式的请求才会从HAR文件中获取响应。如果未指定,则所有请求都将从HAR文件中获取响应。
-
返回
RouteWebSocketAsync
Added in: v1.48该方法允许修改浏览器上下文中任何页面建立的websocket连接。
请注意,只有在此方法调用后创建的WebSocket
才会被路由。建议在创建任何页面之前调用此方法。
用法
以下是一个简单处理程序的示例,它可以阻止某些WebSocket消息。更多详情和示例请参阅WebSocketRoute。
await context.RouteWebSocketAsync("/ws", async ws => {
ws.RouteSend(message => {
if (message == "to-be-blocked")
return;
ws.Send(message);
});
await ws.ConnectAsync();
});
参数
-
url
string | Regex | Func<string, bool>#只有URL匹配此模式的WebSocket连接会被路由。字符串模式可以相对于BaseURL上下文选项。
-
handler
Action<WebSocketRoute>#用于路由WebSocket的处理函数。
返回
RunAndWaitForConsoleMessageAsync
Added in: v1.34执行操作并等待上下文中的页面记录ConsoleMessage。如果提供了谓词函数,会将ConsoleMessage值传递给predicate
函数,并等待predicate(message)
返回真值。如果在BrowserContext.Console事件触发前页面被关闭,将会抛出错误。
用法
await BrowserContext.RunAndWaitForConsoleMessageAsync(action, options);
参数
-
触发事件的动作。
-
options
BrowserContextRunAndWaitForConsoleMessageOptions?
(可选)-
Predicate
Func<ConsoleMessage?, bool> (可选)#接收ConsoleMessage对象,当等待应该解决时解析为真值。
-
Timeout
[float]? (可选)#最大等待时间,单位为毫秒。默认为
30000
(30秒)。传入0
表示禁用超时。默认值可以通过BrowserContext.SetDefaultTimeout()进行修改。
-
返回
等待控制台消息异步
Added in: v1.34执行操作并等待上下文中的页面记录ConsoleMessage。如果提供了predicate函数,会将ConsoleMessage值传入predicate
函数,并等待predicate(message)
返回真值。如果在触发BrowserContext.Console事件前页面被关闭,将抛出错误。
用法
await BrowserContext.WaitForConsoleMessageAsync(action, options);
参数
options
BrowserContextRunAndWaitForConsoleMessageOptions?
(optional)-
Predicate
Func<ConsoleMessage?, bool> (可选)#接收ConsoleMessage对象,当等待应该解决时解析为真值。
-
Timeout
[float]? (可选)#最大等待时间,单位为毫秒。默认为
30000
(30秒)。传入0
表示禁用超时。默认值可以通过使用BrowserContext.SetDefaultTimeout()来修改。
-
返回
RunAndWaitForPageAsync
Added in: v1.9执行操作并等待上下文中创建一个新的Page。如果提供了predicate,它会将Page值传递给predicate
函数,并等待predicate(event)
返回真值。如果在创建新的Page之前上下文关闭,将会抛出错误。
用法
await BrowserContext.RunAndWaitForPageAsync(action, options);
参数
-
触发该事件的动作。
-
options
BrowserContextRunAndWaitForPageOptions?
(可选)
返回
WaitForPageAsync
Added in: v1.9执行操作并等待上下文中创建一个新的Page。如果提供了predicate,它会将Page值传递给predicate
函数,并等待predicate(event)
返回真值。如果在创建新的Page之前上下文关闭,将会抛出错误。
用法
await BrowserContext.WaitForPageAsync(action, options);
参数
options
BrowserContextRunAndWaitForPageOptions?
(optional)
返回
设置默认导航超时时间
Added before v1.9此设置将更改以下方法及相关快捷方式的默认最大导航时间:
- Page.GoBackAsync()
- Page.GoForwardAsync()
- Page.GotoAsync()
- Page.ReloadAsync()
- Page.SetContentAsync()
- Page.RunAndWaitForNavigationAsync()
用法
BrowserContext.SetDefaultNavigationTimeout(timeout);
参数
-
timeout
[float]#最大导航时间(毫秒)
设置默认超时时间
Added before v1.9此设置将更改所有接受timeout选项的方法的默认最大时间。
用法
BrowserContext.SetDefaultTimeout(timeout);
参数
-
timeout
[float]#最大时间,单位为毫秒。传入
0
表示禁用超时。
SetExtraHTTPHeadersAsync
Added before v1.9额外的HTTP头信息将与上下文中任何页面发起的每个请求一起发送。这些头信息与通过Page.SetExtraHTTPHeadersAsync()设置的页面特定额外HTTP头信息合并。如果页面覆盖了某个特定头信息,将使用页面特定的头信息值而非浏览器上下文的头信息值。
BrowserContext.SetExtraHTTPHeadersAsync() 不能保证传出请求中头信息的顺序。
用法
await BrowserContext.SetExtraHTTPHeadersAsync(headers);
参数
-
headers
IDictionary<string, string>#一个包含要随每个请求发送的额外HTTP头信息的对象。所有头信息的值必须是字符串。
返回
SetGeolocationAsync
Added before v1.9设置上下文的定位地理位置。传入null
或undefined
将模拟位置不可用状态。
用法
await context.SetGeolocationAsync(new Geolocation()
{
Latitude = 59.95f,
Longitude = 30.31667f
});
考虑使用 BrowserContext.GrantPermissionsAsync() 来授予浏览器上下文页面读取其地理位置的权限。
参数
geolocation
Geolocation?#-
Latitude
[float]纬度值介于-90到90之间。
-
Longitude
[float]介于-180到180之间的经度值。
-
Accuracy
[float]? (可选)非负精度值。默认为
0
。
-
返回
SetOfflineAsync
Added before v1.9用法
await BrowserContext.SetOfflineAsync(offline);
参数
返回
StorageStateAsync
Added before v1.9返回此浏览器上下文的存储状态,包含当前cookies、本地存储快照和IndexedDB快照。
用法
await BrowserContext.StorageStateAsync(options);
参数
options
BrowserContextStorageStateOptions?
(optional)
返回
UnrouteAsync
Added before v1.9移除通过BrowserContext.RouteAsync()创建的路由。当未指定handler时,将移除该url的所有路由。
用法
await BrowserContext.UnrouteAsync(url, handler);
参数
-
url
string | Regex | Func<string, bool>#一个用于接收URL的全局模式、正则表达式模式或谓词,用于通过BrowserContext.RouteAsync()注册路由。
-
用于通过BrowserContext.RouteAsync()注册路由的可选处理函数。
返回
UnrouteAllAsync
Added in: v1.41移除所有通过BrowserContext.RouteAsync()和BrowserContext.RouteFromHARAsync()创建的路由。
用法
await BrowserContext.UnrouteAllAsync(options);
参数
options
BrowserContextUnrouteAllOptions?
(optional)-
Behavior
enum UnrouteBehavior { Wait, IgnoreErrors, Default }?
(可选)#指定是否等待已运行的处理器以及当它们抛出错误时的处理方式:
'default'
- 不等待当前处理程序调用(如果有)完成,如果未路由的处理程序抛出异常,可能导致未处理的错误'wait'
- 等待当前处理程序调用(如果有)完成'ignoreErrors'
- 不等待当前处理程序调用(如果有)完成,取消路由后由处理程序抛出的所有错误将被静默捕获
-
返回
属性
API请求
Added in: v1.16与此上下文关联的API测试助手。使用此API发出的请求将使用上下文中的cookies。
用法
BrowserContext.APIRequest
类型
时钟
Added in: v1.45Playwright 具备模拟时钟和时间流逝的功能。
用法
BrowserContext.Clock
类型
追踪
Added in: v1.12用法
BrowserContext.Tracing
类型
事件
事件 BackgroundPage
Added in: v1.11仅适用于Chromium浏览器的持久化上下文。
当上下文中创建新的后台页面时触发。
context.BackgroundPage += (_, backgroundPage) =>
{
Console.WriteLine(backgroundPage.Url);
};
用法
BrowserContext.BackgroundPage += async (_, page) => {};
事件数据
关闭事件
Added before v1.9当浏览器上下文关闭时触发。这可能由以下原因之一导致:
- 浏览器上下文已关闭。
- 浏览器应用程序已关闭或崩溃。
- 调用了 Browser.CloseAsync() 方法。
用法
BrowserContext.Close += async (_, browserContext) => {};
事件数据
事件 Console
Added in: v1.34当页面中的JavaScript调用控制台API方法时触发,例如 console.log
或 console.dir
。
传递给console.log
的参数和页面内容可在ConsoleMessage事件处理程序参数中使用。
用法
context.Console += async (_, msg) =>
{
foreach (var arg in msg.Args)
Console.WriteLine(await arg.JsonValueAsync<object>());
};
await page.EvaluateAsync("console.log('hello', 5, { foo: 'bar' })");
事件数据
事件对话框
Added in: v1.34当出现JavaScript对话框时触发,例如alert
、prompt
、confirm
或beforeunload
。监听器必须选择Dialog.AcceptAsync()或Dialog.DismissAsync()来处理对话框 - 否则页面将冻结等待对话框响应,点击等操作将永远无法完成。
用法
Context.Dialog += async (_, dialog) =>
{
await dialog.AcceptAsync();
};
当没有设置Page.Dialog或BrowserContext.Dialog监听器时,所有对话框将自动被关闭。
事件数据
事件 Page
Added before v1.9当在BrowserContext中创建新Page时,会触发该事件。页面可能仍在加载中。该事件也会针对弹出页面触发。另请参阅Page.Popup以接收与特定页面相关的弹出窗口事件。
页面最早可用的时刻是当它导航到初始URL时。例如,当使用window.open('http://example.com')
打开弹出窗口时,这个事件将在对"http://example.com"的网络请求完成且其响应开始在弹出窗口中加载时触发。如果您想路由/监听此网络请求,请分别使用BrowserContext.RouteAsync()和BrowserContext.Request,而不是在Page上使用类似方法。
var popup = await context.RunAndWaitForPageAsync(async =>
{
await page.GetByText("open new page").ClickAsync();
});
Console.WriteLine(await popup.EvaluateAsync<string>("location.href"));
使用 Page.WaitForLoadStateAsync() 等待页面进入特定状态(在大多数情况下您不需要它)。
用法
BrowserContext.Page += async (_, page) => {};
事件数据
事件 请求
Added in: v1.12当通过此上下文创建的任何页面发出请求时触发。request对象是只读的。要仅监听特定页面的请求,请使用Page.Request。
为了拦截和修改请求,请参阅BrowserContext.RouteAsync()或Page.RouteAsync()。
用法
BrowserContext.Request += async (_, request) => {};
事件数据
事件 RequestFailed
Added in: v1.12当请求失败时触发,例如超时。若只想监听特定页面的失败请求,请使用Page.RequestFailed。
HTTP错误响应,如404或503,从HTTP角度来看仍然是成功的响应,因此请求将以BrowserContext.RequestFinished事件完成,而不是以BrowserContext.RequestFailed事件完成。
用法
BrowserContext.RequestFailed += async (_, request) => {};
事件数据
事件 RequestFinished
Added in: v1.12当请求成功下载响应体后触发。对于一个成功的响应,事件顺序是request
、response
和requestfinished
。要监听特定页面的成功请求,请使用Page.RequestFinished。
用法
BrowserContext.RequestFinished += async (_, request) => {};
事件数据
事件响应
Added in: v1.12当请求收到response状态和头部时触发。对于成功的响应,事件顺序是request
、response
和requestfinished
。要监听特定页面的响应事件,请使用Page.Response。
用法
BrowserContext.Response += async (_, response) => {};
事件数据
事件 WebError
Added in: v1.38当此上下文中任何页面出现未捕获的异常时触发。要监听特定页面的错误,请改用Page.PageError。
用法
BrowserContext.WebError += async (_, webError) => {};
事件数据