ElementHandle

繼承自： JSHandle

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

不建議使用

不建議使用 ElementHandle，請改用 Locator 物件和 web-first 斷言。

ElementHandle hrefElement = page.querySelector("a");
hrefElement.click();

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

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

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

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

ElementHandle handle = page.querySelector("text=Submit");
handle.hover();
handle.click();

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

Locator locator = page.getByText("Submit");
locator.hover();
locator.click();

方法

boundingBox

在 v1.9 之前新增

elementHandle.boundingBox

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

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

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

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

用法

BoundingBox box = elementHandle.boundingBox();
page.mouse().click(box.x + box.width / 2, box.y + box.height / 2);

傳回

null | BoundingBox#
- x double
  
  元素的 x 座標，以像素為單位。
- y double
  
  元素的 y 座標，以像素為單位。
- width double
  
  元素的寬度，以像素為單位。
- height double
  
  元素的高度，以像素為單位。

contentFrame

在 v1.9 之前新增

elementHandle.contentFrame

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

用法

ElementHandle.contentFrame();

傳回

null | Frame #

ownerFrame

在 v1.9 之前新增

elementHandle.ownerFrame

傳回包含給定元素的 frame。

用法

ElementHandle.ownerFrame();

傳回

null | Frame #

waitForElementState

在 v1.9 之前新增

elementHandle.waitForElementState

當元素滿足 state 時傳回。

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

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

如果元素在 setTimeout 毫秒內未滿足條件，此方法將拋出例外。

用法

ElementHandle.waitForElementState(state);
ElementHandle.waitForElementState(state, options);

引數

state enum ElementState { VISIBLE, HIDDEN, STABLE, ENABLED, DISABLED, EDITABLE }#

要等待的狀態，請參閱下文以瞭解更多詳細資訊。
options ElementHandle.WaitForElementStateOptions (optional)
- setTimeout double (optional)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

已棄用

check

在 v1.9 之前新增

elementHandle.check

不建議使用

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

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

確保元素是核取方塊或 radio 輸入。如果不是，此方法會拋出例外。如果元素已選取，此方法會立即傳回。
等待元素上的 actionability 檢查，除非設定 setForce 選項。
如果需要，將元素滾動到視窗中。
使用 Page.mouse() 在元素的中心點擊。
確保元素現在已選取。如果不是，此方法會拋出例外。

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

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

用法

ElementHandle.check();
ElementHandle.check(options);

引數

options ElementHandle.CheckOptions (optional)
- setForce boolean (optional)#
  
  是否繞過 actionability 檢查。預設為 false。
- setNoWaitAfter boolean (optional)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (optional)新增於：v1.11#
  - setX double
  - setY double
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- setTimeout double (optional)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial boolean (optional)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並跳過動作。預設為 false。在不執行動作的情況下等待元素準備好動作時很有用。

傳回

void #

click

在 v1.9 之前新增

elementHandle.click

不建議使用

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

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

等待元素上的 actionability 檢查，除非設定 setForce 選項。
如果需要，將元素滾動到視窗中。
使用 Page.mouse() 在元素的中心或指定的 setPosition 點擊。
等待啟動的導航成功或失敗，除非設定 setNoWaitAfter 選項。

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

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

用法

ElementHandle.click();
ElementHandle.click(options);

引數

options ElementHandle.ClickOptions (optional)
- setButton enum MouseButton { LEFT, RIGHT, MIDDLE } (optional)#
  
  預設為 left。
- setClickCount int (optional)#
  
  預設為 1。請參閱 UIEvent.detail。
- setDelay double (optional)#
  
  mousedown 和 mouseup 之間等待的時間（以毫秒為單位）。預設為 0。
- setForce boolean (optional)#
  
  是否繞過 actionability 檢查。預設為 false。
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (optional)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- setNoWaitAfter boolean (optional)#
  
  已棄用
  此選項在未來將預設為 true。
  
  啟動導航的動作正在等待這些導航發生以及頁面開始載入。您可以透過設定此標誌來選擇不等待。您只需要在特殊情況下使用此選項，例如導航到無法存取的頁面。預設為 false。
- setPosition Position (optional)#
  - setX double
  - setY double
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- setTimeout double (optional)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial boolean (optional)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並跳過動作。預設為 false。在不執行動作的情況下等待元素準備好動作時很有用。

傳回

void #

dblclick

在 v1.9 之前新增

elementHandle.dblclick

不建議使用

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

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

等待元素上的 actionability 檢查，除非設定 setForce 選項。
如果需要，將元素滾動到視窗中。
使用 Page.mouse() 在元素的中心或指定的 setPosition 雙擊。

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

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

注意

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

用法

ElementHandle.dblclick();
ElementHandle.dblclick(options);

引數

options ElementHandle.DblclickOptions (optional)
- setButton enum MouseButton { LEFT, RIGHT, MIDDLE } (optional)#
  
  預設為 left。
- setDelay double (optional)#
  
  mousedown 和 mouseup 之間等待的時間（以毫秒為單位）。預設為 0。
- setForce boolean (optional)#
  
  是否繞過 actionability 檢查。預設為 false。
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (optional)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- setNoWaitAfter boolean (optional)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (optional)#
  - setX double
  - setY double
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- setTimeout double (optional)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial boolean (optional)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並跳過動作。預設為 false。在不執行動作的情況下等待元素準備好動作時很有用。

傳回

void #

dispatchEvent

在 v1.9 之前新增

elementHandle.dispatchEvent

不建議使用

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

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

用法

elementHandle.dispatchEvent("click");

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

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

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

// Note you can only create DataTransfer in Chromium and Firefox
JSHandle dataTransfer = page.evaluateHandle("() => new DataTransfer()");
Map<String, Object> arg = new HashMap<>();
arg.put("dataTransfer", dataTransfer);
elementHandle.dispatchEvent("dragstart", arg);

引數

type String #

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

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

傳回

void #

evalOnSelector

新增於：v1.9

elementHandle.evalOnSelector

不建議使用

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

傳回 expression 的傳回值。

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

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

用法

ElementHandle tweetHandle = page.querySelector(".tweet");
assertEquals("100", tweetHandle.evalOnSelector(".like", "node => node.innerText"));
assertEquals("10", tweetHandle.evalOnSelector(".retweets", "node => node.innerText"));

引數

selector String #

要查詢的 selector。
expression String #

要在瀏覽器上下文中評估的 JavaScript 表達式。如果表達式評估為函式，則會自動調用該函式。
arg EvaluationArgument (optional)#

要傳遞給 expression 的可選引數。

傳回

Object #

evalOnSelectorAll

新增於：v1.9

elementHandle.evalOnSelectorAll

不建議使用

在大多數情況下，Locator.evaluateAll()、其他 Locator 輔助方法和 web-first 斷言效果更好。

傳回 expression 的傳回值。

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

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

用法

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

ElementHandle feedHandle = page.querySelector(".feed");
assertEquals(Arrays.asList("Hello!", "Hi!"), feedHandle.evalOnSelectorAll(".tweet", "nodes => nodes.map(n => n.innerText)"));

引數

selector String #

要查詢的 selector。
expression String #

要在瀏覽器上下文中評估的 JavaScript 表達式。如果表達式評估為函式，則會自動調用該函式。
arg EvaluationArgument (optional)#

要傳遞給 expression 的可選引數。

傳回

Object #

fill

在 v1.9 之前新增

elementHandle.fill

不建議使用

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

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

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

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

用法

ElementHandle.fill(value);
ElementHandle.fill(value, options);

引數

value String #

要為 <input>、<textarea> 或 [contenteditable] 元素設定的值。
options ElementHandle.FillOptions (optional)
- setForce boolean (optional)新增於：v1.13#
  
  是否繞過 actionability 檢查。預設為 false。
- setNoWaitAfter boolean (optional)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setTimeout double (optional)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

focus

在 v1.9 之前新增

elementHandle.focus

不建議使用

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

在元素上呼叫 focus。

用法

ElementHandle.focus();

傳回

void #

getAttribute

在 v1.9 之前新增

elementHandle.getAttribute

不建議使用

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

傳回元素屬性值。

用法

ElementHandle.getAttribute(name);

引數

name String #

要取得值的屬性名稱。

傳回

null | String #

hover

在 v1.9 之前新增

elementHandle.hover

不建議使用

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

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

等待元素上的 actionability 檢查，除非設定 setForce 選項。
如果需要，將元素滾動到視窗中。
使用 Page.mouse() 將滑鼠懸停在元素的中心或指定的 setPosition 上。

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

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

用法

ElementHandle.hover();
ElementHandle.hover(options);

引數

options ElementHandle.HoverOptions (optional)
- setForce boolean (選填)#
  
  是否繞過 actionability 檢查。預設為 false。
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (選填)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- setNoWaitAfter boolean (選填)新增於版本：v1.28#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (選填)#
  - setX double
  - setY double
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial boolean (optional)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並跳過動作。預設為 false。在不執行動作的情況下等待元素準備好動作時很有用。

傳回

void #

innerHTML

在 v1.9 之前新增

elementHandle.innerHTML

不建議使用

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

傳回 element.innerHTML。

用法

ElementHandle.innerHTML();

傳回

String #

innerText

在 v1.9 之前新增

elementHandle.innerText

不建議使用

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

傳回 element.innerText。

用法

ElementHandle.innerText();

傳回

String #

inputValue

新增於：v1.13

elementHandle.inputValue

不建議使用

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

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

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

用法

ElementHandle.inputValue();
ElementHandle.inputValue(options);

引數

options ElementHandle.InputValueOptions (選填)
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

String #

isChecked

在 v1.9 之前新增

elementHandle.isChecked

不建議使用

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

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

用法

ElementHandle.isChecked();

傳回

boolean #

isDisabled

在 v1.9 之前新增

elementHandle.isDisabled

不建議使用

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

傳回元素是否為停用狀態，與 enabled 相反。

用法

ElementHandle.isDisabled();

傳回

boolean #

isEditable

在 v1.9 之前新增

elementHandle.isEditable

不建議使用

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

傳回元素是否為可編輯狀態。

用法

ElementHandle.isEditable();

傳回

boolean #

isEnabled

在 v1.9 之前新增

elementHandle.isEnabled

不建議使用

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

傳回元素是否為啟用狀態。

用法

ElementHandle.isEnabled();

傳回

boolean #

isHidden

在 v1.9 之前新增

elementHandle.isHidden

不建議使用

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

傳回元素是否為隱藏狀態，與 visible 相反。

用法

ElementHandle.isHidden();

傳回

boolean #

isVisible

在 v1.9 之前新增

elementHandle.isVisible

不建議使用

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

傳回元素是否為可見狀態。

用法

ElementHandle.isVisible();

傳回

boolean #

press

在 v1.9 之前新增

elementHandle.press

不建議使用

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

聚焦元素，然後使用 Keyboard.down() 和 Keyboard.up()。

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" 之類的快捷鍵。當使用修飾鍵指定時，修飾鍵會在後續按鍵被按下時保持按下狀態。

用法

ElementHandle.press(key);
ElementHandle.press(key, options);

引數

key String #

要按下的按鍵名稱或要產生的字元，例如 ArrowLeft 或 a。
options ElementHandle.PressOptions (選填)
- setDelay double (選填)#
  
  keydown 和 keyup 之間等待的時間，以毫秒為單位。預設為 0。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項在未來將預設為 true。
  
  啟動導航的動作正在等待這些導航發生以及頁面開始載入。您可以透過設定此標誌來選擇不等待。您只需要在特殊情況下使用此選項，例如導航到無法存取的頁面。預設為 false。
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

querySelector

新增於：v1.9

elementHandle.querySelector

不建議使用

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

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

用法

ElementHandle.querySelector(selector);

引數

selector String #

要查詢的 selector。

傳回

null | ElementHandle #

querySelectorAll

新增於：v1.9

elementHandle.querySelectorAll

不建議使用

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

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

用法

ElementHandle.querySelectorAll(selector);

引數

selector String #

要查詢的 selector。

傳回

List<ElementHandle>#

screenshot

在 v1.9 之前新增

elementHandle.screenshot

不建議使用

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

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

此方法會等待 actionability 檢查，然後將元素捲動到檢視畫面中，再拍攝螢幕截圖。如果元素從 DOM 中分離，則此方法會拋出錯誤。

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

用法

ElementHandle.screenshot();
ElementHandle.screenshot(options);

引數

options ElementHandle.ScreenshotOptions (選填)
- setAnimations enum ScreenshotAnimations { DISABLED, ALLOW } (選填)#
  
  當設定為 "disabled" 時，會停止 CSS 動畫、CSS 過渡和 Web 動畫。動畫會根據其持續時間獲得不同的處理方式
  - 有限動畫會快速轉發到完成，因此它們會觸發 transitionend 事件。
  - 無限動畫會取消到初始狀態，然後在螢幕截圖後重新播放。
  預設為 "allow"，保持動畫不受影響。
- setCaret enum ScreenshotCaret { HIDE, INITIAL } (選填)#
  
  當設定為 "hide" 時，螢幕截圖將會隱藏文字游標。當設定為 "initial" 時，文字游標行為將不會變更。預設為 "hide"。
- setMask List<Locator> (選填)#
  
  指定在拍攝螢幕截圖時應遮罩的 locator。遮罩元素將會以粉紅色方塊 #FF00FF（由 setMaskColor 自訂）覆蓋，完全遮蓋其邊界框。
- setMaskColor String (選填)新增於版本：v1.35#
  
  以 CSS 色彩格式指定遮罩元素的覆蓋方塊顏色。預設顏色為粉紅色 #FF00FF。
- setOmitBackground boolean (選填)#
  
  隱藏預設白色背景，並允許擷取具有透明度的螢幕截圖。不適用於 jpeg 影像。預設為 false。
- setPath Path (選填)#
  
  要將影像儲存到的檔案路徑。螢幕截圖類型將從檔案副檔名推斷。如果 setPath 是相對路徑，則會相對於目前的工作目錄解析。如果未提供路徑，則影像不會儲存到磁碟。
- setQuality int (選填)#
  
  影像品質，介於 0-100 之間。不適用於 png 影像。
- setScale enum ScreenshotScale { CSS, DEVICE } (選填)#
  
  當設定為 "css" 時，螢幕截圖在頁面上每個 CSS 像素將會有一個像素。對於高 DPI 裝置，這將使螢幕截圖保持較小。使用 "device" 選項將會使每個裝置像素產生一個像素，因此高 DPI 裝置的螢幕截圖將會大兩倍甚至更大。
  
  預設為 "device"。
- setStyle String (選填)新增於版本：v1.41#
  
  在製作螢幕截圖時要套用的樣式表文字。您可以在此處隱藏動態元素、使元素不可見或變更其屬性，以協助您建立可重複的螢幕截圖。此樣式表會穿透 Shadow DOM 並套用至內部框架。
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setType enum ScreenshotType { PNG, JPEG } (選填)#
  
  指定螢幕截圖類型，預設為 png。

傳回

byte[]#

scrollIntoViewIfNeeded

在 v1.9 之前新增

elementHandle.scrollIntoViewIfNeeded

不建議使用

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

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

當 elementHandle 未指向連線到 Document 或 ShadowRoot 的元素時，會拋出例外。

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

用法

ElementHandle.scrollIntoViewIfNeeded();
ElementHandle.scrollIntoViewIfNeeded(options);

引數

options ElementHandle.ScrollIntoViewIfNeededOptions (選填)
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

selectOption

在 v1.9 之前新增

elementHandle.selectOption

不建議使用

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

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

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

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

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

用法

// Single selection matching the value or label
handle.selectOption("blue");
// single selection matching the label
handle.selectOption(new SelectOption().setLabel("Blue"));
// multiple selection
handle.selectOption(new String[] {"red", "green", "blue"});

引數

values null | String | ElementHandle | String[] | SelectOption | ElementHandle[] | SelectOption[]#
- setValue String (選填)
  
  依據 option.value 比對。選填。
- setLabel String (選填)
  
  依據 option.label 比對。選填。
- setIndex int (選填)
  
  依據索引比對。選填。
要選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有符合的選項，否則只會選取第一個符合傳遞選項之一的選項。字串值會比對值和標籤。如果所有指定的屬性都符合，則選項會被視為符合。
options ElementHandle.SelectOptionOptions (選填)
- setForce boolean (optional)新增於：v1.13#
  
  是否繞過 actionability 檢查。預設為 false。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

List<String>#

selectText

在 v1.9 之前新增

elementHandle.selectText

不建議使用

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

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

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

用法

ElementHandle.selectText();
ElementHandle.selectText(options);

引數

options ElementHandle.SelectTextOptions (選填)
- setForce boolean (optional)新增於：v1.13#
  
  是否繞過 actionability 檢查。預設為 false。
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

setChecked

新增於版本：v1.15

elementHandle.setChecked

不建議使用

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

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

確認元素是核取方塊或收音機輸入。如果不是，此方法會拋出例外。
如果元素已經處於正確的勾選狀態，此方法會立即傳回。
等待符合元素的 actionability 檢查，除非設定了 setForce 選項。如果元素在檢查期間分離，則會重試整個動作。
如果需要，將元素滾動到視窗中。
使用 Page.mouse() 在元素的中心點擊。
確認元素現在已勾選或取消勾選。如果不是，此方法會拋出例外。

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

用法

ElementHandle.setChecked(checked);
ElementHandle.setChecked(checked, options);

引數

checked boolean #

是否勾選或取消勾選核取方塊。
options ElementHandle.SetCheckedOptions (選填)
- setForce boolean (選填)#
  
  是否繞過 actionability 檢查。預設為 false。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (選填)#
  - setX double
  - setY double
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial boolean (選填)#
  
  設定後，此方法僅執行 actionability 檢查並跳過動作。預設為 false。在不執行動作的情況下等待元素準備好動作時很有用。

傳回

void #

setInputFiles

在 v1.9 之前新增

elementHandle.setInputFiles

不建議使用

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

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

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

用法

ElementHandle.setInputFiles(files);
ElementHandle.setInputFiles(files, options);

引數

files Path | Path[] | FilePayload | FilePayload[]#
- setName String
  
  檔案名稱
- setMimeType String
  
  檔案類型
- setBuffer byte[]
  
  檔案內容
options ElementHandle.SetInputFilesOptions (選填)
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

tap

在 v1.9 之前新增

elementHandle.tap

不建議使用

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

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

等待元素的 actionability 檢查，除非設定了 setForce 選項。
如果需要，將元素滾動到視窗中。
使用 Page.touchscreen() 點擊元素的中心，或指定的 setPosition。

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

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

注意

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

用法

ElementHandle.tap();
ElementHandle.tap(options);

引數

options ElementHandle.TapOptions (選填)
- setForce boolean (選填)#
  
  是否繞過 actionability 檢查。預設為 false。
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (選填)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (選填)#
  - setX double
  - setY double
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial boolean (optional)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並跳過動作。預設為 false。在不執行動作的情況下等待元素準備好動作時很有用。

傳回

void #

textContent

在 v1.9 之前新增

elementHandle.textContent

不建議使用

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

傳回 node.textContent。

用法

ElementHandle.textContent();

傳回

null | String #

type

在 v1.9 之前新增

elementHandle.type

已棄用

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

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

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

用法

引數

text String #

要輸入到焦點元素中的文字。
options ElementHandle.TypeOptions (選填)
- setDelay double (選填)#
  
  按鍵之間等待的時間，以毫秒為單位。預設值為 0。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

void #

uncheck

在 v1.9 之前新增

elementHandle.uncheck

不建議使用

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

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

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

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

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

用法

ElementHandle.uncheck();
ElementHandle.uncheck(options);

引數

options ElementHandle.UncheckOptions (選填)
- setForce boolean (選填)#
  
  是否繞過 actionability 檢查。預設為 false。
- setNoWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- setPosition Position (optional)新增於：v1.11#
  - setX double
  - setY double
  相對於元素 padding box 左上角的點。如果未指定，則使用元素的某些可見點。
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。
- setTrial boolean (optional)新增於：v1.11#
  
  設定後，此方法僅執行 actionability 檢查並跳過動作。預設為 false。在不執行動作的情況下等待元素準備好動作時很有用。

傳回

void #

waitForSelector

在 v1.9 之前新增

elementHandle.waitForSelector

不建議使用

請改用 web assertion 來斷言可見性，或基於 locator 的 Locator.waitFor()。

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

等待相對於元素 handle 的 selector 滿足 setState 選項 (在 DOM 中出現/消失，或變成可見/隱藏)。如果在呼叫方法時 selector 已經滿足條件，則該方法將立即返回。如果 selector 在 setTimeout 毫秒內未滿足條件，則該函數將擲出例外。

用法

page.setContent("<div><span></span></div>");
ElementHandle div = page.querySelector("div");
// Waiting for the "span" selector relative to the div.
ElementHandle span = div.waitForSelector("span", new ElementHandle.WaitForSelectorOptions()
  .setState(WaitForSelectorState.ATTACHED));

注意

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

引數

selector String #

要查詢的 selector。
options ElementHandle.WaitForSelectorOptions (選填)
- setState enum WaitForSelectorState { ATTACHED, DETACHED, VISIBLE, HIDDEN } (選填)#
  
  預設值為 'visible'。可以是下列其中之一
  - 'attached' - 等待元素出現在 DOM 中。
  - 'detached' - 等待元素不要出現在 DOM 中。
  - 'visible' - 等待元素具有非空的邊界框且沒有 visibility:hidden。請注意，沒有任何內容或具有 display:none 的元素具有空的邊界框，並且不被視為可見。
  - 'hidden' - 等待元素從 DOM 中分離，或具有空的邊界框或 visibility:hidden。這與 'visible' 選項相反。
- setStrict boolean (選填)新增於版本：v1.15#
  
  當為 true 時，呼叫需要 selector 解析為單個元素。如果給定的 selector 解析為多個元素，則呼叫會擲出例外。
- setTimeout double (選填)#
  
  最大時間（以毫秒為單位）。預設為 30000 (30 秒)。傳遞 0 以停用逾時。預設值可以使用 BrowserContext.setDefaultTimeout() 或 Page.setDefaultTimeout() 方法變更。

傳回

null | ElementHandle #

方法​

boundingBox​

contentFrame​

ownerFrame​

waitForElementState​

已棄用​

check​

click​

dblclick​

dispatchEvent​

evalOnSelector​

evalOnSelectorAll​

fill​

focus​

getAttribute​

hover​

innerHTML​

innerText​

inputValue​

isChecked​

isDisabled​

isEditable​

isEnabled​

isHidden​

isVisible​

press​

querySelector​

querySelectorAll​

screenshot​

scrollIntoViewIfNeeded​

selectOption​

selectText​

setChecked​

setInputFiles​

tap​

textContent​

type​

uncheck​

waitForSelector​

方法

boundingBox

contentFrame

ownerFrame

waitForElementState

已棄用

check

click

dblclick

dispatchEvent

evalOnSelector

evalOnSelectorAll

fill

focus

getAttribute

hover

innerHTML

innerText

inputValue

isChecked

isDisabled

isEditable

isEnabled

isHidden

isVisible

press

querySelector

querySelectorAll

screenshot

scrollIntoViewIfNeeded

selectOption

selectText

setChecked

setInputFiles

tap

textContent

type

uncheck

waitForSelector