Page

Page 提供與 Browser 中的單一分頁互動的方法，或 Chromium 中的擴充功能背景頁面。一個 Browser 實例可能有多個 Page 實例。

此範例建立一個頁面，導航到 URL，然後儲存螢幕截圖

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

class PageExamples
{
    public static async Task Run()
    {
        using var playwright = await Playwright.CreateAsync();
        await using var browser = await playwright.Webkit.LaunchAsync();
        var page = await browser.NewPageAsync();
        await page.GotoAsync("https://www.theverge.com");
        await page.ScreenshotAsync(new() { Path = "theverge.png" });
    }
}

Page 類別發出各種事件（如下所述），可以使用任何 Node 的原生 EventEmitter 方法（例如 on、once 或 removeListener）來處理這些事件。

此範例記錄單一頁面 load 事件的訊息

page.Load += (_, _) => Console.WriteLine("Page loaded!");

若要取消訂閱事件，請使用 removeListener 方法

void PageLoadHandler(object _, IPage p) {
    Console.WriteLine("Page loaded!");
};

page.Load += PageLoadHandler;
// Do some work...
page.Load -= PageLoadHandler;

方法

AddInitScriptAsync

版本 v1.9 前新增

page.AddInitScriptAsync

新增一個腳本，該腳本將在以下其中一種情況下評估

每當頁面導航時。
每當子框架附加或導航時。在這種情況下，腳本會在新附加的框架的上下文中評估。

腳本在文件建立之後但在其任何腳本執行之前評估。這對於修改 JavaScript 環境非常有用，例如，為 Math.random 播種。

用法

在頁面載入之前覆寫 Math.random 的範例

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

await Page.AddInitScriptAsync(scriptPath: "./preload.js");

注意

透過 BrowserContext.AddInitScriptAsync() 和 Page.AddInitScriptAsync() 安裝的多個腳本的評估順序未定義。

引數

script string | string #

要在瀏覽器內容中的所有頁面中評估的腳本。

傳回

void #

AddLocatorHandlerAsync

版本 v1.42 新增

page.AddLocatorHandlerAsync

在測試網頁時，有時會出現意外的覆蓋層，例如「註冊」對話方塊，並阻擋您想要自動化的動作，例如點擊按鈕。這些覆蓋層不一定以相同的方式或在同一時間顯示，這使得它們在自動化測試中難以處理。

此方法可讓您設定一個特殊的函式，稱為處理常式，當它偵測到覆蓋層可見時會啟動。處理常式的工作是移除覆蓋層，讓您的測試繼續進行，就像覆蓋層不存在一樣。

注意事項

當覆蓋層以可預測的方式顯示時，我們建議在您的測試中明確等待它，並將其作為正常測試流程的一部分解除，而不是使用 Page.AddLocatorHandlerAsync()。
Playwright 會在每次執行或重試需要可操作性檢查的動作之前，或在執行自動等待斷言檢查之前，檢查覆蓋層。當覆蓋層可見時，Playwright 會先呼叫處理常式，然後繼續執行動作/斷言。請注意，只有在您執行動作/斷言時才會呼叫處理常式 - 如果覆蓋層變得可見，但您未執行任何動作，則不會觸發處理常式。
執行處理常式後，Playwright 將確保觸發處理常式的覆蓋層不再可見。您可以透過 NoWaitAfter 選擇退出此行為。
處理常式的執行時間計入執行處理常式的動作/斷言的逾時時間。如果您的處理常式花費太長時間，可能會導致逾時。
您可以註冊多個處理常式。但是，一次只會執行一個處理常式。請確保處理常式中的動作不依賴另一個處理常式。

警告

執行處理常式將在測試期間更改您的頁面狀態。例如，它將更改目前焦點元素並移動滑鼠。請確保在處理常式之後執行的動作是獨立的，並且不依賴焦點和滑鼠狀態保持不變。

例如，考慮一個呼叫 Locator.FocusAsync()，然後呼叫 Keyboard.PressAsync() 的測試。如果您的處理常式在這兩個動作之間點擊一個按鈕，則焦點元素很可能不正確，並且按鍵將發生在意外的元素上。請改用 Locator.PressAsync() 來避免此問題。

另一個範例是一系列滑鼠動作，其中 Mouse.MoveAsync() 後面跟著 Mouse.DownAsync()。同樣地，當處理常式在這兩個動作之間執行時，滑鼠位置在滑鼠按下期間將不正確。請優先選擇獨立的動作，例如 Locator.ClickAsync()，這些動作不依賴處理常式變更狀態。

用法

關閉「註冊電子報」對話方塊的範例（當它出現時）

// Setup the handler.
await page.AddLocatorHandlerAsync(page.GetByText("Sign up to the newsletter"), async () => {
  await page.GetByRole(AriaRole.Button, new() { Name = "No thanks" }).ClickAsync();
});

// Write the test as usual.
await page.GotoAsync("https://example.com");
await page.GetByRole("button", new() { Name = "Start here" }).ClickAsync();

略過「確認您的安全詳細資訊」頁面的範例（當它顯示時）

// Setup the handler.
await page.AddLocatorHandlerAsync(page.GetByText("Confirm your security details"), async () => {
  await page.GetByRole(AriaRole.Button, new() { Name = "Remind me later" }).ClickAsync();
});

// Write the test as usual.
await page.GotoAsync("https://example.com");
await page.GetByRole("button", new() { Name = "Start here" }).ClickAsync();

每個可操作性檢查都有自訂回呼的範例。它使用始終可見的 <body> 定位器，因此在每次可操作性檢查之前都會呼叫處理常式。指定 NoWaitAfter 很重要，因為處理常式不會隱藏 <body> 元素。

// Setup the handler.
await page.AddLocatorHandlerAsync(page.Locator("body"), async () => {
  await page.EvaluateAsync("window.removeObstructionsForTestIfNeeded()");
}, new() { NoWaitAfter = true });

// Write the test as usual.
await page.GotoAsync("https://example.com");
await page.GetByRole("button", new() { Name = "Start here" }).ClickAsync();

處理常式將原始定位器作為引數。您也可以透過設定 Times 在多次調用後自動移除處理常式

await page.AddLocatorHandlerAsync(page.GetByText("Sign up to the newsletter"), async locator => {
  await locator.ClickAsync();
}, new() { Times = 1 });

引數

locator Locator #

觸發處理常式的定位器。
handler Func<Locator, Task>#

在 locator 出現後應執行的函式。此函式應移除阻擋點擊等動作的元素。
options PageAddLocatorHandlerOptions? (選用)
- NoWaitAfter bool? (選用)版本 v1.44 新增#
  
  依預設，在呼叫處理常式後，Playwright 將等待直到覆蓋層變成隱藏，然後 Playwright 才會繼續執行觸發處理常式的動作/斷言。此選項允許選擇退出此行為，以便覆蓋層可以在處理常式執行後保持可見。
- Times int? (選用)版本 v1.44 新增#
  
  指定應呼叫此處理常式的最大次數。預設為無限次。

傳回

void #

AddScriptTagAsync

版本 v1.9 前新增

page.AddScriptTagAsync

將 <script> 標籤新增到具有所需 URL 或內容的頁面中。當腳本的 onload 事件觸發或腳本內容注入到框架中時，傳回新增的標籤。

用法

await Page.AddScriptTagAsync(options);

引數

options PageAddScriptTagOptions? (選用)
- Content string? (選用)#
  
  要注入到框架中的原始 JavaScript 內容。
- Path string? (選用)#
  
  要注入到框架中的 JavaScript 檔案的路徑。如果 path 是相對路徑，則相對於目前的工作目錄解析。
- Type string? (選用)#
  
  腳本類型。使用 'module' 以載入 JavaScript ES6 模組。請參閱 script 以取得更多詳細資訊。
- Url string? (選用)#
  
  要新增的腳本的 URL。

傳回

ElementHandle #

AddStyleTagAsync

版本 v1.9 前新增

page.AddStyleTagAsync

將 <link rel="stylesheet"> 標籤新增到具有所需 URL 的頁面中，或將具有內容的 <style type="text/css"> 標籤新增到頁面中。當樣式表的 onload 事件觸發或 CSS 內容注入到框架中時，傳回新增的標籤。

用法

await Page.AddStyleTagAsync(options);

引數

options PageAddStyleTagOptions? (選用)
- Content string? (選用)#
  
  要注入到框架中的原始 CSS 內容。
- Path string? (選用)#
  
  要注入到框架中的 CSS 檔案的路徑。如果 path 是相對路徑，則相對於目前的工作目錄解析。
- Url string? (選用)#
  
  <link> 標籤的 URL。

傳回

ElementHandle #

BringToFrontAsync

版本 v1.9 前新增

page.BringToFrontAsync

將頁面帶到最前面（啟動分頁）。

用法

await Page.BringToFrontAsync();

傳回

void #

CloseAsync

版本 v1.9 前新增

page.CloseAsync

如果 RunBeforeUnload 為 false，則不執行任何卸載處理常式，並等待頁面關閉。如果 RunBeforeUnload 為 true，則該方法將執行卸載處理常式，但不會等待頁面關閉。

依預設，page.close() 不會執行 beforeunload 處理常式。

注意

如果 RunBeforeUnload 作為 true 傳遞，則可能會傳喚 beforeunload 對話方塊，應透過 Page.Dialog 事件手動處理。

用法

await Page.CloseAsync(options);

引數

options PageCloseOptions? (選用)
- Reason string? (選用)版本 v1.40 新增#
  
  要報告給頁面關閉中斷的操作的原因。
- RunBeforeUnload bool? (選用)#
  
  預設值為 false。是否執行 before unload 頁面處理常式。

傳回

void #

ContentAsync

版本 v1.9 前新增

page.ContentAsync

取得頁面的完整 HTML 內容，包括 doctype。

用法

await Page.ContentAsync();

傳回

string #

Context

版本 v1.9 前新增

page.Context

取得頁面所屬的瀏覽器內容。

用法

Page.Context

傳回

BrowserContext #

DragAndDropAsync

版本 v1.13 新增

page.DragAndDropAsync

此方法將來源元素拖曳到目標元素。它將首先移動到來源元素，執行 mousedown，然後移動到目標元素並執行 mouseup。

用法

await Page.DragAndDropAsync("#source", "#target");
// or specify exact positions relative to the top-left corners of the elements:
await Page.DragAndDropAsync("#source", "#target", new()
{
    SourcePosition = new() { X = 34, Y = 7 },
    TargetPosition = new() { X = 10, Y = 20 },
});

引數

source string #

用於搜尋要拖曳的元素的選取器。如果有多個元素符合選取器，將使用第一個元素。
target string #

用於搜尋要拖放到的元素的選取器。如果有多個元素符合選取器，將使用第一個元素。
options PageDragAndDropOptions? (選用)
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設值為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- SourcePosition SourcePosition? (選用)版本 v1.14 新增#
  - X [float]
  - Y [float]
  在此點擊來源元素，相對於元素填補方塊的左上角。如果未指定，則使用元素的某個可見點。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- TargetPosition TargetPosition? (選用)版本 v1.14 新增#
  - X [float]
  - Y [float]
  在此點擊目標元素，相對於元素填補方塊的左上角。如果未指定，則使用元素的某個可見點。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設值為 false。在不執行動作的情況下，等待元素準備好進行動作時很有用。

傳回

void #

EmulateMediaAsync

版本 v1.9 前新增

page.EmulateMediaAsync

此方法透過 media 引數變更 CSS 媒體類型，和/或使用 colorScheme 引數變更 'prefers-colors-scheme' 媒體功能。

用法

await page.EvaluateAsync("() => matchMedia('screen').matches");
// → true
await page.EvaluateAsync("() => matchMedia('print').matches");
// → false

await page.EmulateMediaAsync(new() { Media = Media.Print });
await page.EvaluateAsync("() => matchMedia('screen').matches");
// → false
await page.EvaluateAsync("() => matchMedia('print').matches");
// → true

await page.EmulateMediaAsync(new() { Media = Media.Screen });
await page.EvaluateAsync("() => matchMedia('screen').matches");
// → true
await page.EvaluateAsync("() => matchMedia('print').matches");
// → false

await page.EmulateMediaAsync(new() { ColorScheme = ColorScheme.Dark });
await page.EvaluateAsync("matchMedia('(prefers-color-scheme: dark)').matches");
// → true
await page.EvaluateAsync("matchMedia('(prefers-color-scheme: light)').matches");
// → false

引數

options PageEmulateMediaOptions? (選用)
- ColorScheme enum ColorScheme { Light, Dark, NoPreference, Null }? (選用)版本 v1.9 新增#
  
  模擬 prefers-colors-scheme 媒體功能，支援的值為 'light' 和 'dark'。傳遞 'Null' 會停用色彩配置模擬。'no-preference' 已棄用。
- ForcedColors enum ForcedColors { Active, None, Null }? (選用)版本 v1.15 新增#
- Media enum Media { Screen, Print, Null }? (選用)版本 v1.9 新增#
  
  變更頁面的 CSS 媒體類型。唯一允許的值為 'Screen'、'Print' 和 'Null'。傳遞 'Null' 會停用 CSS 媒體模擬。
- ReducedMotion enum ReducedMotion { Reduce, NoPreference, Null }? (選用)版本 v1.12 新增#
  
  模擬 'prefers-reduced-motion' 媒體功能，支援的值為 'reduce'、'no-preference'。傳遞 null 會停用減少動態效果模擬。

傳回

void #

EvaluateAsync

版本 v1.9 前新增

page.EvaluateAsync

傳回 expression 調用的值。

如果傳遞給 Page.EvaluateAsync() 的函式傳回 Promise，則 Page.EvaluateAsync() 將等待 Promise 解析並傳回其值。

如果傳遞給 Page.EvaluateAsync() 的函式傳回非 Serializable 值，則 Page.EvaluateAsync() 解析為 undefined。Playwright 也支援傳輸某些其他無法透過 JSON 序列化的值：-0、NaN、Infinity、-Infinity。

用法

將引數傳遞給 expression

var result = await page.EvaluateAsync<int>("([x, y]) => Promise.resolve(x * y)", new[] { 7, 8 });
Console.WriteLine(result);

字串也可以傳遞進來，而不是函式

Console.WriteLine(await page.EvaluateAsync<int>("1 + 2")); // prints "3"

ElementHandle 實例可以作為引數傳遞給 Page.EvaluateAsync()

var bodyHandle = await page.EvaluateAsync("document.body");
var html = await page.EvaluateAsync<string>("([body, suffix]) => body.innerHTML + suffix", new object [] { bodyHandle, "hello" });
await bodyHandle.DisposeAsync();

引數

expression string #

要在瀏覽器內容中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動調用該函式。
arg EvaluationArgument? (選用)#

要傳遞給 expression 的選用引數。

傳回

[object]#

EvaluateHandleAsync

版本 v1.9 前新增

page.EvaluateHandleAsync

傳回 expression 調用的值作為 JSHandle。

Page.EvaluateAsync() 和 Page.EvaluateHandleAsync() 之間的唯一區別在於 Page.EvaluateHandleAsync() 傳回 JSHandle。

如果傳遞給 Page.EvaluateHandleAsync() 的函式傳回 Promise，則 Page.EvaluateHandleAsync() 將等待 Promise 解析並傳回其值。

用法

// Handle for the window object.
var aWindowHandle = await page.EvaluateHandleAsync("() => Promise.resolve(window)");

字串也可以傳遞進來，而不是函式

var docHandle = await page.EvaluateHandleAsync("document"); // Handle for the `document`

JSHandle 實例可以作為引數傳遞給 Page.EvaluateHandleAsync()

var handle = await page.EvaluateHandleAsync("() => document.body");
var resultHandle = await page.EvaluateHandleAsync("([body, suffix]) => body.innerHTML + suffix", new object[] { handle, "hello" });
Console.WriteLine(await resultHandle.JsonValueAsync<string>());
await resultHandle.DisposeAsync();

引數

expression string #

要在瀏覽器內容中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動調用該函式。
arg EvaluationArgument? (選用)#

要傳遞給 expression 的選用引數。

傳回

JSHandle #

ExposeBindingAsync

版本 v1.9 前新增

page.ExposeBindingAsync

此方法在該頁面中每個框架的 window 物件上新增一個名為 name 的函式。呼叫時，該函式會執行 callback，並傳回 Promise，該 Promise 會解析為 callback 的傳回值。如果 callback 傳回 Promise，則將會等待它。

callback 函式的第一個引數包含有關呼叫者的資訊：{ browserContext: BrowserContext, page: Page, frame: Frame }。

請參閱 BrowserContext.ExposeBindingAsync() 以取得內容範圍的版本。

注意

透過 Page.ExposeBindingAsync() 安裝的函式會在導航後繼續存在。

用法

將頁面 URL 公開給頁面中所有框架的範例

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

class PageExamples
{
    public static async Task Main()
    {
        using var playwright = await Playwright.CreateAsync();
        await using var browser = await playwright.Webkit.LaunchAsync(new()
        {
            Headless = false,
        });
        var page = await browser.NewPageAsync();

        await page.ExposeBindingAsync("pageUrl", (source) => source.Page.Url);
        await page.SetContentAsync("<script>\n" +
        "  async function onClick() {\n" +
        "    document.querySelector('div').textContent = await window.pageURL();\n" +
        "  }\n" +
        "</script>\n" +
        "<button onclick=\"onClick()\">Click me</button>\n" +
        "<div></div>");

        await page.ClickAsync("button");
    }
}

引數

name string #

window 物件上函式的名稱。
callback Action<BindingSource, T, [TResult]>#

將在 Playwright 的內容中呼叫的回呼函式。
options PageExposeBindingOptions? (選用)
- Handle bool? (選用)#
  
  已棄用
  此選項將在未來版本中移除。
  
  是否將引數作為控制代碼傳遞，而不是按值傳遞。當傳遞控制代碼時，僅支援一個引數。當按值傳遞時，支援多個引數。

傳回

void #

ExposeFunctionAsync

版本 v1.9 前新增

page.ExposeFunctionAsync

此方法在頁面中每個框架的 window 物件上新增一個名為 name 的函式。呼叫時，該函式會執行 callback，並傳回 Promise，該 Promise 會解析為 callback 的傳回值。

如果 callback 傳回 Promise，則將會等待它。

請參閱 BrowserContext.ExposeFunctionAsync() 以取得內容範圍的公開函式。

注意

透過 Page.ExposeFunctionAsync() 安裝的函式會在導航後繼續存在。

用法

將 sha256 函式新增到頁面的範例

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

class PageExamples
{
    public static async Task Main()
    {
        using var playwright = await Playwright.CreateAsync();
        await using var browser = await playwright.Webkit.LaunchAsync(new()
        {
            Headless = false
        });
        var page = await browser.NewPageAsync();

        await page.ExposeFunctionAsync("sha256", (string input) =>
        {
            return Convert.ToBase64String(
                SHA256.Create().ComputeHash(System.Text.Encoding.UTF8.GetBytes(input)));
        });

        await page.SetContentAsync("<script>\n" +
        "  async function onClick() {\n" +
        "    document.querySelector('div').textContent = await window.sha256('PLAYWRIGHT');\n" +
        "  }\n" +
        "</script>\n" +
        "<button onclick=\"onClick()\">Click me</button>\n" +
        "<div></div>");

        await page.ClickAsync("button");
        Console.WriteLine(await page.TextContentAsync("div"));
    }
}

引數

name string #

window 物件上函式的名稱
callback Action<T, [TResult]>#

將在 Playwright 的內容中呼叫的回呼函式。

傳回

void #

Frame

版本 v1.9 前新增

page.Frame

傳回符合指定條件的框架。必須指定 name 或 url。

用法

var frame = page.Frame("frame-name");

var frame = page.FrameByUrl(".*domain.*");

引數

name string版本 v1.9 新增#

在 iframe 的 name 屬性中指定的框架名稱。

傳回

Frame?#

FrameByUrl

版本 v1.9 新增

page.FrameByUrl

傳回 URL 相符的框架。

用法

Page.FrameByUrl(url);

引數

url string | Regex | Func<string, bool>#

Glob 模式、Regex 模式或接收框架 url 作為 URL 物件的謂詞。

傳回

Frame?#

FrameLocator

版本 v1.17 新增

page.FrameLocator

當使用 iframe 時，您可以建立一個框架定位器，它將進入 iframe 並允許在該 iframe 中選取元素。

用法

以下程式碼片段在 id 為 my-frame 的 iframe 中找到文字為「Submit」的元素，例如 <iframe id="my-frame">

var locator = page.FrameLocator("#my-iframe").GetByText("Submit");
await locator.ClickAsync();

引數

selector string #

在解析 DOM 元素時要使用的選取器。

傳回

FrameLocator #

框架

版本 v1.9 前新增

page.Frames

頁面上所有附加框架的陣列。

用法

Page.Frames

傳回

IEnumerable<Frame>#

GetByAltText

新增於版本：v1.27

page.GetByAltText

允許透過元素的替代文字 (alt text) 定位元素。

用法

例如，此方法將透過替代文字 "Playwright logo" 找到圖片

<img alt='Playwright logo'>

await page.GetByAltText("Playwright logo").ClickAsync();

引數

text string | Regex #

用於定位元素的文字。
options PageGetByAltTextOptions? (選用)
- Exact bool? (選用)#
  
  是否尋找完全符合的項目：區分大小寫且完全相符的字串。預設為 false。當使用正規表示式定位時會被忽略。請注意，完全比對仍然會修剪空白字元。

傳回

Locator #

GetByLabel

新增於版本：v1.27

page.GetByLabel

允許透過相關聯的 <label> 或 aria-labelledby 元素的文字，或透過 aria-label 屬性來定位輸入元素。

用法

例如，此方法將在以下 DOM 中透過標籤 "Username" 和 "Password" 找到輸入框

<input aria-label="Username">
<label for="password-input">Password:</label>
<input id="password-input">

await page.GetByLabel("Username").FillAsync("john");
await page.GetByLabel("Password").FillAsync("secret");

引數

text string | Regex #

用於定位元素的文字。
options PageGetByLabelOptions? (選用)
- Exact bool? (選用)#
  
  是否尋找完全符合的項目：區分大小寫且完全相符的字串。預設為 false。當使用正規表示式定位時會被忽略。請注意，完全比對仍然會修剪空白字元。

傳回

Locator #

GetByPlaceholder

新增於版本：v1.27

page.GetByPlaceholder

允許透過 placeholder 文字定位輸入元素。

用法

例如，考慮以下 DOM 結構。

<input type="email" placeholder="name@example.com" />

您可以在透過 placeholder 文字定位輸入框後填寫內容

await page
    .GetByPlaceholder("name@example.com")
    .FillAsync("playwright@microsoft.com");

引數

text string | Regex #

用於定位元素的文字。
options PageGetByPlaceholderOptions? (選用)
- Exact bool? (選用)#
  
  是否尋找完全符合的項目：區分大小寫且完全相符的字串。預設為 false。當使用正規表示式定位時會被忽略。請注意，完全比對仍然會修剪空白字元。

傳回

Locator #

GetByRole

新增於版本：v1.27

page.GetByRole

允許透過元素的 ARIA 角色、ARIA 屬性和可存取名稱定位元素。

用法

考慮以下 DOM 結構。

<h3>Sign up</h3>
<label>
  <input type="checkbox" /> Subscribe
</label>
<br/>
<button>Submit</button>

您可以透過其隱含角色定位每個元素

await Expect(Page
    .GetByRole(AriaRole.Heading, new() { Name = "Sign up" }))
    .ToBeVisibleAsync();

await page
    .GetByRole(AriaRole.Checkbox, new() { Name = "Subscribe" })
    .CheckAsync();

await page
    .GetByRole(AriaRole.Button, new() {
        NameRegex = new Regex("submit", RegexOptions.IgnoreCase)
    })
    .ClickAsync();

引數

role enum AriaRole { Alert, Alertdialog, Application, Article, Banner, Blockquote, Button, Caption, Cell, Checkbox, Code, Columnheader, Combobox, Complementary, Contentinfo, Definition, Deletion, Dialog, Directory, Document, Emphasis, Feed, Figure, Form, Generic, Grid, Gridcell, Group, Heading, Img, Insertion, Link, List, Listbox, Listitem, Log, Main, Marquee, Math, Meter, Menu, Menubar, Menuitem, Menuitemcheckbox, Menuitemradio, Navigation, None, Note, Option, Paragraph, Presentation, Progressbar, Radio, Radiogroup, Region, Row, Rowgroup, Rowheader, Scrollbar, Search, Searchbox, Separator, Slider, Spinbutton, Status, Strong, Subscript, Superscript, Switch, Tab, Table, Tablist, Tabpanel, Term, Textbox, Time, Timer, Toolbar, Tooltip, Tree, Treegrid, Treeitem }#

必要的 ARIA 角色。
options PageGetByRoleOptions? (選用)
- Checked bool? (選用)#
  
  通常由 aria-checked 或原生 <input type=checkbox> 控制項設定的屬性。
  
  深入了解 aria-checked。
- Disabled bool? (選用)#
  
  通常由 aria-disabled 或 disabled 設定的屬性。
  
  注意
  與大多數其他屬性不同，disabled 會透過 DOM 階層繼承。深入了解 aria-disabled。
- Exact bool? (選用)新增於版本：v1.28#
  
  是否完全比對 Name|NameRegex：區分大小寫且完全相符的字串。預設為 false。Name|NameRegex 為正規表示式時會被忽略。請注意，完全比對仍然會修剪空白字元。
- Expanded bool? (選用)#
  
  通常由 aria-expanded 設定的屬性。
  
  深入了解 aria-expanded。
- IncludeHidden bool? (選用)#
  
  控制是否比對隱藏元素的選項。預設情況下，角色選擇器僅比對非隱藏元素，如 ARIA 定義。
  
  深入了解 aria-hidden。
- Level int? (選用)#
  
  數字屬性，通常用於角色 heading、listitem、row、treeitem，<h1>-<h6> 元素具有預設值。
  
  深入了解 aria-level。
- Name|NameRegex string? | Regex? (選用)#
  
  比對可存取名稱的選項。預設情況下，比對不區分大小寫並搜尋子字串，使用 Exact 控制此行為。
  
  深入了解可存取名稱。
- Pressed bool? (選用)#
  
  通常由 aria-pressed 設定的屬性。
  
  深入了解 aria-pressed。
- Selected bool? (選用)#
  
  通常由 aria-selected 設定的屬性。
  
  深入了解 aria-selected。

傳回

Locator #

詳細資訊

角色選擇器不會取代可存取性稽核和一致性測試，而是提供關於 ARIA 指導方針的早期回饋。

許多 html 元素具有隱含的已定義角色，角色選擇器可以識別它。您可以在此處找到所有支援的角色。ARIA 指導方針不建議透過將 role 和/或 aria-* 屬性設定為預設值來重複隱含角色和屬性。

GetByTestId

新增於版本：v1.27

page.GetByTestId

依測試 ID 定位元素。

用法

考慮以下 DOM 結構。

<button data-testid="directions">Itinéraire</button>

您可以依元素的測試 ID 定位它

await page.GetByTestId("directions").ClickAsync();

引數

testId string | Regex #

用於定位元素的 ID。

傳回

Locator #

詳細資訊

預設情況下，data-testid 屬性用作測試 ID。如有必要，請使用 Selectors.SetTestIdAttribute() 設定不同的測試 ID 屬性。

GetByText

新增於版本：v1.27

page.GetByText

允許定位包含給定文字的元素。

另請參閱 Locator.Filter()，它允許依另一個條件（例如可存取角色）進行比對，然後依文字內容篩選。

用法

考慮以下 DOM 結構

<div>Hello <span>world</span></div>
<div>Hello</div>

您可以依文字子字串、完全相符的字串或正規表示式進行定位

// Matches <span>
page.GetByText("world");

// Matches first <div>
page.GetByText("Hello world");

// Matches second <div>
page.GetByText("Hello", new() { Exact = true });

// Matches both <div>s
page.GetByText(new Regex("Hello"));

// Matches second <div>
page.GetByText(new Regex("^hello$", RegexOptions.IgnoreCase));

引數

text string | Regex #

用於定位元素的文字。
options PageGetByTextOptions? (選用)
- Exact bool? (選用)#
  
  是否尋找完全符合的項目：區分大小寫且完全相符的字串。預設為 false。當使用正規表示式定位時會被忽略。請注意，完全比對仍然會修剪空白字元。

傳回

Locator #

詳細資訊

即使使用完全比對，依文字比對也總是會正規化空白字元。例如，它會將多個空格變成一個，將換行符號變成空格，並忽略開頭和結尾的空白字元。

類型為 button 和 submit 的輸入元素會依其 value 而非文字內容進行比對。例如，依文字 "Log in" 定位會比對 <input type=button value="Log in">。

GetByTitle

新增於版本：v1.27

page.GetByTitle

允許透過元素的 title 屬性定位元素。

用法

考慮以下 DOM 結構。

<span title='Issues count'>25 issues</span>

您可以在透過標題文字定位問題計數後檢查它

await Expect(Page.GetByTitle("Issues count")).toHaveText("25 issues");

引數

text string | Regex #

用於定位元素的文字。
options PageGetByTitleOptions? (選用)
- Exact bool? (選用)#
  
  是否尋找完全符合的項目：區分大小寫且完全相符的字串。預設為 false。當使用正規表示式定位時會被忽略。請注意，完全比對仍然會修剪空白字元。

傳回

Locator #

GoBackAsync

版本 v1.9 前新增

page.GoBackAsync

傳回主要資源回應。在多次重新導向的情況下，導航將解析為最後一次重新導向的回應。如果無法返回，則傳回 null。

導航到瀏覽歷史記錄中的上一頁。

用法

await Page.GoBackAsync(options);

引數

options PageGoBackOptions? (選用)
- Timeout [float]? (選用)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選用)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - 不建議使用，當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，而是依靠 Web 斷言來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。

傳回

Response?#

GoForwardAsync

版本 v1.9 前新增

page.GoForwardAsync

傳回主要資源回應。在多次重新導向的情況下，導航將解析為最後一次重新導向的回應。如果無法前進，則傳回 null。

導航到瀏覽歷史記錄中的下一頁。

用法

await Page.GoForwardAsync(options);

引數

options PageGoForwardOptions? (選用)
- Timeout [float]? (選用)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選用)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - 不建議使用，當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，而是依靠 Web 斷言來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。

傳回

Response?#

GotoAsync

版本 v1.9 前新增

page.GotoAsync

傳回主要資源回應。在多次重新導向的情況下，導航將解析為第一次非重新導向的回應。

如果發生以下情況，此方法將拋出錯誤

發生 SSL 錯誤（例如，在自我簽署憑證的情況下）。
目標 URL 無效。
在導航期間超過逾時。
遠端伺服器沒有回應或無法連線。
主要資源載入失敗。

當遠端伺服器傳回任何有效的 HTTP 狀態碼時，此方法不會拋出錯誤，包括 404 "Not Found" 和 500 "Internal Server Error"。此類回應的狀態碼可以透過呼叫 Response.Status 取得。

注意

此方法會拋出錯誤或傳回主要資源回應。唯一的例外是導航到 about:blank 或導航到具有不同雜湊的相同 URL，這將會成功並傳回 null。

注意

Headless 模式不支援導航到 PDF 文件。請參閱上游問題。

用法

await Page.GotoAsync(url, options);

引數

url string #

頁面要導航到的 URL。URL 應包含 scheme，例如 https://。當透過內容選項提供 BaseURL 且傳遞的 URL 是路徑時，它會透過 new URL() 建構函式合併。
options PageGotoOptions? (選用)
- Referer string? (選用)#
  
  Referer 標頭值。如果提供，它將優先於 Page.SetExtraHTTPHeadersAsync() 設定的 referer 標頭值。
- Timeout [float]? (選用)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選用)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - 不建議使用，當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，而是依靠 Web 斷言來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。

傳回

Response?#

IsClosed

版本 v1.9 前新增

page.IsClosed

指示頁面是否已關閉。

用法

Page.IsClosed

傳回

bool #

Locator

版本 v1.14 新增

page.Locator

此方法傳回元素定位器，可用於對此頁面/框架執行操作。定位器在執行操作之前立即解析為元素，因此對同一定位器的一系列操作實際上可以在不同的 DOM 元素上執行。如果這些操作之間的 DOM 結構已變更，則會發生這種情況。

深入了解定位器.

用法

Page.Locator(selector, options);

引數

selector string #

在解析 DOM 元素時要使用的選取器。
options PageLocatorOptions? (選用)
- Has Locator? (選用)#
  
  將此方法的结果縮小到包含與此相對定位器相符的元素的結果。例如，具有 text=Playwright 的 article 會比對 <article><div>Playwright</div></article>。
  
  內部定位器必須相對於外部定位器，並且從外部定位器比對開始查詢，而不是文件根目錄。例如，您可以在 <article><content><div>Playwright</div></content></article> 中找到具有 div 的 content。但是，尋找具有 article div 的 content 將會失敗，因為內部定位器必須是相對的，並且不應使用 content 外部的任何元素。
  
  請注意，外部和內部定位器必須屬於同一個框架。內部定位器不得包含 FrameLocator。
- HasNot Locator? (選用)新增於版本：v1.33#
  
  比對不包含與內部定位器相符的元素的元素。內部定位器會針對外部定位器進行查詢。例如，不具有 div 的 article 會比對 <article><span>Playwright</span></article>。
  
  請注意，外部和內部定位器必須屬於同一個框架。內部定位器不得包含 FrameLocator。
- HasNotText|HasNotTextRegex string? | Regex? (選用)新增於版本：v1.33#
  
  比對在某處內部（可能在子元素或後代元素中）不包含指定文字的元素。當傳遞 string 時，比對不區分大小寫並搜尋子字串。
- HasText|HasTextRegex string? | Regex? (選用)#
  
  比對在某處內部（可能在子元素或後代元素中）包含指定文字的元素。當傳遞 string 時，比對不區分大小寫並搜尋子字串。例如，"Playwright" 會比對 <article><div>Playwright</div></article>。

傳回

Locator #

MainFrame

版本 v1.9 前新增

page.MainFrame

頁面的主要框架。頁面保證有一個在導航期間持續存在的主要框架。

用法

Page.MainFrame

傳回

Frame #

OpenerAsync

版本 v1.9 前新增

page.OpenerAsync

傳回彈出頁面的開啟器，其他頁面則傳回 null。如果開啟器已關閉，則傳回 null。

用法

await Page.OpenerAsync();

傳回

Page?#

PauseAsync

版本 v1.9 新增

page.PauseAsync

暫停腳本執行。Playwright 將停止執行腳本，並等待使用者按下頁面覆蓋中的「繼續」按鈕，或在 DevTools 控制台中呼叫 playwright.resume()。

使用者可以在暫停時檢查選擇器或執行手動步驟。「繼續」將從暫停的位置繼續執行原始腳本。

注意

此方法需要以 Headed 模式啟動 Playwright，並使用 falsy Headless 選項。

用法

await Page.PauseAsync();

傳回

void #

PdfAsync

版本 v1.9 前新增

page.PdfAsync

傳回 PDF 緩衝區。

page.pdf() 使用 print CSS 媒體產生頁面的 PDF。若要使用 screen 媒體產生 PDF，請在呼叫 page.pdf() 之前呼叫 Page.EmulateMediaAsync()

注意

預設情況下，page.pdf() 產生的 PDF 會修改列印的顏色。使用 -webkit-print-color-adjust 屬性強制呈現精確的顏色。

用法

// Generates a PDF with 'screen' media type
await page.EmulateMediaAsync(new() { Media = Media.Screen });
await page.PdfAsync(new() { Path = "page.pdf" });

Width、Height 和 Margin 選項接受標記單位的數值。未標記單位的值將被視為像素。

一些範例

page.pdf({width: 100}) - 列印寬度設定為 100 像素
page.pdf({width: '100px'}) - 列印寬度設定為 100 像素
page.pdf({width: '10cm'}) - 列印寬度設定為 10 公分。

所有可能的單位為

px - 像素
in - 英吋
cm - 公分
mm - 公釐

Format 選項為

Letter：8.5 英吋 x 11 英吋
Legal：8.5 英吋 x 14 英吋
Tabloid：11 英吋 x 17 英吋
Ledger：17 英吋 x 11 英吋
A0：33.1 英吋 x 46.8 英吋
A1：23.4 英吋 x 33.1 英吋
A2：16.54 英吋 x 23.4 英吋
A3：11.7 英吋 x 16.54 英吋
A4：8.27 英吋 x 11.7 英吋
A5：5.83 英吋 x 8.27 英吋
A6：4.13 英吋 x 5.83 英吋

注意

HeaderTemplate 和 FooterTemplate 標記有以下限制：> 1. 範本內的 Script 標籤不會被評估。 > 2. 頁面樣式在範本內不可見。

引數

options PagePdfOptions? (選用)
- DisplayHeaderFooter bool? (選用)#
  
  顯示頁首和頁尾。預設為 false。
- FooterTemplate string? (選用)#
  
  列印頁尾的 HTML 範本。應使用與 HeaderTemplate 相同的格式。
- Format string? (選用)#
  
  紙張格式。如果設定，則優先於 Width 或 Height 或 Format 選項。預設為 'Letter'。
- HeaderTemplate string? (選用)#
  
  列印頁首的 HTML 範本。應為有效的 HTML 標記，並使用以下類別將列印值注入其中
  - 'date' 格式化的列印日期
  - 'title' 文件標題
  - 'url' 文件位置
  - 'pageNumber' 目前頁碼
  - 'totalPages' 文件中的總頁數
- Height string? (選用)#
  
  紙張高度，接受標記單位的數值。
- Landscape bool? (選用)#
  
  紙張方向。預設為 false。
- Margin Margin? (選用)#
  - Top string? (選用)
    
    上邊距，接受標記單位的數值。預設為 0。
  - Right string? (選用)
    
    右邊距，接受標記單位的數值。預設為 0。
  - Bottom string? (選用)
    
    下邊距，接受標記單位的數值。預設為 0。
  - Left string? (選用)
    
    左邊距，接受標記單位的數值。預設為 0。
  紙張邊距，預設為無。
- Outline bool? (選用)版本 v1.42 新增#
  
  是否將文件外框嵌入 PDF 中。預設為 false。
- PageRanges string? (選用)#
  
  要列印的紙張範圍，例如 '1-5, 8, 11-13'。預設為空字串，表示列印所有頁面。
- Path string? (選用)#
  
  要將 PDF 儲存到的檔案路徑。如果 Path 是相對路徑，則會相對於目前的工作目錄解析。如果未提供路徑，則 PDF 將不會儲存到磁碟。
- PreferCSSPageSize bool? (選用)#
  
  優先考慮頁面中宣告的任何 CSS @page 大小，而不是 Width 和 Height 或 Format 選項中宣告的大小。預設為 false，這會縮放內容以適合紙張大小。
- PrintBackground bool? (選用)#
  
  列印背景圖形。預設為 false。
- Scale [float]? (選用)#
  
  網頁呈現的縮放比例。預設為 1。縮放比例必須介於 0.1 和 2 之間。
- Tagged bool? (選用)版本 v1.42 新增#
  
  是否產生標記 (可存取) 的 PDF。預設為 false。
- Width string? (選用)#
  
  紙張寬度，接受標示單位的數值。

傳回

byte[]#

ReloadAsync

版本 v1.9 前新增

page.ReloadAsync

此方法會重新載入目前頁面，如同使用者觸發瀏覽器重新整理一樣。傳回主要資源回應。若發生多次重新導向，導航將會以最後一次重新導向的回應來解析。

用法

await Page.ReloadAsync(options);

引數

options PageReloadOptions? (選填)
- Timeout [float]? (選填)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選填)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - 不建議使用，當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，而是依靠 Web 斷言來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。

傳回

Response?#

RemoveLocatorHandlerAsync

版本 v1.44 新增

page.RemoveLocatorHandlerAsync

移除由 Page.AddLocatorHandlerAsync() 為特定 locator 新增的所有 locator 處理常式。

用法

await Page.RemoveLocatorHandlerAsync(locator);

引數

locator Locator #

傳遞至 Page.AddLocatorHandlerAsync() 的 Locator。

傳回

void #

RequestGCAsync

新增於：v1.48

page.RequestGCAsync

請求頁面執行垃圾回收。請注意，無法保證所有無法存取的物件都會被回收。

這對於協助偵測記憶體洩漏很有用。例如，如果您的頁面有一個可能洩漏的大型物件 'suspect'，您可以使用 WeakRef 來檢查它是否沒有洩漏。

// 1. In your page, save a WeakRef for the "suspect".
await Page.EvaluateAsync("globalThis.suspectWeakRef = new WeakRef(suspect)");
// 2. Request garbage collection.
await Page.RequestGCAsync();
// 3. Check that weak ref does not deref to the original object.
Assert.True(await Page.EvaluateAsync("!globalThis.suspectWeakRef.deref()"));

用法

await Page.RequestGCAsync();

傳回

void #

RouteAsync

版本 v1.9 前新增

page.RouteAsync

路由提供修改頁面發出的網路請求的功能。

一旦啟用路由，每個符合 URL 模式的請求都會停滯，除非它被繼續、滿足或中止。

注意

如果回應是重新導向，則只會針對第一個 URL 呼叫處理常式。

注意

Page.RouteAsync() 不會攔截 Service Worker 攔截的請求。請參閱此問題。我們建議在使用請求攔截時停用 Service Worker，方法是將 ServiceWorkers 設定為 'block'。

注意

Page.RouteAsync() 不會攔截彈出頁面的第一個請求。請改用 BrowserContext.RouteAsync()。

用法

一個簡單的處理常式範例，會中止所有圖片請求

var page = await browser.NewPageAsync();
await page.RouteAsync("**/*.{png,jpg,jpeg}", async r => await r.AbortAsync());
await page.GotoAsync("https://www.microsoft.com");

或使用 regex 模式的相同程式碼片段

var page = await browser.NewPageAsync();
await page.RouteAsync(new Regex("(\\.png$)|(\\.jpg$)"), async r => await r.AbortAsync());
await page.GotoAsync("https://www.microsoft.com");

可以檢查請求以決定路由動作。例如，模擬所有包含某些 post 資料的請求，並將所有其他請求保持原樣

await page.RouteAsync("/api/**", async r =>
{
  if (r.Request.PostData.Contains("my-string"))
      await r.FulfillAsync(new() { Body = "mocked-data" });
  else
      await r.ContinueAsync();
});

當請求同時符合頁面路由和瀏覽器內容路由的處理常式時，頁面路由優先於瀏覽器內容路由（使用 BrowserContext.RouteAsync() 設定）。

若要移除具有其處理常式的路由，您可以使用 Page.UnrouteAsync()。

注意

啟用路由會停用 http 快取。

引數

url string | Regex | Func<string, bool>#

Glob 模式、regex 模式或謂詞，接收 URL 以在路由時進行比對。當透過內容選項提供 BaseURL 且傳遞的 URL 是路徑時，它會透過 new URL() 建構函式合併。
handler Action<Route>#

用於路由請求的處理函式。
options PageRouteOptions? (選填)
- Times int? (選用)版本 v1.15 新增#
  
  路由應使用的頻率。預設情況下，每次都會使用。

傳回

void #

RouteFromHARAsync

新增於：v1.23

page.RouteFromHARAsync

如果指定，則頁面中發出的網路請求將從 HAR 檔案提供。請閱讀更多關於從 HAR 重新播放的資訊。

Playwright 不會從 HAR 檔案提供 Service Worker 攔截的請求。請參閱此問題。我們建議在使用請求攔截時停用 Service Worker，方法是將 ServiceWorkers 設定為 'block'。

用法

await Page.RouteFromHARAsync(har, options);

引數

har string #

具有預先錄製網路資料的 HAR 檔案路徑。如果 path 是相對路徑，則會相對於目前工作目錄解析。
options PageRouteFromHAROptions? (選填)
- NotFound enum HarNotFound { Abort, Fallback }? (選填)#
  - 如果設定為 'abort'，則 HAR 檔案中找不到的任何請求都會被中止。
  - 如果設定為 'fallback'，則遺失的請求將會傳送到網路。
  預設值為 abort。
- Update bool? (選填)#
  
  如果指定，則使用實際網路資訊更新給定的 HAR，而不是從檔案提供服務。當呼叫 BrowserContext.CloseAsync() 時，檔案會寫入磁碟。
- UpdateContent enum RouteFromHarUpdateContentPolicy { Embed, Attach }? (選填)新增於：v1.32#
  
  用於控制資源內容管理的選填設定。如果指定 attach，資源會以個別檔案或 ZIP 封存檔中的條目形式保存。如果指定 embed，則內容會內嵌儲存在 HAR 檔案中。
- UpdateMode enum HarMode { Full, Minimal }? (選填)新增於：v1.32#
  
  當設定為 minimal 時，僅記錄從 HAR 路由所需的資訊。這會省略大小、時間、頁面、Cookie、安全性以及其他類型的 HAR 資訊，這些資訊在從 HAR 重新播放時不會使用。預設值為 minimal。
- Url|UrlRegex string? | Regex? (選填)#
  
  用於比對請求 URL 的 Glob 模式、正則表達式或謂詞。只有 URL 符合模式的請求才會從 HAR 檔案提供服務。如果未指定，則所有請求都會從 HAR 檔案提供服務。

傳回

void #

RouteWebSocketAsync

新增於：v1.48

page.RouteWebSocketAsync

此方法允許修改頁面建立的 WebSocket 連線。

請注意，只有在此方法呼叫後建立的 WebSocket 才會被路由。建議在導航頁面之前呼叫此方法。

用法

以下是一個簡單模擬的範例，它會回應單一訊息。請參閱 WebSocketRoute 以取得更多詳細資訊和範例。

await page.RouteWebSocketAsync("/ws", ws => {
  ws.OnMessage(frame => {
    if (frame.Text == "request")
      ws.Send("response");
  });
});

引數

url string | Regex | Func<string, bool>#

只有 URL 符合此模式的 WebSocket 才会被路由。字串模式可以是相對於 BaseURL 內容選項的相對路徑。
handler Action<WebSocketRoute>#

用於路由 WebSocket 的處理函式。

傳回

void #

RunAndWaitForConsoleMessageAsync

版本 v1.9 新增

page.RunAndWaitForConsoleMessageAsync

執行動作並等待頁面中記錄 ConsoleMessage。如果提供謂詞，它會將 ConsoleMessage 值傳遞到 predicate 函式中，並等待 predicate(message) 傳回真值。如果在 Page.Console 事件觸發之前頁面關閉，將會擲回錯誤。

用法

await Page.RunAndWaitForConsoleMessageAsync(action, options);

引數

action Func<Task>版本 v1.12 新增#

觸發事件的動作。
options PageRunAndWaitForConsoleMessageOptions? (選填)
- Predicate Func<ConsoleMessage?, bool> (選填)#
  
  接收 ConsoleMessage 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

ConsoleMessage #

WaitForConsoleMessageAsync

版本 v1.9 新增

page.WaitForConsoleMessageAsync

用法

await Page.WaitForConsoleMessageAsync(action, options);

引數

options PageRunAndWaitForConsoleMessageOptions? (選填)
- Predicate Func<ConsoleMessage?, bool> (選填)#
  
  接收 ConsoleMessage 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

ConsoleMessage #

RunAndWaitForDownloadAsync

版本 v1.9 新增

page.RunAndWaitForDownloadAsync

執行動作並等待新的 Download。如果提供謂詞，它會將 Download 值傳遞到 predicate 函式中，並等待 predicate(download) 傳回真值。如果在下載事件觸發之前頁面關閉，將會擲回錯誤。

用法

await Page.RunAndWaitForDownloadAsync(action, options);

引數

action Func<Task>版本 v1.12 新增#

觸發事件的動作。
options PageRunAndWaitForDownloadOptions? (選填)
- Predicate Func<Download?, bool> (選填)#
  
  接收 Download 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

Download #

WaitForDownloadAsync

版本 v1.9 新增

page.WaitForDownloadAsync

用法

await Page.WaitForDownloadAsync(action, options);

引數

options PageRunAndWaitForDownloadOptions? (選填)
- Predicate Func<Download?, bool> (選填)#
  
  接收 Download 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

Download #

RunAndWaitForFileChooserAsync

版本 v1.9 新增

page.RunAndWaitForFileChooserAsync

執行動作並等待新的 FileChooser 被建立。如果提供謂詞，它會將 FileChooser 值傳遞到 predicate 函式中，並等待 predicate(fileChooser) 傳回真值。如果在檔案選擇器開啟之前頁面關閉，將會擲回錯誤。

用法

await Page.RunAndWaitForFileChooserAsync(action, options);

引數

action Func<Task>版本 v1.12 新增#

觸發事件的動作。
options PageRunAndWaitForFileChooserOptions? (選填)
- Predicate Func<FileChooser?, bool> (選填)#
  
  接收 FileChooser 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

FileChooser #

WaitForFileChooserAsync

版本 v1.9 新增

page.WaitForFileChooserAsync

用法

await Page.WaitForFileChooserAsync(action, options);

引數

options PageRunAndWaitForFileChooserOptions? (選填)
- Predicate Func<FileChooser?, bool> (選填)#
  
  接收 FileChooser 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

FileChooser #

版本 v1.9 新增

page.RunAndWaitForPopupAsync

執行動作並等待彈出視窗 Page。如果提供謂詞，它會將 [Popup] 值傳遞到 predicate 函式中，並等待 predicate(page) 傳回真值。如果在彈出視窗事件觸發之前頁面關閉，將會擲回錯誤。

用法

await Page.RunAndWaitForPopupAsync(action, options);

引數

action Func<Task>版本 v1.12 新增#

觸發事件的動作。
options PageRunAndWaitForPopupOptions? (選填)
- Predicate Func<Page?, bool> (選填)#
  
  接收 Page 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

Page #

版本 v1.9 新增

page.WaitForPopupAsync

用法

await Page.WaitForPopupAsync(action, options);

引數

options PageRunAndWaitForPopupOptions? (選填)
- Predicate Func<Page?, bool> (選填)#
  
  接收 Page 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

Page #

RunAndWaitForRequestAsync

版本 v1.9 前新增

page.RunAndWaitForRequestAsync

等待符合的請求並傳回它。請參閱等待事件以取得更多關於事件的詳細資訊。

用法

// Waits for the next request with the specified url.
await page.RunAndWaitForRequestAsync(async () =>
{
    await page.GetByText("trigger request").ClickAsync();
}, "http://example.com/resource");

// Alternative way with a predicate.
await page.RunAndWaitForRequestAsync(async () =>
{
    await page.GetByText("trigger request").ClickAsync();
}, request => request.Url == "https://example.com" && request.Method == "GET");

引數

action Func<Task>版本 v1.12 新增#

觸發事件的動作。
urlOrPredicate string | Regex | Func<Request, bool>#

請求 URL 字串、regex 或謂詞，接收 Request 物件。當透過內容選項提供 BaseURL 且傳遞的 URL 是路徑時，它會透過 new URL() 建構函式合併。
options PageRunAndWaitForRequestOptions? (選填)
- Timeout [float]? (選填)#
  
  最大等待時間，以毫秒為單位，預設值為 30 秒，傳遞 0 以停用超時。預設值可以使用 Page.SetDefaultTimeout() 方法變更。

傳回

Request #

WaitForRequestAsync

版本 v1.9 前新增

page.WaitForRequestAsync

等待符合的請求並傳回它。請參閱等待事件以取得更多關於事件的詳細資訊。

用法

// Waits for the next request with the specified url.
await page.RunAndWaitForRequestAsync(async () =>
{
    await page.GetByText("trigger request").ClickAsync();
}, "http://example.com/resource");

// Alternative way with a predicate.
await page.RunAndWaitForRequestAsync(async () =>
{
    await page.GetByText("trigger request").ClickAsync();
}, request => request.Url == "https://example.com" && request.Method == "GET");

引數

urlOrPredicate string | Regex | Func<Request, bool>#

請求 URL 字串、regex 或謂詞，接收 Request 物件。當透過內容選項提供 BaseURL 且傳遞的 URL 是路徑時，它會透過 new URL() 建構函式合併。
options PageRunAndWaitForRequestOptions? (選填)
- Timeout [float]? (選填)#
  
  最大等待時間，以毫秒為單位，預設值為 30 秒，傳遞 0 以停用超時。預設值可以使用 Page.SetDefaultTimeout() 方法變更。

傳回

Request #

RunAndWaitForRequestFinishedAsync

版本 v1.12 新增

page.RunAndWaitForRequestFinishedAsync

執行動作並等待 Request 完成載入。如果提供謂詞，它會將 Request 值傳遞到 predicate 函式中，並等待 predicate(request) 傳回真值。如果在 Page.RequestFinished 事件觸發之前頁面關閉，將會擲回錯誤。

用法

await Page.RunAndWaitForRequestFinishedAsync(action, options);

引數

action Func<Task>#

觸發事件的動作。
options PageRunAndWaitForRequestFinishedOptions? (選填)
- Predicate Func<Request?, bool> (選填)#
  
  接收 Request 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

Request #

WaitForRequestFinishedAsync

版本 v1.12 新增

page.WaitForRequestFinishedAsync

用法

await Page.WaitForRequestFinishedAsync(action, options);

引數

options PageRunAndWaitForRequestFinishedOptions? (選填)
- Predicate Func<Request?, bool> (選填)#
  
  接收 Request 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

Request #

RunAndWaitForResponseAsync

版本 v1.9 前新增

page.RunAndWaitForResponseAsync

傳回符合的回應。請參閱等待事件以取得更多關於事件的詳細資訊。

用法

// Waits for the next response with the specified url.
await page.RunAndWaitForResponseAsync(async () =>
{
    await page.GetByText("trigger response").ClickAsync();
}, "http://example.com/resource");

// Alternative way with a predicate.
await page.RunAndWaitForResponseAsync(async () =>
{
    await page.GetByText("trigger response").ClickAsync();
}, response => response.Url == "https://example.com" && response.Status == 200 && response.Request.Method == "GET");

引數

action Func<Task>版本 v1.12 新增#

觸發事件的動作。
urlOrPredicate string | Regex | Func<Response, bool>#

請求 URL 字串、regex 或謂詞，接收 Response 物件。當透過內容選項提供 BaseURL 且傳遞的 URL 是路徑時，它會透過 new URL() 建構函式合併。
options PageRunAndWaitForResponseOptions? (選填)
- Timeout [float]? (選填)#
  
  最大等待時間，以毫秒為單位，預設值為 30 秒，傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

Response #

WaitForResponseAsync

版本 v1.9 前新增

page.WaitForResponseAsync

傳回符合的回應。請參閱等待事件以取得更多關於事件的詳細資訊。

用法

// Waits for the next response with the specified url.
await page.RunAndWaitForResponseAsync(async () =>
{
    await page.GetByText("trigger response").ClickAsync();
}, "http://example.com/resource");

// Alternative way with a predicate.
await page.RunAndWaitForResponseAsync(async () =>
{
    await page.GetByText("trigger response").ClickAsync();
}, response => response.Url == "https://example.com" && response.Status == 200 && response.Request.Method == "GET");

引數

urlOrPredicate string | Regex | Func<Response, bool>#

請求 URL 字串、regex 或謂詞，接收 Response 物件。當透過內容選項提供 BaseURL 且傳遞的 URL 是路徑時，它會透過 new URL() 建構函式合併。
options PageRunAndWaitForResponseOptions? (選填)
- Timeout [float]? (選填)#
  
  最大等待時間，以毫秒為單位，預設值為 30 秒，傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

Response #

RunAndWaitForWebSocketAsync

版本 v1.9 新增

page.RunAndWaitForWebSocketAsync

執行動作並等待新的 WebSocket。如果提供謂詞，它會將 WebSocket 值傳遞到 predicate 函式中，並等待 predicate(webSocket) 傳回真值。如果在 WebSocket 事件觸發之前頁面關閉，將會擲回錯誤。

用法

await Page.RunAndWaitForWebSocketAsync(action, options);

引數

action Func<Task>版本 v1.12 新增#

觸發事件的動作。
options PageRunAndWaitForWebSocketOptions? (選填)
- Predicate Func<WebSocket?, bool> (選填)#
  
  接收 WebSocket 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

WebSocket #

WaitForWebSocketAsync

版本 v1.9 新增

page.WaitForWebSocketAsync

用法

await Page.WaitForWebSocketAsync(action, options);

引數

options PageRunAndWaitForWebSocketOptions? (選填)
- Predicate Func<WebSocket?, bool> (選填)#
  
  接收 WebSocket 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

WebSocket #

RunAndWaitForWorkerAsync

版本 v1.9 新增

page.RunAndWaitForWorkerAsync

執行動作並等待新的 Worker。如果提供謂詞，它會將 Worker 值傳遞到 predicate 函式中，並等待 predicate(worker) 傳回真值。如果在 worker 事件觸發之前頁面關閉，將會擲回錯誤。

用法

await Page.RunAndWaitForWorkerAsync(action, options);

引數

action Func<Task>版本 v1.12 新增#

觸發事件的動作。
options PageRunAndWaitForWorkerOptions? (選填)
- Predicate Func<Worker?, bool> (選填)#
  
  接收 Worker 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

Worker #

WaitForWorkerAsync

版本 v1.9 新增

page.WaitForWorkerAsync

用法

await Page.WaitForWorkerAsync(action, options);

引數

options PageRunAndWaitForWorkerOptions? (選填)
- Predicate Func<Worker?, bool> (選填)#
  
  接收 Worker 物件，並在等待應該解析時解析為真值。
- Timeout [float]? (選填)#
  
  等待的最長時間，以毫秒為單位。預設值為 30000（30 秒）。傳遞 0 以停用超時。預設值可以使用 BrowserContext.SetDefaultTimeout() 變更。

傳回

Worker #

ScreenshotAsync

版本 v1.9 前新增

page.ScreenshotAsync

傳回包含擷取螢幕截圖的緩衝區。

用法

await Page.ScreenshotAsync(options);

引數

options PageScreenshotOptions? (選填)
- Animations enum ScreenshotAnimations { Disabled, Allow }? (選填)#
  
  當設定為 "disabled" 時，會停止 CSS 動畫、CSS 過渡和 Web Animations。動畫會根據其持續時間獲得不同的處理方式
  - 有限動畫會快速轉到完成，因此它們會觸發 transitionend 事件。
  - 無限動畫會取消到初始狀態，然後在螢幕截圖後重新播放。
  預設值為 "allow"，這會讓動畫保持不變。
- Caret enum ScreenshotCaret { Hide, Initial }? (選填)#
  
  當設定為 "hide" 時，螢幕截圖將會隱藏文字游標。當設定為 "initial" 時，文字游標行為將不會變更。預設值為 "hide"。
- Clip Clip? (選填)#
  - X [float]
    
    剪裁區域左上角的 x 座標
  - Y [float]
    
    剪裁區域左上角的 y 座標
  - Width [float]
    
    剪裁區域的寬度
  - Height [float]
    
    剪裁區域的高度
  指定結果影像剪裁的物件。
- FullPage bool? (選填)#
  
  當為 true 時，會擷取整個可捲動頁面的螢幕截圖，而不是目前可見的視窗。預設值為 false。
- Mask IEnumerable?<Locator> (選填)#
  
  指定在擷取螢幕截圖時應遮罩的 locator。遮罩元素將會被粉紅色方塊 #FF00FF（由 MaskColor 自訂）覆蓋，完全覆蓋其邊界框。
- MaskColor string? (選填)新增於：v1.35#
  
  指定遮罩元素的覆蓋方塊顏色，以 CSS 顏色格式。預設顏色為粉紅色 #FF00FF。
- OmitBackground bool? (選填)#
  
  隱藏預設白色背景，並允許擷取具有透明度的螢幕截圖。不適用於 jpeg 影像。預設值為 false。
- Path string? (選填)#
  
  儲存影像的檔案路徑。螢幕截圖類型將從檔案副檔名推斷。如果 Path 是相對路徑，則會相對於目前工作目錄解析。如果未提供路徑，則影像不會儲存到磁碟。
- Quality int? (選填)#
  
  影像品質，介於 0-100 之間。不適用於 png 影像。
- Scale enum ScreenshotScale { Css, Device }? (選填)#
  
  當設定為 "css" 時，螢幕截圖的每個像素將對應到頁面上的一個 css 像素。對於高 dpi 裝置，這將使螢幕截圖保持較小。使用 "device" 選項將為每個裝置像素產生一個像素，因此高 dpi 裝置的螢幕截圖將會大兩倍甚至更大。
  
  預設值為 "device"。
- Style string? (選填)新增於：v1.41#
  
  在製作螢幕截圖時套用的樣式表文字。您可以在此處隱藏動態元素、使元素不可見或變更其屬性，以協助您建立可重複的螢幕截圖。此樣式表會穿透 Shadow DOM 並套用至內部框架。
- Timeout [float]? (選填)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Type enum ScreenshotType { Png, Jpeg }? (選填)#
  
  指定螢幕截圖類型，預設為 png。

傳回

byte[]#

SetContentAsync

版本 v1.9 前新增

page.SetContentAsync

此方法在內部呼叫 document.write()，繼承其所有特定特性和行為。

用法

await Page.SetContentAsync(html, options);

引數

html string #

要指派給頁面的 HTML 標記。
options PageSetContentOptions? (選用)
- Timeout [float]? (選用)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選用)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - 不建議使用，當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，而是依靠 Web 斷言來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。

傳回

void #

版本 v1.9 前新增

page.SetDefaultNavigationTimeout

此設定將變更以下方法和相關快捷方式的預設最大導航時間

注意

Page.SetDefaultNavigationTimeout() 的優先順序高於 Page.SetDefaultTimeout()、BrowserContext.SetDefaultTimeout() 和 BrowserContext.SetDefaultNavigationTimeout()。

用法

Page.SetDefaultNavigationTimeout(timeout);

引數

timeout [float]#

最大導航時間，以毫秒為單位

SetDefaultTimeout

版本 v1.9 前新增

page.SetDefaultTimeout

此設定將變更所有接受 timeout 選項之方法的預設最大時間。

注意

Page.SetDefaultNavigationTimeout() 的優先順序高於 Page.SetDefaultTimeout()。

用法

Page.SetDefaultTimeout(timeout);

引數

timeout [float]#

最大時間，以毫秒為單位。傳遞 0 以停用逾時。

SetExtraHTTPHeadersAsync

版本 v1.9 前新增

page.SetExtraHTTPHeadersAsync

額外的 HTTP 標頭將與頁面啟動的每個請求一起傳送。

注意

Page.SetExtraHTTPHeadersAsync() 不保證傳出請求中標頭的順序。

用法

await Page.SetExtraHTTPHeadersAsync(headers);

引數

headers IDictionary<string, string>#

包含要與每個請求一起傳送之額外 HTTP 標頭的物件。所有標頭值都必須是字串。

傳回

void #

SetViewportSizeAsync

版本 v1.9 前新增

page.SetViewportSizeAsync

在單一瀏覽器中有多個頁面的情況下，每個頁面都可以有自己的 viewport 大小。但是，Browser.NewContextAsync() 允許一次為內容中的所有頁面設定 viewport 大小（以及更多）。

Page.SetViewportSizeAsync() 將調整頁面大小。許多網站不希望手機變更大小，因此您應該在導航至頁面之前設定 viewport 大小。Page.SetViewportSizeAsync() 也會重設 screen 大小，如果您需要更好地控制這些屬性，請使用帶有 screen 和 viewport 參數的 Browser.NewContextAsync()。

用法

var page = await browser.NewPageAsync();
await page.SetViewportSizeAsync(640, 480);
await page.GotoAsync("https://www.microsoft.com");

引數

width intAdded in: v1.10#

頁面寬度，以像素為單位。
height intAdded in: v1.10#

頁面高度，以像素為單位。

傳回

void #

TitleAsync

版本 v1.9 前新增

page.TitleAsync

傳回頁面的標題。

用法

await Page.TitleAsync();

傳回

string #

UnrouteAsync

版本 v1.9 前新增

page.UnrouteAsync

移除使用 Page.RouteAsync() 建立的路由。當未指定 handler 時，移除 url 的所有路由。

用法

await Page.UnrouteAsync(url, handler);

引數

url string | Regex | Func<string, bool>#

在路由時要比對的 glob 模式、Regex 模式或接收 URL 的謂詞。
handler Action<Route?> (選用)#

用於路由請求的選用處理常式函式。

傳回

void #

UnrouteAllAsync

新增於：v1.41

page.UnrouteAllAsync

移除使用 Page.RouteAsync() 和 Page.RouteFromHARAsync() 建立的所有路由。

用法

await Page.UnrouteAllAsync(options);

引數

options PageUnrouteAllOptions? (選用)
- Behavior enum UnrouteBehavior { Wait, IgnoreErrors, Default }? (選用)#
  
  指定是否等待已在執行的處理常式，以及在它們擲回錯誤時該怎麼做
  - 'default' - 不等待目前的處理常式呼叫（如果有的話）完成，如果未路由的處理常式擲回錯誤，則可能會導致未處理的錯誤
  - 'wait' - 等待目前的處理常式呼叫（如果有的話）完成
  - 'ignoreErrors' - 不等待目前的處理常式呼叫（如果有的話）完成，在取消路由後，處理常式擲回的所有錯誤都會被靜默捕獲

傳回

void #

Url

版本 v1.9 前新增

page.Url

用法

Page.Url

傳回

string #

Video

版本 v1.9 前新增

page.Video

與此頁面關聯的 Video 物件。

用法

Page.Video

傳回

Video?#

ViewportSize

版本 v1.9 前新增

page.ViewportSize

用法

Page.ViewportSize

傳回

ViewportSize?#
- width int
  
  頁面寬度，以像素為單位。
- height int
  
  頁面高度，以像素為單位。

WaitForFunctionAsync

版本 v1.9 前新增

page.WaitForFunctionAsync

當 expression 傳回 truthy 值時傳回。它解析為 truthy 值的 JSHandle。

用法

Page.WaitForFunctionAsync() 可用於觀察 viewport 大小變更

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

class FrameExamples
{
  public static async Task WaitForFunction()
  {
    using var playwright = await Playwright.CreateAsync();
    await using var browser = await playwright.Webkit.LaunchAsync();
    var page = await browser.NewPageAsync();
    await page.SetViewportSizeAsync(50, 50);
    await page.MainFrame.WaitForFunctionAsync("window.innerWidth < 100");
  }
}

若要將引數傳遞至 Page.WaitForFunctionAsync() 函式的述詞

var selector = ".foo";
await page.WaitForFunctionAsync("selector => !!document.querySelector(selector)", selector);

引數

expression string #

要在瀏覽器內容中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動調用該函式。
arg EvaluationArgument? (選用)#

要傳遞至 expression 的選用引數。
options PageWaitForFunctionOptions? (選用)
- PollingInterval [float]? (選用)#
  
  如果指定，則會將其視為函數將執行的間隔，以毫秒為單位。依預設，如果未指定選項，則 expression 會在 requestAnimationFrame 回呼中執行。
- Timeout [float]? (選用)#
  
  最大等待時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

JSHandle #

WaitForLoadStateAsync

版本 v1.9 前新增

page.WaitForLoadStateAsync

當達到所需的載入狀態時傳回。

當頁面達到所需的載入狀態時，預設為 load 時，此方法會解析。當呼叫此方法時，導航必須已提交。如果目前的文檔已達到所需狀態，則會立即解析。

注意

大多數情況下，不需要此方法，因為 Playwright 會在每個動作之前自動等待。

用法

await page.GetByRole(AriaRole.Button).ClickAsync(); // Click triggers navigation.
await page.WaitForLoadStateAsync(); // The promise resolves after 'load' event.

var popup = await page.RunAndWaitForPopupAsync(async () =>
{
    await page.GetByRole(AriaRole.Button).ClickAsync(); // click triggers the popup
});
// Wait for the "DOMContentLoaded" event.
await popup.WaitForLoadStateAsync(LoadState.DOMContentLoaded);
Console.WriteLine(await popup.TitleAsync()); // popup is ready to use.

引數

state enum LoadState { Load, DOMContentLoaded, NetworkIdle }? (選用)#

要等待的選用載入狀態，預設為 load。如果載入目前文檔時已達到該狀態，則該方法會立即解析。可以是下列其中之一
- 'load' - 等待 load 事件觸發。
- 'domcontentloaded' - 等待 DOMContentLoaded 事件觸發。
- 'networkidle' - 不建議使用 等待直到至少 500 毫秒沒有網路連線。請勿使用此方法進行測試，而是依賴網路斷言來評估就緒狀態。
options PageWaitForLoadStateOptions? (選用)
- Timeout [float]? (選用)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

WaitForURLAsync

Added in: v1.11

page.WaitForURLAsync

等待主框架導航至給定的 URL。

用法

await page.ClickAsync("a.delayed-navigation"); // clicking the link will indirectly cause a navigation
await page.WaitForURLAsync("**/target.html");

引數

url string | Regex | Func<string, bool>#

在等待導航時要比對的 glob 模式、Regex 模式或接收 URL 的謂詞。請注意，如果參數是不帶萬用字元的字串，則此方法將等待導航到與該字串完全相同的 URL。
options PageWaitForURLOptions? (選用)
- Timeout [float]? (選用)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選用)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - 不建議使用，當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，而是依靠 Web 斷言來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。

傳回

void #

Workers

版本 v1.9 前新增

page.Workers

此方法傳回與頁面關聯的所有專用 WebWorkers。

注意

這不包含 ServiceWorkers

用法

Page.Workers

傳回

IEnumerable<Worker>#

Properties

APIRequest

Added in: v1.16

page.APIRequest

與此頁面關聯的 API 測試輔助程式。此方法傳回與頁面內容上的 BrowserContext.APIRequest 相同的執行個體。請參閱 BrowserContext.APIRequest 以取得更多詳細資訊。

用法

Page.APIRequest

Type

APIRequestContext

Clock

Added in: v1.45

page.Clock

Playwright 具有模擬時鐘和時間流逝的能力。

用法

Page.Clock

Type

Clock

Keyboard

版本 v1.9 前新增

page.Keyboard

用法

Page.Keyboard

Type

Keyboard

Mouse

版本 v1.9 前新增

page.Mouse

用法

Page.Mouse

Type

Mouse

Touchscreen

版本 v1.9 前新增

page.Touchscreen

用法

Page.Touchscreen

Type

Touchscreen

Events

event Close

版本 v1.9 前新增

page.event Close

當頁面關閉時發出。

用法

Page.Close += async (_, page) => {};

事件資料

Page

event Console

版本 v1.9 前新增

page.event Console

當頁面內的 JavaScript 呼叫其中一個 console API 方法時發出，例如 console.log 或 console.dir。

傳遞到 console.log 中的引數可在 ConsoleMessage 事件處理常式引數中使用。

用法

page.Console += async (_, msg) =>
{
    foreach (var arg in msg.Args)
        Console.WriteLine(await arg.JsonValueAsync<object>());
};

await page.EvaluateAsync("console.log('hello', 5, { foo: 'bar' })");

事件資料

ConsoleMessage

event Crash

版本 v1.9 前新增

page.event Crash

當頁面崩潰時發出。如果瀏覽器頁面嘗試分配過多記憶體，則可能會崩潰。當頁面崩潰時，正在進行和後續的操作將會擲回。

處理崩潰最常見的方式是捕獲例外

try {
  // Crash might happen during a click.
  await page.ClickAsync("button");
  // Or while waiting for an event.
  await page.WaitForPopup();
} catch (PlaywrightException e) {
  // When the page crashes, exception message contains "crash".
}

用法

Page.Crash += async (_, page) => {};

事件資料

Page

event Dialog

版本 v1.9 前新增

page.event Dialog

當出現 JavaScript 對話方塊時發出，例如 alert、prompt、confirm 或 beforeunload。接聽程式必須 Dialog.AcceptAsync() 或 Dialog.DismissAsync() 對話方塊 - 否則頁面將會凍結等待對話方塊，而點擊等動作將永遠不會完成。

用法

page.RequestFailed += (_, request) =>
{
    Console.WriteLine(request.Url + " " + request.Failure);
};

注意

當沒有 Page.Dialog 或 BrowserContext.Dialog 接聽程式存在時，所有對話方塊都會自動關閉。

事件資料

Dialog

event DOMContentLoaded

版本 v1.9 新增

page.event DOMContentLoaded

當 JavaScript DOMContentLoaded 事件分派時發出。

用法

Page.DOMContentLoaded += async (_, page) => {};

事件資料

Page

event Download

版本 v1.9 前新增

page.event Download

當附件下載開始時發出。使用者可以透過傳遞的 Download 執行個體存取下載內容的基本檔案操作。

用法

Page.Download += async (_, download) => {};

事件資料

Download

event FileChooser

版本 v1.9 新增

page.event FileChooser

當應該出現檔案選擇器時發出，例如在點擊 <input type=file> 之後。Playwright 可以透過使用 FileChooser.SetFilesAsync() 設定輸入檔案來回應它，然後可以上傳這些檔案。

page.FileChooser += (_, fileChooser) =>
{
    fileChooser.SetFilesAsync(@"C:\temp\myfile.pdf");
};

用法

Page.FileChooser += async (_, fileChooser) => {};

事件資料

FileChooser

event FrameAttached

版本 v1.9 新增

page.event FrameAttached

當附加框架時發出。

用法

Page.FrameAttached += async (_, frame) => {};

事件資料

Frame

event FrameDetached

版本 v1.9 新增

page.event FrameDetached

當卸離框架時發出。

用法

Page.FrameDetached += async (_, frame) => {};

事件資料

Frame

event FrameNavigated

版本 v1.9 新增

page.event FrameNavigated

當框架導航到新的 URL 時發出。

用法

Page.FrameNavigated += async (_, frame) => {};

事件資料

Frame

event Load

版本 v1.9 前新增

page.event Load

當 JavaScript load 事件分派時發出。

用法

Page.Load += async (_, page) => {};

事件資料

Page

event PageError

版本 v1.9 新增

page.event PageError

當頁面內發生未捕獲的例外狀況時發出。

// Log all uncaught errors to the terminal
page.PageError += (_, exception) =>
{
  Console.WriteLine("Uncaught exception: " + exception);
};

用法

Page.PageError += async (_, value) => {};

事件資料

string

版本 v1.9 前新增

page.event Popup

當頁面開啟新的索引標籤或視窗時發出。除了 BrowserContext.Page 之外，還會發出此事件，但僅適用於與此頁面相關的彈出視窗。

頁面可用的最早時刻是它導航到初始 URL 時。例如，當使用 window.open('http://example.com') 開啟彈出視窗時，當對 "http://example.com" 的網路請求完成且其回應已開始在彈出視窗中載入時，將會觸發此事件。如果您想要路由/監聽此網路請求，請分別使用 BrowserContext.RouteAsync() 和 BrowserContext.Request，而不是 Page 上的類似方法。

var popup = await page.RunAndWaitForPopupAsync(async () =>
{
    await page.GetByText("open the popup").ClickAsync();
});
Console.WriteLine(await popup.EvaluateAsync<string>("location.href"));

注意

使用 Page.WaitForLoadStateAsync() 等待頁面達到特定狀態（在大多數情況下您不需要它）。

用法

Page.Popup += async (_, page) => {};

事件資料

Page

event Request

版本 v1.9 前新增

page.event Request

當頁面發出請求時發出。request 物件是唯讀的。為了攔截和變更請求，請參閱 Page.RouteAsync() 或 BrowserContext.RouteAsync()。

用法

Page.Request += async (_, request) => {};

事件資料

Request

event RequestFailed

版本 v1.9 新增

page.event RequestFailed

當請求失敗時發出，例如逾時。

注意

HTTP 錯誤回應（例如 404 或 503）從 HTTP 的角度來看仍然是成功的回應，因此請求將使用 Page.RequestFinished 事件完成，而不是 Page.RequestFailed。只有當用戶端無法從伺服器取得 HTTP 回應時，例如由於網路錯誤 net::ERR_FAILED，請求才被視為失敗。

用法

Page.RequestFailed += async (_, request) => {};

事件資料

Request

event RequestFinished

版本 v1.9 新增

page.event RequestFinished

當請求在下載回應主體後成功完成時發出。對於成功的回應，事件順序為 request、response 和 requestfinished。

用法

Page.RequestFinished += async (_, request) => {};

事件資料

Request

event Response

版本 v1.9 前新增

page.event Response

當接收到請求的 response 狀態和標頭時發出。對於成功的回應，事件順序為 request、response 和 requestfinished。

用法

Page.Response += async (_, response) => {};

事件資料

Response

event WebSocket

版本 v1.9 新增

page.event WebSocket

當傳送 WebSocket 請求時發出。

用法

Page.WebSocket += async (_, webSocket) => {};

事件資料

WebSocket

event Worker

版本 v1.9 前新增

page.event Worker

當頁面衍生出專用的 WebWorker 時發出。

用法

Page.Worker += async (_, worker) => {};

事件資料

Worker

Deprecated

Accessibility

版本 v1.9 前新增

page.Accessibility

已棄用

不建議使用此屬性。如果您需要測試頁面可訪問性，請使用其他程式庫，例如 Axe。請參閱我們的 Node.js 指南以了解與 Axe 的整合。

用法

Page.Accessibility

Type

Accessibility

CheckAsync

版本 v1.9 前新增

page.CheckAsync

不建議使用

請改用基於定位器的 Locator.CheckAsync()。閱讀更多關於定位器的資訊。

此方法會檢查符合 selector 的元素，方法是執行下列步驟

尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM。
確保符合的元素是核取方塊或單選輸入。如果不是，此方法會擲回例外。如果元素已選取，則此方法會立即傳回。
等待對符合元素進行可操作性檢查，除非設定 Force 選項。如果元素在檢查期間卸離，則會重試整個動作。
如有需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 在元素的中心點擊。
確保元素現在已選取。如果沒有，此方法會擲回例外。

當所有步驟組合在指定的 Timeout 期間未完成時，此方法會擲回 TimeoutError。傳遞零逾時會停用此功能。

用法

await Page.CheckAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageCheckOptions? (選用)
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設值為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)Added in: v1.11#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距方塊的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)Added in: v1.11#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設值為 false。在不執行動作的情況下，等待元素準備好進行動作時很有用。

傳回

void #

ClickAsync

版本 v1.9 前新增

page.ClickAsync

不建議使用

請改用基於定位器的 Locator.ClickAsync()。閱讀更多關於定位器的資訊。

此方法會點擊符合 selector 的元素，方法是執行下列步驟

尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM。
等待對符合元素進行可操作性檢查，除非設定 Force 選項。如果元素在檢查期間卸離，則會重試整個動作。
如有需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 在元素的中心點擊，或指定的 Position。
等待啟動的導航成功或失敗，除非設定 NoWaitAfter 選項。

當所有步驟組合在指定的 Timeout 期間未完成時，此方法會擲回 TimeoutError。傳遞零逾時會停用此功能。

用法

await Page.ClickAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageClickOptions? (選用)
- Button enum MouseButton { Left, Right, Middle }? (選用)#
  
  預設為 left。
- ClickCount int? (選用)#
  
  預設為 1。請參閱 UIEvent.detail。
- Delay [float]? (選用)#
  
  mousedown 和 mouseup 之間等待的時間，以毫秒為單位。預設為 0。
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設值為 false。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (選用)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項在未來將預設為 true。
  
  啟動導航的操作會等待這些導航發生，以及頁面開始載入。您可以透過設定此旗標來選擇不等待。您只有在導航至無法存取的頁面等特殊情況下才需要此選項。預設值為 false。
- Position Position? (選用)#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距方塊的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)Added in: v1.11#
  
  設定後，此方法只會執行可操作性檢查，並跳過動作。預設值為 false。適用於等待元素準備好執行動作，但無需實際執行動作的情況。請注意，鍵盤 modifiers 無論 trial 設定為何都會被按下，以便測試僅在按下這些按鍵時才可見的元素。

傳回

void #

DblClickAsync

版本 v1.9 前新增

page.DblClickAsync

不建議使用

請改用基於 locator 的 Locator.DblClickAsync()。閱讀更多關於 locators 的資訊。

此方法透過執行以下步驟，在符合 selector 的元素上執行雙擊

尋找符合 selector 的元素。如果沒有符合的元素，則等待直到符合的元素附加到 DOM。
等待對相符元素進行可操作性檢查，除非設定了 Force 選項。如果在檢查期間元素被分離，則會重試整個動作。
如有需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 在元素的中心或指定的 Position 執行雙擊。

當所有步驟組合起來在指定的 Timeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

注意

page.dblclick() 會分派兩個 click 事件和一個 dblclick 事件。

用法

await Page.DblClickAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageDblClickOptions? (選用)
- Button enum MouseButton { Left, Right, Middle }? (選用)#
  
  預設為 left。
- Delay [float]? (選用)#
  
  mousedown 和 mouseup 之間等待的時間，以毫秒為單位。預設為 0。
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設值為 false。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (選用)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距方塊的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)Added in: v1.11#
  
  設定後，此方法只會執行可操作性檢查，並跳過動作。預設值為 false。適用於等待元素準備好執行動作，但無需實際執行動作的情況。請注意，鍵盤 modifiers 無論 trial 設定為何都會被按下，以便測試僅在按下這些按鍵時才可見的元素。

傳回

void #

DispatchEventAsync

版本 v1.9 前新增

page.DispatchEventAsync

不建議使用

請改用基於 locator 的 Locator.DispatchEventAsync()。閱讀更多關於 locators 的資訊。

以下程式碼片段會在元素上分派 click 事件。無論元素的顯示狀態為何，都會分派 click。這相當於呼叫 element.click()。

用法

await page.DispatchEventAsync("button#submit", "click");

在底層，它會根據給定的 type 建立事件的執行個體，使用 eventInit 屬性初始化它，並在元素上分派它。事件預設為 composed、cancelable 和 bubble。

由於 eventInit 是事件特定的，請參閱事件文件以取得初始屬性清單

如果您希望將即時物件傳遞到事件中，您也可以將 JSHandle 指定為屬性值

var dataTransfer = await page.EvaluateHandleAsync("() => new DataTransfer()");
await page.DispatchEventAsync("#source", "dragstart", new { dataTransfer });

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
type string #

DOM 事件類型："click"、"dragstart" 等。
eventInit EvaluationArgument? (選用)#

選用的事件特定初始化屬性。
options PageDispatchEventOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

EvalOnSelectorAsync

版本 v1.9 新增

page.EvalOnSelectorAsync

不建議使用

此方法不會等待元素通過可操作性檢查，因此可能會導致測試不穩定。請改用 Locator.EvaluateAsync()、其他 Locator 輔助方法或 web-first assertions。

此方法會在頁面中尋找符合指定 selector 的元素，並將其作為第一個引數傳遞給 expression。如果沒有元素符合 selector，則此方法會拋出錯誤。傳回 expression 的值。

如果 expression 傳回 Promise，則 Page.EvalOnSelectorAsync() 將會等待 Promise 解析並傳回其值。

用法

var searchValue = await page.EvalOnSelectorAsync<string>("#search", "el => el.value");
var preloadHref = await page.EvalOnSelectorAsync<string>("link[rel=preload]", "el => el.href");
var html = await page.EvalOnSelectorAsync(".main-container", "(e, suffix) => e.outerHTML + suffix", "hello");

引數

selector string #

要查詢的 selector。
expression string #

要在瀏覽器內容中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動調用該函式。
arg EvaluationArgument? (選用)#

要傳遞給 expression 的選用引數。
options PageEvalOnSelectorOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

傳回

[object]#

EvalOnSelectorAllAsync

版本 v1.9 新增

page.EvalOnSelectorAllAsync

不建議使用

在大多數情況下，Locator.EvaluateAllAsync()、其他 Locator 輔助方法和 web-first assertions 會做得更好。

此方法會在頁面中尋找符合指定 selector 的所有元素，並將相符元素的陣列作為第一個引數傳遞給 expression。傳回 expression 呼叫的結果。

如果 expression 傳回 Promise，則 Page.EvalOnSelectorAllAsync() 將會等待 Promise 解析並傳回其值。

用法

var divsCount = await page.EvalOnSelectorAllAsync<bool>("div", "(divs, min) => divs.length >= min", 10);

引數

selector string #

要查詢的 selector。
expression string #

要在瀏覽器內容中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動調用該函式。
arg EvaluationArgument? (選用)#

要傳遞給 expression 的選用引數。

傳回

[object]#

FillAsync

版本 v1.9 前新增

page.FillAsync

不建議使用

請改用基於 locator 的 Locator.FillAsync()。閱讀更多關於 locators 的資訊。

此方法會等待符合 selector 的元素，等待可操作性檢查，將焦點放在元素上，填寫元素，並在填寫後觸發 input 事件。請注意，您可以傳遞空字串來清除輸入欄位。

如果目標元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法會拋出錯誤。但是，如果元素位於具有相關聯 control 的 <label> 元素內，則會改為填寫 control。

若要傳送細微的鍵盤事件，請使用 Locator.PressSequentiallyAsync()。

用法

await Page.FillAsync(selector, value, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
value string #

要為 <input>、<textarea> 或 [contenteditable] 元素填寫的值。
options PageFillOptions? (選用)
- Force bool? (選用)版本 v1.13 新增#
  
  是否略過可操作性檢查。預設值為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

FocusAsync

版本 v1.9 前新增

page.FocusAsync

不建議使用

請改用基於 locator 的 Locator.FocusAsync()。閱讀更多關於 locators 的資訊。

此方法會擷取具有 selector 的元素並將其設為焦點。如果沒有符合 selector 的元素，此方法會等待直到符合的元素出現在 DOM 中。

用法

await Page.FocusAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageFocusOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

GetAttributeAsync

版本 v1.9 前新增

page.GetAttributeAsync

不建議使用

請改用基於 locator 的 Locator.GetAttributeAsync()。閱讀更多關於 locators 的資訊。

傳回元素屬性值。

用法

await Page.GetAttributeAsync(selector, name, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
name string #

要取得值的屬性名稱。
options PageGetAttributeOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

string?#

HoverAsync

版本 v1.9 前新增

page.HoverAsync

不建議使用

請改用基於 locator 的 Locator.HoverAsync()。閱讀更多關於 locators 的資訊。

此方法透過執行以下步驟，將滑鼠懸停在符合 selector 的元素上

尋找符合 selector 的元素。如果沒有符合的元素，則等待直到符合的元素附加到 DOM。
等待對相符元素進行可操作性檢查，除非設定了 Force 選項。如果在檢查期間元素被分離，則會重試整個動作。
如有需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 將滑鼠懸停在元素的中心或指定的 Position 上。

當所有步驟組合起來在指定的 Timeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

用法

await Page.HoverAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageHoverOptions? (選用)
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設值為 false。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (選用)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- NoWaitAfter bool? (選用)新增於版本：v1.28#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距方塊的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)Added in: v1.11#
  
  設定後，此方法只會執行可操作性檢查，並跳過動作。預設值為 false。適用於等待元素準備好執行動作，但無需實際執行動作的情況。請注意，鍵盤 modifiers 無論 trial 設定為何都會被按下，以便測試僅在按下這些按鍵時才可見的元素。

傳回

void #

InnerHTMLAsync

版本 v1.9 前新增

page.InnerHTMLAsync

不建議使用

請改用基於 locator 的 Locator.InnerHTMLAsync()。閱讀更多關於 locators 的資訊。

傳回 element.innerHTML。

用法

await Page.InnerHTMLAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageInnerHTMLOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

string #

InnerTextAsync

版本 v1.9 前新增

page.InnerTextAsync

不建議使用

請改用基於 locator 的 Locator.InnerTextAsync()。閱讀更多關於 locators 的資訊。

傳回 element.innerText。

用法

await Page.InnerTextAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageInnerTextOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

string #

InputValueAsync

版本 v1.13 新增

page.InputValueAsync

不建議使用

請改用基於 locator 的 Locator.InputValueAsync()。閱讀更多關於 locators 的資訊。

傳回所選取 <input> 或 <textarea> 或 <select> 元素的 input.value。

針對非輸入元素拋出例外。但是，如果元素位於具有相關聯 control 的 <label> 元素內，則傳回 control 的值。

用法

await Page.InputValueAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageInputValueOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

string #

IsCheckedAsync

版本 v1.9 前新增

page.IsCheckedAsync

不建議使用

請改用基於 locator 的 Locator.IsCheckedAsync()。閱讀更多關於 locators 的資訊。

傳回元素是否已勾選。如果元素不是核取方塊或單選輸入，則會拋出例外。

用法

await Page.IsCheckedAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageIsCheckedOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

bool #

IsDisabledAsync

版本 v1.9 前新增

page.IsDisabledAsync

不建議使用

請改用基於 locator 的 Locator.IsDisabledAsync()。閱讀更多關於 locators 的資訊。

傳回元素是否已停用，與已啟用相反。

用法

await Page.IsDisabledAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageIsDisabledOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

bool #

IsEditableAsync

版本 v1.9 前新增

page.IsEditableAsync

不建議使用

請改用基於 locator 的 Locator.IsEditableAsync()。閱讀更多關於 locators 的資訊。

傳回元素是否為可編輯。

用法

await Page.IsEditableAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageIsEditableOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

bool #

IsEnabledAsync

版本 v1.9 前新增

page.IsEnabledAsync

不建議使用

請改用基於 locator 的 Locator.IsEnabledAsync()。閱讀更多關於 locators 的資訊。

傳回元素是否為已啟用。

用法

await Page.IsEnabledAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageIsEnabledOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

bool #

IsHiddenAsync

版本 v1.9 前新增

page.IsHiddenAsync

不建議使用

請改用基於 locator 的 Locator.IsHiddenAsync()。閱讀更多關於 locators 的資訊。

傳回元素是否隱藏，與可見相反。不符合任何元素的 selector 會被視為隱藏。

用法

await Page.IsHiddenAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageIsHiddenOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  已棄用
  此選項會被忽略。Page.IsHiddenAsync() 不會等待元素變成隱藏，並立即傳回。

傳回

bool #

IsVisibleAsync

版本 v1.9 前新增

page.IsVisibleAsync

不建議使用

請改用基於 locator 的 Locator.IsVisibleAsync()。閱讀更多關於 locators 的資訊。

傳回元素是否可見。不符合任何元素的 selector 會被視為不可見。

用法

await Page.IsVisibleAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageIsVisibleOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  已棄用
  此選項會被忽略。Page.IsVisibleAsync() 不會等待元素變成可見，並立即傳回。

傳回

bool #

PressAsync

版本 v1.9 前新增

page.PressAsync

不建議使用

請改用基於 locator 的 Locator.PressAsync()。閱讀更多關於 locators 的資訊。

將焦點放在元素上，然後使用 Keyboard.DownAsync() 和 Keyboard.UpAsync()。

key 可以指定預期的 keyboardEvent.key 值或產生文字的單一字元。可以在此處找到 key 值的超集。按鍵範例包括

F1 - F12、Digit0- Digit9、KeyA- KeyZ、Backquote、Minus、Equal、Backslash、Backspace、Tab、Delete、Escape、ArrowDown、End、Enter、Home、Insert、PageDown、PageUp、ArrowRight、ArrowUp 等。

也支援以下修改捷徑：Shift、Control、Alt、Meta、ShiftLeft、ControlOrMeta。ControlOrMeta 在 Windows 和 Linux 上解析為 Control，在 macOS 上解析為 Meta。

按住 Shift 將會輸入與大寫 key 對應的文字。

如果 key 是單一字元，則區分大小寫，因此值 a 和 A 將會產生不同的各自文字。

也支援諸如 key: "Control+o"、key: "Control++ 或 key: "Control+Shift+T" 之類的捷徑。當使用修飾鍵指定時，修飾鍵會被按下並保持按住狀態，同時按下後續的按鍵。

用法

var page = await browser.NewPageAsync();
await page.GotoAsync("https://keycode.info");
await page.PressAsync("body", "A");
await page.ScreenshotAsync(new() { Path = "A.png" });
await page.PressAsync("body", "ArrowLeft");
await page.ScreenshotAsync(new() { Path = "ArrowLeft.png" });
await page.PressAsync("body", "Shift+O");
await page.ScreenshotAsync(new() { Path = "O.png" });

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
key string #

要按下按鍵的名稱或要產生的字元，例如 ArrowLeft 或 a。
options PagePressOptions? (選用)
- Delay [float]? (選用)#
  
  keydown 和 keyup 之間等待的時間，以毫秒為單位。預設為 0。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項在未來將預設為 true。
  
  啟動導航的操作會等待這些導航發生，以及頁面開始載入。您可以透過設定此旗標來選擇不等待。您只有在導航至無法存取的頁面等特殊情況下才需要此選項。預設值為 false。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

QuerySelectorAsync

版本 v1.9 新增

page.QuerySelectorAsync

不建議使用

請改用基於 Locator 的 Page.Locator()。閱讀更多關於 locator 的資訊。

此方法在頁面中尋找符合指定 selector 的元素。如果沒有元素符合 selector，則傳回值會解析為 null。若要等待頁面上的元素，請使用 Locator.WaitForAsync()。

用法

await Page.QuerySelectorAsync(selector, options);

引數

selector string #

要查詢的 selector。
options PageQuerySelectorOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。

傳回

ElementHandle?#

QuerySelectorAllAsync

版本 v1.9 新增

page.QuerySelectorAllAsync

不建議使用

請改用基於 Locator 的 Page.Locator()。閱讀更多關於 locator 的資訊。

此方法在頁面中尋找所有符合指定 selector 的元素。如果沒有元素符合 selector，則傳回值會解析為 []。

用法

await Page.QuerySelectorAllAsync(selector);

引數

selector string #

要查詢的 selector。

傳回

IEnumerable<ElementHandle>#

版本 v1.9 前新增

page.RunAndWaitForNavigationAsync

已棄用

此方法本質上是競爭性的，請改用 Page.WaitForURLAsync()。

等待主框架導航並傳回主要資源回應。如果發生多次重新導向，導航將使用最後一次重新導向的回應來解析。如果導航到不同的錨點或由於 History API 使用而導航，則導航將解析為 null。

用法

當頁面導航到新的 URL 或重新載入時，此方法會解析。當您執行會間接導致頁面導航的程式碼時，此方法非常有用。例如，點擊目標具有從 setTimeout 觸發導航的 onclick 處理常式。請考慮以下範例

await page.RunAndWaitForNavigationAsync(async () =>
{
    // This action triggers the navigation after a timeout.
    await page.GetByText("Navigate after timeout").ClickAsync();
});

// The method continues after navigation has finished

注意

使用 History API 變更 URL 也被視為導航。

引數

action Func<Task>版本 v1.12 新增#

觸發事件的動作。
options PageRunAndWaitForNavigationOptions? (選用)
- Timeout [float]? (選用)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Url|UrlRegex|UrlFunc string? | Regex? | Func<string?, bool> (選用)#
  
  在等待導航時要比對的 glob 模式、Regex 模式或接收 URL 的謂詞。請注意，如果參數是不帶萬用字元的字串，則此方法將等待導航到與該字串完全相同的 URL。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選用)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - 不建議使用，當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，而是依靠 Web 斷言來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。

傳回

Response?#

版本 v1.9 前新增

page.WaitForNavigationAsync

已棄用

此方法本質上是競爭性的，請改用 Page.WaitForURLAsync()。

用法

await page.RunAndWaitForNavigationAsync(async () =>
{
    // This action triggers the navigation after a timeout.
    await page.GetByText("Navigate after timeout").ClickAsync();
});

// The method continues after navigation has finished

注意

使用 History API 變更 URL 也被視為導航。

引數

options PageRunAndWaitForNavigationOptions? (選用)
- Timeout [float]? (選用)#
  
  最大操作時間，以毫秒為單位，預設為 30 秒，傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultNavigationTimeout()、BrowserContext.SetDefaultTimeout()、Page.SetDefaultNavigationTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Url|UrlRegex|UrlFunc string? | Regex? | Func<string?, bool> (選用)#
  
  在等待導航時要比對的 glob 模式、Regex 模式或接收 URL 的謂詞。請注意，如果參數是不帶萬用字元的字串，則此方法將等待導航到與該字串完全相同的 URL。
- WaitUntil enum WaitUntilState { Load, DOMContentLoaded, NetworkIdle, Commit }? (選用)#
  
  何時視為操作成功，預設為 load。事件可以是
  - 'domcontentloaded' - 當 DOMContentLoaded 事件觸發時，視為操作已完成。
  - 'load' - 當 load 事件觸發時，視為操作已完成。
  - 'networkidle' - 不建議使用，當至少 500 毫秒沒有網路連線時，視為操作已完成。請勿將此方法用於測試，而是依靠 Web 斷言來評估就緒狀態。
  - 'commit' - 當收到網路回應且文件開始載入時，視為操作已完成。

傳回

Response?#

SelectOptionAsync

版本 v1.9 前新增

page.SelectOptionAsync

不建議使用

請改用基於 Locator 的 Locator.SelectOptionAsync()。閱讀更多關於 locator 的資訊。

此方法等待符合 selector 的元素，等待可操作性檢查，等待直到所有指定的選項都出現在 <select> 元素中，然後選取這些選項。

如果目標元素不是 <select> 元素，此方法會擲回錯誤。但是，如果元素位於具有關聯控制項的 <label> 元素內，則會改為使用該控制項。

傳回已成功選取的選項值陣列。

一旦選取所有提供的選項，就會觸發 change 和 input 事件。

用法

// Single selection matching the value or label
await page.SelectOptionAsync("select#colors", new[] { "blue" });
// single selection matching both the value and the label
await page.SelectOptionAsync("select#colors", new[] { new SelectOptionValue() { Label = "blue" } });
// multiple
await page.SelectOptionAsync("select#colors", new[] { "red", "green", "blue" });

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
values string | ElementHandle | IEnumerable | SelectOption | IEnumerable | IEnumerable?#
- Value string? (選用)
  
  依 option.value 進行比對。選用。
- Label string? (選用)
  
  依 option.label 進行比對。選用。
- Index int? (選用)
  
  依索引進行比對。選用。
要選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有符合的選項，否則只會選取第一個符合其中一個傳遞選項的選項。字串值會比對值和標籤。如果所有指定的屬性都符合，則選項會被視為符合。
options PageSelectOptionOptions? (選用)
- Force bool? (選用)版本 v1.13 新增#
  
  是否略過可操作性檢查。預設值為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

IEnumerable<string>#

SetCheckedAsync

版本 v1.15 新增

page.SetCheckedAsync

不建議使用

請改用基於 Locator 的 Locator.SetCheckedAsync()。閱讀更多關於 locator 的資訊。

此方法透過執行以下步驟來勾選或取消勾選符合 selector 的元素

尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM。
確保符合的元素是核取方塊或單選輸入框。如果不是，此方法會擲回錯誤。
如果元素已具有正確的勾選狀態，此方法會立即傳回。
等待符合元素上的可操作性檢查，除非設定了 Force 選項。如果元素在檢查期間分離，則會重試整個動作。
如有需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 在元素的中心點擊。
確保元素現在已勾選或取消勾選。如果不是，此方法會擲回錯誤。

當所有步驟組合在指定的 Timeout 期間未完成時，此方法會擲回 TimeoutError。傳遞零逾時會停用此功能。

用法

await Page.SetCheckedAsync(selector, checked, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
checkedState bool #

是否勾選或取消勾選核取方塊。
options PageSetCheckedOptions? (選用)
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設值為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距方塊的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設值為 false。在不執行動作的情況下，等待元素準備好進行動作時很有用。

傳回

void #

SetInputFilesAsync

版本 v1.9 前新增

page.SetInputFilesAsync

不建議使用

請改用基於 Locator 的 Locator.SetInputFilesAsync()。閱讀更多關於 locator 的資訊。

將檔案輸入的值設定為這些檔案路徑或檔案。如果某些 filePaths 是相對路徑，則它們會相對於目前的工作目錄解析。對於空陣列，會清除選取的檔案。對於具有 [webkitdirectory] 屬性的輸入，僅支援單一目錄路徑。

此方法預期 selector 指向 input 元素。但是，如果元素位於具有關聯控制項的 <label> 元素內，則會改為以控制項為目標。

用法

await Page.SetInputFilesAsync(selector, files, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
files string | IEnumerable<string> | FilePayload | IEnumerable<FilePayload>#
- Name string
  
  檔案名稱
- MimeType string
  
  檔案類型
- Buffer byte[]
  
  檔案內容
options PageSetInputFilesOptions? (選用)
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

TapAsync

版本 v1.9 前新增

page.TapAsync

不建議使用

請改用基於 Locator 的 Locator.TapAsync()。閱讀更多關於 locator 的資訊。

此方法透過執行以下步驟來輕觸符合 selector 的元素

尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM。
等待符合元素上的可操作性檢查，除非設定了 Force 選項。如果元素在檢查期間分離，則會重試整個動作。
如有需要，將元素捲動到檢視畫面中。
使用 Page.Touchscreen 來輕觸元素的中心，或指定的 Position。

當所有步驟組合在指定的 Timeout 期間未完成時，此方法會擲回 TimeoutError。傳遞零逾時會停用此功能。

注意

Page.TapAsync() 方法在瀏覽器內容的 HasTouch 選項為 false 時會擲回錯誤。

用法

await Page.TapAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageTapOptions? (選用)
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設值為 false。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (選用)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距方塊的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)Added in: v1.11#
  
  設定後，此方法只會執行可操作性檢查，並跳過動作。預設值為 false。適用於等待元素準備好執行動作，但無需實際執行動作的情況。請注意，鍵盤 modifiers 無論 trial 設定為何都會被按下，以便測試僅在按下這些按鍵時才可見的元素。

傳回

void #

TextContentAsync

版本 v1.9 前新增

page.TextContentAsync

不建議使用

請改用基於 Locator 的 Locator.TextContentAsync()。閱讀更多關於 locator 的資訊。

傳回 element.textContent。

用法

await Page.TextContentAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageTextContentOptions? (選用)
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

string?#

TypeAsync

版本 v1.9 前新增

page.TypeAsync

已棄用

在大多數情況下，您應該改用 Locator.FillAsync()。只有在頁面上有特殊的鍵盤處理時，才需要逐個按下按鍵 - 在這種情況下，請使用 Locator.PressSequentiallyAsync()。

為文字中的每個字元傳送 keydown、keypress/input 和 keyup 事件。page.type 可用於傳送細緻的鍵盤事件。若要在表單欄位中填寫值，請使用 Page.FillAsync()。

若要按下特殊按鍵，例如 Control 或 ArrowDown，請使用 Keyboard.PressAsync()。

用法

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
text string #

要輸入到焦點元素中的文字。
options PageTypeOptions? (選用)
- Delay [float]? (選用)#
  
  按鍵之間等待的時間，以毫秒為單位。預設為 0。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

UncheckAsync

版本 v1.9 前新增

page.UncheckAsync

不建議使用

請改用基於 Locator 的 Locator.UncheckAsync()。閱讀更多關於 locator 的資訊。

此方法透過執行以下步驟來取消勾選符合 selector 的元素

尋找符合 selector 的元素。如果沒有，請等到符合的元素附加到 DOM。
確保符合的元素是核取方塊或單選輸入框。如果不是，此方法會擲回錯誤。如果元素已取消勾選，此方法會立即傳回。
等待符合元素上的可操作性檢查，除非設定了 Force 選項。如果元素在檢查期間分離，則會重試整個動作。
如有需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 在元素的中心點擊。
確保元素現在已取消勾選。如果不是，此方法會擲回錯誤。

當所有步驟組合在指定的 Timeout 期間未完成時，此方法會擲回 TimeoutError。傳遞零逾時會停用此功能。

用法

await Page.UncheckAsync(selector, options);

引數

selector string #

要搜尋元素的選取器。如果有複數個元素符合選取器，將會使用第一個。
options PageUncheckOptions? (選用)
- Force bool? (選用)#
  
  是否略過可操作性檢查。預設值為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)Added in: v1.11#
  - X [float]
  - Y [float]
  要使用的點，相對於元素內邊距方塊的左上角。如果未指定，則使用元素的某些可見點。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)Added in: v1.11#
  
  設定後，此方法僅執行可操作性檢查，並略過動作。預設值為 false。在不執行動作的情況下，等待元素準備好進行動作時很有用。

傳回

void #

WaitForSelectorAsync

版本 v1.9 前新增

page.WaitForSelectorAsync

不建議使用

請改用 Web 斷言來斷言可見性或基於 Locator 的 Locator.WaitForAsync()。閱讀更多關於 locator 的資訊。

當 selector 指定的元素滿足 State 選項時傳回。如果等待 hidden 或 detached，則傳回 null。

注意

Playwright 會在執行動作之前自動等待元素準備就緒。使用 Locator 物件和 Web 優先斷言使程式碼無需等待 selector。

等待 selector 滿足 State 選項（從 DOM 出現/消失，或變得可見/隱藏）。如果在呼叫方法時 selector 已經滿足條件，則該方法將立即傳回。如果在 Timeout 毫秒內 selector 未滿足條件，則該函數將擲回錯誤。

用法

此方法適用於跨導航

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

class FrameExamples
{
  public static async Task Images()
  {
      using var playwright = await Playwright.CreateAsync();
      await using var browser = await playwright.Chromium.LaunchAsync();
      var page = await browser.NewPageAsync();

      foreach (var currentUrl in new[] { "https://www.google.com", "https://bbc.com" })
      {
          await page.GotoAsync(currentUrl);
          var element = await page.WaitForSelectorAsync("img");
          Console.WriteLine($"Loaded image: {await element.GetAttributeAsync("src")}");
      }

      await browser.CloseAsync();
  }
}

引數

selector string #

要查詢的 selector。
options PageWaitForSelectorOptions? (選用)
- State enum WaitForSelectorState { Attached, Detached, Visible, Hidden }? (選用)#
  
  預設為 'visible'。可以是以下其中之一
  - 'attached' - 等待元素出現在 DOM 中。
  - 'detached' - 等待元素未出現在 DOM 中。
  - 'visible' - 等待元素具有非空的邊界框且沒有 visibility:hidden。請注意，沒有任何內容或具有 display:none 的元素具有空的邊界框，且不被視為可見。
  - 'hidden' - 等待元素從 DOM 分離，或具有空的邊界框或 visibility:hidden。這與 'visible' 選項相反。
- Strict bool? (選用)版本 v1.14 新增#
  
  當為 true 時，呼叫需要選取器解析為單一元素。如果給定的選取器解析為多個元素，則呼叫會擲回例外狀況。
- Timeout [float]? (選用)#
  
  以毫秒為單位的最大時間。預設值為 30000（30 秒）。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

ElementHandle?#

WaitForTimeoutAsync

版本 v1.9 前新增

page.WaitForTimeoutAsync

不建議使用

永遠不要在生產環境中等待逾時。等待時間的測試本質上是不穩定的。請改用 Locator 動作和自動等待的 Web 斷言。

等待給定的 timeout，以毫秒為單位。

請注意，page.waitForTimeout() 僅應用於偵錯。在生產環境中使用計時器的測試將會不穩定。請改用網路事件、selector 變得可見等訊號。

用法

// Wait for 1 second
await page.WaitForTimeoutAsync(1000);

引數

timeout [float]#

要等待的逾時時間

傳回

void #

方法​

AddInitScriptAsync​

AddLocatorHandlerAsync​

AddScriptTagAsync​

AddStyleTagAsync​

BringToFrontAsync​

CloseAsync​

ContentAsync​

Context​

DragAndDropAsync​

EmulateMediaAsync​

EvaluateAsync​

EvaluateHandleAsync​

ExposeBindingAsync​

ExposeFunctionAsync​

Frame​

FrameByUrl​

FrameLocator​

框架​

GetByAltText​

GetByLabel​

GetByPlaceholder​

GetByRole​

GetByTestId​

GetByText​

GetByTitle​

GoBackAsync​

GoForwardAsync​

GotoAsync​

IsClosed​

Locator​

MainFrame​

OpenerAsync​

PauseAsync​

PdfAsync​

ReloadAsync​

RemoveLocatorHandlerAsync​

RequestGCAsync​

RouteAsync​

RouteFromHARAsync​

RouteWebSocketAsync​

RunAndWaitForConsoleMessageAsync​

WaitForConsoleMessageAsync​

RunAndWaitForDownloadAsync​

WaitForDownloadAsync​

RunAndWaitForFileChooserAsync​

WaitForFileChooserAsync​

RunAndWaitForPopupAsync​

WaitForPopupAsync​

RunAndWaitForRequestAsync​

WaitForRequestAsync​

RunAndWaitForRequestFinishedAsync​

WaitForRequestFinishedAsync​

RunAndWaitForResponseAsync​

WaitForResponseAsync​

RunAndWaitForWebSocketAsync​

WaitForWebSocketAsync​

RunAndWaitForWorkerAsync​

WaitForWorkerAsync​

ScreenshotAsync​

SetContentAsync​

SetDefaultNavigationTimeout​

SetDefaultTimeout​

SetExtraHTTPHeadersAsync​

SetViewportSizeAsync​

TitleAsync​

UnrouteAsync​

UnrouteAllAsync​

Url​

Video​

ViewportSize​

WaitForFunctionAsync​

WaitForLoadStateAsync​

WaitForURLAsync​

Workers​

Properties​

APIRequest​

Clock​

Keyboard​

Mouse​

方法

AddInitScriptAsync

AddLocatorHandlerAsync

AddScriptTagAsync

AddStyleTagAsync

BringToFrontAsync

CloseAsync

ContentAsync

Context

DragAndDropAsync

EmulateMediaAsync

EvaluateAsync

EvaluateHandleAsync

ExposeBindingAsync

ExposeFunctionAsync

Frame

FrameByUrl

FrameLocator

框架

GetByAltText

GetByLabel

GetByPlaceholder

GetByRole

GetByTestId

GetByText

GetByTitle

GoBackAsync

GoForwardAsync

GotoAsync

IsClosed

Locator

MainFrame

OpenerAsync

PauseAsync

PdfAsync

ReloadAsync

RemoveLocatorHandlerAsync

RequestGCAsync

RouteAsync

RouteFromHARAsync

RouteWebSocketAsync

RunAndWaitForConsoleMessageAsync

WaitForConsoleMessageAsync

RunAndWaitForDownloadAsync

WaitForDownloadAsync

RunAndWaitForFileChooserAsync

WaitForFileChooserAsync

RunAndWaitForPopupAsync

WaitForPopupAsync

RunAndWaitForRequestAsync

WaitForRequestAsync

RunAndWaitForRequestFinishedAsync

WaitForRequestFinishedAsync

RunAndWaitForResponseAsync

WaitForResponseAsync

RunAndWaitForWebSocketAsync

WaitForWebSocketAsync

RunAndWaitForWorkerAsync

WaitForWorkerAsync

ScreenshotAsync

SetContentAsync

SetDefaultNavigationTimeout

SetDefaultTimeout

SetExtraHTTPHeadersAsync

SetViewportSizeAsync

TitleAsync

UnrouteAsync

UnrouteAllAsync

Url

Video

ViewportSize

WaitForFunctionAsync

WaitForLoadStateAsync

WaitForURLAsync

Workers

Properties

APIRequest

Clock

Keyboard

Mouse