Skip to main content

BrowserType

BrowserType 提供启动特定浏览器实例或连接到现有浏览器实例的方法。以下是使用 Playwright 驱动自动化的典型示例：

from playwright.sync_api import sync_playwright

def run(playwright):
    chromium = playwright.chromium
    browser = chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com")
    # 其他操作...
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

browser_type.connect(ws_endpoint, **kwargs)​

Added in: v1.8
  • ws_endpoint <str> 要连接的浏览器 websocket 端点。Added in: v1.10#
  • headers <Dict[str, str]> 随 web socket 连接请求发送的附加 HTTP 标头。可选。Added in: v1.11#
  • slow_mo <float> 将 Playwright 操作减慢指定的毫秒数。很有用，让您可以看清发生了什么。默认为 0。Added in: v1.10#
  • timeout <float> 等待建立连接的最长时间（毫秒）。默认为 0（无超时）。Added in: v1.10#
  • 返回值: <Browser>#

此方法将 Playwright 附加到现有的浏览器实例。当连接到在 Node.js 中通过 BrowserType.launchServer 启动的另一个浏览器时，主版本号和次版本号需要与客户端版本匹配（1.2.3 → 与 1.2.x 兼容）。

browser_type.connect_over_cdp(endpoint_url, **kwargs)​

Added in: v1.9
  • endpoint_url <str> 要连接的 CDP websocket 端点或 http url。例如 http://localhost:9222/ 或 ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4。Added in: v1.11#
  • headers <Dict[str, str]> 随 connect 请求发送的附加 HTTP 标头。可选。Added in: v1.11#
  • slow_mo <float> 将 Playwright 操作减慢指定的毫秒数。很有用，让您可以看清发生了什么。默认为 0。Added in: v1.11#
  • timeout <float> 等待建立连接的最长时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。Added in: v1.11#
  • 返回值: <Browser>#

此方法使用 Chrome DevTools 协议将 Playwright 附加到现有的浏览器实例。

默认浏览器上下文可通过 browser.contexts 访问。

note

仅基于 Chromium 的浏览器支持通过 Chrome DevTools 协议进行连接。

browser = playwright.chromium.connect_over_cdp("http://localhost:9222")
default_context = browser.contexts[0]
page = default_context.pages[0]

browser_type.executable_path​

Added in: v1.8

Playwright 期望找到捆绑的浏览器可执行文件的路径。

browser_type.launch(**kwargs)​

Added in: v1.8
  • args <List[str]> 传递给浏览器实例的附加参数。Chromium 标志列表可在此处找到。#
  • channel <str> 浏览器分发通道。支持的值为 "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", "msedge-canary"。阅读有关使用 Google Chrome 和 Microsoft Edge 的更多信息。#
  • chromium_sandbox <bool> 启用 Chromium 沙箱。默认为 false。#
  • devtools <bool> 仅限 Chromium 是否为每个选项卡自动打开开发者工具面板。如果此选项为 true，则 headless 选项将设置为 false。#
  • downloads_path <Union[str, pathlib.Path]> 如果指定，则已接受的下载将下载到此目录中。否则，将创建临时目录，并在浏览器关闭时将其删除。在任何一种情况下，当创建下载的浏览器上下文关闭时，下载均会被删除。#
  • env <Dict[str, str|float|bool]> 指定对浏览器可见的环境变量。默认为 process.env。#
  • executable_path <Union[str, pathlib.Path]> 要运行的浏览器可执行文件的路径，而不是捆绑的浏览器可执行文件。如果 executable_path 是相对路径，则相对于当前工作目录解析。请注意，Playwright 仅适用于捆绑的 Chromium、Firefox 或 WebKit，使用风险自负。#
  • firefox_user_prefs <Dict[str, str|float|bool]> Firefox 用户首选项。在 about:config 中了解有关 Firefox 用户首选项的更多信息。#
  • handle_sighup <bool> 在 SIGHUP 时关闭浏览器进程。默认为 true。#
  • handle_sigint <bool> 在 Ctrl-C 时关闭浏览器进程。默认为 true。#
  • handle_sigterm <bool> 在 SIGTERM 时关闭浏览器进程。默认为 true。#
  • headless <bool> 是否在无头模式下运行浏览器。有关 Chromium 和 Firefox 的更多详细信息。除非 devtools 选项为 true，否则默认为 true。#
  • ignore_default_args <bool|List[str]> 如果为 true，则 Playwright 不传递其自己的配置参数，而仅使用 args 中的参数。如果给定了数组，则过滤掉给定的默认参数。危险选项；请谨慎使用。默认为 false。#
  • proxy <Dict> 网络代理设置。#
    • server <str> 用于所有请求的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。短格式 myproxy.com:3128 被视为 HTTP 代理。
    • bypass <str> 用于绕过代理的可选的逗号分隔域，例如 ".com, chromium.org, .domain.com"。
    • username <str> 如果 HTTP 代理需要身份验证，则为可选用户名。
    • password <str> 如果 HTTP 代理需要身份验证，则为可选密码。
  • slow_mo <float> 将 Playwright 操作减慢指定的毫秒数。很有用，让您可以看清发生了什么。#
  • timeout <float> 等待浏览器实例启动的最长时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。#
  • traces_dir <Union[str, pathlib.Path]> 如果指定，则跟踪将保存到此目录中。#
  • 返回值: <Browser>#

返回浏览器实例。

您可以使用 ignore_default_args 从默认参数中过滤掉 --mute-audio：

browser = playwright.chromium.launch( # or "firefox" or "webkit".
    ignore_default_args=["--mute-audio"]
)

仅限 Chromium Playwright 也可用于控制 Google Chrome 或 Microsoft Edge 浏览器，但它与捆绑的 Chromium 版本效果最好。不保证它与其他任何版本兼容。请极其谨慎地使用 executable_path 选项。

如果首选 Google Chrome（而不是 Chromium），建议使用 Chrome Canary 或 Dev Channel 版本。

像 Google Chrome 和 Microsoft Edge 这样的原生浏览器适用于需要专有媒体编解码器进行视频播放的测试。请参阅此文章以了解 Chromium 和 Chrome 之间的其他差异。此文章介绍了 Linux 用户的一些差异。

browser_type.launch_persistent_context(user_data_dir, **kwargs)​

Added in: v1.8
  • user_data_dir <Union[str, pathlib.Path]> 用户数据目录的路径，其中存储浏览器会话数据，如 cookie 和本地存储。 Chromium 和 Firefox 的更多详细信息。请注意，Chromium 的用户数据目录是 chrome://version 中看到的 "Profile Path" 的父目录。传递空字符串以改用临时目录。#
  • accept_downloads <bool> 是否自动下载所有附件。默认为 true，即接受所有下载。#
  • args <List[str]> 传递给浏览器实例的附加参数。Chromium 标志列表可在此处找到。#
  • base_url <str> 当使用 page.goto(url, **kwargs)、page.route(url, handler, **kwargs)、page.wait_for_url(url, **kwargs)、page.expect_request(url_or_predicate, **kwargs) 或 page.expect_response(url_or_predicate, **kwargs) 时，它会考虑基准 URL，通过使用 URL() 构造函数构建相应的 URL。示例：#
    • baseURL: http://localhost:3000 并且导航到 /bar.html 结果为 http://localhost:3000/bar.html
    • baseURL: http://localhost:3000/foo/ 并且导航到 ./bar.html 结果为 http://localhost:3000/foo/bar.html
    • baseURL: http://localhost:3000/foo (无尾部斜杠) 并且导航到 ./bar.html 结果为 http://localhost:3000/bar.html
  • bypass_csp <bool> 切换绕过页面的 Content-Security-Policy。#
  • channel <str> 浏览器分发通道。支持的值为 "chrome", "chrome-beta", "chrome-dev", "chrome-canary", "msedge", "msedge-beta", "msedge-dev", "msedge-canary"。阅读有关使用 Google Chrome 和 Microsoft Edge 的更多信息。#
  • chromium_sandbox <bool> 启用 Chromium 沙箱。默认为 false。#
  • color_scheme <"light"|"dark"|"no-preference"> 模拟 'prefers-colors-scheme' 媒体特性，支持的值为 'light'、'dark'、'no-preference'。有关更多详细信息，请参阅 page.emulate_media(**kwargs)。默认为 'light'。#
  • device_scale_factor <float> 指定设备缩放因子（可以认为是 dpr）。默认为 1。#
  • devtools <bool> 仅限 Chromium 是否为每个选项卡自动打开开发者工具面板。如果此选项为 true，则 headless 选项将设置为 false。#
  • downloads_path <Union[str, pathlib.Path]> 如果指定，则已接受的下载将下载到此目录中。否则，将创建临时目录，并在浏览器关闭时将其删除。在任何一种情况下，当创建下载的浏览器上下文关闭时，下载均会被删除。#
  • env <Dict[str, str|float|bool]> 指定对浏览器可见的环境变量。默认为 process.env。#
  • executable_path <Union[str, pathlib.Path]> 要运行的浏览器可执行文件的路径，而不是捆绑的浏览器可执行文件。如果 executable_path 是相对路径，则相对于当前工作目录解析。请注意，Playwright 仅适用于捆绑的 Chromium、Firefox 或 WebKit，使用风险自负。#
  • extra_http_headers <Dict[str, str]> 包含随每个请求发送的附加 HTTP 标头的对象。#
  • forced_colors <"active"|"none"> 模拟 'forced-colors' 媒体特性，支持的值为 'active'、'none'。有关更多详细信息，请参阅 page.emulate_media(**kwargs)。默认为 'none'。#
  • geolocation <Dict>#
    • latitude <float> -90 到 90 之间的纬度。
    • longitude <float> -180 到 180 之间的经度。
    • accuracy <float> 非负精度值。默认为 0。
  • handle_sighup <bool> 在 SIGHUP 时关闭浏览器进程。默认为 true。#
  • handle_sigint <bool> 在 Ctrl-C 时关闭浏览器进程。默认为 true。#
  • handle_sigterm <bool> 在 SIGTERM 时关闭浏览器进程。默认为 true。#
  • has_touch <bool> 指定视口是否支持触摸事件。默认为 false。#
  • headless <bool> 是否在无头模式下运行浏览器。有关 Chromium 和 Firefox 的更多详细信息。除非 devtools 选项为 true，否则默认为 true。#
  • http_credentials <Dict> HTTP authentication 的凭据。#
  • ignore_default_args <bool|List[str]> 如果为 true，则 Playwright 不传递其自己的配置参数，而仅使用 args 中的参数。如果给定了数组，则过滤掉给定的默认参数。危险选项；请谨慎使用。默认为 false。#
  • ignore_https_errors <bool> 是否在发送网络请求时忽略 HTTPS 错误。默认为 false。#
  • is_mobile <bool> 是否考虑 meta viewport 标签并启用触摸事件。默认为 false。Firefox 不支持。#
  • java_script_enabled <bool> 是否在上下文中启用 JavaScript。默认为 true。#
  • locale <str> 指定用户区域设置，例如 en-GB、de-DE 等。区域设置将影响 navigator.language 值、Accept-Language 请求标头值以及数字和日期格式规则。#
  • no_viewport <bool> 不强制执行固定视口，允许在有头模式下调整窗口大小。#
  • offline <bool> 是否模拟网络离线。默认为 false。#
  • permissions <List[str]> 授予此上下文中所有页面的权限列表。有关更多详细信息，请参阅 browser_context.grant_permissions(permissions, **kwargs)。#
  • proxy <Dict> 网络代理设置。#
    • server <str> 用于所有请求的代理。支持 HTTP 和 SOCKS 代理，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。短格式 myproxy.com:3128 被视为 HTTP 代理。
    • bypass <str> 用于绕过代理的可选的逗号分隔域，例如 ".com, chromium.org, .domain.com"。
    • username <str> 如果 HTTP 代理需要身份验证，则为可选用户名。
    • password <str> 如果 HTTP 代理需要身份验证，则为可选密码。
  • record_har_content <"omit"|"embed"|"attach"> 控制资源内容管理的可选设置。如果指定为 omit，则不保留内容。如果指定为 attach，则资源将作为单独的文件保存，并且所有这些文件都与 HAR 文件一起存档。默认为 embed，根据 HAR 规范将内容内联存储在 HAR 文件中。#
  • record_har_mode <"full"|"minimal"> 当设置为 minimal 时，仅记录从 HAR 路由所需的信息。这会省略大小、时间、页面、cookie、安全性以及从 HAR 重播时不使用的其他类型的 HAR 信息。默认为 full。#
  • record_har_omit_content <bool> 控制是否从 HAR 中省略请求内容的可选设置。默认为 false。#
  • record_har_path <Union[str, pathlib.Path]> 启用将所有页面的 HAR 记录到文件系统上的指定 HAR 文件中。如果未指定，则不记录 HAR。确保调用 browser_context.close() 以保存 HAR。#
  • record_har_url_filter <str|Pattern>#
  • record_video_dir <Union[str, pathlib.Path]> 启用将所有页面的视频录制到指定目录。如果未指定，则不录制视频。确保调用 browser_context.close() 以保存视频。#
  • record_video_size <Dict> 录制视频的尺寸。如果未指定，则尺寸将等于缩放到适合 800x800 的 viewport。如果未显式配置 viewport，则视频尺寸默认为 800x450。如有必要，每页的实际图片将按比例缩小以适合指定尺寸。#
    • width <int> 视频帧宽度。
    • height <int> 视频帧高度。
  • reduced_motion <"reduce"|"no-preference"> 模拟 'prefers-reduced-motion' 媒体特性，支持的值为 'reduce'、'no-preference'。有关更多详细信息，请参阅 page.emulate_media(**kwargs)。默认为 'no-preference'。#
  • screen <Dict> 模拟通过 window.screen 在网页内可用的一致窗口屏幕大小。仅当设置了 viewport 时使用。#
    • width <int> 页面宽度（像素）。
    • height <int> 页面高度（像素）。
  • service_workers <"allow"|"block"> 是否允许站点注册 Service Worker。默认为 'allow'。#
    • 'allow': 可以注册 Service Workers。
    • 'block': Playwright 将阻止所有 Service Workers 的注册。
  • slow_mo <float> 将 Playwright 操作减慢指定的毫秒数。很有用，让您可以看清发生了什么。#
  • strict_selectors <bool> 如果指定，则为此上下文启用严格选择器模式。在严格选择器模式下，当多个元素与选择器匹配时，所有针对暗示单个目标 DOM 元素的选择器的操作都将抛出异常。查看 Locator 了解有关严格模式的更多信息。#
  • timeout <float> 等待浏览器实例启动的最长时间（毫秒）。默认为 30000（30 秒）。传递 0 可禁用超时。#
  • timezone_id <str> 更改上下文的时区。有关支持的时区 ID 列表，请参阅 ICU's metaZones.txt。#
  • traces_dir <Union[str, pathlib.Path]> 如果指定，则跟踪将保存到此目录中。#
  • user_agent <str> 在此上下文使用的特定用户代理。#
  • viewport <NoneType|Dict> 为每个页面设置一致的视口。默认为 1280x720 视口。no_viewport 禁用固定视口。#
    • width <int> 页面宽度（像素）。
    • height <int> 页面高度（像素）。
  • returns: <BrowserContext>#

返回浏览器实例。

启动使用位于 user_data_dir 的持久存储的浏览器并返回唯一的上下文。关闭此上下文将自动关闭浏览器。

browser_type.name​

Added in: v1.8

返回浏览器名称。例如：'chromium'、'webkit' 或 'firefox'。