BrowserType

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

using Microsoft.Playwright;
using System.Threading.Tasks;

class BrowserTypeExamples
{
    public static async Task Run()
    {
        using var playwright = await Playwright.CreateAsync();
        var chromium = playwright.Chromium;
        var browser = await chromium.LaunchAsync();
        var page = await browser.NewPageAsync();
        await page.GotoAsync("https://www.bing.com");
        // other actions
        await browser.CloseAsync();
    }
}

方法

ConnectAsync

在 v1.9 之前新增

browserType.ConnectAsync

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

用法

await BrowserType.ConnectAsync(wsEndpoint, options);

引數

wsEndpoint string在 v1.10 中新增#

要連線的瀏覽器 websocket 端點。
options BrowserTypeConnectOptions? (選用)
- ExposeNetwork string? (選用)在 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 IDictionary?<string, string> (選用)在 v1.11 中新增#
  
  要與 web socket 連線請求一起傳送的其他 HTTP 標頭。選用。
- SlowMo [float]? (選用)在 v1.10 中新增#
  
  以指定的毫秒數減慢 Playwright 運作速度。有助於您查看正在發生的事情。預設為 0。
- Timeout [float]? (選用)在 v1.10 中新增#
  
  等待建立連線的最長時間 (以毫秒為單位)。預設為 0 (無逾時)。

傳回

Browser #

ConnectOverCDPAsync

在 v1.9 中新增

browserType.ConnectOverCDPAsync

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

預設瀏覽器內容可透過 Browser.Contexts 存取。

注意

透過 Chrome DevTools Protocol 連線僅支援以 Chromium 為基礎的瀏覽器。

用法

var browser = await playwright.Chromium.ConnectOverCDPAsync("https://127.0.0.1:9222");
var defaultContext = browser.Contexts[0];
var page = defaultContext.Pages[0];

引數

endpointURL string在 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。
options BrowserTypeConnectOverCDPOptions? (選用)
- Headers IDictionary?<string, string> (選用)在 v1.11 中新增#
  
  要與連線請求一起傳送的其他 HTTP 標頭。選用。
- SlowMo [float]? (選用)在 v1.11 中新增#
  
  以指定的毫秒數減慢 Playwright 運作速度。有助於您查看正在發生的事情。預設為 0。
- Timeout [float]? (選用)在 v1.11 中新增#
  
  等待建立連線的最長時間 (以毫秒為單位)。預設為 30000 (30 秒)。傳遞 0 以停用逾時。

傳回

Browser #

ExecutablePath

在 v1.9 之前新增

browserType.ExecutablePath

Playwright 預期找到套裝瀏覽器執行檔的路徑。

用法

BrowserType.ExecutablePath

傳回

string #

LaunchAsync

在 v1.9 之前新增

browserType.LaunchAsync

傳回瀏覽器實例。

用法

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

var browser = await playwright.Chromium.LaunchAsync(new() {
    IgnoreDefaultArgs = new[] { "--mute-audio" }
});

僅限 Chromium Playwright 也可用於控制 Google Chrome 或 Microsoft Edge 瀏覽器，但與其套裝的 Chromium 版本搭配使用效果最佳。無法保證它能與任何其他版本搭配運作。請極度謹慎地使用 ExecutablePath 選項。

如果偏好使用 Google Chrome (而非 Chromium)，建議使用 Chrome Canary 或 Dev Channel 組建。

Google Chrome 和 Microsoft Edge 等庫存瀏覽器適用於需要專有媒體編解碼器進行視訊播放的測試。請參閱這篇文章，瞭解 Chromium 和 Chrome 之間的其他差異。這篇文章描述了 Linux 使用者的一些差異。

引數

options BrowserTypeLaunchOptions? (選用)
- Args IEnumerable?<string> (選用)#
  
  警告
  請自行承擔使用自訂瀏覽器引數的風險，因為其中一些引數可能會破壞 Playwright 功能。
  
  要傳遞到瀏覽器實例的其他引數。Chromium 旗標清單可以在此處找到。
- Channel string? (選用)#
  
  瀏覽器發佈管道。
  
  使用 "chromium" 以選擇加入新的無頭模式。
  
  使用 "chrome"、"chrome-beta"、"chrome-dev"、"chrome-canary"、"msedge"、"msedge-beta"、"msedge-dev" 或 "msedge-canary" 以使用品牌Google Chrome 和 Microsoft Edge。
- ChromiumSandbox bool? (選用)#
  
  啟用 Chromium 沙箱。預設為 false。
- Devtools bool? (選用)#
  
  已淘汰
  改為使用偵錯工具。
  
  僅限 Chromium 是否為每個索引標籤自動開啟開發人員工具面板。如果此選項為 true，則 Headless 選項將設定為 false。
- DownloadsPath string? (選用)#
  
  如果指定，接受的下載會下載到此目錄中。否則，會建立暫存目錄，並在瀏覽器關閉時刪除。在任何情況下，下載會在建立下載所在的瀏覽器內容關閉時刪除。
- Env IDictionary?<string, string> (選用)#
  
  指定瀏覽器可見的環境變數。預設為 process.env。
- ExecutablePath string? (選用)#
  
  要執行的瀏覽器執行檔路徑，而不是套裝的執行檔。如果 ExecutablePath 是相對路徑，則會相對於目前的工作目錄解析。請注意，Playwright 僅適用於套裝的 Chromium、Firefox 或 WebKit，請自行承擔風險使用。
- FirefoxUserPrefs IDictionary?<string, [object]> (選用)#
  
  Firefox 使用者喜好設定。深入瞭解 Firefox 使用者喜好設定，請參閱 about:config。
- HandleSIGHUP bool? (選用)#
  
  在 SIGHUP 時關閉瀏覽器程序。預設為 true。
- HandleSIGINT bool? (選用)#
  
  在 Ctrl-C 時關閉瀏覽器程序。預設為 true。
- HandleSIGTERM bool? (選用)#
  
  在 SIGTERM 時關閉瀏覽器程序。預設為 true。
- Headless bool? (選用)#
  
  是否在無頭模式下執行瀏覽器。更多詳細資訊請參閱 Chromium 和 Firefox。預設為 true，除非 Devtools 選項為 true。
- IgnoreAllDefaultArgs bool? (選用)在 v1.9 中新增#
  
  如果為 true，Playwright 不會傳遞其自己的組態引數，而僅使用來自 Args 的引數。危險選項；請謹慎使用。預設為 false。
- IgnoreDefaultArgs IEnumerable?<string> (選用)#
  
  如果為 true，Playwright 不會傳遞其自己的組態引數，而僅使用來自 Args 的引數。危險選項；請謹慎使用。
- Proxy Proxy? (選用)#
  - Server string
    
    用於所有請求的 Proxy。支援 HTTP 和 SOCKS Proxy，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。簡短形式 myproxy.com:3128 被視為 HTTP Proxy。
  - Bypass string? (選用)
    
    要繞過 Proxy 的選用逗號分隔網域，例如 ".com, chromium.org, .domain.com"。
  - Username string? (選用)
    
    如果 HTTP Proxy 需要驗證，則為要使用的選用使用者名稱。
  - Password string? (選用)
    
    如果 HTTP Proxy 需要驗證，則為要使用的選用密碼。
  網路 Proxy 設定。
- SlowMo [float]? (選用)#
  
  以指定的毫秒數減慢 Playwright 運作速度。有助於您查看正在發生的事情。
- Timeout [float]? (選用)#
  
  等待瀏覽器實例啟動的最長時間 (以毫秒為單位)。預設為 30000 (30 秒)。傳遞 0 以停用逾時。
- TracesDir string? (選用)#
  
  如果指定，追蹤會儲存到此目錄中。

傳回

Browser #

LaunchPersistentContextAsync

在 v1.9 之前新增

browserType.LaunchPersistentContextAsync

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

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

用法

await BrowserType.LaunchPersistentContextAsync(userDataDir, options);

引數

userDataDir string #

使用者資料目錄的路徑，其中儲存瀏覽器工作階段資料，例如 Cookie 和本機儲存空間。更多詳細資訊請參閱 Chromium 和 Firefox。請注意，Chromium 的使用者資料目錄是 chrome://version 中看到的「設定檔路徑」的父目錄。傳遞空字串以改為使用暫存目錄。
options BrowserTypeLaunchPersistentContextOptions? (選用)
- AcceptDownloads bool? (選用)#
  
  是否自動下載所有附件。預設為 true，其中接受所有下載。
- Args IEnumerable?<string> (選用)#
  
  警告
  請自行承擔使用自訂瀏覽器引數的風險，因為其中一些引數可能會破壞 Playwright 功能。
  
  要傳遞到瀏覽器實例的其他引數。Chromium 旗標清單可以在此處找到。
- BaseURL string? (選用)#
  
  當使用 Page.GotoAsync()、Page.RouteAsync()、Page.WaitForURLAsync()、Page.RunAndWaitForRequestAsync() 或 Page.RunAndWaitForResponseAsync() 時，它會使用 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
- BypassCSP bool? (選用)#
  
  切換繞過頁面的內容安全策略。預設為 false。
- Channel string? (選用)#
  
  瀏覽器發佈管道。
  
  使用 "chromium" 以選擇加入新的無頭模式。
  
  使用 "chrome"、"chrome-beta"、"chrome-dev"、"chrome-canary"、"msedge"、"msedge-beta"、"msedge-dev" 或 "msedge-canary" 以使用品牌Google Chrome 和 Microsoft Edge。
- ChromiumSandbox bool? (選用)#
  
  啟用 Chromium 沙箱。預設為 false。
- ClientCertificates IEnumerable?<ClientCertificates> (選用)在 1.46 中新增#
  - Origin string
    
    憑證有效的確切來源。來源包含 https 協定、主機名稱和選用的埠。
  - CertPath string? (選用)
    
    PEM 格式憑證檔案的路徑。
  - Cert byte[]? (選用)
    
    PEM 格式憑證的直接值。
  - KeyPath string? (選用)
    
    PEM 格式私密金鑰檔案的路徑。
  - Key byte[]? (選用)
    
    PEM 格式私密金鑰的直接值。
  - PfxPath string? (選用)
    
    PFX 或 PKCS12 編碼私密金鑰和憑證鏈的路徑。
  - Pfx byte[]? (選用)
    
    PFX 或 PKCS12 編碼私密金鑰和憑證鏈的直接值。
  - Passphrase string? (選用)
    
    私密金鑰 (PEM 或 PFX) 的密碼。
  TLS 用戶端驗證允許伺服器請求用戶端憑證並驗證它。
  
  詳細資訊
  
  要使用的用戶端憑證陣列。每個憑證物件都必須同時具有 certPath 和 keyPath、單一 pfxPath，或其對應的直接值對等項 (cert 和 key，或 pfx)。或者，如果憑證已加密，則應提供 passphrase 屬性。origin 屬性應提供與憑證有效的請求來源的完全相符項。
  
  注意
  在 macOS 上使用 WebKit 時，存取 localhost 不會選取用戶端憑證。您可以透過將 localhost 取代為 local.playwright 來使其運作。
- ColorScheme enum ColorScheme { Light, Dark, NoPreference, Null }? (選用)#
  
  模擬 prefers-colors-scheme 媒體功能，支援的值為 'light' 和 'dark'。請參閱 Page.EmulateMediaAsync() 以取得更多詳細資訊。傳遞 'null' 會將模擬重設為系統預設值。預設為 'light'。
- DeviceScaleFactor [float]? (選用)#
  
  指定裝置縮放比例 (可以視為 dpr)。預設為 1。深入瞭解使用裝置縮放比例模擬裝置。
- Devtools bool? (選用)#
  
  已淘汰
  改為使用偵錯工具。
  
  僅限 Chromium 是否為每個索引標籤自動開啟開發人員工具面板。如果此選項為 true，則 Headless 選項將設定為 false。
- DownloadsPath string? (選用)#
  
  如果指定，接受的下載會下載到此目錄中。否則，會建立暫存目錄，並在瀏覽器關閉時刪除。在任何情況下，下載會在建立下載所在的瀏覽器內容關閉時刪除。
- Env IDictionary?<string, string> (選用)#
  
  指定瀏覽器可見的環境變數。預設為 process.env。
- ExecutablePath string? (選用)#
  
  要執行的瀏覽器執行檔路徑，而不是套裝的執行檔。如果 ExecutablePath 是相對路徑，則會相對於目前的工作目錄解析。請注意，Playwright 僅適用於套裝的 Chromium、Firefox 或 WebKit，請自行承擔風險使用。
- ExtraHTTPHeaders IDictionary?<string, string> (選用)#
  
  包含要與每個請求一起傳送的其他 HTTP 標頭的物件。預設為無。
- FirefoxUserPrefs IDictionary?<string, [object]> (選用)在 v1.40 中新增#
  
  Firefox 使用者喜好設定。深入瞭解 Firefox 使用者喜好設定，請參閱 about:config。
- ForcedColors enum ForcedColors { Active, None, Null }? (選用)#
  
  模擬 'forced-colors' 媒體功能，支援的值為 'active'、'none'。請參閱 Page.EmulateMediaAsync() 以取得更多詳細資訊。傳遞 'null' 會將模擬重設為系統預設值。預設為 'none'。
- Geolocation Geolocation? (選用)#
  - Latitude [float]
    
    介於 -90 和 90 之間的緯度。
  - Longitude [float]
    
    介於 -180 和 180 之間的經度。
  - Accuracy [float]? (選用)
    
    非負精確度值。預設為 0。
- HandleSIGHUP bool? (選用)#
  
  在 SIGHUP 時關閉瀏覽器程序。預設為 true。
- HandleSIGINT bool? (選用)#
  
  在 Ctrl-C 時關閉瀏覽器程序。預設為 true。
- HandleSIGTERM bool? (選用)#
  
  在 SIGTERM 時關閉瀏覽器程序。預設為 true。
- HasTouch bool? (選用)#
  
  指定視窗是否支援觸控事件。預設為 false。深入瞭解行動裝置模擬。
- Headless bool? (選填)#
  
  是否在無頭模式下執行瀏覽器。更多詳細資訊請參閱 Chromium 和 Firefox。預設為 true，除非 Devtools 選項為 true。
- HttpCredentials HttpCredentials? (選填)#
  - Username string
  - Password string
  - Origin string? (選填)
    
    限制在特定網域來源上發送 http 憑證 (scheme://host:port).
  - Send enum HttpCredentialsSend { Unauthorized, Always }? (選填)
    
    此選項僅適用於從對應的 APIRequestContext 發送的請求，且不影響從瀏覽器發送的請求。'always' - 每次 API 請求都會發送包含基本驗證憑證的 Authorization 標頭。'unauthorized - 僅在收到 401 (Unauthorized) 回應且帶有 WWW-Authenticate 標頭時才發送憑證。預設值為 'unauthorized'。
  用於 HTTP 驗證的憑證。如果未指定網域來源，則使用者名稱和密碼將在收到未經授權的回應時發送給任何伺服器。
- IgnoreAllDefaultArgs bool? (選用)在 v1.9 中新增#
  
  如果為 true，Playwright 將不會傳遞其自身的組態引數，而僅使用來自 Args 的引數。危險的選項；請謹慎使用。預設值為 false。
- IgnoreDefaultArgs IEnumerable?<string> (選填)#
  
  如果為 true，Playwright 將不會傳遞其自身的組態引數，而僅使用來自 Args 的引數。危險的選項；請謹慎使用。
- IgnoreHTTPSErrors bool? (選填)#
  
  是否在發送網路請求時忽略 HTTPS 錯誤。預設值為 false。
- IsMobile bool? (選填)#
  
  是否考慮 meta viewport 標籤並啟用觸控事件。isMobile 是裝置設定的一部分，因此實際上不需要手動設定。預設值為 false，且 Firefox 不支援。深入了解行動裝置模擬。
- JavaScriptEnabled bool? (選填)#
  
  是否在此環境中啟用 JavaScript。預設值為 true。深入了解停用 JavaScript。
- Locale string? (選填)#
  
  指定使用者語系，例如 en-GB、de-DE 等。語系將影響 navigator.language 值、Accept-Language 請求標頭值以及數字和日期格式規則。預設為系統預設語系。在我們的模擬指南中深入了解模擬。
- Offline bool? (選填)#
  
  是否模擬網路離線。預設值為 false。深入了解網路模擬。
- Permissions IEnumerable?<string> (選填)#
  
  要授予此環境中所有頁面的權限列表。請參閱 BrowserContext.GrantPermissionsAsync() 以取得更多詳細資訊。預設為無。
- Proxy Proxy? (選填)#
  - Server string
    
    用於所有請求的 Proxy。支援 HTTP 和 SOCKS Proxy，例如 http://myproxy.com:3128 或 socks5://myproxy.com:3128。簡短形式 myproxy.com:3128 被視為 HTTP Proxy。
  - Bypass string? (選用)
    
    要繞過 Proxy 的選用逗號分隔網域，例如 ".com, chromium.org, .domain.com"。
  - Username string? (選用)
    
    如果 HTTP Proxy 需要驗證，則為要使用的選用使用者名稱。
  - Password string? (選用)
    
    如果 HTTP Proxy 需要驗證，則為要使用的選用密碼。
  網路 Proxy 設定。
- RecordHarContent enum HarContentPolicy { Omit, Embed, Attach }? (選填)#
  
  用於控制資源內容管理的選填設定。如果指定 omit，則不會保存內容。如果指定 attach，資源將保存為個別檔案，並且所有這些檔案都將與 HAR 檔案一起封存。預設值為 embed，根據 HAR 規範將內容內嵌儲存在 HAR 檔案中。
- RecordHarMode enum HarMode { Full, Minimal }? (選填)#
  
  當設定為 minimal 時，僅記錄從 HAR 路由所需的資訊。這會省略大小、時間、頁面、Cookie、安全性和其他類型的 HAR 資訊，這些資訊在從 HAR 重新播放時不會使用。預設值為 full。
- RecordHarOmitContent bool? (選填)#
  
  用於控制是否從 HAR 中省略請求內容的選填設定。預設值為 false。
- RecordHarPath string? (選填)#
  
  啟用將所有頁面的 HAR 記錄到檔案系統上指定的 HAR 檔案中。如果未指定，則不會記錄 HAR。請務必呼叫 BrowserContext.CloseAsync() 以儲存 HAR。
- RecordHarUrlFilter|RecordHarUrlFilterRegex string? | Regex? (選填)#
- RecordVideoDir string? (選填)#
  
  啟用將所有頁面的影片記錄到指定的目錄中。如果未指定，則不會錄製影片。請務必呼叫 BrowserContext.CloseAsync() 以儲存影片。
- RecordVideoSize RecordVideoSize? (選填)#
  - Width int
    
    影片影格寬度。
  - Height int
    
    影片影格高度。
  錄製影片的尺寸。如果未指定，尺寸將等於 viewport 縮放至符合 800x800。如果未明確設定 viewport，則影片尺寸預設為 800x450。每個頁面的實際圖片將在必要時縮小以符合指定的尺寸。
- ReducedMotion enum ReducedMotion { Reduce, NoPreference, Null }? (選填)#
  
  模擬 'prefers-reduced-motion' 媒體功能，支援的值為 'reduce'、'no-preference'。請參閱 Page.EmulateMediaAsync() 以取得更多詳細資訊。傳遞 'null' 會將模擬重設為系統預設值。預設值為 'no-preference'。
- ScreenSize ScreenSize? (選填)#
  - Width int
    
    頁面寬度 (像素)。
  - Height int
    
    頁面高度 (像素)。
  模擬透過網頁內的 window.screen 取得的一致的視窗螢幕尺寸。僅在設定 ViewportSize 時使用。
- ServiceWorkers enum ServiceWorkerPolicy { Allow, Block }? (選填)#
  
  是否允許網站註冊 Service workers。預設值為 'allow'。
  - 'allow': 可以註冊 Service Workers。
  - 'block': Playwright 將會封鎖所有 Service Workers 的註冊。
- SlowMo [float]? (選填)#
  
  以指定的毫秒數減慢 Playwright 運作速度。有助於您查看正在發生的事情。
- StrictSelectors bool? (選填)#
  
  如果設定為 true，則為此環境啟用嚴格選取器模式。在嚴格選取器模式下，當有多個元素符合選取器時，所有對選取器的操作 (表示單一目標 DOM 元素) 都會擲回例外。此選項不影響任何 Locator API（Locator 永遠是嚴格模式）。預設值為 false。請參閱 Locator 以深入了解嚴格模式。
- Timeout [float]? (選填)#
  
  等待瀏覽器實例啟動的最長時間 (以毫秒為單位)。預設為 30000 (30 秒)。傳遞 0 以停用逾時。
- TimezoneId string? (選填)#
  
  變更環境的時區。請參閱 ICU's metaZones.txt 以取得支援的時區 ID 列表。預設為系統時區。
- TracesDir string? (選填)#
  
  如果指定，追蹤會儲存到此目錄中。
- UserAgent string? (選填)#
  
  在此環境中使用的特定使用者代理程式。
- ViewportSize ViewportSize? (選填)#
  - Width int
    
    頁面寬度 (像素)。
  - Height int
    
    頁面高度 (像素)。
  模擬每個頁面一致的視窗。預設為 1280x720 視窗。使用 ViewportSize.NoViewport 以停用一致的視窗模擬。深入了解視窗模擬。
  
  注意
  ViewportSize.NoViewport 值選擇退出預設設定，使視窗尺寸取決於作業系統定義的主機視窗尺寸。這會使測試的執行變得不確定。

傳回

BrowserContext #

Name

在 v1.9 之前新增

browserType.Name

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

用法

BrowserType.Name

傳回

string #

方法​

ConnectAsync​

ConnectOverCDPAsync​

ExecutablePath​

LaunchAsync​

LaunchPersistentContextAsync​

Name​

方法

ConnectAsync

ConnectOverCDPAsync

ExecutablePath

LaunchAsync

LaunchPersistentContextAsync

Name