ElementHandle

繼承自： JSHandle

ElementHandle 代表頁面內的 DOM 元素。ElementHandle 可以使用 Page.QuerySelectorAsync() 方法建立。

不建議使用

不建議使用 ElementHandle，請改用 Locator 物件和網頁優先的斷言。

var handle = await page.QuerySelectorAsync("a");
await handle.ClickAsync();

ElementHandle 會阻止 DOM 元素進行垃圾回收，除非使用 JsHandle.DisposeAsync() 處置 handle。當其原始 frame 導航時，ElementHandle 會自動處置。

ElementHandle 實例可以用作 Page.EvalOnSelectorAsync() 和 Page.EvaluateAsync() 方法中的引數。

Locator 和 ElementHandle 之間的區別在於，ElementHandle 指向特定的元素，而 Locator 捕捉了如何檢索元素的邏輯。

在以下範例中，handle 指向頁面上特定的 DOM 元素。如果該元素變更了文字，或被 React 用於渲染完全不同的元件，handle 仍然指向該 DOM 元素。這可能會導致意外的行為。

var handle = await page.QuerySelectorAsync("text=Submit");
await handle.HoverAsync();
await handle.ClickAsync();

使用 locator，每次使用 element 時，都會使用 selector 在頁面中找到最新的 DOM 元素。因此，在下面的程式碼片段中，底層的 DOM 元素將被定位兩次。

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

方法

BoundingBoxAsync

在 v1.9 之前新增

elementHandle.BoundingBoxAsync

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

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

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

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

用法

var box = await elementHandle.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]
  
  元素在像素中的高度。

ContentFrameAsync

在 v1.9 之前新增

elementHandle.ContentFrameAsync

傳回參考 iframe 節點的元素 handle 的內容 frame，否則傳回 null

用法

await ElementHandle.ContentFrameAsync();

傳回

Frame?#

OwnerFrameAsync

在 v1.9 之前新增

elementHandle.OwnerFrameAsync

傳回包含指定元素的 frame。

用法

await ElementHandle.OwnerFrameAsync();

傳回

Frame?#

WaitForElementStateAsync

在 v1.9 之前新增

elementHandle.WaitForElementStateAsync

當元素滿足 state 時傳回。

根據 state 參數，此方法會等待其中一個 actionability 檢查通過。當元素在等待時分離時，此方法會擲回例外，除非等待 "hidden" 狀態。

"visible" 等待直到元素可見。
"hidden" 等待直到元素不可見或未附加。請注意，等待 hidden 狀態在元素分離時不會擲回例外。
"stable" 等待直到元素可見且穩定。
"enabled" 等待直到元素已啟用。
"disabled" 等待直到元素未啟用。
"editable" 等待直到元素可編輯。

如果元素在 Timeout 毫秒內未滿足條件，此方法將擲回例外。

用法

await ElementHandle.WaitForElementStateAsync(state, options);

引數

state enum ElementState { Visible, Hidden, Stable, Enabled, Disabled, Editable }#

要等待的狀態，請參閱下文以取得更多詳細資訊。
options ElementHandleWaitForElementStateOptions? (選用)
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

已棄用

CheckAsync

在 v1.9 之前新增

elementHandle.CheckAsync

不建議使用

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

此方法透過執行以下步驟來檢查元素

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

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

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

用法

await ElementHandle.CheckAsync(options);

引數

options ElementHandleCheckOptions? (選用)
- Force bool? (選用)#
  
  是否略過 actionability 檢查。預設值為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)新增於：v1.11#
  - X [float]
  - Y [float]
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並略過動作。預設值為 false。可用於等待直到元素準備好執行動作，而無需實際執行。

傳回

void #

ClickAsync

在 v1.9 之前新增

elementHandle.ClickAsync

不建議使用

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

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

等待元素上的 actionability 檢查，除非設定了 Force 選項。
如果需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 點擊元素的中心，或指定的 Position。
等待啟動的導航成功或失敗，除非設定了 NoWaitAfter 選項。

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

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

用法

await ElementHandle.ClickAsync(options);

引數

options ElementHandleClickOptions? (選用)
- Button enum MouseButton { Left, Right, Middle }? (選用)#
  
  預設值為 left。
- ClickCount int? (選用)#
  
  預設值為 1。請參閱 UIEvent.detail。
- Delay [float]? (選用)#
  
  在 mousedown 和 mouseup 之間等待的時間，以毫秒為單位。預設值為 0。
- Force bool? (選用)#
  
  是否略過 actionability 檢查。預設值為 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]
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並略過動作。預設值為 false。可用於等待直到元素準備好執行動作，而無需實際執行。

傳回

void #

DblClickAsync

在 v1.9 之前新增

elementHandle.DblClickAsync

不建議使用

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

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

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

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

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

注意

elementHandle.dblclick() 會發送兩個 click 事件和一個 dblclick 事件。

用法

await ElementHandle.DblClickAsync(options);

引數

options ElementHandleDblClickOptions? (選用)
- Button enum MouseButton { Left, Right, Middle }? (選用)#
  
  預設值為 left。
- Delay [float]? (選用)#
  
  在 mousedown 和 mouseup 之間等待的時間，以毫秒為單位。預設值為 0。
- Force bool? (選用)#
  
  是否略過 actionability 檢查。預設值為 false。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (選用)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)#
  - X [float]
  - Y [float]
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並略過動作。預設值為 false。可用於等待直到元素準備好執行動作，而無需實際執行。

傳回

void #

DispatchEventAsync

在 v1.9 之前新增

elementHandle.DispatchEventAsync

不建議使用

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

以下程式碼片段在元素上發送 click 事件。無論元素的可見性狀態如何，都會發送 click 事件。這相當於呼叫 element.click()。

用法

await elementHandle.DispatchEventAsync("click");

在底層，它會根據給定的 type 建立事件的實例，使用 eventInit 屬性初始化它，並在元素上發送它。事件預設為 composed、cancelable 和 bubble。

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

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

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

引數

type string #

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

選用的事件特定初始化屬性。

傳回

void #

EvalOnSelectorAsync

新增於：v1.9

elementHandle.EvalOnSelectorAsync

不建議使用

此方法不會等待元素通過 actionability 檢查，因此可能會導致測試不穩定。請改用 Locator.EvaluateAsync()、其他 Locator 輔助方法或網頁優先的斷言。

傳回 expression 的傳回值。

此方法在 ElementHandle 的子樹中找到符合指定 selector 的元素，並將其作為第一個引數傳遞給 expression。如果沒有元素符合 selector，此方法會擲回錯誤。

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

用法

var tweetHandle = await page.QuerySelectorAsync(".tweet");
Assert.AreEqual("100", await tweetHandle.EvalOnSelectorAsync(".like", "node => node.innerText"));
Assert.AreEqual("10", await tweetHandle.EvalOnSelectorAsync(".retweets", "node => node.innerText"));

引數

selector string #

要查詢的 selector。
expression string #

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

要傳遞給 expression 的選用引數。

傳回

[object]#

EvalOnSelectorAllAsync

新增於：v1.9

elementHandle.EvalOnSelectorAllAsync

不建議使用

在大多數情況下，Locator.EvaluateAllAsync()、其他 Locator 輔助方法和網頁優先的斷言可以更好地完成工作。

傳回 expression 的傳回值。

此方法在 ElementHandle 的子樹中找到符合指定 selector 的所有元素，並將符合元素的陣列作為第一個引數傳遞給 expression。

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

用法

<div class="feed">
  <div class="tweet">Hello!</div>
  <div class="tweet">Hi!</div>
</div>

var feedHandle = await page.QuerySelectorAsync(".feed");
Assert.AreEqual(new [] { "Hello!", "Hi!" }, await feedHandle.EvalOnSelectorAllAsync<string[]>(".tweet", "nodes => nodes.map(n => n.innerText)"));

引數

selector string #

要查詢的 selector。
expression string #

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

要傳遞給 expression 的選用引數。

傳回

[object]#

FillAsync

在 v1.9 之前新增

elementHandle.FillAsync

不建議使用

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

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

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

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

用法

await ElementHandle.FillAsync(value, options);

引數

value string #

要為 <input>、<textarea> 或 [contenteditable] 元素設定的值。
options ElementHandleFillOptions? (選用)
- Force bool? (選用)新增於：v1.13#
  
  是否略過 actionability 檢查。預設值為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

FocusAsync

在 v1.9 之前新增

elementHandle.FocusAsync

不建議使用

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

在元素上呼叫 focus。

用法

await ElementHandle.FocusAsync();

傳回

void #

GetAttributeAsync

在 v1.9 之前新增

elementHandle.GetAttributeAsync

不建議使用

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

傳回元素屬性值。

用法

await ElementHandle.GetAttributeAsync(name);

引數

name string #

要取得值的屬性名稱。

傳回

string?#

HoverAsync

在 v1.9 之前新增

elementHandle.HoverAsync

不建議使用

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

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

等待元素上的 actionability 檢查，除非設定了 Force 選項。
如果需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 將滑鼠懸停在元素的中心，或指定的 Position。

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

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

用法

await ElementHandle.HoverAsync(options);

引數

options ElementHandleHoverOptions? (選用)
- Force bool? (選用)#
  
  是否略過 actionability 檢查。預設值為 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]
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並略過動作。預設值為 false。可用於等待直到元素準備好執行動作，而無需實際執行。

傳回

void #

InnerHTMLAsync

在 v1.9 之前新增

elementHandle.InnerHTMLAsync

不建議使用

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

傳回 element.innerHTML。

用法

await ElementHandle.InnerHTMLAsync();

傳回

string #

InnerTextAsync

在 v1.9 之前新增

elementHandle.InnerTextAsync

不建議使用

請改用基於定位器的 Locator.InnerTextAsync()。深入了解定位器。

傳回 element.innerText。

用法

await ElementHandle.InnerTextAsync();

傳回

string #

InputValueAsync

新增於：v1.13

elementHandle.InputValueAsync

不建議使用

請改用基於定位器的 Locator.InputValueAsync()。深入了解定位器。

針對選取的 <input>、<textarea> 或 <select> 元素，傳回 input.value。

若為非輸入元素則會擲回例外。然而，如果元素位於具有關聯控制項的 <label> 元素內，則會傳回該控制項的值。

用法

await ElementHandle.InputValueAsync(options);

引數

options ElementHandleInputValueOptions? (選用)
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

string #

IsCheckedAsync

在 v1.9 之前新增

elementHandle.IsCheckedAsync

不建議使用

請改用基於定位器的 Locator.IsCheckedAsync()。深入了解定位器。

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

用法

await ElementHandle.IsCheckedAsync();

傳回

bool #

IsDisabledAsync

在 v1.9 之前新增

elementHandle.IsDisabledAsync

不建議使用

請改用基於定位器的 Locator.IsDisabledAsync()。深入了解定位器。

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

用法

await ElementHandle.IsDisabledAsync();

傳回

bool #

IsEditableAsync

在 v1.9 之前新增

elementHandle.IsEditableAsync

不建議使用

請改用基於定位器的 Locator.IsEditableAsync()。深入了解定位器。

傳回元素是否為可編輯。

用法

await ElementHandle.IsEditableAsync();

傳回

bool #

IsEnabledAsync

在 v1.9 之前新增

elementHandle.IsEnabledAsync

不建議使用

請改用基於定位器的 Locator.IsEnabledAsync()。深入了解定位器。

傳回元素是否為啟用。

用法

await ElementHandle.IsEnabledAsync();

傳回

bool #

IsHiddenAsync

在 v1.9 之前新增

elementHandle.IsHiddenAsync

不建議使用

請改用基於定位器的 Locator.IsHiddenAsync()。深入了解定位器。

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

用法

await ElementHandle.IsHiddenAsync();

傳回

bool #

IsVisibleAsync

在 v1.9 之前新增

elementHandle.IsVisibleAsync

不建議使用

請改用基於定位器的 Locator.IsVisibleAsync()。深入了解定位器。

傳回元素是否為可見。

用法

await ElementHandle.IsVisibleAsync();

傳回

bool #

PressAsync

在 v1.9 之前新增

elementHandle.PressAsync

不建議使用

請改用基於定位器的 Locator.PressAsync()。深入了解定位器。

聚焦元素，然後使用 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。

按住 Shift 鍵將輸入對應於大寫 key 的文字。

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

也支援諸如 key: "Control+o"、key: "Control++ 或 key: "Control+Shift+T" 等快捷鍵。當使用修飾鍵指定時，在按下後續按鍵時，修飾鍵會保持按下狀態。

用法

await ElementHandle.PressAsync(key, options);

引數

key string #

要按下的按鍵名稱或要產生的字元，例如 ArrowLeft 或 a。
options ElementHandlePressOptions? (選用)
- Delay [float]? (選用)#
  
  keydown 和 keyup 之間等待的時間，以毫秒為單位。預設為 0。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項在未來將預設為 true。
  
  啟動導航的操作正在等待這些導航發生並等待頁面開始載入。您可以透過設定此旗標來選擇不等待。您只需要在特殊情況下使用此選項，例如導航到無法存取的頁面。預設值為 false。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

QuerySelectorAsync

新增於：v1.9

elementHandle.QuerySelectorAsync

不建議使用

請改用基於定位器的 Page.Locator()。深入了解定位器。

此方法會在 ElementHandle 的子樹狀結構中尋找符合指定選取器的元素。如果沒有元素符合選取器，則傳回 null。

用法

await ElementHandle.QuerySelectorAsync(selector);

引數

selector string #

要查詢的 selector。

傳回

ElementHandle?#

QuerySelectorAllAsync

新增於：v1.9

elementHandle.QuerySelectorAllAsync

不建議使用

請改用基於定位器的 Page.Locator()。深入了解定位器。

此方法會在 ElementHandle 的子樹狀結構中尋找符合指定選取器的所有元素。如果沒有元素符合選取器，則傳回空陣列。

用法

await ElementHandle.QuerySelectorAllAsync(selector);

引數

selector string #

要查詢的 selector。

傳回

IEnumerable<ElementHandle>#

ScreenshotAsync

在 v1.9 之前新增

elementHandle.ScreenshotAsync

不建議使用

請改用基於定位器的 Locator.ScreenshotAsync()。深入了解定位器。

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

此方法會等待可操作性檢查，然後將元素捲動到檢視畫面中，再擷取螢幕擷取畫面。如果元素與 DOM 分離，此方法會擲回錯誤。

傳回包含擷取螢幕擷取畫面的緩衝區。

用法

await ElementHandle.ScreenshotAsync(options);

引數

options ElementHandleScreenshotOptions? (選用)
- 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。

傳回

byte[]#

ScrollIntoViewIfNeededAsync

在 v1.9 之前新增

elementHandle.ScrollIntoViewIfNeededAsync

不建議使用

請改用基於定位器的 Locator.ScrollIntoViewIfNeededAsync()。深入了解定位器。

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

當 elementHandle 未指向連接到 Document 或 ShadowRoot 的元素時，會擲回例外。

如需捲動的替代方法，請參閱捲動。

用法

await ElementHandle.ScrollIntoViewIfNeededAsync(options);

引數

options ElementHandleScrollIntoViewIfNeededOptions? (選用)
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

SelectOptionAsync

在 v1.9 之前新增

elementHandle.SelectOptionAsync

不建議使用

請改用基於定位器的 Locator.SelectOptionAsync()。深入了解定位器。

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

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

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

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

用法

// Single selection matching the value or label
await handle.SelectOptionAsync(new[] { "blue" });
// single selection matching the label
await handle.SelectOptionAsync(new[] { new SelectOptionValue() { Label = "blue" } });
// multiple selection
await handle.SelectOptionAsync(new[] { "red", "green", "blue" });
// multiple selection for blue, red and second option
await handle.SelectOptionAsync(new[] {
    new SelectOptionValue() { Label = "blue" },
    new SelectOptionValue() { Index = 2 },
    new SelectOptionValue() { Value = "red" }});

引數

values string | ElementHandle | IEnumerable | SelectOption | IEnumerable | IEnumerable?#
- Value string? (選用)
  
  依 option.value 比對。選用。
- Label string? (選用)
  
  依 option.label 比對。選用。
- Index int? (選用)
  
  依索引比對。選用。
要選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有相符的選項，否則只會選取第一個符合其中一個傳遞選項的選項。字串值會同時比對值和標籤。如果所有指定的屬性都相符，則視為選項相符。
options ElementHandleSelectOptionOptions? (選用)
- Force bool? (選用)新增於：v1.13#
  
  是否略過 actionability 檢查。預設值為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

IEnumerable<string>#

SelectTextAsync

在 v1.9 之前新增

elementHandle.SelectTextAsync

不建議使用

請改用基於定位器的 Locator.SelectTextAsync()。深入了解定位器。

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

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

用法

await ElementHandle.SelectTextAsync(options);

引數

options ElementHandleSelectTextOptions? (選用)
- Force bool? (選用)新增於：v1.13#
  
  是否略過 actionability 檢查。預設值為 false。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

SetCheckedAsync

新增於：v1.15

elementHandle.SetCheckedAsync

不建議使用

請改用基於定位器的 Locator.SetCheckedAsync()。深入了解定位器。

此方法會透過執行下列步驟來核取或取消核取元素

確保元素是核取方塊或選項按鈕輸入。如果不是，此方法會擲回例外。
如果元素已具有正確的核取狀態，此方法會立即傳回。
等待相符元素上的可操作性檢查，除非設定 Force 選項。如果在檢查期間元素分離，則會重試整個動作。
如果需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 點擊元素的中心。
確保元素現在已核取或取消核取。如果不是，此方法會擲回例外。

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

用法

await ElementHandle.SetCheckedAsync(checked, options);

引數

checkedState bool #

是否要核取或取消核取核取方塊。
options ElementHandleSetCheckedOptions? (選用)
- Force bool? (選用)#
  
  是否略過 actionability 檢查。預設值為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)#
  - X [float]
  - Y [float]
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)#
  
  設定後，此方法僅執行 actionability 檢查並略過動作。預設值為 false。可用於等待直到元素準備好執行動作，而無需實際執行。

傳回

void #

SetInputFilesAsync

在 v1.9 之前新增

elementHandle.SetInputFilesAsync

不建議使用

請改用基於定位器的 Locator.SetInputFilesAsync()。深入了解定位器。

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

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

用法

await ElementHandle.SetInputFilesAsync(files, options);

引數

files string | IEnumerable<string> | FilePayload | IEnumerable<FilePayload>#
- Name string
  
  檔案名稱
- MimeType string
  
  檔案類型
- Buffer byte[]
  
  檔案內容
options ElementHandleSetInputFilesOptions? (選用)
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

TapAsync

在 v1.9 之前新增

elementHandle.TapAsync

不建議使用

請改用基於定位器的 Locator.TapAsync()。深入了解定位器。

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

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

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

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

注意

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

用法

await ElementHandle.TapAsync(options);

引數

options ElementHandleTapOptions? (選用)
- Force bool? (選用)#
  
  是否略過 actionability 檢查。預設值為 false。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (選用)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)#
  - X [float]
  - Y [float]
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並略過動作。預設值為 false。可用於等待直到元素準備好執行動作，而無需實際執行。

傳回

void #

TextContentAsync

在 v1.9 之前新增

elementHandle.TextContentAsync

不建議使用

請改用基於定位器的 Locator.TextContentAsync()。深入了解定位器。

傳回 node.textContent。

用法

await ElementHandle.TextContentAsync();

傳回

string?#

TypeAsync

在 v1.9 之前新增

elementHandle.TypeAsync

已棄用

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

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

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

用法

引數

text string #

要輸入到聚焦元素中的文字。
options ElementHandleTypeOptions? (選用)
- Delay [float]? (選用)#
  
  按鍵之間等待的時間，以毫秒為單位。預設為 0。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

void #

UncheckAsync

在 v1.9 之前新增

elementHandle.UncheckAsync

不建議使用

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

此方法透過執行以下步驟來檢查元素

確保元素為核取方塊或 radio 輸入。否則，此方法會擲出例外。如果元素已取消核取，此方法會立即返回。
等待元素上的可操作性檢查，除非設定了 Force 選項。
如果需要，將元素捲動到檢視畫面中。
使用 Page.Mouse 點擊元素的中心。
確保元素現在已取消核取。否則，此方法會擲出例外。

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

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

用法

await ElementHandle.UncheckAsync(options);

引數

options ElementHandleUncheckOptions? (選用)
- Force bool? (選用)#
  
  是否略過 actionability 檢查。預設值為 false。
- NoWaitAfter bool? (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- Position Position? (選用)新增於：v1.11#
  - X [float]
  - Y [float]
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。
- Trial bool? (選用)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並略過動作。預設值為 false。可用於等待直到元素準備好執行動作，而無需實際執行。

傳回

void #

WaitForSelectorAsync

在 v1.9 之前新增

elementHandle.WaitForSelectorAsync

不建議使用

改用宣告可見性的網路斷言或基於 Locator 的 Locator.WaitForAsync()。

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

等待相對於元素句柄的 selector 滿足 State 選項（在 DOM 中出現/消失，或變得可見/隱藏）。如果在呼叫方法時，selector 已經滿足條件，則該方法將立即返回。如果選取器在 Timeout 毫秒內不滿足條件，則該函數將擲出例外。

用法

await page.SetContentAsync("<div><span></span></div>");
var div = await page.QuerySelectorAsync("div");
// Waiting for the "span" selector relative to the div.
var span = await page.WaitForSelectorAsync("span", WaitForSelectorState.Attached);

注意

此方法不適用於跨導航，請改用 Page.WaitForSelectorAsync()。

引數

selector string #

要查詢的 selector。
options ElementHandleWaitForSelectorOptions? (選用)
- 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.15#
  
  當為 true 時，呼叫需要選取器解析為單個元素。如果給定的選取器解析為多個元素，則呼叫會擲出例外。
- Timeout [float]? (選用)#
  
  最大時間，以毫秒為單位。預設值為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.SetDefaultTimeout() 或 Page.SetDefaultTimeout() 方法變更。

傳回

ElementHandle?#

方法​

BoundingBoxAsync​

ContentFrameAsync​

OwnerFrameAsync​

WaitForElementStateAsync​

已棄用​

CheckAsync​

ClickAsync​

DblClickAsync​

DispatchEventAsync​

EvalOnSelectorAsync​

EvalOnSelectorAllAsync​

FillAsync​

FocusAsync​

GetAttributeAsync​

HoverAsync​

InnerHTMLAsync​

InnerTextAsync​

InputValueAsync​

IsCheckedAsync​

IsDisabledAsync​

IsEditableAsync​

IsEnabledAsync​

IsHiddenAsync​

IsVisibleAsync​

PressAsync​

QuerySelectorAsync​

QuerySelectorAllAsync​

ScreenshotAsync​

ScrollIntoViewIfNeededAsync​

SelectOptionAsync​

SelectTextAsync​

SetCheckedAsync​

SetInputFilesAsync​

TapAsync​

TextContentAsync​

TypeAsync​

UncheckAsync​

WaitForSelectorAsync​

方法

BoundingBoxAsync

ContentFrameAsync

OwnerFrameAsync

WaitForElementStateAsync

已棄用

CheckAsync

ClickAsync

DblClickAsync

DispatchEventAsync

EvalOnSelectorAsync

EvalOnSelectorAllAsync

FillAsync

FocusAsync

GetAttributeAsync

HoverAsync

InnerHTMLAsync

InnerTextAsync

InputValueAsync

IsCheckedAsync

IsDisabledAsync

IsEditableAsync

IsEnabledAsync

IsHiddenAsync

IsVisibleAsync

PressAsync

QuerySelectorAsync

QuerySelectorAllAsync

ScreenshotAsync

ScrollIntoViewIfNeededAsync

SelectOptionAsync

SelectTextAsync

SetCheckedAsync

SetInputFilesAsync

TapAsync

TextContentAsync

TypeAsync

UncheckAsync

WaitForSelectorAsync