BrowserType

BrowserType 提供啟動特定瀏覽器實例或連接到現有實例的方法。以下是使用 Playwright 驅動自動化的典型範例

同步

from playwright.sync_api import sync_playwright, Playwright

def run(playwright: Playwright):
    chromium = playwright.chromium
    browser = chromium.launch()
    page = browser.new_page()
    page.goto("https://example.com")
    # other actions...
    browser.close()

with sync_playwright() as playwright:
    run(playwright)

非同步

import asyncio
from playwright.async_api import async_playwright, Playwright

async def run(playwright: Playwright):
    chromium = playwright.chromium
    browser = await chromium.launch()
    page = await browser.new_page()
    await page.goto("https://example.com")
    # other actions...
    await browser.close()

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

---

方法

連接

在 v1.9 之前新增 browserType.connect

此方法將 Playwright 連接到現有的瀏覽器實例。當連接到另一個透過 Node.js 中的 BrowserType.launchServer 啟動的瀏覽器時，主要版本和次要版本需要與客戶端版本相符 (1.2.3 → 與 1.2.x 相容)。

用法

browser_type.connect(ws_endpoint)
browser_type.connect(ws_endpoint, **kwargs)

參數

• ws_endpoint str在 v1.10 中新增#

  要連接的瀏覽器 WebSocket 端點。

• expose_network str (選填)在 v1.37 中新增#

  此選項將連接客戶端上可用的網路公開給正在連接的瀏覽器。由逗號分隔的規則列表組成。

  可用規則

  1. 主機名稱模式，例如：example.com、*.org:99、x.*.y.com、*foo.org。
  2. IP 字面值，例如：127.0.0.1、0.0.0.0:99、[::1]、[0:0::1]:99。
  3. <loopback>，符合本機迴路介面：localhost、*.localhost、127.0.0.1、[::1]。

  一些常見範例

  1. "*" 以公開所有網路。
  2. "<loopback>" 以公開 localhost 網路。
  3. "*.test.internal-domain,*.staging.internal-domain,<loopback>" 以公開測試/預備部署和 localhost。

• headers Dict[str, str] (選填)在 v1.11 中新增#

  要與 WebSocket 連接請求一起傳送的其他 HTTP 標頭。選填。

• slow_mo float (選填)在 v1.10 中新增#

  以指定的毫秒數減慢 Playwright 操作速度。方便您查看正在發生的情況。預設值為 0。

• timeout float (選填)在 v1.10 中新增#

  等待建立連線的最長時間 (以毫秒為單位)。預設值為 0 (無超時)。

回傳

• 瀏覽器#

---

connect_over_cdp

在 v1.9 中新增 browserType.connect_over_cdp

此方法使用 Chrome DevTools Protocol 將 Playwright 連接到現有的瀏覽器實例。

預設瀏覽器內容可透過 browser.contexts 存取。

注意

透過 Chrome DevTools Protocol 連接僅適用於基於 Chromium 的瀏覽器。

用法

同步

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

非同步

browser = await playwright.chromium.connect_over_cdp("https://127.0.0.1:9222")
default_context = browser.contexts[0]
page = default_context.pages[0]

參數

• endpoint_url str在 v1.11 中新增#

  要連接的 CDP WebSocket 端點或 HTTP URL。例如 https://127.0.0.1:9222/ 或 ws://127.0.0.1:9222/devtools/browser/387adf4c-243f-4051-a181-46798f4a46f4。

• headers Dict[str, str] (選填)在 v1.11 中新增#

  要與連接請求一起傳送的其他 HTTP 標頭。選填。

• slow_mo float (選填)在 v1.11 中新增#

  以指定的毫秒數減慢 Playwright 操作速度。方便您查看正在發生的情況。預設值為 0。

• timeout float (選填)在 v1.11 中新增#

  等待建立連線的最長時間 (以毫秒為單位)。預設值為 30000 (30 秒)。傳遞 0 以停用超時。

回傳

• 瀏覽器#

---

啟動

在 v1.9 之前新增 browserType.launch

回傳瀏覽器實例。

用法

您可以使用 ignore_default_args 從預設引數中篩選掉 --mute-audio

同步

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

非同步

browser = await 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 使用者的一些差異。

參數

• args List[str] (選填)#

  警告

  請自行承擔使用自訂瀏覽器引數的風險，因為其中一些引數可能會破壞 Playwright 功能。

  要傳遞給瀏覽器實例的其他引數。Chromium 標誌列表可以在這裡找到。

• channel str (選填)#

  瀏覽器發行管道。

  使用 "chromium" 選擇加入新的無頭模式。

  使用 "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] (選填)#

  如果指定，追蹤會儲存到此目錄中。

回傳

• 瀏覽器#

---

launch_persistent_context

在 v1.9 之前新增 browserType.launch_persistent_context

回傳持續性瀏覽器內容實例。

啟動使用位於 user_data_dir 的持續性儲存空間的瀏覽器，並回傳唯一的內容。關閉此內容將自動關閉瀏覽器。

用法

browser_type.launch_persistent_context(user_data_dir)
browser_type.launch_persistent_context(user_data_dir, **kwargs)

參數

• user_data_dir Union[str, pathlib.Path]#

  使用者資料目錄的路徑，用於儲存瀏覽器工作階段資料，例如 Cookie 和本機儲存空間。有關 Chromium 和 Firefox 的更多詳細資訊。請注意，Chromium 的使用者資料目錄是在 chrome://version 中看到的「設定檔路徑」的父目錄。傳遞空字串以改用暫存目錄。

• accept_downloads bool (選填)#

  是否自動下載所有附件。預設值為 true，其中接受所有下載。

• args List[str] (選填)#

  警告

  請自行承擔使用自訂瀏覽器引數的風險，因為其中一些引數可能會破壞 Playwright 功能。

  要傳遞給瀏覽器實例的其他引數。Chromium 標誌列表可以在這裡找到。

• base_url str (選填)#

  當使用 page.goto()、page.route()、page.wait_for_url()、page.expect_request() 或 page.expect_response() 時，它會透過使用 URL() 建構函式來建置對應的 URL，從而將基本 URL 納入考量。預設為未設定。範例

  • baseURL：https://127.0.0.1:3000，導覽至 /bar.html 會產生 https://127.0.0.1:3000/bar.html
  • baseURL：https://127.0.0.1:3000/foo/，導覽至 ./bar.html 會產生 https://127.0.0.1:3000/foo/bar.html
  • baseURL：https://127.0.0.1:3000/foo (沒有尾部斜線)，導覽至 ./bar.html 會產生 https://127.0.0.1:3000/bar.html

• bypass_csp bool (選填)#

  切換繞過頁面的內容安全策略。預設值為 false。

• channel str (選填)#

  瀏覽器發行管道。

  使用 "chromium" 選擇加入新的無頭模式。

  使用 "chrome"、"chrome-beta"、"chrome-dev"、"chrome-canary"、"msedge"、"msedge-beta"、"msedge-dev" 或 "msedge-canary" 以使用品牌 Google Chrome 和 Microsoft Edge。

• chromium_sandbox bool (選填)#

  啟用 Chromium 沙箱。預設值為 false。

• client_certificates List[Dict] (選填)在 1.46 中新增#

  • origin str

    憑證有效的確切來源。來源包括 https 協定、主機名稱和選用的連接埠。

  • certPath Union[str, pathlib.Path] (選填)

    PEM 格式憑證檔案的路徑。

  • cert bytes (選填)

    PEM 格式憑證的直接值。

  • keyPath Union[str, pathlib.Path] (選填)

    PEM 格式私密金鑰檔案的路徑。

  • key bytes (選填)

    PEM 格式私密金鑰的直接值。

  • pfxPath Union[str, pathlib.Path] (選填)

    PFX 或 PKCS12 編碼私密金鑰和憑證鏈的路徑。

  • pfx bytes (選填)

    PFX 或 PKCS12 編碼私密金鑰和憑證鏈的直接值。

  • passphrase str (選填)

    私密金鑰 (PEM 或 PFX) 的通行詞組。

  TLS 用戶端驗證允許伺服器請求用戶端憑證並驗證它。

  詳細資訊

  要使用的用戶端憑證陣列。每個憑證物件都必須具有 certPath 和 keyPath、單個 pfxPath 或其對應的直接值等效項 (cert 和 key，或 pfx)。或者，如果憑證已加密，則應提供 passphrase 屬性。應提供 origin 屬性，以完全符合憑證有效的請求來源。

  注意

  在 macOS 上使用 WebKit 時，存取 localhost 不會選取用戶端憑證。您可以透過將 localhost 替換為 local.playwright 來使其運作。

• color_scheme "light" | "dark" | "no-preference" | "null" (選填)#

  模擬 prefers-colors-scheme 媒體功能，支援的值為 'light' 和 'dark'。請參閱 page.emulate_media() 以取得更多詳細資訊。傳遞 'null' 會將模擬重設為系統預設值。預設值為 '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 標頭的物件。預設為無。

• firefox_user_prefs Dict[str, str | float | bool] (選填)新增於：v1.40#

  Firefox 使用者偏好設定。在 about:config 了解更多關於 Firefox 使用者偏好設定的資訊。

• forced_colors "active" | "none" | "null" (選填)#

  模擬 'forced-colors' 媒體功能，支援的值為 'active'、'none'。參閱 page.emulate_media() 以取得更多詳細資訊。傳遞 'null' 會將模擬重設為系統預設值。預設值為 '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 (選填)#

  • username str

  • password str

  • origin str (選填)

    限制在特定來源 (scheme://host:port).

  • send "unauthorized" | "always" (選填)

    此選項僅適用於從對應的 APIRequestContext 發送的請求，且不影響從瀏覽器發送的請求。'always' - Authorization 標頭與基本身分驗證憑證將隨每個 API 請求一起發送。'unauthorized' - 憑證僅在收到 401 (Unauthorized) 回應且帶有 WWW-Authenticate 標頭時發送。預設值為 'unauthorized'。

  用於 HTTP 驗證 的憑證。如果未指定來源，則使用者名稱和密碼將在收到未經授權的回應時發送至任何伺服器。

• ignore_default_args bool | List[str] (選填)#

  如果為 true，Playwright 不會傳遞其自身的組態引數，而僅使用來自 args 的引數。如果給定陣列，則會篩選掉給定的預設引數。危險選項；請謹慎使用。預設值為 false。

• ignore_https_errors bool (選填)#

  是否忽略在發送網路請求時的 HTTPS 錯誤。預設值為 false。

• is_mobile bool (選填)#

  是否考量 meta viewport 標籤並啟用觸控事件。isMobile 是裝置的一部分，因此實際上不需要手動設定。預設值為 false，且 Firefox 不支援。深入瞭解 行動裝置模擬。

• java_script_enabled bool (選填)#

  是否在此內容中啟用 JavaScript。預設值為 true。深入瞭解 停用 JavaScript。

• locale str (選填)#

  指定使用者地區設定，例如 en-GB、de-DE 等。地區設定將影響 navigator.language 值、Accept-Language 請求標頭值以及數字和日期格式規則。預設值為系統預設地區設定。深入瞭解我們的 模擬指南 中的模擬資訊。

• no_viewport bool (選填)#

  不強制執行固定視窗，允許在 Headed 模式中調整視窗大小。

• offline bool (選填)#

  是否模擬網路離線狀態。預設值為 false。深入瞭解 網路模擬。

• permissions List[str] (選填)#

  要授予此內容中所有頁面的權限清單。參閱 browser_context.grant_permissions() 以取得更多詳細資訊。預設值為無。

• 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 (選填)#

  • width int

    影片幀寬度。

  • height int

    影片幀高度。

  記錄影片的尺寸。如果未指定，尺寸將等於 viewport 縮小以符合 800x800。如果未明確設定 viewport，則影片尺寸預設為 800x450。如有必要，每個頁面的實際圖片將縮小以符合指定的尺寸。

• reduced_motion "reduce" | "no-preference" | "null" (選填)#

  模擬 'prefers-reduced-motion' 媒體功能，支援的值為 'reduce'、'no-preference'。參閱 page.emulate_media() 以取得更多詳細資訊。傳遞 'null' 會將模擬重設為系統預設值。預設值為 'no-preference'。

• screen Dict (選填)#

  • width int

    頁面寬度 (像素)。

  • height int

    頁面高度 (像素)。

  模擬透過 window.screen 在網頁內可使用的一致視窗螢幕尺寸。僅在設定 viewport 時使用。

• service_workers "allow" | "block" (選填)#

  是否允許網站註冊 Service Worker。預設值為 'allow'。

  • 'allow': Service Worker 可以註冊。
  • 'block': Playwright 將封鎖所有 Service Worker 的註冊。

• slow_mo float (選填)#

  以指定的毫秒數減慢 Playwright 操作速度。方便您查看正在發生的情況。

• strict_selectors bool (選填)#

  如果設定為 true，則為此內容啟用嚴格選取器模式。在嚴格選取器模式下，對選取器執行的所有操作（暗示單一目標 DOM 元素）在多個元素符合選取器時都會擲回例外。此選項不影響任何 Locator API (Locator 始終是嚴格的)。預設值為 false。參閱 Locator 以深入瞭解嚴格模式。

• timeout float (選填)#

  等待瀏覽器實例啟動的最長時間 (以毫秒為單位)。預設值為 30000 (30 秒)。傳遞 0 以停用超時。

• timezone_id str (選填)#

  變更內容的時區。請參閱 ICU 的 metaZones.txt 以取得支援的時區 ID 清單。預設值為系統時區。

• traces_dir Union[str, pathlib.Path] (選填)#

  如果指定，追蹤會儲存到此目錄中。

• user_agent str (選填)#

  在此內容中使用的特定使用者代理程式。

• viewport NoneType | Dict (選填)#

  • width int

    頁面寬度 (像素)。

  • height int

    頁面高度 (像素)。

  為每個頁面設定一致的視窗。預設值為 1280x720 視窗。no_viewport 會停用固定視窗。深入瞭解 視窗模擬。

回傳

• BrowserContext#

---

屬性

executable_path

在 v1.9 之前新增 browserType.executable_path

Playwright 預期在此路徑中找到捆綁的瀏覽器可執行檔。

用法

browser_type.executable_path

回傳

• str#

---

name

在 v1.9 之前新增 browserType.name

傳回瀏覽器名稱。例如：'chromium'、'webkit' 或 'firefox'。

用法

browser_type.name

回傳

• str#