BrowserContext

BrowserContexts 提供了一种操作多个独立浏览器会话的方法。

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

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

同步
异步

# create a new incognito browser context
context = browser.new_context()
# create a new page inside context.
page = context.new_page()
page.goto("https://example.com")
# dispose context once it is no longer needed.
context.close()

# create a new incognito browser context
context = await browser.new_context()
# create a new page inside context.
page = await context.new_page()
await page.goto("https://example.com")
# dispose context once it is no longer needed.
await context.close()

方法

add_cookies

在 v1.9 之前添加

browserContext.add_cookies

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

用法

同步
异步

browser_context.add_cookies([cookie_object1, cookie_object2])

await browser_context.add_cookies([cookie_object1, cookie_object2])

参数

cookies List[Dict]#
- name str
- value str
- url str (可选)
  
  url 或 domain / path 是必需的。可选。
- domain str (可选)
  
  为了使 Cookie 也适用于所有子域名，请在域名domain前加上一个点，例如：".example.com"。 url 或 domain / path 是必需的。可选。
- path str (可选)
  
  url 或 domain / path 是必需的可选。
- expires float (可选)
  
  Unix 时间戳，单位为秒。可选。
- httpOnly bool (可选)
  
  可选。
- secure bool (可选)
  
  可选。
- sameSite "Strict" | "Lax" | "None" (可选)
  
  可选。

返回值

NoneType #

add_init_script

在 v1.9 之前添加

browserContext.add_init_script

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

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

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

用法

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

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

同步
异步

# in your playwright script, assuming the preload.js file is in same directory.
browser_context.add_init_script(path="preload.js")

# in your playwright script, assuming the preload.js file is in same directory.
await browser_context.add_init_script(path="preload.js")

注意

通过 browser_context.add_init_script() 和 page.add_init_script() 安装的多个脚本的执行顺序未定义。

参数

path Union[str, pathlib.Path] (可选)#

JavaScript 文件的路径。如果 path 是相对路径，则它相对于当前工作目录解析。可选。
script str (可选)#

要在浏览器上下文中的所有页面中执行的脚本。可选。

返回值

NoneType #

clear_cookies

在 v1.9 之前添加

browserContext.clear_cookies

从上下文中删除 Cookie。接受可选过滤器。

用法

同步
异步

context.clear_cookies()
context.clear_cookies(name="session-id")
context.clear_cookies(domain="my-origin.com")
context.clear_cookies(path="/api/v1")
context.clear_cookies(name="session-id", domain="my-origin.com")

await context.clear_cookies()
await context.clear_cookies(name="session-id")
await context.clear_cookies(domain="my-origin.com")
await context.clear_cookies(path="/api/v1")
await context.clear_cookies(name="session-id", domain="my-origin.com")

参数

domain str | Pattern (可选)添加于: v1.43#

仅删除具有给定域名的 Cookie。
name str | Pattern (可选)添加于: v1.43#

仅删除具有给定名称的 Cookie。
path str | Pattern (可选)添加于: v1.43#

仅删除具有给定路径的 Cookie。

返回值

NoneType #

clear_permissions

在 v1.9 之前添加

browserContext.clear_permissions

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

用法

同步
异步

context = browser.new_context()
context.grant_permissions(["clipboard-read"])
# do stuff ..
context.clear_permissions()

context = await browser.new_context()
await context.grant_permissions(["clipboard-read"])
# do stuff ..
context.clear_permissions()

返回值

NoneType #

close

在 v1.9 之前添加

browserContext.close

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

注意

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

用法

browser_context.close()
browser_context.close(**kwargs)

参数

reason str (可选)添加于: v1.40#

要报告给上下文关闭中断的操作的原因。

返回值

NoneType #

cookies

在 v1.9 之前添加

browserContext.cookies

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

用法

browser_context.cookies()
browser_context.cookies(**kwargs)

参数

urls str | List[str] (可选)#

可选的 URL 列表。

返回值

List[Dict]#
- name str
- value str
- domain str
- path str
- expires float
  
  Unix 时间戳，单位为秒。
- httpOnly bool
- secure bool
- sameSite "Strict" | "Lax" | "None"

expect_console_message

添加于: v1.34

browserContext.expect_console_message

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

用法

browser_context.expect_console_message()
browser_context.expect_console_message(**kwargs)

参数

predicate Callable[ConsoleMessage]:bool (可选)#

接收 ConsoleMessage 对象，并在等待应解决时解析为真值。
timeout float (可选)#

等待的最大时间（以毫秒为单位）。默认为 30000 (30 秒)。传递 0 以禁用超时。默认值可以使用 browser_context.set_default_timeout() 更改。

返回值

EventContextManager[ConsoleMessage]#

expect_event

在 v1.9 之前添加

browserContext.expect_event

等待事件触发并将其值传递到 predicate 函数中。当 predicate 返回真值时返回。如果上下文在事件触发之前关闭，则会抛出错误。返回事件数据值。

用法

同步
异步

with context.expect_event("page") as event_info:
    page.get_by_role("button").click()
page = event_info.value

async with context.expect_event("page") as event_info:
    await page.get_by_role("button").click()
page = await event_info.value

参数

event str #

事件名称，与将传递到 browserContext.on(event) 中的名称相同。
predicate Callable (可选)#

接收事件数据，并在等待应解决时解析为真值。
timeout float (可选)#

等待的最大时间（以毫秒为单位）。默认为 30000 (30 秒)。传递 0 以禁用超时。默认值可以使用 browser_context.set_default_timeout() 更改。

返回值

EventContextManager #

expect_page

添加于: v1.9

browserContext.expect_page

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

用法

browser_context.expect_page()
browser_context.expect_page(**kwargs)

参数

predicate Callable[Page]:bool (可选)#

接收 Page 对象，并在等待应解决时解析为真值。
timeout float (可选)#

等待的最大时间（以毫秒为单位）。默认为 30000 (30 秒)。传递 0 以禁用超时。默认值可以使用 browser_context.set_default_timeout() 更改。

返回值

EventContextManager[Page]#

expose_binding

在 v1.9 之前添加

browserContext.expose_binding

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

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

有关仅页面版本的更多信息，请参阅 page.expose_binding()。

用法

将页面 URL 暴露给上下文中所有页面的所有框架的示例

同步
异步

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: Playwright):
    webkit = playwright.webkit
    browser = webkit.launch(headless=False)
    context = browser.new_context()
    context.expose_binding("pageURL", lambda source: source["page"].url)
    page = context.new_page()
    page.set_content("""
    <script>
      async function onClick() {
        document.querySelector('div').textContent = await window.pageURL();
      }
    </script>
    <button onclick="onClick()">Click me</button>
    <div></div>
    """)
    page.get_by_role("button").click()

with sync_playwright() as playwright:
    run(playwright)

import asyncio
from playwright.async_api import async_playwright, Playwright

async def run(playwright: Playwright):
    webkit = playwright.webkit
    browser = await webkit.launch(headless=False)
    context = await browser.new_context()
    await context.expose_binding("pageURL", lambda source: source["page"].url)
    page = await context.new_page()
    await page.set_content("""
    <script>
      async function onClick() {
        document.querySelector('div').textContent = await window.pageURL();
      }
    </script>
    <button onclick="onClick()">Click me</button>
    <div></div>
    """)
    await page.get_by_role("button").click()

async def main():
    async with async_playwright() as playwright:
        await run(playwright)
asyncio.run(main())

参数

name str #

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

将在 Playwright 上下文中调用的回调函数。
handle bool (可选)#

已弃用
此选项将在未来版本中移除。

是否将参数作为句柄传递，而不是按值传递。当传递句柄时，仅支持一个参数。当按值传递时，支持多个参数。

返回值

NoneType #

expose_function

在 v1.9 之前添加

browserContext.expose_function

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

如果 callback 返回一个 Promise，则将等待它完成。

有关仅页面版本的更多信息，请参阅 page.expose_function()。

用法

将 sha256 函数添加到上下文中所有页面的示例

同步
异步

import hashlib
from playwright.sync_api import sync_playwright

def sha256(text: str) -> str:
    m = hashlib.sha256()
    m.update(bytes(text, "utf8"))
    return m.hexdigest()


def run(playwright: Playwright):
    webkit = playwright.webkit
    browser = webkit.launch(headless=False)
    context = browser.new_context()
    context.expose_function("sha256", sha256)
    page = context.new_page()
    page.set_content("""
        <script>
          async function onClick() {
            document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
          }
        </script>
        <button onclick="onClick()">Click me</button>
        <div></div>
    """)
    page.get_by_role("button").click()

with sync_playwright() as playwright:
    run(playwright)

import asyncio
import hashlib
from playwright.async_api import async_playwright, Playwright

def sha256(text: str) -> str:
    m = hashlib.sha256()
    m.update(bytes(text, "utf8"))
    return m.hexdigest()


async def run(playwright: Playwright):
    webkit = playwright.webkit
    browser = await webkit.launch(headless=False)
    context = await browser.new_context()
    await context.expose_function("sha256", sha256)
    page = await context.new_page()
    await page.set_content("""
        <script>
          async function onClick() {
            document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');
          }
        </script>
        <button onclick="onClick()">Click me</button>
        <div></div>
    """)
    await page.get_by_role("button").click()

async def main():
    async with async_playwright() as playwright:
        await run(playwright)
asyncio.run(main())

参数

name str #

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

将在 Playwright 上下文中调用的回调函数。

返回值

NoneType #

grant_permissions

在 v1.9 之前添加

browserContext.grant_permissions

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

用法

browser_context.grant_permissions(permissions)
browser_context.grant_permissions(permissions, **kwargs)

参数

permissions List[str]#

要授予的权限列表。

危险
支持的权限在浏览器之间，甚至在同一浏览器的不同版本之间也存在差异。任何权限都可能在更新后停止工作。

以下是一些可能受某些浏览器支持的权限
- 'accelerometer'
- 'ambient-light-sensor'
- 'background-sync'
- 'camera'
- 'clipboard-read'
- 'clipboard-write'
- 'geolocation'
- 'gyroscope'
- 'magnetometer'
- 'microphone'
- 'midi-sysex' (系统独占 midi)
- 'midi'
- 'notifications'
- 'payment-handler'
- 'storage-access'
origin str (可选)#

要授予权限的来源，例如 "https://example.com"。

返回值

NoneType #

new_cdp_session

添加于: v1.11

browserContext.new_cdp_session

注意

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

返回新创建的会话。

用法

browser_context.new_cdp_session(page)

参数

page Page | Frame #

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

返回值

CDPSession #

new_page

在 v1.9 之前添加

browserContext.new_page

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

用法

browser_context.new_page()

返回值

Page #

route

在 v1.9 之前添加

browserContext.route

路由提供了修改浏览器上下文中任何页面发出的网络请求的功能。启用路由后，除非继续、完成或中止，否则每个与 url 模式匹配的请求都将暂停。

注意

browser_context.route() 不会拦截 Service Worker 拦截的请求。请参阅此问题。我们建议在使用请求拦截时禁用 Service Worker，方法是将 service_workers 设置为 'block'。

用法

一个简单的处理程序示例，该处理程序中止所有图像请求

同步
异步

context = browser.new_context()
page = context.new_page()
context.route("**/*.{png,jpg,jpeg}", lambda route: route.abort())
page.goto("https://example.com")
browser.close()

context = await browser.new_context()
page = await context.new_page()
await context.route("**/*.{png,jpg,jpeg}", lambda route: route.abort())
await page.goto("https://example.com")
await browser.close()

或使用正则表达式模式的相同代码片段

同步
异步

context = browser.new_context()
page = context.new_page()
context.route(re.compile(r"(\.png$)|(\.jpg$)"), lambda route: route.abort())
page = await context.new_page()
page = context.new_page()
page.goto("https://example.com")
browser.close()

context = await browser.new_context()
page = await context.new_page()
await context.route(re.compile(r"(\.png$)|(\.jpg$)"), lambda route: route.abort())
page = await context.new_page()
await page.goto("https://example.com")
await browser.close()

可以检查请求以确定路由操作。例如，模拟包含某些 post 数据的所有请求，并将所有其他请求保持原样

同步
异步

def handle_route(route: Route):
  if ("my-string" in route.request.post_data):
    route.fulfill(body="mocked-data")
  else:
    route.continue_()
context.route("/api/**", handle_route)

async def handle_route(route: Route):
  if ("my-string" in route.request.post_data):
    await route.fulfill(body="mocked-data")
  else:
    await route.continue_()
await context.route("/api/**", handle_route)

当请求与两个处理程序都匹配时，页面路由（使用 page.route() 设置）优先于浏览器上下文路由。

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

注意

启用路由会禁用 http 缓存。

参数

url str | Pattern | Callable[URL]:bool #

一个 glob 模式、正则表达式模式或谓词，接收 URL 以在路由时进行匹配。当通过上下文选项提供了 base_url 并且传递的 URL 是路径时，它会通过 new URL() 构造函数合并。
handler Callable[Route, Request]:Promise[Any] | Any #

用于路由请求的处理函数。
times int (可选)添加于: v1.15#

路由应使用的频率。默认情况下，它将每次使用。

返回值

NoneType #

route_from_har

添加于: v1.23

browserContext.route_from_har

如果指定，则在此上下文中发出的网络请求将从 HAR 文件提供。阅读更多关于从 HAR 回放的信息。

Playwright 不会从 HAR 文件提供 Service Worker 拦截的请求。请参阅此问题。我们建议在使用请求拦截时禁用 Service Worker，方法是将 service_workers 设置为 'block'。

用法

browser_context.route_from_har(har)
browser_context.route_from_har(har, **kwargs)

参数

har Union[str, pathlib.Path]#

包含预先录制的网络数据的 HAR 文件的路径。如果 path 是相对路径，则它相对于当前工作目录解析。
not_found "abort" | "fallback" (可选)#
- 如果设置为 'abort'，则任何在 HAR 文件中找不到的请求都将被中止。
- 如果设置为 'fallback'，则会回退到处理程序链中的下一个路由处理程序。
默认为 abort。
update bool (可选)#

如果指定，则使用实际网络信息更新给定的 HAR，而不是从文件提供服务。当调用 browser_context.close() 时，该文件将写入磁盘。
update_content "embed" | "attach" (可选)添加于: v1.32#

用于控制资源内容管理的可选设置。如果指定 attach，则资源将持久化为 ZIP 存档中的单独文件或条目。如果指定 embed，则内容将以内联方式存储在 HAR 文件中。
update_mode "full" | "minimal" (可选)添加于: v1.32#

当设置为 minimal 时，仅记录从 HAR 路由所需的信息。这省略了在从 HAR 回放时不使用的大小、计时、页面、Cookie、安全性和其他类型的 HAR 信息。默认为 minimal。
url str | Pattern (可选)#

用于匹配请求 URL 的 glob 模式、正则表达式或谓词。只有 URL 与模式匹配的请求才会从 HAR 文件提供。如果未指定，则所有请求都从 HAR 文件提供。

返回值

NoneType #

route_web_socket

Added in: v1.48

browserContext.route_web_socket

此方法允许修改浏览器上下文中的任何页面建立的 websocket 连接。

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

用法

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

同步
异步

def message_handler(ws: WebSocketRoute, message: Union[str, bytes]):
  if message == "to-be-blocked":
    return
  ws.send(message)

def handler(ws: WebSocketRoute):
  ws.route_send(lambda message: message_handler(ws, message))
  ws.connect()

context.route_web_socket("/ws", handler)

def message_handler(ws: WebSocketRoute, message: Union[str, bytes]):
  if message == "to-be-blocked":
    return
  ws.send(message)

async def handler(ws: WebSocketRoute):
  ws.route_send(lambda message: message_handler(ws, message))
  await ws.connect()

await context.route_web_socket("/ws", handler)

参数

url str | Pattern | Callable[URL]:bool #

只有 url 与此模式匹配的 WebSocket 才会被路由。字符串模式可以是相对于 base_url 上下文选项的相对路径。
handler Callable[WebSocketRoute]:Promise[Any] | Any #

用于路由 WebSocket 的处理函数。

返回值

NoneType #

在 v1.9 之前添加

browserContext.set_default_navigation_timeout

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

注意

page.set_default_navigation_timeout() 和 page.set_default_timeout() 的优先级高于 browser_context.set_default_navigation_timeout()。

用法

browser_context.set_default_navigation_timeout(timeout)

参数

timeout float #

最大导航时间，以毫秒为单位

set_default_timeout

在 v1.9 之前添加

browserContext.set_default_timeout

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

注意

page.set_default_navigation_timeout()、 page.set_default_timeout() 和 browser_context.set_default_navigation_timeout() 的优先级高于 browser_context.set_default_timeout()。

用法

browser_context.set_default_timeout(timeout)

参数

timeout float #

最大时间，以毫秒为单位。传递 0 以禁用超时。

set_extra_http_headers

在 v1.9 之前添加

browserContext.set_extra_http_headers

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

注意

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

用法

browser_context.set_extra_http_headers(headers)

参数

headers Dict[str, str]#

一个对象，包含要随每个请求一起发送的附加 HTTP 标头。所有标头值都必须是字符串。

返回值

NoneType #

set_geolocation

在 v1.9 之前添加

browserContext.set_geolocation

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

用法

同步
异步

browser_context.set_geolocation({"latitude": 59.95, "longitude": 30.31667})

await browser_context.set_geolocation({"latitude": 59.95, "longitude": 30.31667})

注意

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

参数

geolocation NoneType | Dict#
- latitude float
  
  纬度，介于 -90 和 90 之间。
- longitude float
  
  经度，介于 -180 和 180 之间。
- accuracy float (可选)
  
  非负精度值。默认为 0。

返回值

NoneType #

set_offline

在 v1.9 之前添加

browserContext.set_offline

用法

browser_context.set_offline(offline)

参数

offline bool #

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

返回值

NoneType #

storage_state

在 v1.9 之前添加

browserContext.storage_state

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

用法

browser_context.storage_state()
browser_context.storage_state(**kwargs)

参数

indexed_db bool (可选)Added in: v1.51#

设置为 true 以在存储状态快照中包含 IndexedDB。如果您的应用程序使用 IndexedDB 存储身份验证令牌（例如 Firebase Authentication），请启用此选项。

注意
目前不支持使用类型化数组的 IndexedDB。
path Union[str, pathlib.Path] (可选)#

用于保存存储状态的文件路径。如果 path 是相对路径，则它将相对于当前工作目录解析。如果未提供路径，则仍会返回存储状态，但不会保存到磁盘。

返回值

Dict#
- cookies List[Dict]
  - name str
  - value str
  - domain str
  - path str
  - expires float
    
    Unix 时间戳，单位为秒。
  - httpOnly bool
  - secure bool
  - sameSite "Strict" | "Lax" | "None"
- origins List[Dict]
  - origin str
  - localStorage List[Dict]
    - name str
    - value str

unroute

在 v1.9 之前添加

browserContext.unroute

移除使用 browser_context.route() 创建的路由。如果未指定 handler，则移除 url 的所有路由。

用法

browser_context.unroute(url)
browser_context.unroute(url, **kwargs)

参数

url str | Pattern | Callable[URL]:bool #

用于注册使用 browser_context.route() 的路由的 glob 模式、正则表达式模式或谓词，接收 URL。
handler Callable[Route, Request]:Promise[Any] | Any (可选)#

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

返回值

NoneType #

unroute_all

Added in: v1.41

browserContext.unroute_all

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

用法

browser_context.unroute_all()
browser_context.unroute_all(**kwargs)

参数

behavior "wait" | "ignoreErrors" | "default" (可选)#

指定是否等待已在运行的处理程序以及如果它们抛出错误时该怎么做
- 'default' - 不等待当前处理程序调用（如果有）完成，如果未路由的处理程序抛出错误，则可能导致未处理的错误
- 'wait' - 等待当前处理程序调用（如果有）完成
- 'ignoreErrors' - 不等待当前处理程序调用（如果有）完成，未路由后处理程序抛出的所有错误都将被静默捕获

返回值

NoneType #

wait_for_event

在 v1.9 之前添加

browserContext.wait_for_event

注意

在大多数情况下，您应该使用 browser_context.expect_event()。

等待给定的 event 触发。如果提供了谓词，它会将事件的值传递到 predicate 函数中，并等待 predicate(event) 返回真值。如果浏览器上下文在 event 触发之前关闭，将抛出错误。

用法

browser_context.wait_for_event(event)
browser_context.wait_for_event(event, **kwargs)

参数

event str #

事件名称，与通常传递到 *.on(event) 中的名称相同。
predicate Callable (可选)#

接收事件数据，并在等待应解决时解析为真值。
timeout float (可选)#

等待的最大时间（以毫秒为单位）。默认为 30000 (30 秒)。传递 0 以禁用超时。默认值可以使用 browser_context.set_default_timeout() 更改。

返回值

Any #

属性

background_pages

添加于: v1.11

browserContext.background_pages

注意

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

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

用法

browser_context.background_pages

返回值

List[Page]#

browser

在 v1.9 之前添加

browserContext.browser

返回上下文的浏览器实例。如果它是作为持久上下文启动的，则返回 null。

用法

browser_context.browser

返回值

NoneType | Browser #

clock

Added in: v1.45

browserContext.clock

Playwright 具有模拟时钟和时间流逝的能力。

用法

browser_context.clock

类型

Clock

pages

在 v1.9 之前添加

browserContext.pages

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

用法

browser_context.pages

返回值

List[Page]#

request

Added in: v1.16

browserContext.request

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

用法

browser_context.request

类型

APIRequestContext

service_workers

添加于: v1.11

browserContext.service_workers

注意

Service workers 仅在基于 Chromium 的浏览器上受支持。

上下文中所有现有的 service worker。

用法

browser_context.service_workers

返回值

List[Worker]#

tracing

Added in: v1.12

browserContext.tracing

用法

browser_context.tracing

类型

Tracing

事件

on("backgroundpage")

添加于: v1.11

browserContext.on("backgroundpage")

注意

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

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

同步
异步

background_page = context.wait_for_event("backgroundpage")

background_page = await context.wait_for_event("backgroundpage")

用法

browser_context.on("backgroundpage", handler)

事件数据

Page

on("close")

在 v1.9 之前添加

browserContext.on("close")

当浏览器上下文关闭时发出。这可能是由于以下原因之一造成的

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

用法

browser_context.on("close", handler)

事件数据

BrowserContext

on("console")

添加于: v1.34

browserContext.on("console")

当页面内的 JavaScript 调用控制台 API 方法之一时发出，例如 console.log 或 console.dir。

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

用法

同步
异步

def print_args(msg):
    for arg in msg.args:
        print(arg.json_value())

context.on("console", print_args)
page.evaluate("console.log('hello', 5, { foo: 'bar' })")

async def print_args(msg):
    values = []
    for arg in msg.args:
        values.append(await arg.json_value())
    print(values)

context.on("console", print_args)
await page.evaluate("console.log('hello', 5, { foo: 'bar' })")

事件数据

ConsoleMessage

on("dialog")

添加于: v1.34

browserContext.on("dialog")

当出现 JavaScript 对话框时发出，例如 alert、 prompt、 confirm 或 beforeunload。监听器必须 dialog.accept() 或 dialog.dismiss() 对话框 - 否则页面将 freeze 等待对话框，并且像 click 这样的操作将永远不会完成。

用法

context.on("dialog", lambda dialog: dialog.accept())

注意

当没有 page.on("dialog") 或 browser_context.on("dialog") 监听器时，所有对话框都会自动关闭。

事件数据

Dialog

on("page")

在 v1.9 之前添加

browserContext.on("page")

当在 BrowserContext 中创建新页面时发出此事件。页面可能仍在加载中。此事件也适用于弹出页面。另请参阅 page.on("popup") 以接收有关特定页面的弹出窗口的事件。

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

同步
异步

with context.expect_page() as page_info:
    page.get_by_text("open new page").click(),
page = page_info.value
print(page.evaluate("location.href"))

async with context.expect_page() as page_info:
    await page.get_by_text("open new page").click(),
page = await page_info.value
print(await page.evaluate("location.href"))

注意

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

用法

browser_context.on("page", handler)

事件数据

Page

on("request")

Added in: v1.12

browserContext.on("request")

当通过此上下文创建的任何页面发出请求时发出。 request 对象是只读的。要仅监听来自特定页面的请求，请使用 page.on("request")。

为了拦截和修改请求，请参阅 browser_context.route() 或 page.route()。

用法

browser_context.on("request", handler)

事件数据

Request

on("requestfailed")

Added in: v1.12

browserContext.on("requestfailed")

当请求失败时发出，例如由于超时。要仅监听来自特定页面的失败请求，请使用 page.on("requestfailed")。

注意

HTTP 错误响应（例如 404 或 503）从 HTTP 的角度来看仍然是成功的响应，因此请求将使用 browser_context.on("requestfinished") 事件完成，而不是 browser_context.on("requestfailed")。

用法

browser_context.on("requestfailed", handler)

事件数据

Request

on("requestfinished")

Added in: v1.12

browserContext.on("requestfinished")

当请求在下载响应主体后成功完成时发出。对于成功的响应，事件序列为 request、 response 和 requestfinished。要监听来自特定页面的成功请求，请使用 page.on("requestfinished")。

用法

browser_context.on("requestfinished", handler)

事件数据

Request

on("response")

Added in: v1.12

browserContext.on("response")

当接收到请求的 response 状态和标头时发出。对于成功的响应，事件序列为 request、 response 和 requestfinished。要监听来自特定页面的响应事件，请使用 page.on("response")。

用法

browser_context.on("response", handler)

事件数据

Response

on("serviceworker")

添加于: v1.11

browserContext.on("serviceworker")

注意

Service workers 仅在基于 Chromium 的浏览器上受支持。

当在上下文中创建新的 service worker 时发出。

用法

browser_context.on("serviceworker", handler)

事件数据

Worker

on("weberror")

Added in: v1.38

browserContext.on("weberror")

当在此上下文中的任何页面中未处理异常时发出。要监听来自特定页面的错误，请改用 page.on("pageerror")。

用法

browser_context.on("weberror", handler)

事件数据

WebError

方法​

add_cookies​

add_init_script​

clear_cookies​

clear_permissions​

close​

cookies​

expect_console_message​

expect_event​

expect_page​

expose_binding​

expose_function​

grant_permissions​

new_cdp_session​

new_page​

route​

route_from_har​

route_web_socket​

set_default_navigation_timeout​

set_default_timeout​

set_extra_http_headers​

set_geolocation​

set_offline​

storage_state​

unroute​

unroute_all​

wait_for_event​

属性​

background_pages​

browser​

clock​

pages​

request​

service_workers​

tracing​

事件​

on("backgroundpage")​

on("close")​

on("console")​

on("dialog")​

on("page")​

on("request")​

on("requestfailed")​

on("requestfinished")​

on("response")​

on("serviceworker")​

on("weberror")​

方法

add_cookies

add_init_script

clear_cookies

clear_permissions

close

cookies

expect_console_message

expect_event

expect_page

expose_binding

expose_function

grant_permissions

new_cdp_session

new_page

route

route_from_har

route_web_socket

set_default_navigation_timeout

set_default_timeout

set_extra_http_headers

set_geolocation

set_offline

storage_state

unroute

unroute_all

wait_for_event

属性

background_pages

browser

clock

pages

request

service_workers

tracing

事件

on("backgroundpage")

on("close")

on("console")

on("dialog")

on("page")

on("request")

on("requestfailed")

on("requestfinished")

on("response")

on("serviceworker")

on("weberror")