BrowserContext

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

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

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

// Create a new incognito browser context
BrowserContext context = browser.newContext();
// Create a new page inside context.
Page page = context.newPage();
page.navigate("https://example.com");
// Dispose context once it is no longer needed.
context.close();

方法

addCookies

v1.9 之前添加

browserContext.addCookies

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

用法

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 } (可选)
  
  可选。
- setPartitionKey String (可选)
  
  对于分区的第三方 cookie (又称 CHIPS)，分区键。可选。

void #

addInitScript

v1.9 之前添加

browserContext.addInitScript

添加一个脚本，该脚本将在以下情况之一中进行评估：

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

脚本在文档创建后但在任何脚本运行之前进行评估。这对于修改 JavaScript 环境非常有用，例如，为 Math.random 设置种子。

用法

在页面加载之前覆盖 Math.random 的示例

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

// In your playwright script, assuming the preload.js file is in same directory.
browserContext.addInitScript(Paths.get("preload.js"));

注意

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

参数

script String | Path #

要在浏览器上下文中的所有页面中评估的脚本。

[Disposable]#

browser

v1.9 之前添加

browserContext.browser

获取拥有该上下文的浏览器实例。如果该上下文在正常浏览器之外创建（例如 Android 或 Electron），则返回 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"));
// do stuff ..
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 }
- partitionKey String (可选)

exposeBinding

v1.9 之前添加

browserContext.exposeBinding

该方法在上下文中每个页面的每个 frame 的 window 对象上添加一个名为 name 的函数。当被调用时，该函数会执行 callback 并返回一个 Promise，其解析结果为 callback 的返回值。如果 callback 返回一个 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 #

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

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

[Disposable]#

exposeFunction

v1.9 之前添加

browserContext.exposeFunction

该方法在上下文中每个页面的每个 frame 的 window 对象上添加一个名为 name 的函数。当被调用时，该函数执行 callback 并返回一个 Promise，其解析结果为 callback 的返回值。

如果 callback 返回一个 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 上下文中调用的回调函数。

[Disposable]#

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'
- 'local-fonts'
- 'local-network-access'
- 'magnetometer'
- 'microphone'
- 'midi-sysex' (系统专属 midi)
- 'midi'
- 'notifications'
- 'payment-handler'
- 'storage-access'
- 'screen-wake-lock'
options BrowserContext.GrantPermissionsOptions (可选)
- setOrigin String (可选)#
  
  要授予权限的源，例如 "https://example.com"。

void #

isClosed

新增于: v1.59

browserContext.isClosed

表明浏览器上下文正在关闭或已经关闭。

用法

BrowserContext.isClosed();

boolean #

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] 的 glob 模式、正则表达式或谓词。如果上下文选项中设置了 setBaseURL，且提供的 URL 是不以 * 开头的字符串，则它将使用 new URL() 构造函数进行解析。
handler Consumer<Route>#

用于路由请求的处理函数。
options BrowserContext.RouteOptions (可选)
- setTimes int (可选)新增于: v1.15#
  
  路由应该被使用多少次。默认情况下，每次都会使用。

[Disposable]#

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'，则会退回到处理程序链中的下一个路由处理程序。
  默认为中止。
- 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 路由所需的信息。这会省略 HAR 信息中不用于从 HAR 重放的大小、时间、页面、cookie、安全性和其他类型的信息。默认为 minimal。
- setUrl String | Pattern (可选)#
  
  一个 glob 模式、正则表达式或谓词，用于匹配请求 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 匹配此模式的 WebSockets 才会被路由。字符串模式可以是相对于 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 双精度浮点数
  
  纬度，介于 -90 和 90 之间。
- setLongitude 双精度浮点数
  
  经度，介于 -180 和 180 之间。
- setAccuracy 双精度浮点数 (可选)
  
  非负精度值。默认为 0。

void #

setOffline

v1.9 之前添加

browserContext.setOffline

用法

BrowserContext.setOffline(offline);

参数

offline boolean #

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

void #

setStorageState

新增于: v1.59

browserContext.setStorageState

清除所有源的现有 Cookie、本地存储和 IndexedDB 条目，并设置新的存储状态。

用法

// Load storage state from a file and apply it to the context.
context.setStorageState(Paths.get("state.json"));

参数

storageStatePath Path #

用给定的存储状态填充上下文。此选项可用于通过 BrowserContext.storageState() 获取的登录信息来初始化上下文。这是保存存储状态的文件路径。

void #

storageState

v1.9 之前添加

browserContext.storageState

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

用法

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

参数

options BrowserContext.StorageStateOptions (可选)
- setIndexedDB boolean (可选)添加于: v1.51#
  
  设置为 true 以将 IndexedDB 包含在存储状态快照中。如果您的应用程序使用 IndexedDB 存储身份验证令牌（如 Firebase Authentication），请启用此选项。
- 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>#

用于注册 BrowserContext.route() 路由的 glob 模式、正则表达式或接收 [URL] 的谓词。
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。如果提供了谓词，它会将 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()

时钟

debugger()

新增于: v1.59

browserContext.debugger()

调试器允许暂停和恢复执行。

用法

BrowserContext.debugger()

调试器

request()

添加于：v1.16

browserContext.request()

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

用法

BrowserContext.request()

APIRequestContext

tracing()

添加于：v1.12

browserContext.tracing()

用法

BrowserContext.tracing()

Tracing

事件

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.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 错误响应（例如 404 或 503）从 HTTP 角度来看仍然是成功的响应，因此请求将以 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

已弃用

onBackgroundPage(handler)

添加于：v1.11

browserContext.onBackgroundPage(handler)

已弃用

后台页面已从 Chromium 与 Manifest V2 扩展一起移除。

不触发此事件。

用法

BrowserContext.onBackgroundPage(handler)

事件数据

Page

backgroundPages

添加于：v1.11

browserContext.backgroundPages

已弃用

后台页面已从 Chromium 与 Manifest V2 扩展一起移除。

返回一个空列表。

用法

BrowserContext.backgroundPages();

List<Page>#

方法​

addCookies​

addInitScript​

browser​

clearCookies​

clearPermissions​

close​

cookies​

exposeBinding​

exposeFunction​

grantPermissions​

isClosed​

newCDPSession​

newPage​

pages​

route​

routeFromHAR​

routeWebSocket​

setDefaultNavigationTimeout​

setDefaultTimeout​

setExtraHTTPHeaders​

setGeolocation​

setOffline​

setStorageState​

storageState​

unroute​

unrouteAll​

waitForCondition​

waitForConsoleMessage​

waitForPage​

属性​

clock()​

debugger()​

request()​

tracing()​

事件​

onClose(handler)​

onConsoleMessage(handler)​

onDialog(handler)​

onPage(handler)​

onRequest(handler)​

onRequestFailed(handler)​

onRequestFinished(handler)​

onResponse(handler)​

onWebError(handler)​

已弃用​

onBackgroundPage(handler)​

backgroundPages​

方法

addCookies

addInitScript

browser

clearCookies

clearPermissions

close

cookies

exposeBinding

exposeFunction

grantPermissions

isClosed

newCDPSession

newPage

pages

route

routeFromHAR

routeWebSocket

setDefaultNavigationTimeout

setDefaultTimeout

setExtraHTTPHeaders

setGeolocation

setOffline

setStorageState

storageState

unroute

unrouteAll

waitForCondition

waitForConsoleMessage

waitForPage

属性

clock()

debugger()

request()

tracing()

事件

onClose(handler)

onConsoleMessage(handler)

onDialog(handler)

onPage(handler)

onRequest(handler)

onRequestFailed(handler)

onRequestFinished(handler)

onResponse(handler)

onWebError(handler)

已弃用

onBackgroundPage(handler)

backgroundPages