跳到主要內容

Locator

定位器 (Locators) 是 Playwright 自動等待和重試能力的核心組件。簡而言之，定位器代表一種在任何時刻於頁面上尋找元素的方式。定位器可以使用 Page.Locator() 方法建立。

深入瞭解定位器.

方法​

AllAsync​

新增於：v1.29 locator.AllAsync

當定位器指向元素列表時，這會傳回定位器陣列，指向它們各自的元素。

注意

Locator.AllAsync() 不會等待元素符合定位器，而是立即傳回頁面上存在的任何內容。

當元素列表動態變更時，Locator.AllAsync() 將產生不可預測且不穩定的結果。

當元素列表穩定，但動態載入時，請等待完整列表完成載入，然後再呼叫 Locator.AllAsync()。

用法

foreach (var li in await page.GetByRole("listitem").AllAsync())
  await li.ClickAsync();

傳回

AllInnerTextsAsync​

新增於：v1.14 locator.AllInnerTextsAsync

傳回所有符合節點的 node.innerText 值陣列。

斷言文字

如果您需要在頁面上斷言文字，請優先使用 Expect(Locator).ToHaveTextAsync() 和 UseInnerText 選項，以避免不穩定性。請參閱斷言指南以取得更多詳細資訊。

用法

var texts = await page.GetByRole(AriaRole.Link).AllInnerTextsAsync();

傳回

AllTextContentsAsync​

新增於：v1.14 locator.AllTextContentsAsync

傳回所有符合節點的 node.textContent 值陣列。

斷言文字

如果您需要在頁面上斷言文字，請優先使用 Expect(Locator).ToHaveTextAsync() 以避免不穩定性。請參閱斷言指南以取得更多詳細資訊。

用法

var texts = await page.GetByRole(AriaRole.Link).AllTextContentsAsync();

傳回

And​

新增於：v1.34 locator.And

建立一個同時符合此定位器和引數定位器的定位器。

用法

以下範例尋找具有特定標題的按鈕。

var button = page.GetByRole(AriaRole.Button).And(page.GetByTitle("Subscribe"));

引數

  • locator Locator#

    要比對的其他定位器。

傳回

AriaSnapshotAsync​

新增於：v1.49 locator.AriaSnapshotAsync

擷取給定元素的 aria 快照。閱讀更多關於 aria 快照和 Expect(Locator).ToMatchAriaSnapshotAsync() 以取得對應的斷言。

用法

await page.GetByRole(AriaRole.Link).AriaSnapshotAsync();

引數

傳回

詳細資訊

此方法擷取給定元素的 aria 快照。快照是一個字串，表示元素及其子元素的狀態。快照可以用於斷言測試中元素的狀態，或將其與未來的狀態進行比較。

ARIA 快照使用 YAML 標記語言表示

  • 物件的鍵是元素的角色和可選的可存取名稱。
  • 值可以是文字內容或子元素陣列。
  • 通用靜態文字可以使用 text 鍵表示。

以下是 HTML 標記和各自的 ARIA 快照

<ul aria-label="Links">
  <li><a href="/">Home</a></li>
  <li><a href="/about">About</a></li>
<ul>
- list "Links":
  - listitem:
    - link "Home"
  - listitem:
    - link "About"

BlurAsync​

新增於：v1.28 locator.BlurAsync

在元素上呼叫 blur。

用法

await Locator.BlurAsync(options);

引數

傳回

BoundingBoxAsync​

新增於：v1.14 locator.BoundingBoxAsync

此方法傳回符合定位器的元素的邊界框，如果元素不可見，則傳回 null。邊界框是相對於主框架視窗 (通常與瀏覽器視窗相同) 計算的。

用法

var box = await page.GetByRole(AriaRole.Button).BoundingBoxAsync();
await page.Mouse.ClickAsync(box.X + box.Width / 2, box.Y + box.Height / 2);

引數

傳回

  • BoundingBox?#

    • x [float]

      元素在像素中的 x 座標。

    • y [float]

      元素在像素中的 y 座標。

    • width [float]

      元素的寬度，單位為像素。

    • height [float]

      元素的高度，單位為像素。

詳細資訊

捲動會影響傳回的邊界框，類似於 Element.getBoundingClientRect。這表示 x 和/或 y 可能是負數。

來自子框架的元素傳回相對於主框架的邊界框，與 Element.getBoundingClientRect 不同。

假設頁面是靜態的，則使用邊界框座標來執行輸入是安全的。例如，以下程式碼片段應點擊元素的中心。

CheckAsync​

新增於：v1.14 locator.CheckAsync

確保已勾選核取方塊或單選按鈕元素。

用法

await page.GetByRole(AriaRole.Checkbox).CheckAsync();

引數

  • options LocatorCheckOptions? (optional)

    • Force bool? (optional)#

      是否繞過可操作性檢查。預設為 false。

    • NoWaitAfter bool? (optional)#

      已棄用

      此選項無效。

      此選項無效。

    • Position Position? (optional)#

      • X [float]

      • Y [float]

      相對於元素內邊距框左上角的點。如果未指定，則使用元素的某些可見點。

    • Timeout [float]? (optional)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

    • Trial bool? (optional)#

      設定後，此方法僅執行可操作性檢查，並跳過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。

傳回

詳細資訊

執行以下步驟

  1. 確保元素是核取方塊或單選輸入。如果不是，此方法會擲回例外。如果元素已經被勾選，此方法會立即傳回。
  2. 等待元素上的可操作性檢查，除非設定 Force 選項。
  3. 如果需要，將元素捲動到檢視畫面中。
  4. 使用 Page.Mouse 點擊元素的中心。
  5. 確保元素現在已被勾選。如果沒有，此方法會擲回例外。

如果在動作期間的任何時刻，元素從 DOM 中分離，此方法會擲回例外。

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

ClearAsync​

新增於：v1.28 locator.ClearAsync

清除輸入欄位。

用法

await page.GetByRole(AriaRole.Textbox).ClearAsync();

引數

  • options LocatorClearOptions? (optional)

傳回

詳細資訊

此方法會等待可操作性檢查、聚焦元素、清除它，並在清除後觸發 input 事件。

如果目標元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法會擲回錯誤。但是，如果元素位於具有關聯 control 的 <label> 元素內，則會改為清除該 control。

ClickAsync​

新增於：v1.14 locator.ClickAsync

點擊元素。

用法

點擊按鈕

await page.GetByRole(AriaRole.Button).ClickAsync();

在畫布上的特定位置按住 Shift 鍵並按下滑鼠右鍵

await page.Locator("canvas").ClickAsync(new() {
  Button = MouseButton.Right,
  Modifiers = new[] { KeyboardModifier.Shift },
  Position = new Position { X = 0, Y = 0 }
});

引數

  • options LocatorClickOptions? (optional)

    • Button enum MouseButton { Left, Right, Middle }? (optional)#

      預設為 left。

    • ClickCount int? (optional)#

      預設為 1。請參閱 UIEvent.detail。

    • Delay [float]? (optional)#

      mousedown 和 mouseup 之間等待的時間，單位為毫秒。預設為 0。

    • Force bool? (optional)#

      是否繞過可操作性檢查。預設為 false。

    • Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (optional)#

      要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。

    • NoWaitAfter bool? (optional)#

      已棄用

      此選項在未來將預設為 true。

      啟動導覽的動作正在等待這些導覽發生並等待頁面開始載入。您可以透過設定此旗標來選擇不等待。您只需要在特殊情況下使用此選項，例如導覽到無法存取的頁面。預設為 false。

    • Position Position? (optional)#

      • X [float]

      • Y [float]

      相對於元素內邊距框左上角的點。如果未指定，則使用元素的某些可見點。

    • Timeout [float]? (optional)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

    • Trial bool? (optional)#

      設定後，此方法僅執行可操作性檢查，並跳過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

詳細資訊

此方法透過執行以下步驟點擊元素

  1. 等待元素上的可操作性檢查，除非設定 Force 選項。
  2. 如果需要，將元素捲動到檢視畫面中。
  3. 使用 Page.Mouse 點擊元素的中心，或指定的 Position。
  4. 等待啟動的導覽成功或失敗，除非設定 NoWaitAfter 選項。

如果在動作期間的任何時刻，元素從 DOM 中分離，此方法會擲回例外。

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

ContentFrame​

新增於：v1.43 locator.ContentFrame

傳回指向與此定位器相同 iframe 的 FrameLocator 物件。

當您在某處取得 Locator 物件，稍後想要與框架內的內容互動時，這非常有用。

對於反向操作，請使用 FrameLocator.Owner。

用法

var locator = Page.Locator("iframe[name=\"embedded\"]");
// ...
var frameLocator = locator.ContentFrame;
await frameLocator.GetByRole(AriaRole.Button).ClickAsync();

傳回

CountAsync​

新增於：v1.14 locator.CountAsync

傳回符合定位器的元素數量。

斷言計數

如果您需要在頁面上斷言元素的數量，請優先使用 Expect(Locator).ToHaveCountAsync() 以避免不穩定性。請參閱斷言指南以取得更多詳細資訊。

用法

int count = await page.GetByRole(AriaRole.Listitem).CountAsync();

傳回

DblClickAsync​

新增於：v1.14 locator.DblClickAsync

雙擊元素。

用法

await Locator.DblClickAsync(options);

引數

  • options LocatorDblClickOptions? (optional)

    • Button enum MouseButton { Left, Right, Middle }? (optional)#

      預設為 left。

    • Delay [float]? (optional)#

      mousedown 和 mouseup 之間等待的時間，單位為毫秒。預設為 0。

    • Force bool? (optional)#

      是否繞過可操作性檢查。預設為 false。

    • Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (optional)#

      要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。

    • NoWaitAfter bool? (optional)#

      已棄用

      此選項無效。

      此選項無效。

    • Position Position? (optional)#

      • X [float]

      • Y [float]

      相對於元素內邊距框左上角的點。如果未指定，則使用元素的某些可見點。

    • Timeout [float]? (optional)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

    • Trial bool? (optional)#

      設定後，此方法僅執行可操作性檢查，並跳過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

詳細資訊

此方法透過執行以下步驟雙擊元素

  1. 等待元素上的可操作性檢查，除非設定 Force 選項。
  2. 如果需要，將元素捲動到檢視畫面中。
  3. 使用 Page.Mouse 雙擊元素的中心，或指定的 Position。

如果在動作期間的任何時刻，元素從 DOM 中分離，此方法會擲回例外。

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

注意

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

DispatchEventAsync​

新增於：v1.14 locator.DispatchEventAsync

以程式設計方式在符合的元素上分派事件。

用法

await locator.DispatchEventAsync("click");

引數

傳回

詳細資訊

上面的程式碼片段在元素上分派 click 事件。無論元素的能見度狀態如何，都會分派 click。這相當於呼叫 element.click()。

在底層，它會根據給定的 type 建立事件的實例，使用 eventInit 屬性初始化它，並在元素上分派它。預設情況下，事件是 composed、cancelable 和可冒泡的。

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

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

var dataTransfer = await page.EvaluateHandleAsync("() => new DataTransfer()");
await locator.DispatchEventAsync("dragstart", new Dictionary<string, object>
{
    { "dataTransfer", dataTransfer }
});

DragToAsync​

新增於：v1.18 locator.DragToAsync

將來源元素拖曳到目標元素並放下。

用法

var source = Page.Locator("#source");
var target = Page.Locator("#target");

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

引數

  • target Locator#

    要拖曳到的元素的定位器。

  • options LocatorDragToOptions? (optional)

    • Force bool? (optional)#

      是否繞過可操作性檢查。預設為 false。

    • NoWaitAfter bool? (optional)#

      已棄用

      此選項無效。

      此選項無效。

    • SourcePosition SourcePosition? (optional)#

      • X [float]

      • Y [float]

      在此點擊來源元素，相對於元素內邊距框的左上角。如果未指定，則使用元素的某些可見點。

    • TargetPosition TargetPosition? (optional)#

      • X [float]

      • Y [float]

      在此點在目標元素上放下，相對於元素內邊距框的左上角。如果未指定，則使用元素的某些可見點。

    • Timeout [float]? (optional)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

    • Trial bool? (optional)#

      設定後，此方法僅執行可操作性檢查，並跳過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。

傳回

詳細資訊

此方法將定位器拖曳到另一個目標定位器或目標位置。它將首先移動到來源元素，執行 mousedown，然後移動到目標元素或位置並執行 mouseup。

EvaluateAsync​

新增於：v1.14 locator.EvaluateAsync

在頁面中執行 JavaScript 程式碼，將符合的元素作為引數。

用法

var tweets = page.Locator(".tweet .retweets");
Assert.AreEqual("10 retweets", await tweets.EvaluateAsync("node => node.innerText"));

引數

  • expression string#

    要在瀏覽器環境中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動叫用該函式。

  • arg EvaluationArgument? (選用)#

    傳遞至 expression 的選用參數。

  • options LocatorEvaluateOptions? (選用)

傳回

  • [object]#

詳細資訊

傳回 expression 的傳回值，並以符合條件的元素作為第一個引數，以及 arg 作為第二個引數來呼叫。

如果 expression 傳回 Promise，此方法將等待 Promise 解析並傳回其值。

如果 expression 拋出錯誤或拒絕，此方法也會拋出錯誤。

EvaluateAllAsync​

新增於：v1.14 locator.EvaluateAllAsync

在頁面中執行 JavaScript 程式碼，並將所有符合條件的元素作為引數。

用法

var locator = page.Locator("div");
var moreThanTen = await locator.EvaluateAllAsync<bool>("(divs, min) => divs.length > min", 10);

引數

  • expression string#

    要在瀏覽器環境中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動叫用該函式。

  • arg EvaluationArgument? (選用)#

    傳遞至 expression 的選用參數。

傳回

  • [object]#

詳細資訊

傳回 expression 的傳回值，並以包含所有符合條件元素的陣列作為第一個引數，以及 arg 作為第二個引數來呼叫。

如果 expression 傳回 Promise，此方法將等待 Promise 解析並傳回其值。

如果 expression 拋出錯誤或拒絕，此方法也會拋出錯誤。

EvaluateHandleAsync​

新增於：v1.14 locator.EvaluateHandleAsync

在頁面中執行 JavaScript 程式碼，並將符合條件的元素作為引數，並傳回帶有結果的 JSHandle。

用法

await Locator.EvaluateHandleAsync(expression, arg, options);

引數

  • expression string#

    要在瀏覽器環境中評估的 JavaScript 運算式。如果運算式評估為函式，則會自動叫用該函式。

  • arg EvaluationArgument? (選用)#

    傳遞至 expression 的選用參數。

  • options LocatorEvaluateHandleOptions? (選用)

傳回

詳細資訊

以 JSHandle 傳回 expression 的傳回值，並以符合條件的元素作為第一個引數，以及 arg 作為第二個引數來呼叫。

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

如果 expression 傳回 Promise，此方法將等待 Promise 解析並傳回其值。

如果 expression 拋出錯誤或拒絕，此方法也會拋出錯誤。

更多詳細資訊請參閱 Page.EvaluateHandleAsync()。

FillAsync​

新增於：v1.14 locator.FillAsync

設定輸入欄位的值。

用法

await page.GetByRole(AriaRole.Textbox).FillAsync("example value");

引數

  • value string#

    要為 <input>、<textarea> 或 [contenteditable] 元素設定的值。

  • options LocatorFillOptions? (選用)

傳回

詳細資訊

此方法會等待可操作性檢查、聚焦元素、填寫內容，並在填寫後觸發 input 事件。請注意，您可以傳遞空字串來清除輸入欄位。

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

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

Filter​

新增於：v1.22 locator.Filter

此方法根據選項縮小現有的定位器範圍，例如依文字篩選。它可以鏈式調用以進行多次篩選。

用法

var rowLocator = page.Locator("tr");
// ...
await rowLocator
    .Filter(new() { HasText = "text in column 1" })
    .Filter(new() {
        Has = page.GetByRole(AriaRole.Button, new() { Name = "column 2 button" } )
    })
    .ScreenshotAsync();

引數

  • options LocatorFilterOptions? (選用)

    • Has Locator? (選用)#

      將方法結果縮小到包含符合此相對定位器的元素的結果。例如，article 包含 text=Playwright 會符合 <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>。

傳回

First​

新增於：v1.14 locator.First

傳回第一個符合條件的元素的定位器。

用法

Locator.First

傳回

FocusAsync​

新增於：v1.14 locator.FocusAsync

在符合條件的元素上呼叫 focus。

用法

await Locator.FocusAsync(options);

引數

傳回

FrameLocator​

新增於：v1.17 locator.FrameLocator

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

用法

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

引數

  • selector string#

    用於解析 DOM 元素的選擇器。

傳回

GetAttributeAsync​

新增於：v1.14 locator.GetAttributeAsync

傳回符合條件的元素的屬性值。

斷言屬性

如果您需要斷言元素的屬性，建議使用 Expect(Locator).ToHaveAttributeAsync() 以避免不穩定。請參閱斷言指南以取得更多詳細資訊。

用法

await Locator.GetAttributeAsync(name, options);

引數

傳回

GetByAltText​

新增於：v1.27 locator.GetByAltText

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

用法

例如，此方法將依據替代文字 "Playwright logo" 尋找圖片

<img alt='Playwright logo'>
await page.GetByAltText("Playwright logo").ClickAsync();

引數

  • text string | Regex#

    用於定位元素的文字。

  • options LocatorGetByAltTextOptions? (選用)

    • Exact bool? (選用)#

      是否尋找完全匹配：區分大小寫和全字串匹配。預設為 false。當依據正則表達式定位時，將忽略此選項。請注意，完全匹配仍然會修剪空白字元。

傳回

GetByLabel​

新增於：v1.27 locator.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 LocatorGetByLabelOptions? (選用)

    • Exact bool? (選用)#

      是否尋找完全匹配：區分大小寫和全字串匹配。預設為 false。當依據正則表達式定位時，將忽略此選項。請注意，完全匹配仍然會修剪空白字元。

傳回

GetByPlaceholder​

新增於：v1.27 locator.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 LocatorGetByPlaceholderOptions? (選用)

    • Exact bool? (選用)#

      是否尋找完全匹配：區分大小寫和全字串匹配。預設為 false。當依據正則表達式定位時，將忽略此選項。請注意，完全匹配仍然會修剪空白字元。

傳回

GetByRole​

新增於：v1.27 locator.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 LocatorGetByRoleOptions? (選用)

    • 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。

傳回

詳細資訊

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

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

GetByTestId​

新增於：v1.27 locator.GetByTestId

依據測試 ID 定位元素。

用法

考慮以下 DOM 結構。

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

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

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

引數

傳回

詳細資訊

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

GetByText​

新增於：v1.27 locator.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 LocatorGetByTextOptions? (選用)

    • Exact bool? (選用)#

      是否尋找完全匹配：區分大小寫和全字串匹配。預設為 false。當依據正則表達式定位時，將忽略此選項。請注意，完全匹配仍然會修剪空白字元。

傳回

詳細資訊

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

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

GetByTitle​

新增於：v1.27 locator.GetByTitle

允許依據元素的 title 屬性定位元素。

用法

考慮以下 DOM 結構。

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

您可以在依據標題文字定位後檢查問題計數

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

引數

  • text string | Regex#

    用於定位元素的文字。

  • options LocatorGetByTitleOptions? (選用)

    • Exact bool? (選用)#

      是否尋找完全匹配：區分大小寫和全字串匹配。預設為 false。當依據正則表達式定位時，將忽略此選項。請注意，完全匹配仍然會修剪空白字元。

傳回

HighlightAsync​

新增於：v1.20 locator.HighlightAsync

在螢幕上醒目提示對應的元素。對於偵錯很有用，請勿提交使用 Locator.HighlightAsync() 的程式碼。

用法

await Locator.HighlightAsync();

傳回

HoverAsync​

新增於：v1.14 locator.HoverAsync

將滑鼠懸停在符合條件的元素之上。

用法

await page.GetByRole(AriaRole.Link).HoverAsync();

引數

  • options LocatorHoverOptions? (選用)

    • 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]

      相對於元素內邊距框左上角的點。如果未指定，則使用元素的某些可見點。

    • Timeout [float]? (可選)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

    • Trial bool? (可選)#

      設定後，此方法僅執行可操作性檢查，並跳過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

詳細資訊

此方法透過執行以下步驟，將游標懸停在元素上方

  1. 等待元素上的可操作性檢查，除非設定了Force選項。
  2. 如果需要，將元素捲動到檢視畫面中。
  3. 使用 Page.Mouse 將游標懸停在元素的中心，或指定的 Position。

如果在動作期間的任何時刻，元素從 DOM 中分離，此方法會擲回例外。

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

InnerHTMLAsync​

新增於：v1.14 locator.InnerHTMLAsync

傳回 element.innerHTML。

用法

await Locator.InnerHTMLAsync(options);

引數

傳回

InnerTextAsync​

新增於：v1.14 locator.InnerTextAsync

傳回 element.innerText。

斷言文字

如果您需要在頁面上斷言文字，請優先使用 Expect(Locator).ToHaveTextAsync() 和 UseInnerText 選項，以避免不穩定性。請參閱斷言指南以取得更多詳細資訊。

用法

await Locator.InnerTextAsync(options);

引數

傳回

InputValueAsync​

新增於：v1.14 locator.InputValueAsync

傳回符合的 <input> 或 <textarea> 或 <select> 元素的值。

判斷值

如果您需要判斷輸入值，建議使用 Expect(Locator).ToHaveValueAsync() 以避免不穩定。請參閱判斷提示指南以取得更多詳細資訊。

用法

String value = await page.GetByRole(AriaRole.Textbox).InputValueAsync();

引數

傳回

詳細資訊

如果元素不是輸入框、文字區域或選取框，則會拋出例外。但是，如果元素位於具有相關聯控制項的 <label> 元素內，則會傳回控制項的值。

IsCheckedAsync​

新增於：v1.14 locator.IsCheckedAsync

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

判斷選取狀態

如果您需要判斷核取方塊是否已選取，建議使用 Expect(Locator).ToBeCheckedAsync() 以避免不穩定。請參閱判斷提示指南以取得更多詳細資訊。

用法

var isChecked = await page.GetByRole(AriaRole.Checkbox).IsCheckedAsync();

引數

傳回

IsDisabledAsync​

新增於：v1.14 locator.IsDisabledAsync

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

判斷停用狀態

如果您需要判斷元素是否已停用，建議使用 Expect(Locator).ToBeDisabledAsync() 以避免不穩定。請參閱判斷提示指南以取得更多詳細資訊。

用法

Boolean disabled = await page.GetByRole(AriaRole.Button).IsDisabledAsync();

引數

傳回

IsEditableAsync​

新增於：v1.14 locator.IsEditableAsync

傳回元素是否可編輯。如果目標元素不是 <input>、<textarea>、<select>、[contenteditable] 且沒有允許 [aria-readonly] 的角色，則此方法會拋出錯誤。

判斷可編輯狀態

如果您需要判斷元素是否可編輯，建議使用 Expect(Locator).ToBeEditableAsync() 以避免不穩定。請參閱判斷提示指南以取得更多詳細資訊。

用法

Boolean editable = await page.GetByRole(AriaRole.Textbox).IsEditableAsync();

引數

傳回

IsEnabledAsync​

新增於：v1.14 locator.IsEnabledAsync

傳回元素是否已啟用。

判斷啟用狀態

如果您需要判斷元素是否已啟用，建議使用 Expect(Locator).ToBeEnabledAsync() 以避免不穩定。請參閱判斷提示指南以取得更多詳細資訊。

用法

Boolean enabled = await page.GetByRole(AriaRole.Button).IsEnabledAsync();

引數

傳回

IsHiddenAsync​

新增於：v1.14 locator.IsHiddenAsync

傳回元素是否已隱藏，與可見相反。

判斷可見性

如果您需要判斷元素是否已隱藏，建議使用 Expect(Locator).ToBeHiddenAsync() 以避免不穩定。請參閱判斷提示指南以取得更多詳細資訊。

用法

Boolean hidden = await page.GetByRole(AriaRole.Button).IsHiddenAsync();

引數

  • options LocatorIsHiddenOptions? (可選)

    • Timeout [float]? (可選)#

      已棄用

      此選項會被忽略。Locator.IsHiddenAsync() 不會等待元素變成隱藏，並立即傳回。

傳回

IsVisibleAsync​

新增於：v1.14 locator.IsVisibleAsync

傳回元素是否可見。

判斷可見性

如果您需要判斷元素是否可見，建議使用 Expect(Locator).ToBeVisibleAsync() 以避免不穩定。請參閱判斷提示指南以取得更多詳細資訊。

用法

Boolean visible = await page.GetByRole(AriaRole.Button).IsVisibleAsync();

引數

  • options LocatorIsVisibleOptions? (可選)

    • Timeout [float]? (可選)#

      已棄用

      此選項會被忽略。Locator.IsVisibleAsync() 不會等待元素變成可見，並立即傳回。

傳回

Last​

新增於：v1.14 locator.Last

傳回最後一個符合元素的定位器。

用法

var banana = await page.GetByRole(AriaRole.Listitem).Last(1);

傳回

Locator​

新增於：v1.14 locator.Locator

此方法會在定位器的子樹狀結構中尋找符合指定選擇器的元素。它也接受篩選選項，類似於 Locator.Filter() 方法。

深入瞭解定位器.

用法

Locator.Locator(selectorOrLocator, options);

引數

  • selectorOrLocator string | Locator#

    用於解析 DOM 元素的選擇器或定位器。

  • options LocatorLocatorOptions? (可選)

    • Has Locator? (可選)#

      將方法結果縮小到包含符合此相對定位器的元素的結果。例如，article 包含 text=Playwright 會符合 <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>。

傳回

Nth​

新增於：v1.14 locator.Nth

傳回第 n 個符合元素的定位器。它是從零開始的，nth(0) 選擇第一個元素。

用法

var banana = await page.GetByRole(AriaRole.Listitem).Nth(2);

引數

傳回

Or​

新增於：v1.33 locator.Or

建立一個定位器，比對符合兩個定位器之一或兩者的所有元素。

請注意，當兩個定位器都符合某些項目時，產生的定位器將會有多個比對項，可能會導致定位器嚴格性違規。

用法

考慮一種情境，您想要按一下「新電子郵件」按鈕，但有時會改為顯示安全性設定對話方塊。在這種情況下，您可以等待「新電子郵件」按鈕或對話方塊，然後採取相應的行動。

注意

如果「新電子郵件」按鈕和安全性對話方塊都出現在螢幕上，「or」定位器將會同時比對它們，可能會拋出「嚴格模式違規」錯誤。在這種情況下，您可以使用 Locator.First 僅比對其中一個。

var newEmail = page.GetByRole(AriaRole.Button, new() { Name = "New" });
var dialog = page.GetByText("Confirm security settings");
await Expect(newEmail.Or(dialog).First).ToBeVisibleAsync();
if (await dialog.IsVisibleAsync())
  await page.GetByRole(AriaRole.Button, new() { Name = "Dismiss" }).ClickAsync();
await newEmail.ClickAsync();

引數

  • locator Locator#

    要比對的替代定位器。

傳回

Page​

新增於：v1.19 locator.Page

此定位器所屬的頁面。

用法

Locator.Page

傳回

PressAsync​

新增於：v1.14 locator.PressAsync

聚焦符合的元素並按下按鍵組合。

用法

await page.GetByRole(AriaRole.Textbox).PressAsync("Backspace");

引數

  • key string#

    要按下的按鍵名稱或要產生的字元，例如 ArrowLeft 或 a。

  • options LocatorPressOptions? (可選)

    • Delay [float]? (可選)#

      keydown 和 keyup 之間等待的時間，以毫秒為單位。預設值為 0。

    • NoWaitAfter bool? (可選)#

      已棄用

      此選項在未來將預設為 true。

      啟動導覽的動作正在等待這些導覽發生並等待頁面開始載入。您可以透過設定此旗標來選擇不等待。您只需要在特殊情況下使用此選項，例如導覽到無法存取的頁面。預設為 false。

    • Timeout [float]? (可選)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

詳細資訊

聚焦元素，然後使用 Keyboard.DownAsync() 和 Keyboard.UpAsync()。

key 可以指定預期的 keyboardEvent.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" 之類的快速鍵。當使用修飾符指定時，修飾符會被按下並保持按住狀態，同時按下後續的按鍵。

PressSequentiallyAsync​

新增於：v1.38 locator.PressSequentiallyAsync
提示

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

聚焦元素，然後為文字中的每個字元傳送 keydown、keypress/input 和 keyup 事件。

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

用法

await locator.PressSequentiallyAsync("Hello"); // Types instantly
await locator.PressSequentiallyAsync("World", new() { Delay = 100 }); // Types slower, like a user

將文字輸入文字欄位然後提交表單的範例

var locator = page.GetByLabel("Password");
await locator.PressSequentiallyAsync("my password");
await locator.PressAsync("Enter");

引數

  • text string#

    要依序按下聚焦元素的字元字串。

  • options LocatorPressSequentiallyOptions? (可選)

    • Delay [float]? (可選)#

      按鍵之間等待的時間，以毫秒為單位。預設值為 0。

    • NoWaitAfter bool? (可選)#

      已棄用

      此選項無效。

      此選項無效。

    • Timeout [float]? (可選)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

ScreenshotAsync​

新增於：v1.14 locator.ScreenshotAsync

拍攝符合定位器的元素的螢幕截圖。

用法

await page.GetByRole(AriaRole.Link).ScreenshotAsync();

停用動畫並將螢幕截圖儲存到檔案

await page.GetByRole(AriaRole.Link).ScreenshotAsync(new() {
  Animations = ScreenshotAnimations.Disabled,
  Path = "link.png"
});

引數

  • options LocatorScreenshotOptions? (可選)

    • Animations enum ScreenshotAnimations { Disabled, Allow }? (可選)#

      當設定為 "disabled" 時，會停止 CSS 動畫、CSS 轉換和 Web 動畫。動畫會根據其持續時間而有不同的處理方式

      • 有限動畫會快速轉至完成，因此它們會觸發 transitionend 事件。
      • 無限動畫會取消為初始狀態，然後在螢幕截圖後重新播放。

      預設值為 "allow"，保持動畫不受影響。

    • Caret enum ScreenshotCaret { Hide, Initial }? (可選)#

      當設定為 "hide" 時，螢幕截圖將會隱藏文字游標。當設定為 "initial" 時，文字游標行為將不會變更。預設值為 "hide"。

    • Mask IEnumerable?<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。

傳回

詳細資訊

此方法會擷取頁面的螢幕截圖，裁剪為符合定位器的特定元素的大小和位置。如果元素被其他元素覆蓋，則實際上不會在螢幕截圖上看到。如果元素是可捲動的容器，則只有目前捲動的內容會顯示在螢幕截圖上。

此方法會等待可操作性檢查，然後在拍攝螢幕截圖之前將元素捲動到檢視畫面中。如果元素與 DOM 分離，則此方法會拋出錯誤。

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

ScrollIntoViewIfNeededAsync​

新增於：v1.14 locator.ScrollIntoViewIfNeededAsync

此方法會等待可操作性檢查，然後嘗試將元素捲動到檢視畫面中，除非它已完全可見，如 IntersectionObserver 的 ratio 所定義。

請參閱 捲動 以取得其他捲動方式。

用法

await Locator.ScrollIntoViewIfNeededAsync(options);

引數

傳回

SelectOptionAsync​

新增於：v1.14 locator.SelectOptionAsync

在 <select> 中選取選項。

用法

<select multiple>
  <option value="red">Red</div>
  <option value="green">Green</div>
  <option value="blue">Blue</div>
</select>
// single selection matching the value or label
await element.SelectOptionAsync(new[] { "blue" });
// single selection matching the label
await element.SelectOptionAsync(new[] { new SelectOptionValue() { Label = "blue" } });
// multiple selection for blue, red and second option
await element.SelectOptionAsync(new[] { "red", "green", "blue" });

引數

  • values string | ElementHandle | IEnumerable | SelectOption | IEnumerable | IEnumerable?#

    • Value string? (可選)

      依 option.value 比對。可選。

    • Label string? (可選)

      依 option.label 比對。可選。

    • Index int? (可選)

      依索引比對。可選。

    要選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有符合的選項，否則只會選取第一個符合傳遞選項之一的選項。字串值會同時比對值和標籤。如果所有指定的屬性都符合，則選項會被視為符合。
  • options LocatorSelectOptionOptions? (可選)

傳回

詳細資訊

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

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

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

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

SelectTextAsync​

新增於：v1.14 locator.SelectTextAsync

此方法會等待可操作性檢查，然後聚焦元素並選取其所有文字內容。

如果元素位於具有相關聯控制項的 <label> 元素內，則會改為聚焦和選取控制項中的文字。

用法

await Locator.SelectTextAsync(options);

引數

傳回

SetCheckedAsync​

新增於：v1.15 locator.SetCheckedAsync

設定核取方塊或單選按鈕元素的狀態。

用法

await page.GetByRole(AriaRole.Checkbox).SetCheckedAsync(true);

引數

  • checkedState bool#

    是否核取或取消核取核取方塊。

  • options LocatorSetCheckedOptions? (可選)

    • Force bool? (可選)#

      是否繞過可操作性檢查。預設為 false。

    • NoWaitAfter bool? (可選)#

      已棄用

      此選項無效。

      此選項無效。

    • Position Position? (可選)#

      • X [float]

      • Y [float]

      相對於元素內邊距框左上角的點。如果未指定，則使用元素的某些可見點。

    • Timeout [float]? (可選)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

    • Trial bool? (選用)#

      設定後，此方法僅執行可操作性檢查，並跳過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。

傳回

詳細資訊

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

  1. 確保相符的元素為核取方塊或 radio 輸入。若否，此方法將會擲回錯誤。
  2. 如果元素已處於正確的勾選狀態，此方法會立即返回。
  3. 等待對相符元素執行可操作性檢查，除非已設定 Force 選項。如果在檢查期間元素遭到卸離，則會重試整個動作。
  4. 如果需要，將元素捲動到檢視畫面中。
  5. 使用 Page.Mouse 點擊元素的中心。
  6. 確保元素現在已勾選或取消勾選。若否，此方法將會擲回錯誤。

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

SetInputFilesAsync​

新增於：v1.14 locator.SetInputFilesAsync

將檔案或多個檔案上傳到 <input type=file> 中。對於具有 [webkitdirectory] 屬性的輸入，僅支援單一目錄路徑。

用法

// Select one file
await page.GetByLabel("Upload file").SetInputFilesAsync("myfile.pdf");

// Select multiple files
await page.GetByLabel("Upload files").SetInputFilesAsync(new[] { "file1.txt", "file12.txt" });

// Select a directory
await page.GetByLabel("Upload directory").SetInputFilesAsync("mydir");

// Remove all the selected files
await page.GetByLabel("Upload file").SetInputFilesAsync(new[] {});

// Upload buffer from memory
await page.GetByLabel("Upload file").SetInputFilesAsync(new FilePayload
{
    Name = "file.txt",
    MimeType = "text/plain",
    Buffer = System.Text.Encoding.UTF8.GetBytes("this is a test"),
});

引數

傳回

詳細資訊

將檔案輸入的值設定為這些檔案路徑或檔案。如果某些 filePaths 是相對路徑，則會相對於目前的工作目錄解析這些路徑。對於空陣列，則會清除選取的檔案。

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

TapAsync​

新增於：v1.14 locator.TapAsync

在符合 locator 的元素上執行點擊手勢。

用法

await Locator.TapAsync(options);

引數

  • options LocatorTapOptions? (選用)

    • 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]

      相對於元素內邊距框左上角的點。如果未指定，則使用元素的某些可見點。

    • Timeout [float]? (選用)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

    • Trial bool? (選用)#

      設定後，此方法僅執行可操作性檢查，並跳過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。請注意，無論 trial 為何，都會按下鍵盤 modifiers，以允許測試僅在按下這些鍵時才可見的元素。

傳回

詳細資訊

此方法透過執行以下步驟來點擊元素

  1. 等待對元素執行可操作性檢查，除非已設定 Force 選項。
  2. 如果需要，將元素捲動到檢視畫面中。
  3. 使用 Page.Touchscreen 點擊元素的中心，或指定的 Position。

如果在動作期間的任何時刻，元素從 DOM 中分離，此方法會擲回例外。

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

注意

element.tap() 需要瀏覽器內容的 hasTouch 選項設定為 true。

TextContentAsync​

新增於：v1.14 locator.TextContentAsync

傳回 node.textContent。

斷言文字

如果您需要在頁面上斷言文字，請優先使用 Expect(Locator).ToHaveTextAsync() 以避免不穩定性。請參閱斷言指南以取得更多詳細資訊。

用法

await Locator.TextContentAsync(options);

引數

傳回

UncheckAsync​

新增於：v1.14 locator.UncheckAsync

確保核取方塊或 radio 元素為未勾選狀態。

用法

await page.GetByRole(AriaRole.Checkbox).UncheckAsync();

引數

  • options LocatorUncheckOptions? (選用)

    • Force bool? (選用)#

      是否繞過可操作性檢查。預設為 false。

    • NoWaitAfter bool? (選用)#

      已棄用

      此選項無效。

      此選項無效。

    • Position Position? (選用)#

      • X [float]

      • Y [float]

      相對於元素內邊距框左上角的點。如果未指定，則使用元素的某些可見點。

    • Timeout [float]? (選用)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

    • Trial bool? (選用)#

      設定後，此方法僅執行可操作性檢查，並跳過動作。預設為 false。適用於等待元素準備好執行動作，而無需實際執行它。

傳回

詳細資訊

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

  1. 確保元素為核取方塊或 radio 輸入。若否，此方法將會擲回錯誤。如果元素已處於未勾選狀態，此方法會立即返回。
  2. 等待對元素執行可操作性檢查，除非已設定 Force 選項。
  3. 如果需要，將元素捲動到檢視畫面中。
  4. 使用 Page.Mouse 點擊元素的中心。
  5. 確保元素現在已取消勾選。若否，此方法將會擲回錯誤。

如果在動作期間的任何時刻，元素從 DOM 中分離，此方法會擲回例外。

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

WaitForAsync​

新增於：v1.16 locator.WaitForAsync

當 locator 指定的元素滿足 State 選項時返回。

如果目標元素已滿足條件，則此方法會立即返回。否則，會等待最多 Timeout 毫秒，直到滿足條件為止。

用法

var orderSent = page.Locator("#order-sent");
orderSent.WaitForAsync();

引數

  • options LocatorWaitForOptions? (選用)

    • State enum WaitForSelectorState { Attached, Detached, Visible, Hidden }? (選用)#

      預設為 'visible'。可以是

      • 'attached' - 等待元素出現在 DOM 中。
      • 'detached' - 等待元素未出現在 DOM 中。
      • 'visible' - 等待元素具有非空邊界框且沒有 visibility:hidden。請注意，沒有任何內容或具有 display:none 的元素具有空邊界框，且不被視為可見。
      • 'hidden' - 等待元素從 DOM 卸離，或具有空邊界框或 visibility:hidden。這與 'visible' 選項相反。

    • Timeout [float]? (選用)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

已棄用​

ElementHandleAsync​

新增於：v1.14 locator.ElementHandleAsync
不建議使用

始終建議使用 Locator 和 Web 判斷提示，而不是 ElementHandle，因為後者本質上是競爭條件。

將指定的 locator 解析為第一個相符的 DOM 元素。如果沒有相符的元素，則等待一個元素出現。如果有多個元素符合 locator，則擲回錯誤。

用法

await Locator.ElementHandleAsync(options);

引數

傳回

ElementHandlesAsync​

新增於：v1.14 locator.ElementHandlesAsync
不建議使用

始終建議使用 Locator 和 Web 判斷提示，而不是 ElementHandle，因為後者本質上是競爭條件。

將指定的 locator 解析為所有相符的 DOM 元素。如果沒有相符的元素，則返回空列表。

用法

await Locator.ElementHandlesAsync();

傳回

TypeAsync​

新增於：v1.14 locator.TypeAsync
已棄用

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

聚焦元素，然後為文字中的每個字元傳送 keydown、keypress/input 和 keyup 事件。

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

用法

引數

  • text string#

    要輸入到焦點元素中的文字。

  • options LocatorTypeOptions? (選用)

    • Delay [float]? (選用)#

      按鍵之間等待的時間，以毫秒為單位。預設值為 0。

    • NoWaitAfter bool? (選用)#

      已棄用

      此選項無效。

      此選項無效。

    • Timeout [float]? (選用)#

      最大等待時間，單位為毫秒。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回