BrowserContext

浏览器上下文（BrowserContexts）提供了一种操作多个独立浏览器会话的方式。

如果一个页面打开另一个页面，例如通过 window.open 调用，弹出窗口将属于父页面的浏览器上下文。

Playwright 允许使用 Browser.newContext() 方法创建隔离的非持久化浏览器上下文。非持久化浏览器上下文不会将任何浏览数据写入磁盘。

// 创建一个新的无痕浏览器上下文
BrowserContext context = browser.newContext();
// 在上下文中创建一个新页面。
Page page = context.newPage();
page.navigate("https://example.com");
// 当上下文不再需要时，释放它。
context.close();

方法

addCookies

在 v1.9 之前添加

browserContext.addCookies

将 cookies 添加到此浏览器上下文。此上下文中的所有页面都将安装这些 cookies。可以通过 BrowserContext.cookies() 获取 cookies。

用法

browserContext.addCookies(Arrays.asList(cookieObject1, cookieObject2));

参数

cookies List<Cookie>#
- setName String
- setValue String
- setUrl String（可选）
  
  url 或 domain/path 二者必填其一。可选。
- setDomain String（可选）
  
  若要使 cookie 也应用于所有子域，请在域名前加一个点，如下所示：".example.com"。url 或 domain/path 二者必填其一。可选。
- setPath String（可选）
  
  url 或 domain/path 二者必填其一。可选。
- setExpires double（可选）
  
  以秒为单位的 Unix 时间。可选。
- setHttpOnly boolean（可选）
  
  可选。
- setSecure boolean（可选）
  
  可选。
- setSameSite enum SameSiteAttribute { STRICT, LAX, NONE }（可选）
  
  可选。

返回值

void #

addInitScript

在 v1.9 之前添加

browserContext.addInitScript

添加一个脚本，该脚本会在以下场景之一中执行：

每当在浏览器上下文中创建页面或导航到新页面时。
每当在浏览器上下文中的任何页面中附加或导航子框架时。在这种情况下，脚本会在新附加框架的上下文中执行。

该脚本在文档创建后但在其任何脚本运行之前执行。这对于修改 JavaScript 环境很有用，例如为 Math.random 设定初始值。

用法

在页面加载前重写 Math.random 的示例：

// preload.js
Math.random = () => 42;

// 在你的 Playwright 脚本中，假设 preload.js 文件在同一目录下。
browserContext.addInitScript(Paths.get("preload.js"));

备注

通过 BrowserContext.addInitScript() 和 Page.addInitScript() 安装的多个脚本的执行顺序未定义。

参数

script String | Path # 在浏览器上下文中的所有页面中执行的脚本。

返回值

void #

backgroundPages

添加于：v1.11

browserContext.backgroundPages

备注

后台页面仅在基于 Chromium 的浏览器上受支持。

上下文中所有现有的后台页面。

用法

BrowserContext.backgroundPages();

返回值

List<Page>#

browser

在 v1.9 之前添加browserContext.browser 返回上下文的浏览器实例。如果它作为持久化上下文启动，则返回 null。

用法

BrowserContext.browser();

返回值

null | Browser #

clearCookies

在 v1.9 之前添加

browserContext.clearCookies

从上下文中移除 cookie。接受可选的筛选条件。

用法

context.clearCookies();
context.clearCookies(new BrowserContext.ClearCookiesOptions().setName("session-id"));
context.clearCookies(new BrowserContext.ClearCookiesOptions().setDomain("my-origin.com"));
context.clearCookies(new BrowserContext.ClearCookiesOptions().setPath("/api/v1"));
context.clearCookies(new BrowserContext.ClearCookiesOptions()
                         .setName("session-id")
                         .setDomain("my-origin.com"));

参数

options BrowserContext.ClearCookiesOptions (可选)
- setDomain String | Pattern (可选) 在 v1.43 中添加#
  
  仅移除具有给定域名的 cookie。
- setName String | Pattern (可选) 在 v1.43 中添加#
  
  仅移除具有给定名称的 cookie。
- setPath String | Pattern (可选) 在 v1.43 中添加#
  
  仅移除具有给定路径的 cookie。

返回值

void #

clearPermissions

在 v1.9 之前添加

browserContext.clearPermissions

清除浏览器上下文的所有权限覆盖设置。

用法

BrowserContext context = browser.newContext();
context.grantPermissions(Arrays.asList("clipboard-read"));
// 执行操作...
context.clearPermissions();

返回值

void #

close

在 v1.9 之前添加

browserContext.close

关闭浏览器上下文。属于该浏览器上下文的所有页面都将被关闭。

:::注意默认浏览器上下文无法关闭。 :::

用法

BrowserContext.close();
BrowserContext.close(options);

参数

options BrowserContext.CloseOptions (可选)
- setReason String (可选) 在 v1.40 中添加#
  
  报告给因上下文关闭而中断的操作的原因。

返回值

void #

cookies

在 v1.9 之前添加

browserContext.cookies

如果未指定 URL，此方法将返回所有 cookie。如果指定了 URL，则仅返回影响这些 URL 的 cookie。

用法

BrowserContext.cookies();
BrowserContext.cookies(urls);

参数

urls String | List<String>（可选）#

可选的 URL 列表。

返回值

List<Cookie>#
- name String
- value String
- domain String
- path String
- expires double
  
  以秒为单位的 Unix 时间。
- httpOnly boolean
- secure boolean
- sameSite enum SameSiteAttribute { STRICT, LAX, NONE }

exposeBinding

在 v1.9 之前添加

browserContext.exposeBinding

此方法会在上下文中每个页面的每个框架的 window 对象上添加一个名为 name 的函数。调用时，该函数会执行 callback 并返回一个 Promise，该 Promise 会解析为 callback 的返回值。如果 callback 返回一个 Promise，则会等待该 Promise 完成。

callback 函数的第一个参数包含有关调用者的信息：{ browserContext: BrowserContext, page: Page, frame: Frame }。

仅针对页面的版本，请参阅 Page.exposeBinding()。

用法

以下是一个将页面 URL 暴露给上下文中所有页面的所有框架的示例：

import com.microsoft.playwright.*;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      BrowserType webkit = playwright.webkit();
      Browser browser = webkit.launch(new BrowserType.LaunchOptions().setHeadless(false));
      BrowserContext context = browser.newContext();
      context.exposeBinding("pageURL", (source, args) -> source.page().url());
      Page page = context.newPage();
      page.setContent("<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>");
      page.getByRole(AriaRole.BUTTON).click();
    }
  }
}

参数

name String #

window 对象上函数的名称。
callback BindingCallback#

将在 Playwright 上下文中调用的回调函数。
options BrowserContext.ExposeBindingOptions (可选)
- setHandle boolean (可选)#
  
  已弃用
  此选项将来会被移除。
  
  是否将参数作为句柄传递，而不是按值传递。传递句柄时，仅支持一个参数。按值传递时，支持多个参数。

返回值

void #

exposeFunction

在 v1.9 之前添加

browserContext.exposeFunction

此方法会在上下文中每个页面的每个框架的 window 对象上添加一个名为 name 的函数。调用该函数时，会执行 callback 并返回一个 Promise，该 Promise 会解析为 callback 的返回值。

如果 callback 返回一个 Promise，则会等待该 Promise 完成。

仅作用于页面的版本请参考 Page.exposeFunction()。

用法

以下是在上下文中向所有页面添加 sha256 函数的示例：

import com.microsoft.playwright.*;

import java.nio.charset.StandardCharsets;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.Base64;

public class Example {
  public static void main(String[] args) {
    try (Playwright playwright = Playwright.create()) {
      BrowserType webkit = playwright.webkit();
      Browser browser = webkit.launch(new BrowserType.LaunchOptions().setHeadless(false));
      BrowserContext context = browser.newContext();
      context.exposeFunction("sha256", args -> {
        String text = (String) args[0];
        MessageDigest crypto;
        try {
          crypto = MessageDigest.getInstance("SHA-256");
        } catch (NoSuchAlgorithmException e) {
          return null;
        }
        byte[] token = crypto.digest(text.getBytes(StandardCharsets.UTF_8));
        return Base64.getEncoder().encodeToString(token);
      });
      Page page = context.newPage();
      page.setContent("<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>\n");
      page.getByRole(AriaRole.BUTTON).click();
    }
  }
}

参数

name String # 窗口对象上函数的名称。
callback FunctionCallback# 将在 Playwright 上下文中调用的回调函数。

返回值

void #

grantPermissions

在 v1.9 之前添加

browserContext.grantPermissions

向浏览器上下文授予指定的权限。如果指定了来源，则仅向给定来源授予相应权限。

用法

BrowserContext.grantPermissions(permissions);
BrowserContext.grantPermissions(permissions, options);

参数

permissions List<String># 要授予的权限列表。
危险
不同浏览器支持的权限不同，甚至同一浏览器的不同版本支持的权限也不同。任何权限都可能在更新后无法使用。
以下是一些可能被某些浏览器支持的权限：
- '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 BrowserContext.GrantPermissionsOptions（可选）
- setOrigin String（可选）# 要授予权限的 [来源]，例如 "https://example.com"。

返回值

void #

newCDPSession

添加于：v1.11

browserContext.newCDPSession

:::注意 CDP 会话仅在基于 Chromium 的浏览器上受支持。 :::

返回新创建的会话。

用法

BrowserContext.newCDPSession(page);

参数

page Page | Frame #

为其创建新会话的目标。为了向后兼容，此参数名为 page，但它可以是 Page 或 Frame 类型。

返回值

CDPSession #

newPage

在 v1.9 之前添加

browserContext.newPage

在浏览器上下文中创建一个新页面。

用法

BrowserContext.newPage();

返回值

Page #

pages

在 v1.9 之前添加

browserContext.pages

返回上下文中所有打开的页面。

用法

BrowserContext.pages();

返回值

List<Page>#

route

在 v1.9 之前添加

browserContext.route

路由功能允许修改浏览器上下文中任何页面发出的网络请求。一旦启用路由，与 URL 模式匹配的每个请求都将暂停，除非继续、完成或中止该请求。

:::注意

BrowserContext.route() 不会拦截由 Service Worker 拦截的请求。请参阅此问题。我们建议在使用请求拦截时，通过将 setServiceWorkers 设置为 'block' 来禁用 Service Worker。 :::

用法

以下是一个简单的处理程序示例，它会中止所有图像请求：

BrowserContext context = browser.newContext();
context.route("**/*.{png,jpg,jpeg}", route -> route.abort());
Page page = context.newPage();
page.navigate("https://example.com");
browser.close();

或者使用正则表达式模式实现相同功能的代码片段：

BrowserContext context = browser.newContext();
context.route(Pattern.compile("(\\.png$)|(\\.jpg$)"), route -> route.abort());
Page page = context.newPage();
page.navigate("https://example.com");
browser.close();

可以检查请求以决定路由操作。例如，模拟所有包含某些 POST 数据的请求，并保持所有其他请求不变：

context.route("/api/**", route -> {
  if (route.request().postData().contains("my-string"))
    route.fulfill(new Route.FulfillOptions().setBody("mocked-data"));
  else
    route.resume();
});

当请求同时匹配页面路由（通过 Page.route() 设置）和浏览器上下文路由的处理程序时，页面路由优先。

要移除路由及其处理程序，可以使用 BrowserContext.unroute()。

备注

启用路由会禁用 HTTP 缓存。

参数

url String | Pattern | Predicate<String>#

一个全局模式、正则表达式模式或谓词，接收一个 [URL] 以在路由期间进行匹配。如果在上下文选项中设置了 setBaseURL，并且提供的 URL 是一个不以 * 开头的字符串，则使用 new URL() 构造函数进行解析。
handler Consumer<Route>#

用于路由请求的处理函数。
options BrowserContext.RouteOptions（可选）
- setTimes int（可选）新增于：v1.15#
  
  路由应使用的频率。默认情况下，每次都会使用。

返回值

void #

routeFromHAR

新增于：v1.23

browserContext.routeFromHAR

如果指定了此选项，在此上下文环境中发出的网络请求将从 HAR 文件中提供服务。详细了解从 HAR 重放。

Playwright 不会从 HAR 文件中提供由 Service Worker 拦截的请求。请参阅此问题。我们建议在使用请求拦截时，通过将 setServiceWorkers 设置为 'block' 来禁用 Service Worker。

用法

BrowserContext.routeFromHAR(har);
BrowserContext.routeFromHAR(har, options);

参数

har Path #

包含预先录制的网络数据的 HAR 文件的路径。如果 path 是相对路径，则相对于当前工作目录进行解析。
options BrowserContext.RouteFromHAROptions（可选）
- setNotFound enum HarNotFound { ABORT, FALLBACK }（可选）#
  - 如果设置为 abort，在 HAR 文件中找不到的任何请求都将被中止。
  - 如果设置为 fallback，则会进入处理程序链中的下一个路由处理程序。
  默认值为 abort。
- setUpdate boolean（可选）#
  
  如果指定，则使用实际网络信息更新给定的 HAR，而不是从文件提供服务。调用 BrowserContext.close() 时，文件将写入磁盘。
- setUpdateContent enum RouteFromHarUpdateContentPolicy { EMBED, ATTACH }（可选）新增于：v1.32#
  
  用于控制资源内容管理的可选设置。如果指定 attach，资源将作为单独的文件或 ZIP 存档中的条目持久化。如果指定 embed，内容将内联存储在 HAR 文件中。
- setUpdateMode enum HarMode { FULL, MINIMAL }（可选）新增于：v1.32#
  
  设置为 minimal 时，仅记录从 HAR 进行路由所需的信息。这将省略大小、时间、页面、cookie、安全性和其他类型的 HAR 信息，这些信息在从 HAR 重放时不会使用。默认值为 minimal。
- setUrl String | Pattern（可选）#
  
  用于匹配请求 URL 的通配符模式、正则表达式或谓词。只有 URL 与模式匹配的请求才会从 HAR 文件提供服务。如果未指定，则所有请求都将从 HAR 文件提供服务。

返回值

void #

routeWebSocket

新增于：v1.48

browserContext.routeWebSocket

此方法允许修改浏览器上下文中任何页面发起的 WebSocket 连接。

请注意，只有在此方法调用后创建的 WebSocket 才会被路由。建议在创建任何页面之前调用此方法。

用法

以下是一个简单的处理程序示例，它会阻止某些 WebSocket 消息。有关更多详细信息和示例，请参阅 WebSocketRoute。

context.routeWebSocket("/ws", ws -> {
  ws.routeSend(message -> {
    if ("to-be-blocked".equals(message))
      return;
    ws.send(message);
  });
  ws.connect();
});

参数

url String | Pattern | Predicate<String>#

只有 URL 与该模式匹配的 WebSocket 才会被路由。字符串模式可以相对于 setBaseURL 上下文选项。
handler Consumer<WebSocketRoute>#

用于路由 WebSocket 的处理函数。

返回值

void #

在 v1.9 之前添加

browserContext.setDefaultNavigationTimeout

此设置将更改以下方法及相关快捷方式的默认最大导航时间：

备注

Page.setDefaultNavigationTimeout() 和 Page.setDefaultTimeout() 优先于 BrowserContext.setDefaultNavigationTimeout()。

用法

BrowserContext.setDefaultNavigationTimeout(timeout);

参数

timeout double #

最大导航时间（毫秒）

setDefaultTimeout

在 v1.9 之前添加

browserContext.setDefaultTimeout

此设置将更改所有接受 timeout 选项的方法的默认最长时间。

备注

Page.setDefaultNavigationTimeout()、Page.setDefaultTimeout() 和 BrowserContext.setDefaultNavigationTimeout() 优先于 BrowserContext.setDefaultTimeout()。

用法

BrowserContext.setDefaultTimeout(timeout);

参数

timeout double #

最长时间（毫秒）。传入 0 以禁用超时。

setExtraHTTPHeaders

在 v1.9 之前添加

browserContext.setExtraHTTPHeaders

额外的 HTTP 标头将与上下文中任何页面发起的每个请求一起发送。这些标头会与通过 Page.setExtraHTTPHeaders() 设置的特定于页面的额外 HTTP 标头合并。如果页面覆盖了特定标头，则将使用特定于页面的标头值，而不是浏览器上下文的标头值。

备注

BrowserContext.setExtraHTTPHeaders() 不保证传出请求中标头的顺序。

使用方法

BrowserContext.setExtraHTTPHeaders(headers);

参数

headers Map<String, String># 一个对象，包含将随每个请求发送的额外 HTTP 标头。所有标头值必须是字符串。

返回值

void #

setGeolocation

在 v1.9 之前添加

browserContext.setGeolocation

设置上下文的地理位置。传入 null 或 undefined 可模拟位置不可用。

使用方法

browserContext.setGeolocation(new Geolocation(59.95, 30.31667));

备注

考虑使用 BrowserContext.grantPermissions() 来授予浏览器上下文页面读取其地理位置的权限。

参数

geolocation null | Geolocation#
- setLatitude double 纬度，范围在 -90 到 90 之间。
- setLongitude double 经度，范围在 -180 到 180 之间。
- setAccuracy double (可选) 非负精度值。默认为 0。

返回值

void #

setOffline

在 v1.9 之前添加

browserContext.setOffline

用法

BrowserContext.setOffline(offline);

参数

offline boolean #

是否为浏览器上下文模拟网络离线状态。

返回值

void #

storageState

在 v1.9 之前添加

browserContext.storageState

返回此浏览器上下文的存储状态，包含当前的 cookie、本地存储快照和 IndexedDB 快照。

用法

BrowserContext.storageState();
BrowserContext.storageState(options);

参数

options BrowserContext.StorageStateOptions（可选）
- setIndexedDB boolean（可选）新增于：v1.51#
  
  设置为 true 以在存储状态快照中包含 IndexedDB。如果您的应用程序使用 IndexedDB 存储身份验证令牌（如 Firebase 身份验证），请启用此选项。
- setPath Path（可选）#
  
  保存存储状态的文件路径。如果 setPath 是相对路径，则相对于当前工作目录进行解析。如果未提供路径，仍会返回存储状态，但不会保存到磁盘。

返回值

String #

unroute

在 v1.9 之前新增

browserContext.unroute

移除使用 BrowserContext.route() 创建的路由。当未指定 handler 时，移除 url 的所有路由。

用法

BrowserContext.unroute(url);
BrowserContext.unroute(url, handler);

参数

url String | Pattern | Predicate<String>#

一个通配符模式、正则表达式模式或接收 [URL] 的断言，用于使用 BrowserContext.route() 注册路由。
handler Consumer<Route> （可选）#

可选的处理函数，用于使用 BrowserContext.route() 注册路由。

返回值

void #

unrouteAll

新增于：v1.41

browserContext.unrouteAll

移除使用 BrowserContext.route() 和 BrowserContext.routeFromHAR() 创建的所有路由。

用法

BrowserContext.unrouteAll();

返回值

void #

waitForCondition

新增于：v1.32

browserContext.waitForCondition

该方法将阻塞，直到条件返回 true。在该方法等待条件时，所有 Playwright 事件都将被派发。

使用方法

使用该方法等待依赖于页面事件的条件：

List<String> failedUrls = new ArrayList<>();
context.onResponse(response -> {
  if (!response.ok()) {
    failedUrls.add(response.url());
  }
});
page1.getByText("Create user").click();
page2.getByText("Submit button").click();
context.waitForCondition(() -> failedUrls.size() > 3);

参数

condition [BooleanSupplier]# 等待的条件。
options BrowserContext.WaitForConditionOptions（可选）
- setTimeout double（可选）# 等待的最长时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改默认值。

返回值

void #

waitForConsoleMessage

添加于：v1.34

browserContext.waitForConsoleMessage

执行操作并等待上下文中的页面记录 ConsoleMessage。如果提供了断言函数，它会将 ConsoleMessage 值传入 predicate 函数，并等待 predicate(message) 返回真值。如果在触发 BrowserContext.onConsoleMessage(handler) 事件之前页面关闭，将会抛出错误。

用法

BrowserContext.waitForConsoleMessage(callback);
BrowserContext.waitForConsoleMessage(callback, options);

参数

options BrowserContext.WaitForConsoleMessageOptions（可选）
- setPredicate Predicate<ConsoleMessage>（可选）#
  
  接收 ConsoleMessage 对象，当等待条件满足时，解析为真值。
- setTimeout double（可选）#
  
  最大等待时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 更改。
callback Runnable #

执行触发事件操作的回调函数。

返回值

ConsoleMessage #

waitForPage

新增于：v1.9

browserContext.waitForPage

执行操作并等待在上下文中创建新的 Page。如果提供了断言函数 predicate，它会将 Page 值传入 predicate 函数，并等待 predicate(event) 返回真值。如果在新 Page 创建之前上下文关闭，则会抛出错误。

用法

BrowserContext.waitForPage(callback);
BrowserContext.waitForPage(callback, options);

参数

options BrowserContext.WaitForPageOptions（可选）
- setPredicate Predicate<Page>（可选）#
  
  接收 Page 对象，当等待条件满足时解析为真值。
- setTimeout double（可选）#
  
  最大等待时间（毫秒）。默认为 30000（30 秒）。传入 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 更改。
callback Runnable #

执行触发事件操作的回调函数。

返回值

Page #

属性

clock()

新增于：v1.45

browserContext.clock()

Playwright 能够模拟时钟和时间流逝。

用法

BrowserContext.clock()

返回值

Clock

request()

新增于：v1.16

browserContext.request()

与此上下文关联的 API 测试辅助工具。使用此 API 发出的请求将使用上下文 cookie。

用法

BrowserContext.request()

返回值

APIRequestContext

tracing()

新增于：v1.12

browserContext.tracing()

用法

BrowserContext.tracing()

返回值

Tracing

事件

onBackgroundPage(handler)

新增于：v1.11

browserContext.onBackgroundPage(handler)

备注

仅适用于 Chromium 浏览器的持久上下文。

当在此上下文中创建新的后台页面时触发。

context.onBackgroundPage(backgroundPage -> {
  System.out.println(backgroundPage.url());
});

用法

BrowserContext.onBackgroundPage(handler)

事件数据

Page

onClose(handler)

在 v1.9 之前新增

browserContext.onClose(handler)

当浏览器上下文关闭时触发。这可能是由于以下原因之一：

浏览器上下文被关闭。
浏览器应用程序关闭或崩溃。
调用了 Browser.close() 方法。

用法

BrowserContext.onClose(handler)

事件数据

BrowserContext

onConsoleMessage(handler)

新增于：v1.34

browserContext.onConsoleMessage(handler)

当页面内的 JavaScript 调用 console API 方法（例如 console.log 或 console.dir）之一时触发。

传递给 console.log 的参数和页面可在 ConsoleMessage 事件处理程序参数中获取。

用法

context.onConsoleMessage(msg -> {
  for (int i = 0; i < msg.args().size(); ++i)
    System.out.println(i + ": " + msg.args().get(i).jsonValue());
});
page.evaluate("() => console.log('hello', 5, { foo: 'bar' })");

事件数据

ConsoleMessage

onDialog(handler)

新增于：v1.34

browserContext.onDialog(handler)

当 JavaScript 对话框（如 alert、prompt、confirm 或 beforeunload）出现时触发。监听器必须调用 Dialog.accept() 或 Dialog.dismiss() 来处理对话框，否则页面将冻结等待对话框处理，诸如点击等操作将永远不会完成。

用法

context.onDialog(dialog -> {
  dialog.accept();
});

备注

当不存在 Page.onDialog(handler) 或 BrowserContext.onDialog(handler) 监听器时，所有对话框将自动被取消。

事件数据

Dialog

onPage(handler)

在 v1.9 之前添加

browserContext.onPage(handler)

当在 BrowserContext 中创建新的 Page 时，会触发此事件。页面可能仍在加载中。此事件也会针对弹出页面触发。另请参阅 Page.onPopup(handler)，以接收与特定页面相关的弹出窗口事件。

页面最早可用的时刻是它导航到初始 URL 时。例如，当使用 window.open('http://example.com') 打开弹出窗口时，当对 “http://example.com” 的网络请求完成并且其响应已开始在弹出窗口中加载时，将触发此事件。如果您想路由/监听此网络请求，请分别使用 BrowserContext.route() 和 BrowserContext.onRequest(handler)，而不是 Page 上的类似方法。

Page newPage = context.waitForPage(() -> {
  page.getByText("open new page").click();
});
System.out.println(newPage.evaluate("location.href"));

备注

使用 Page.waitForLoadState() 等待页面进入特定状态（大多数情况下您可能不需要它）。

用法

BrowserContext.onPage(handler)

事件数据

Page

onRequest(handler)

新增于：v1.12

browserContext.onRequest(handler)

当通过此上下文创建的任何页面发出请求时触发。request 对象是只读的。若只想监听特定页面发出的请求，请使用 Page.onRequest(handler)。

若要拦截并修改请求，请参阅 BrowserContext.route() 或 Page.route()。

用法

BrowserContext.onRequest(handler)

事件数据

Request

onRequestFailed(handler)

新增于：v1.12

browserContext.onRequestFailed(handler)

当请求失败时触发，例如因超时而失败。若只想监听特定页面的失败请求，请使用 Page.onRequestFailed(handler)。

备注

从 HTTP 的角度来看，HTTP 错误响应（例如 404 或 503）仍然是成功的响应，因此请求将通过 BrowserContext.onRequestFinished(handler) 事件完成，而不是通过 BrowserContext.onRequestFailed(handler) 事件。

用法

BrowserContext.onRequestFailed(handler)

事件数据

Request

onRequestFinished(handler)

新增于：v1.12

browserContext.onRequestFinished(handler)

当请求在下载响应体后成功完成时触发。对于成功的响应，事件顺序为 request、response 和 requestfinished。要监听特定页面的成功请求，请使用 Page.onRequestFinished(handler)。

用法

BrowserContext.onRequestFinished(handler)

事件数据

Request

onResponse(handler)

新增于：v1.12

browserContext.onResponse(handler)

当请求接收到 response 状态和标头时触发。对于成功的响应，事件顺序为 request、response 和 requestfinished。要监听特定页面的响应事件，请使用 Page.onResponse(handler)。

用法

BrowserContext.onResponse(handler)

事件数据

Response

onWebError(handler)

新增于：v1.38

browserContext.onWebError(handler)

当此上下文中任何页面出现未处理的异常时触发。要监听特定页面的错误，请改用 Page.onPageError(handler)。

用法

BrowserContext.onWebError(handler)

事件数据

WebError

方法​

addCookies​

addInitScript​

用法​

参数​

返回值​

backgroundPages​

用法​

返回值​

browser​

用法​

clearCookies​

clearPermissions​

close​

cookies​

exposeBinding​

exposeFunction​

用法​

参数​

grantPermissions​

newCDPSession​

newPage​

pages​

route​

用法​

routeFromHAR​

routeWebSocket​

setDefaultNavigationTimeout​

setDefaultTimeout​

setExtraHTTPHeaders​

使用方法​

参数​

返回值​

setGeolocation​

使用方法​

参数​

返回值​

setOffline​

storageState​

参数​

返回值​

unroute​

用法​

unrouteAll​

waitForCondition​

使用方法​

参数​

返回值​

waitForConsoleMessage​

waitForPage​

属性​

clock()​

request()​

tracing()​

事件​

onBackgroundPage(handler)​

onClose(handler)​

onConsoleMessage(handler)​

onDialog(handler)​

onPage(handler)​

onRequest(handler)​

onRequestFailed(handler)​

onRequestFinished(handler)​

onResponse(handler)​

onWebError(handler)​

方法

addCookies

addInitScript

用法

参数

返回值

backgroundPages

用法

返回值

browser

用法

clearCookies

clearPermissions

close

cookies

exposeBinding

exposeFunction

用法

参数

grantPermissions

newCDPSession

newPage

pages

route

用法

routeFromHAR

routeWebSocket

setDefaultNavigationTimeout

setDefaultTimeout

setExtraHTTPHeaders

使用方法

参数

返回值

setGeolocation

使用方法

参数

返回值

setOffline

storageState

参数

返回值

unroute

用法

unrouteAll

waitForCondition

使用方法

参数

返回值

waitForConsoleMessage

waitForPage

属性

clock()

request()

tracing()

事件

onBackgroundPage(handler)

onClose(handler)

onConsoleMessage(handler)

onDialog(handler)

onPage(handler)

onRequest(handler)

onRequestFailed(handler)

onRequestFinished(handler)

onResponse(handler)

onWebError(handler)