ElementHandle

繼承自：JSHandle

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

不建議使用

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

const hrefElement = await page.$('a');
await hrefElement.click();

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

ElementHandle 實例可以用作 page.$eval() 和 page.evaluate() 方法中的引數。

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

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

const handle = await page.$('text=Submit');
// ...
await handle.hover();
await handle.click();

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

const locator = page.getByText('Submit');
// ...
await locator.hover();
await locator.click();

方法

boundingBox

在 v1.9 之前新增

elementHandle.boundingBox

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

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

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

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

用法

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

傳回

Promise<null | Object>#
- x number
  
  元素在像素中的 x 座標。
- y number
  
  元素在像素中的 y 座標。
- width number
  
  元素在像素中的寬度。
- height number
  
  元素在像素中的高度。

contentFrame

在 v1.9 之前新增

elementHandle.contentFrame

傳回參照 iframe 節點的元素 handle 的內容框架，否則傳回 null

用法

await elementHandle.contentFrame();

傳回

Promise<null | Frame>#

ownerFrame

在 v1.9 之前新增

elementHandle.ownerFrame

傳回包含給定元素的框架。

用法

await elementHandle.ownerFrame();

傳回

Promise<null | Frame>#

waitForElementState

在 v1.9 之前新增

elementHandle.waitForElementState

當元素滿足 state 時傳回。

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

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

如果元素在 timeout 毫秒內未滿足條件，此方法將會擲回錯誤。

用法

await elementHandle.waitForElementState(state);
await elementHandle.waitForElementState(state, options);

引數

state "visible" | "hidden" | "stable" | "enabled" | "disabled" | "editable"#

要等待的狀態，請參閱下文以取得更多詳細資訊。
options Object (選用)
- timeout number (選用)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

Promise<void>#

已棄用

$

新增於：v1.9

elementHandle.$

不建議使用

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

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

用法

await elementHandle.$(selector);

引數

selector string #

要查詢的選擇器。

傳回

Promise<null | ElementHandle>#

$$

新增於：v1.9

elementHandle.$$

不建議使用

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

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

用法

await elementHandle.$$(selector);

引數

selector string #

要查詢的選擇器。

傳回

Promise<Array<ElementHandle>>#

$eval

新增於：v1.9

elementHandle.$eval

不建議使用

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

傳回 pageFunction 的傳回值。

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

如果 pageFunction 傳回 Promise，則 elementHandle.$eval() 將等待 Promise 解析並傳回其值。

用法

const tweetHandle = await page.$('.tweet');
expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');

引數

selector string #

要查詢的選擇器。
pageFunction function(Element) | string #

要在頁面內容中評估的函式。
arg EvaluationArgument (選用)#

要傳遞給 pageFunction 的選用引數。

傳回

Promise<Serializable>#

$$eval

新增於：v1.9

elementHandle.$$eval

不建議使用

在大多數情況下，locator.evaluateAll()、其他 Locator 輔助方法和網頁優先的斷言可以做得更好。

傳回 pageFunction 的傳回值。

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

如果 pageFunction 傳回 Promise，則 elementHandle.$$eval() 將等待 Promise 解析並傳回其值。

用法

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

const feedHandle = await page.$('.feed');
expect(await feedHandle.$$eval('.tweet', nodes =>
  nodes.map(n => n.innerText))).toEqual(['Hello!', 'Hi!'],
);

引數

selector string #

要查詢的選擇器。
pageFunction function(Array<Element>) | string #

要在頁面內容中評估的函式。
arg EvaluationArgument (選用)#

要傳遞給 pageFunction 的選用引數。

傳回

Promise<Serializable>#

check

在 v1.9 之前新增

elementHandle.check

不建議使用

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

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

確保元素是核取方塊或單選輸入。如果不是，此方法會擲回錯誤。如果元素已核取，此方法會立即傳回。
等待元素上的可操作性檢查，除非設定 force 選項。
如果需要，將元素滾動到檢視畫面中。
使用 page.mouse 在元素的中心點擊。
確保元素現在已核取。如果沒有，此方法會擲回錯誤。

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

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

用法

await elementHandle.check();
await elementHandle.check(options);

引數

options Object (選用)
- force boolean (選用)#
  
  是否要繞過可操作性檢查。預設為 false。
- noWaitAfter boolean (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- position Object (選用)新增於：v1.11#
  - x number
  - y number
  相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。
- timeout number (選用)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。
- trial boolean (選用)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查並跳過動作。預設為 false。在等待元素準備好執行動作但不想實際執行動作時很有用。

傳回

Promise<void>#

click

在 v1.9 之前新增

elementHandle.click

不建議使用

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

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

等待元素上的可操作性檢查，除非設定 force 選項。
如果需要，將元素滾動到檢視畫面中。
使用 page.mouse 在元素的中心點擊，或指定的 position。
等待啟動的導航成功或失敗，除非設定 noWaitAfter 選項。

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

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

用法

await elementHandle.click();
await elementHandle.click(options);

引數

options Object (選用)
- button "left" | "right" | "middle" (選用)#
  
  預設為 left。
- clickCount number (選用)#
  
  預設為 1。請參閱 UIEvent.detail。
- delay number (選用)#
  
  mousedown 和 mouseup 之間等待的時間，以毫秒為單位。預設為 0。
- force boolean (選用)#
  
  是否要繞過可操作性檢查。預設為 false。
- modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (選用)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- noWaitAfter boolean (選用)#
  
  已棄用
  此選項在未來將預設為 true。
  
  啟動導航的動作正在等待這些導航發生，並等待頁面開始載入。您可以透過設定此旗標來選擇不等待。您只需要在特殊情況下使用此選項，例如導航到無法存取的頁面。預設為 false。
- position Object (選用)#
  - x number
  - y number
  相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。
- timeout number (選用)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。
- trial boolean (選用)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查並跳過動作。預設為 false。在等待元素準備好執行動作但不想實際執行動作時很有用。

傳回

Promise<void>#

dblclick

在 v1.9 之前新增

elementHandle.dblclick

不建議使用

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

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

等待元素上的可操作性檢查，除非設定 force 選項。
如果需要，將元素滾動到檢視畫面中。
使用 page.mouse 在元素的中心雙擊，或指定的 position。

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

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

注意

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

用法

await elementHandle.dblclick();
await elementHandle.dblclick(options);

引數

options Object (選用)
- button "left" | "right" | "middle" (選用)#
  
  預設為 left。
- delay number (選用)#
  
  mousedown 和 mouseup 之間等待的時間，以毫秒為單位。預設為 0。
- force boolean (選用)#
  
  是否要繞過可操作性檢查。預設為 false。
- modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (選用)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- noWaitAfter boolean (選用)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- position Object (選用)#
  - x number
  - y number
  相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。
- timeout number (選用)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。
- trial boolean (選用)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查並跳過動作。預設為 false。在等待元素準備好執行動作但不想實際執行動作時很有用。

傳回

Promise<void>#

dispatchEvent

在 v1.9 之前新增

elementHandle.dispatchEvent

不建議使用

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

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

用法

await elementHandle.dispatchEvent('click');

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

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

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

// Note you can only create DataTransfer in Chromium and Firefox
const dataTransfer = await page.evaluateHandle(() => new DataTransfer());
await elementHandle.dispatchEvent('dragstart', { dataTransfer });

引數

type string #

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

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

傳回

Promise<void>#

填寫

在 v1.9 之前新增

elementHandle.fill

不建議使用

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

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

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

若要發送更精細的鍵盤事件，請使用 locator.pressSequentially()。

用法

await elementHandle.fill(value);
await elementHandle.fill(value, options);

引數

value string #

要為 <input>、<textarea> 或 [contenteditable] 元素設定的值。
options Object (選用)
- force boolean (選填)加入於版本: v1.13#
  
  是否要繞過可操作性檢查。預設為 false。
- noWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

Promise<void>#

聚焦

在 v1.9 之前新增

elementHandle.focus

不建議使用

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

呼叫元素的 focus。

用法

await elementHandle.focus();

傳回

Promise<void>#

getAttribute

在 v1.9 之前新增

elementHandle.getAttribute

不建議使用

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

傳回元素屬性值。

用法

await elementHandle.getAttribute(name);

引數

name string #

要取得值的屬性名稱。

傳回

Promise<null | string>#

懸停

在 v1.9 之前新增

elementHandle.hover

不建議使用

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

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

等待元素上的可操作性檢查，除非設定了 force 選項。
如果需要，將元素滾動到檢視畫面中。
使用 page.mouse 將游標懸停在元素的中心，或指定的 position。

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

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

用法

await elementHandle.hover();
await elementHandle.hover(options);

引數

options Object (選用)
- force boolean (選填)#
  
  是否要繞過可操作性檢查。預設為 false。
- modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (選填)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- noWaitAfter boolean (選填)加入於版本: v1.28#
  
  已棄用
  此選項無效。
  
  此選項無效。
- position Object (選填)#
  - x number
  - y number
  相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。
- trial boolean (選用)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查並跳過動作。預設為 false。在等待元素準備好執行動作但不想實際執行動作時很有用。

傳回

Promise<void>#

innerHTML

在 v1.9 之前新增

elementHandle.innerHTML

不建議使用

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

傳回 element.innerHTML。

用法

await elementHandle.innerHTML();

傳回

Promise<string>#

innerText

在 v1.9 之前新增

elementHandle.innerText

不建議使用

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

傳回 element.innerText。

用法

await elementHandle.innerText();

傳回

Promise<string>#

inputValue

加入於版本: v1.13

elementHandle.inputValue

不建議使用

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

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

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

用法

await elementHandle.inputValue();
await elementHandle.inputValue(options);

引數

options Object (選用)
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

Promise<string>#

isChecked

在 v1.9 之前新增

elementHandle.isChecked

不建議使用

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

傳回元素是否被選取。如果元素不是核取方塊或單選按鈕輸入，則會拋出錯誤。

用法

await elementHandle.isChecked();

傳回

Promise<boolean>#

isDisabled

在 v1.9 之前新增

elementHandle.isDisabled

不建議使用

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

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

用法

await elementHandle.isDisabled();

傳回

Promise<boolean>#

isEditable

在 v1.9 之前新增

elementHandle.isEditable

不建議使用

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

傳回元素是否可編輯。

用法

await elementHandle.isEditable();

傳回

Promise<boolean>#

isEnabled

在 v1.9 之前新增

elementHandle.isEnabled

不建議使用

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

傳回元素是否啟用。

用法

await elementHandle.isEnabled();

傳回

Promise<boolean>#

isHidden

在 v1.9 之前新增

elementHandle.isHidden

不建議使用

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

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

用法

await elementHandle.isHidden();

傳回

Promise<boolean>#

isVisible

在 v1.9 之前新增

elementHandle.isVisible

不建議使用

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

傳回元素是否可見。

用法

await elementHandle.isVisible();

傳回

Promise<boolean>#

按下

在 v1.9 之前新增

elementHandle.press

不建議使用

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

聚焦元素，然後使用 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" 之類的快捷鍵。當使用修改鍵指定時，在按下後續按鍵時，會按下並按住修改鍵。

用法

await elementHandle.press(key);
await elementHandle.press(key, options);

引數

key string #

要按下的按鍵名稱或要產生的字元，例如 ArrowLeft 或 a。
options Object (選用)
- delay number (選填)#
  
  keydown 和 keyup 之間等待的時間，以毫秒為單位。預設為 0。
- noWaitAfter boolean (選填)#
  
  已棄用
  此選項在未來將預設為 true。
  
  啟動導航的動作正在等待這些導航發生，並等待頁面開始載入。您可以透過設定此旗標來選擇不等待。您只需要在特殊情況下使用此選項，例如導航到無法存取的頁面。預設為 false。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

Promise<void>#

screenshot

在 v1.9 之前新增

elementHandle.screenshot

不建議使用

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

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

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

傳回包含擷取螢幕截圖的 buffer。

用法

await elementHandle.screenshot();
await elementHandle.screenshot(options);

引數

options Object (選用)
- animations "disabled" | "allow" (選填)#
  
  當設定為 "disabled" 時，會停止 CSS 動畫、CSS 過場效果和 Web Animations。動畫會根據其持續時間獲得不同的處理方式
  - 有限動畫會快速轉到完成，因此它們會觸發 transitionend 事件。
  - 無限動畫會取消為初始狀態，然後在螢幕截圖後重新播放。
  預設為 "allow"，保持動畫不受影響。
- caret "hide" | "initial" (選填)#
  
  當設定為 "hide" 時，螢幕截圖將會隱藏文字游標。當設定為 "initial" 時，文字游標行為將不會變更。預設為 "hide"。
- mask Array<Locator> (選填)#
  
  指定在擷取螢幕截圖時應遮罩的定位器。遮罩的元素將會被粉紅色方塊 #FF00FF 覆蓋（可透過 maskColor 自訂），該方塊完全覆蓋其邊界框。
- maskColor string (選填)加入於版本: v1.35#
  
  以 CSS 色彩格式指定遮罩元素的覆蓋方塊顏色。預設顏色為粉紅色 #FF00FF。
- omitBackground boolean (選填)#
  
  隱藏預設白色背景，並允許擷取具有透明度的螢幕截圖。不適用於 jpeg 影像。預設為 false。
- path string (選填)#
  
  儲存影像的檔案路徑。螢幕截圖類型將從檔案副檔名推斷。如果 path 是相對路徑，則會相對於目前的工作目錄解析。如果未提供路徑，則影像將不會儲存到磁碟。
- quality number (選填)#
  
  影像的品質，介於 0-100 之間。不適用於 png 影像。
- scale "css" | "device" (選填)#
  
  當設定為 "css" 時，螢幕截圖的每個 CSS 像素將會有一個像素。對於高 dpi 裝置，這將使螢幕截圖保持較小。使用 "device" 選項將為每個裝置像素產生一個像素，因此高 dpi 裝置的螢幕截圖將會大兩倍甚至更大。
  
  預設為 "device"。
- style string (選填)加入於版本: v1.41#
  
  在製作螢幕截圖時要套用的樣式表文字。您可以在此處隱藏動態元素、使元素不可見或變更其屬性，以協助您建立可重複的螢幕截圖。此樣式表會穿透 Shadow DOM 並套用至內部框架。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。
- type "png" | "jpeg" (選填)#
  
  指定螢幕截圖類型，預設為 png。

傳回

Promise<Buffer>#

scrollIntoViewIfNeeded

在 v1.9 之前新增

elementHandle.scrollIntoViewIfNeeded

不建議使用

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

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

當 elementHandle 未指向連接到 Document 或 ShadowRoot 的元素時，會拋出錯誤。

請參閱捲動以取得捲動的替代方法。

用法

await elementHandle.scrollIntoViewIfNeeded();
await elementHandle.scrollIntoViewIfNeeded(options);

引數

options Object (選用)
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

Promise<void>#

selectOption

在 v1.9 之前新增

elementHandle.selectOption

不建議使用

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

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

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

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

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

用法

// Single selection matching the value or label
handle.selectOption('blue');

// single selection matching the label
handle.selectOption({ label: 'Blue' });

// multiple selection
handle.selectOption(['red', 'green', 'blue']);

引數

values null | string | ElementHandle | Array<string> | Object | Array<ElementHandle> | Array<Object>#
- value string (選填)
  
  依據 option.value 進行比對。選填。
- label string (選填)
  
  依據 option.label 進行比對。選填。
- index number (選填)
  
  依據索引進行比對。選填。
要選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有相符的選項，否則只會選取第一個符合傳遞選項的選項。字串值會同時比對值和標籤。如果所有指定的屬性都相符，則選項會被視為相符。
options Object (選用)
- force boolean (選填)加入於版本: v1.13#
  
  是否要繞過可操作性檢查。預設為 false。
- noWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

Promise<Array<string>>#

selectText

在 v1.9 之前新增

elementHandle.selectText

不建議使用

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

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

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

用法

await elementHandle.selectText();
await elementHandle.selectText(options);

引數

options Object (選用)
- force boolean (選填)加入於版本: v1.13#
  
  是否要繞過可操作性檢查。預設為 false。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

Promise<void>#

setChecked

加入於版本：v1.15

elementHandle.setChecked

不建議使用

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

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

確保元素為核取方塊或單選輸入框。否則，此方法會拋出錯誤。
如果元素已處於正確的勾選狀態，此方法會立即返回。
等待相符元素的可操作性檢查，除非設定了 force 選項。如果在檢查期間元素被分離，則會重試整個操作。
如果需要，將元素滾動到檢視畫面中。
使用 page.mouse 在元素的中心點擊。
確保元素現在已勾選或取消勾選。否則，此方法會拋出錯誤。

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

用法

await elementHandle.setChecked(checked);
await elementHandle.setChecked(checked, options);

引數

checked boolean #

是否勾選或取消勾選核取方塊。
options Object (選用)
- force boolean (選填)#
  
  是否要繞過可操作性檢查。預設為 false。
- noWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- position Object (選填)#
  - x number
  - y number
  相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。
- trial boolean (選填)#
  
  設定後，此方法僅執行可操作性檢查並跳過動作。預設為 false。在等待元素準備好執行動作但不想實際執行動作時很有用。

傳回

Promise<void>#

setInputFiles

在 v1.9 之前新增

elementHandle.setInputFiles

不建議使用

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

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

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

用法

await elementHandle.setInputFiles(files);
await elementHandle.setInputFiles(files, options);

引數

files string | Array<string> | Object | Array<Object>#
- name string
  
  檔案名稱
- mimeType string
  
  檔案類型
- buffer Buffer
  
  檔案內容
options Object (選用)
- noWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

Promise<void>#

tap

在 v1.9 之前新增

elementHandle.tap

不建議使用

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

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

等待元素的可操作性檢查，除非設定了 force 選項。
如果需要，將元素滾動到檢視畫面中。
使用 page.touchscreen 點擊元素的中心，或指定的 position。

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

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

注意

elementHandle.tap() 需要瀏覽器環境的 hasTouch 選項設定為 true。

用法

await elementHandle.tap();
await elementHandle.tap(options);

引數

options Object (選用)
- force boolean (選填)#
  
  是否要繞過可操作性檢查。預設為 false。
- modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (選填)#
  
  要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後將目前的修飾鍵還原。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。
- noWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- position Object (選填)#
  - x number
  - y number
  相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。
- trial boolean (選用)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查並跳過動作。預設為 false。在等待元素準備好執行動作但不想實際執行動作時很有用。

傳回

Promise<void>#

textContent

在 v1.9 之前新增

elementHandle.textContent

不建議使用

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

傳回 node.textContent。

用法

await elementHandle.textContent();

傳回

Promise<null | string>#

type

在 v1.9 之前新增

elementHandle.type

已棄用

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

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

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

用法

引數

text string #

要輸入到聚焦元素中的文字。
options Object (選用)
- delay number (選填)#
  
  按鍵之間等待的時間，以毫秒為單位。預設為 0。
- noWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

Promise<void>#

uncheck

在 v1.9 之前新增

elementHandle.uncheck

不建議使用

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

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

確保元素為核取方塊或單選輸入框。否則，此方法會拋出錯誤。如果元素已取消勾選，此方法會立即返回。
等待元素的可操作性檢查，除非設定了 force 選項。
如果需要，將元素滾動到檢視畫面中。
使用 page.mouse 在元素的中心點擊。
確保元素現在已取消勾選。否則，此方法會拋出錯誤。

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

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

用法

await elementHandle.uncheck();
await elementHandle.uncheck(options);

引數

options Object (選用)
- force boolean (選填)#
  
  是否要繞過可操作性檢查。預設為 false。
- noWaitAfter boolean (選填)#
  
  已棄用
  此選項無效。
  
  此選項無效。
- position Object (選用)新增於：v1.11#
  - x number
  - y number
  相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。
- trial boolean (選用)新增於：v1.11#
  
  設定後，此方法僅執行可操作性檢查並跳過動作。預設為 false。在等待元素準備好執行動作但不想實際執行動作時很有用。

傳回

Promise<void>#

waitForSelector

在 v1.9 之前新增

elementHandle.waitForSelector

不建議使用

請使用斷言可見性的 Web 斷言或基於 locator 的 locator.waitFor() 來代替。

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

等待相對於元素控制代碼的 selector 滿足 state 選項（在 DOM 中出現/消失，或變得可見/隱藏）。如果在呼叫方法時 selector 已經滿足條件，則該方法將立即返回。如果 selector 在 timeout 毫秒內未滿足條件，則該函數將拋出錯誤。

用法

await page.setContent(`<div><span></span></div>`);
const div = await page.$('div');
// Waiting for the 'span' selector relative to the div.
const span = await div.waitForSelector('span', { state: 'attached' });

注意

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

引數

selector string #

要查詢的選擇器。
options Object (選用)
- state "attached" | "detached" | "visible" | "hidden" (選填)#
  
  預設為 'visible'。可以是以下之一
  - 'attached' - 等待元素出現在 DOM 中。
  - 'detached' - 等待元素不在 DOM 中。
  - 'visible' - 等待元素具有非空的邊界框且沒有 visibility:hidden。請注意，沒有任何內容或具有 display:none 的元素具有空的邊界框，並且不被視為可見。
  - 'hidden' - 等待元素從 DOM 中分離，或具有空的邊界框或 visibility:hidden。這與 'visible' 選項相反。
- strict boolean (選填)加入於版本：v1.15#
  
  當為 true 時，呼叫需要 selector 解析為單個元素。如果給定的 selector 解析為多個元素，則呼叫會拋出異常。
- timeout number (選填)#
  
  最大等待時間，以毫秒為單位。預設為 0 - 無逾時。預設值可以透過組態中的 actionTimeout 選項變更，或使用 browserContext.setDefaultTimeout() 或 page.setDefaultTimeout() 方法變更。

傳回

Promise<null | ElementHandle>#

方法​

boundingBox​

contentFrame​

ownerFrame​

waitForElementState​

已棄用​

$​

$$​

$eval​

$$eval​

check​

click​

dblclick​

dispatchEvent​

填寫​

聚焦​

getAttribute​

懸停​

innerHTML​

innerText​

inputValue​

isChecked​

isDisabled​

isEditable​

isEnabled​

isHidden​

isVisible​

按下​

screenshot​

scrollIntoViewIfNeeded​

selectOption​

selectText​

setChecked​

setInputFiles​

tap​

textContent​

type​

uncheck​

waitForSelector​

方法

boundingBox

contentFrame

ownerFrame

waitForElementState

已棄用

$

$$

$eval

$$eval

check

click

dblclick

dispatchEvent

填寫

聚焦

getAttribute

懸停

innerHTML

innerText

inputValue

isChecked

isDisabled

isEditable

isEnabled

isHidden

isVisible

按下

screenshot

scrollIntoViewIfNeeded

selectOption

selectText

setChecked

setInputFiles

tap

textContent

type

uncheck

waitForSelector