Playwright中BrowserContext深度解析-BrowserContext方法速查手册

BrowserContext 接口提供了操作多个独立浏览器会话的方式，以下是对其属性和方法的详细解析：

属性

由于 BrowserContext 是一个接口，并没有直接定义属性，但是在其内部类中定义了一些属性，以下为您解析这些内部类属性：

1. ClearCookiesOptions类
   • domain
     • 作用：仅移除具有给定域名的 cookies。
     • 默认值：无
     • 可能的值：字符串类型的域名或 Pattern 类型的正则表达式
     • 使用场景：当需要清除特定域名下的 cookies 时使用，例如清除 my - origin.com 域名下的所有 cookies。
   • name
     • 作用：仅移除具有给定名称的 cookies。
     • 默认值：无
     • 可能的值：字符串类型的 cookie 名称或 Pattern 类型的正则表达式
     • 使用场景：当需要清除特定名称的 cookies 时使用，例如清除名为 session - id 的 cookie。
   • path
     • 作用：仅移除具有给定路径的 cookies。
     • 默认值：无
     • 可能的值：字符串类型的路径或 Pattern 类型的正则表达式
     • 使用场景：当需要清除特定路径下的 cookies 时使用，例如清除 /api/v1 路径下的所有 cookies。
2. CloseOptions类
   • reason
     • 作用：该原因将报告给因上下文关闭而中断的操作。
     • 默认值：无
     • 可能的值：字符串类型，任何描述关闭原因的字符串
     • 使用场景：在关闭浏览器上下文时，提供一个原因说明，方便后续调试或记录操作。
3. ExposeBindingOptions类
   • handle
     • 作用：已弃用，该选项将来会被移除。（从文档看未明确具体作用）
     • 默认值：无
     • 可能的值：布尔值
     • 使用场景：无（因其已弃用）
4. GrantPermissionsOptions类
   • origin
     • 作用：要授予权限的源，例如 "https://example.com"。
     • 默认值：无
     • 可能的值：字符串类型的源地址
     • 使用场景：当需要为特定源授予权限时使用，比如为 https://example.com 授予特定权限。
5. RouteOptions类
   • times
     • 作用：指定路由应使用的次数。默认情况下，每次都会使用。
     • 默认值：无（默认每次都使用）
     • 可能的值：正整数
     • 使用场景：当希望某个路由规则只在特定次数内生效时使用，例如只希望拦截特定次数的请求。
6. RouteFromHAROptions类
   • notFound
     • 作用：控制当请求在 HAR 文件中未找到时的行为。如果设置为 abort，任何未在 HAR 文件中找到的请求将被中止；如果设置为 fallback，则会落入处理链中的下一个路由处理程序。
     • 默认值：abort
     • 可能的值：HarNotFound 枚举类型中的 abort 或 fallback
     • 使用场景：在从 HAR 文件重放网络请求时，决定如何处理未在 HAR 文件中找到的请求。
   • update
     • 作用：如果指定，使用实际网络信息更新给定的 HAR，而不是从文件提供服务。当调用 BrowserContext.close() 时，文件将写入磁盘。
     • 默认值：无
     • 可能的值：布尔值
     • 使用场景：希望在运行过程中更新 HAR 文件以记录实际网络信息时使用。
   • updateContent
     • 作用：可选设置，用于控制资源内容管理。如果指定 attach，资源将作为单独的文件或 ZIP 存档中的条目持久化；如果指定 embed，内容将内联存储在 HAR 文件中。
     • 默认值：无
     • 可能的值：RouteFromHarUpdateContentPolicy 枚举类型中的 attach 或 embed
     • 使用场景：根据需求选择资源内容在 HAR 文件中的存储方式。
   • updateMode
     • 作用：当设置为 minimal 时，仅记录从 HAR 进行路由所需的信息。这将省略在从 HAR 重放时不使用的大小、时间、页面、cookie、安全性和其他类型的 HAR 信息。默认值为 minimal。
     • 默认值：minimal
     • 可能的值：HarMode 枚举类型中的 minimal 等（文档未提及其他可能值）
     • 使用场景：在从 HAR 文件重放请求时，根据需求控制记录的信息详细程度。
   • url
     • 作用：一个 glob 模式、正则表达式或谓词，用于匹配请求 URL。只有 URL 与模式匹配的请求才会从 HAR 文件提供服务。如果未指定，所有请求都将从 HAR 文件提供服务。
     • 默认值：无
     • 可能的值：字符串类型的 glob 模式、Pattern 类型的正则表达式或 Predicate<String> 类型的谓词
     • 使用场景：在从 HAR 文件提供网络请求服务时，筛选出需要从 HAR 文件获取数据的请求。
7. StorageStateOptions类
   • indexedDB
     • 作用：设置为 true 以在存储状态快照中包含 IndexedDB。如果应用程序使用 IndexedDB 存储身份验证令牌（如 Firebase 身份验证），请启用此选项。
     • 默认值：无
     • 可能的值：布尔值
     • 使用场景：当需要在存储状态快照中包含 IndexedDB 数据时使用，例如应用使用 IndexedDB 存储重要信息。
   • path
     • 作用：保存存储状态的文件路径。如果 path 是相对路径，则相对于当前工作目录进行解析。如果未提供路径，仍将返回存储状态，但不会保存到磁盘。
     • 默认值：无
     • 可能的值：Path 类型的文件路径
     • 使用场景：指定存储状态保存的位置，方便后续恢复使用。
8. WaitForConditionOptions类
   • timeout
     • 作用：最大等待时间（以毫秒为单位）。默认值为 30000（30 秒）。传递 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法更改。
     • 默认值：30000
     • 可能的值：大于等于 0 的双精度浮点数
     • 使用场景：在等待某个条件满足时，设置等待的最长时间，避免无限期等待。
9. WaitForConsoleMessageOptions类
   • predicate
     • 作用：接收 ConsoleMessage 对象，并在等待条件满足时解析为真值。
     • 默认值：无
     • 可能的值：Predicate<ConsoleMessage> 类型的谓词
     • 使用场景：当需要根据特定的 ConsoleMessage 条件进行等待时使用，例如等待特定内容的 console.log 输出。
   • timeout
     • 作用：最大等待时间（以毫秒为单位）。默认值为 30000（30 秒）。传递 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 方法更改。
     • 默认值：30000
     • 可能的值：大于等于 0 的双精度浮点数
     • 使用场景：在等待 ConsoleMessage 时，设置等待的最长时间，避免无限期等待。
10. WaitForPageOptions类
    • predicate
      • 作用：接收 Page 对象，并在等待条件满足时解析为真值。
      • 默认值：无
      • 可能的值：Predicate<Page> 类型的谓词
      • 使用场景：当需要根据特定的 Page 条件进行等待时使用，例如等待新页面满足特定条件。
    • timeout
      • 作用：最大等待时间（以毫秒为单位）。默认值为 30000（30 秒）。传递 0 可禁用超时。默认值可以通过 BrowserContext.setDefaultTimeout() 方法更改。
      • 默认值：30000
      • 可能的值：大于等于 0 的双精度浮点数
      • 使用场景：在等待新页面创建并满足条件时，设置等待的最长时间，避免无限期等待。

方法

1. onBackgroundPage
   • 入参详细解释：
     • handler：类型为 Consumer<Page>，是一个接受 Page 对象的消费者函数。用于处理新创建的后台页面。无默认值，值的范围是符合 Consumer<Page> 接口定义的函数。
   • 出参详细解释：无返回值。
   • 方法签名详细解释：void onBackgroundPage(Consumer<Page> handler)，该方法用于为浏览器上下文添加一个监听器，当有新的后台页面创建时，会调用传入的 handler 函数。
   • 核心作用详细解释：监听浏览器上下文中新后台页面的创建，并执行相应的处理逻辑。
   • 使用场景详细解释：当需要对新创建的后台页面进行操作时，例如获取其 URL 并进行记录或进一步操作，可以使用此方法。仅适用于 Chromium 浏览器的持久化上下文。
2. offBackgroundPage
   • 入参详细解释：
     • handler：类型为 Consumer<Page>，是之前通过 onBackgroundPage(handler) 添加的处理函数。无默认值，值的范围是之前添加到 onBackgroundPage 的 Consumer<Page> 函数。
   • 出参详细解释：无返回值。
   • 方法签名详细解释：void offBackgroundPage(Consumer<Page> handler)，该方法用于移除之前通过 onBackgroundPage 添加的监听器。
   • 核心作用详细解释：停止对新后台页面创建事件的监听。
   • 使用场景详细解释：当不再需要监听新后台页面的创建时，使用此方法移除监听器，避免资源浪费。
3. onClose
   • 入参详细解释：
     • handler：类型为 Consumer<BrowserContext>，是一个接受 BrowserContext 对象的消费者函数。用于处理浏览器上下文关闭的事件。无默认值，值的范围是符合 Consumer<BrowserContext> 接口定义的函数。
   • 出参详细解释：无返回值。
   • 方法签名详细解释：void onClose(Consumer<BrowserContext> handler)，该方法用于为浏览器上下文添加一个监听器，当浏览器上下文关闭时，会调用传入的 handler 函数。
   • 核心作用详细解释：监听浏览器上下文关闭事件，并执行相应的处理逻辑。
   • 使用场景详细解释：当需要在浏览器上下文关闭时执行一些清理操作或记录日志等，可以使用此方法。浏览器上下文关闭可能因为多种原因，如手动关闭、浏览器应用关闭或崩溃等。
4. offClose
   • 入参详细解释：
     • handler：类型为 Consumer<BrowserContext>，是之前通过 onClose(handler) 添加的处理函数。无默认值，值的范围是之前添加到 onClose 的 Consumer<BrowserContext> 函数。
   • 出参详细解释：无返回值。
   • 方法签名详细解释：void offClose(Consumer<BrowserContext> handler)，该方法用于移除之前通过 onClose 添加的监听器。
   • 核心作用详细解释：停止对浏览器上下文关闭事件的监听。
   • 使用场景详细解释：当不再需要监听浏览器上下文关闭事件时，使用此方法移除监听器，避免资源浪费。
5. onConsoleMessage
   • 入参详细解释：
     • handler：类型为 Consumer<ConsoleMessage>，是一个接受 ConsoleMessage 对象的消费者函数。用于处理页面中 JavaScript 调用控制台 API 方法（如 console.log 或 console.dir）产生的消息。无默认值，值的范围是符合 Consumer<ConsoleMessage> 接口定义的函数。
   • 出参详细解释：无返回值。
   • 方法签名详细解释：void onConsoleMessage(Consumer<ConsoleMessage> handler)，该方法用于为浏览器上下文添加一个监听器，当页面中有控制台消息时，会调用传入的 handler 函数。
   • 核心作用详细解释：监听页面中 JavaScript 控制台消息，并执行相应的处理逻辑。
   • 使用场景详细解释：当需要捕获页面中的控制台输出，例如记录日志、检查特定输出等，可以使用此方法。可以通过 ConsoleMessage 对象获取控制台消息的参数等信息。
6. offConsoleMessage
   • 入参详细解释：
     • handler：类型为 Consumer<ConsoleMessage>，是之前通过 onConsoleMessage(handler) 添加的处理函数。无默认值，值的范围是之前添加到 onConsoleMessage 的 Consumer<ConsoleMessage> 函数。
   • 出参详细解释：无返回值。
   • 方法签名详细解释：void offConsoleMessage(Consumer<ConsoleMessage> handler)，该方法用于移除之前通过 onConsoleMessage 添加的监听器。
   • 核心作用详细解释：停止对页面中 JavaScript 控制台消息的监听。
   • 使用场景详细解释：当不再需要监听控制台消息时，使用此方法移除监听器，避免资源浪费。
7. onDialog
   • 入参详细解释：
     • handler：类型为 Consumer<Dialog>，是一个接受 Dialog 对象的消费者函数。用于处理 JavaScript 对话框（如 alert、prompt、confirm 或 beforeunload）的出现。无默认值，值的范围是符合 Consumer<Dialog> 接口定义的函数。
   • 出参详细解释：无返回值。
   • 方法签名详细解释：void onDialog(Consumer<Dialog> handler)，该方法用于为浏览器上下文添加一个监听器，当有 JavaScript 对话框出现时，会调用传入的 handler 函数。
   • 核心作用详细解释：监听 JavaScript 对话框的出现，并执行相应的处理逻辑，必须在监听器中对对话框进行 accept 或 dismiss 操作，否则页面可能会冻结。
   • 使用场景详细解释：当需要自动处理页面中的对话框，例如自动点击确认或取消按钮，可以使用此方法。如果没有注册 Page.onDialog() 或 BrowserContext.onDialog() 监听器，所有对话框将自动被取消。
8. offDialog
   • 入参详细解释：
     • handler：类型为 Consumer<Dialog>，是之前通过 onDialog(handler) 添加的处理函数。无默认值，值的范围是之前添加到 onDialog 的 Consumer<Dialog> 函数。
   • 出参详细解释：无返回值。
   • 方法签名详细解释：void offDialog(Consumer<Dialog> handler)，该方法用于移除之前通过 onDialog 添加的监听器。
   • 核心作用详细解释：停止对 JavaScript 对话框出现事件的监听。
   • 使用场景详细解释：当不再需要监听对话框出现事件时，使用此方法移除监听器，避免资源浪费。
9. onPage
   • 入参详细解释：
     • handler：类型为 Consumer<Page>，是一个接受 Page 对象的消费者函数。用于处理在浏览器上下文中创建新页面的事件。无默认值，值的范围是符合 Consumer<Page> 接口定义的函数。
   • 出参详细解释：无返回值。
   • 方法签名详细解释：void onPage(Consumer<Page> handler)，该方法用于为浏览器上下文添加一个监听器，当有新页面在浏览器上下文中创建时，会调用传入的 handler 函数。
   • 核心作用详细解释：监听浏览器上下文中新页面的创建，并执行相应的处理逻辑。新页面可能是正常创建或弹出的页面。
   • 使用场景详细解释：当需要对新创建的页面进行操作，例如在新页面加载完成后立即执行某些操作，可以使用此方法。可以结合 Page.waitForLoadState() 等待页面到达特定状态。
10. offPage
    • 入参详细解释：
      • handler：类型为 Consumer<Page>，是之前通过 onPage(handler) 添加的处理函数。无默认值，值的范围是之前添加到 onPage 的 Consumer<Page> 函数。
    • 出参详细解释：无返回值。
    • 方法签名详细解释：void offPage(Consumer<Page> handler)，该方法用于移除之前通过 onPage 添加的监听器。