ElementHandle

継承元: JSHandle

ElementHandleはページ内のDOM要素を表します。ElementHandleはPage.querySelector()メソッドで作成できます。

非推奨

ElementHandleの使用は非推奨であり、代わりにLocatorオブジェクトとウェブファーストのアサーションを使用してください。

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

JSHandle.dispose()でハンドルが破棄されない限り、ElementHandleはDOM要素がガベージコレクションされるのを防ぎます。ElementHandleは、その元となるフレームがナビゲートされると自動的に破棄されます。

ElementHandleインスタンスは、Page.evalOnSelector()およびPage.evaluate()メソッドの引数として使用できます。

LocatorとElementHandleの違いは、ElementHandleが特定の要素を指すのに対し、Locatorは要素を取得する方法のロジックを捉える点です。

以下の例では、ハンドルはページ上の特定のDOM要素を指しています。その要素のテキストが変更されたり、Reactによって全く異なるコンポーネントがレンダリングされたりしても、ハンドルは依然としてそのDOM要素を指しています。これは予期せぬ動作につながる可能性があります。

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

ロケーターを使用すると、`element`が使用されるたびに、セレクターを使用してページ内で最新のDOM要素が特定されます。したがって、以下のスニペットでは、基になるDOM要素は2回特定されることになります。

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

メソッド

boundingBox

v1.9より前に追加

elementHandle.boundingBox

このメソッドは、要素の境界ボックスを返します。要素が非表示の場合はnullを返します。境界ボックスはメインフレームのビューポート（通常はブラウザウィンドウと同じ）を基準に計算されます。

スクロールは返される境界ボックスに影響します。これはElement.getBoundingClientRectと同様です。つまり、xやyが負になることがあります。

子フレームの要素は、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ノードを参照するElementHandleのコンテンツフレームを返します。それ以外の場合はnullを返します。

使用法

ElementHandle.contentFrame();

戻り値

null | Frame #

ownerFrame

v1.9より前に追加

elementHandle.ownerFrame

指定された要素を含むフレームを返します。

使用法

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 (任意)
- setTimeout double (任意)#
  
  最大ミリ秒単位の時間。デフォルトは30000（30秒）です。タイムアウトを無効にするには0を渡します。デフォルト値はBrowserContext.setDefaultTimeout()またはPage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

void #

非推奨

check

v1.9より前に追加

elementHandle.check

非推奨

代わりにロケーターベースのLocator.check()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは以下の手順を実行して要素をチェックします。

要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドは例外をスローします。要素がすでにチェックされている場合、このメソッドは直ちに返ります。
setForceオプションが設定されていない限り、要素に対するactionabilityチェックを待機します。
必要に応じて要素をビューにスクロールします。
Page.mouse()を使用して要素の中心をクリックします。
要素がチェックされたことを確認します。そうでない場合、このメソッドは例外をスローします。

アクション中に要素がDOMからデタッチされた場合、このメソッドは例外をスローします。

すべてのステップの合計が指定されたsetTimeout内に完了しなかった場合、このメソッドはTimeoutErrorをスローします。タイムアウトに0を渡すと、これを無効にします。

使用法

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

引数

options ElementHandle.CheckOptions (任意)
- setForce boolean (任意)#
  
  操作可能性チェックをバイパスするかどうか。デフォルトはfalseです。
- setNoWaitAfter boolean (任意)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- setPosition Position (任意)追加されたバージョン: v1.11#
  - setX double
  - setY double
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の表示されているいずれかの点を使用します。
- setTimeout double (任意)#
  
  最大ミリ秒単位の時間。デフォルトは30000（30秒）です。タイムアウトを無効にするには0を渡します。デフォルト値はBrowserContext.setDefaultTimeout()またはPage.setDefaultTimeout()メソッドを使用して変更できます。
- setTrial boolean (任意)追加されたバージョン: v1.11#
  
  設定した場合、このメソッドは操作可能性チェックのみを実行し、アクションはスキップします。デフォルトはfalseです。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

void #

click

v1.9より前に追加

elementHandle.click

非推奨

代わりにロケーターベースのLocator.click()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは以下の手順を実行して要素をクリックします。

setForceオプションが設定されていない限り、要素に対するactionabilityチェックを待機します。
必要に応じて要素をビューにスクロールします。
Page.mouse()を使用して要素の中心、または指定されたsetPositionをクリックします。
setNoWaitAfterオプションが設定されていない限り、開始されたナビゲーションが成功するか失敗するまで待機します。

アクション中に要素がDOMからデタッチされた場合、このメソッドは例外をスローします。

使用法

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

引数

options ElementHandle.ClickOptions (任意)
- setButton enum MouseButton { LEFT, RIGHT, MIDDLE } (任意)#
  
  デフォルトはleftです。
- setClickCount int (任意)#
  
  デフォルトは1です。UIEvent.detailを参照してください。
- setDelay double (任意)#
  
  mousedownとmouseupの間の待機時間（ミリ秒単位）。デフォルトは0です。
- setForce boolean (任意)#
  
  操作可能性チェックをバイパスするかどうか。デフォルトはfalseです。
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (任意)#
  
  押す修飾キー。操作中にこれらの修飾キーのみが押され、その後現在の修飾キーが元に戻されることを保証します。指定されていない場合、現在押されている修飾キーが使用されます。"ControlOrMeta"はWindowsおよびLinuxでは"Control"に、macOSでは"Meta"に解決されます。
- setNoWaitAfter boolean (任意)#
  
  非推奨
  このオプションは将来的にtrueがデフォルトになります。
  
  ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページの読み込みが開始されるまで待機します。このフラグを設定することで、待機をオプトアウトできます。このオプションは、アクセスできないページにナビゲートするなどの例外的な場合にのみ必要です。デフォルトはfalseです。
- setPosition Position (任意)#
  - setX double
  - setY double
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の表示されているいずれかの点を使用します。
- setTimeout double (任意)#
  
  最大ミリ秒単位の時間。デフォルトは30000（30秒）です。タイムアウトを無効にするには0を渡します。デフォルト値はBrowserContext.setDefaultTimeout()またはPage.setDefaultTimeout()メソッドを使用して変更できます。
- setTrial boolean (任意)追加されたバージョン: v1.11#
  
  設定した場合、このメソッドは操作可能性チェックのみを実行し、アクションはスキップします。デフォルトはfalseです。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

void #

dblclick

v1.9より前に追加

elementHandle.dblclick

非推奨

代わりにロケーターベースのLocator.dblclick()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは以下の手順を実行して要素をダブルクリックします。

setForceオプションが設定されていない限り、要素に対するactionabilityチェックを待機します。
必要に応じて要素をビューにスクロールします。
Page.mouse()を使用して要素の中心、または指定されたsetPositionをダブルクリックします。

アクション中に要素がDOMからデタッチされた場合、このメソッドは例外をスローします。

注記

elementHandle.dblclick()は、2つのclickイベントと1つのdblclickイベントをディスパッチします。

使用法

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

引数

options ElementHandle.DblclickOptions (任意)
- setButton enum MouseButton { LEFT, RIGHT, MIDDLE } (任意)#
  
  デフォルトはleftです。
- setDelay double (任意)#
  
  mousedownとmouseupの間の待機時間（ミリ秒単位）。デフォルトは0です。
- setForce boolean (任意)#
  
  操作可能性チェックをバイパスするかどうか。デフォルトはfalseです。
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (任意)#
  
  押す修飾キー。操作中にこれらの修飾キーのみが押され、その後現在の修飾キーが元に戻されることを保証します。指定されていない場合、現在押されている修飾キーが使用されます。"ControlOrMeta"はWindowsおよびLinuxでは"Control"に、macOSでは"Meta"に解決されます。
- setNoWaitAfter boolean (任意)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- setPosition Position (任意)#
  - setX double
  - setY double
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の表示されているいずれかの点を使用します。
- setTimeout double (任意)#
  
  最大ミリ秒単位の時間。デフォルトは30000（30秒）です。タイムアウトを無効にするには0を渡します。デフォルト値はBrowserContext.setDefaultTimeout()またはPage.setDefaultTimeout()メソッドを使用して変更できます。
- setTrial boolean (任意)追加されたバージョン: v1.11#
  
  設定した場合、このメソッドは操作可能性チェックのみを実行し、アクションはスキップします。デフォルトはfalseです。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

void #

dispatchEvent

v1.9より前に追加

elementHandle.dispatchEvent

非推奨

代わりにロケーターベースのLocator.dispatchEvent()を使用してください。ロケーターについて詳しくはこちら。

以下のスニペットは、要素に対してclickイベントをディスパッチします。要素の表示状態に関係なく、clickがディスパッチされます。これはelement.click()を呼び出すことと同等です。

使用法

elementHandle.dispatchEvent("click");

内部的には、指定されたtypeに基づいてイベントのインスタンスを作成し、eventInitプロパティで初期化し、要素に対してディスパッチします。イベントはデフォルトでcomposed、cancelable、バブルします。

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 (任意)#

任意のイベント固有の初期化プロパティ。

戻り値

void #

evalOnSelector

追加されたバージョン: v1.9

elementHandle.evalOnSelector

非推奨

このメソッドは、要素が操作可能性チェックを通過するのを待たないため、不安定なテストにつながる可能性があります。代わりにLocator.evaluate()、その他のLocatorヘルパーメソッド、またはウェブファーストのアサーションを使用してください。

expressionの戻り値を返します。

このメソッドは、ElementHandleのサブツリー内で指定されたセレクターに一致する要素を見つけ、それをexpressionの最初の引数として渡します。セレクターに一致する要素がない場合、このメソッドはエラーをスローします。

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 #

クエリ対象のセレクター。
expression String #

ブラウザコンテキストで評価されるJavaScript式。式が関数に評価される場合、その関数は自動的に呼び出されます。
arg EvaluationArgument (任意)#

expressionに渡す任意の引数。

戻り値

Object #

evalOnSelectorAll

追加されたバージョン: v1.9

elementHandle.evalOnSelectorAll

非推奨

ほとんどの場合、Locator.evaluateAll()、その他のLocatorヘルパーメソッド、およびウェブファーストのアサーションの方が適しています。

expressionの戻り値を返します。

このメソッドは、ElementHandleのサブツリー内で指定されたセレクターに一致するすべての要素を見つけ、一致した要素の配列を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 #

クエリ対象のセレクター。
expression String #

ブラウザコンテキストで評価されるJavaScript式。式が関数に評価される場合、その関数は自動的に呼び出されます。
arg EvaluationArgument (任意)#

expressionに渡す任意の引数。

戻り値

Object #

fill

v1.9より前に追加

elementHandle.fill

非推奨

代わりにロケーターベースのLocator.fill()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは、操作可能性チェックを待ち、要素にフォーカスし、要素を埋め、埋め終わった後にinputイベントをトリガーします。入力フィールドをクリアするために空の文字列を渡すことができることに注意してください。

ターゲット要素が<input>、<textarea>、または[contenteditable]要素でない場合、このメソッドはエラーをスローします。ただし、要素が関連付けられたコントロールを持つ<label>要素内にある場合、代わりにそのコントロールが埋められます。

きめ細かなキーボードイベントを送信するには、Locator.pressSequentially()を使用してください。

使用法

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

引数

value String #

<input>、<textarea>、または[contenteditable]要素に設定する値。
options ElementHandle.FillOptions (任意)
- setForce boolean (任意)追加されたバージョン: v1.13#
  
  操作可能性チェックをバイパスするかどうか。デフォルトはfalseです。
- setNoWaitAfter boolean (任意)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- setTimeout double (任意)#
  
  最大ミリ秒単位の時間。デフォルトは30000（30秒）です。タイムアウトを無効にするには0を渡します。デフォルト値はBrowserContext.setDefaultTimeout()またはPage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

void #

focus

v1.9より前に追加

elementHandle.focus

非推奨

代わりにロケーターベースのLocator.focus()を使用してください。ロケーターについて詳しくはこちら。

要素に対してfocusを呼び出します。

使用法

ElementHandle.focus();

戻り値

void #

getAttribute

v1.9より前に追加

elementHandle.getAttribute

非推奨

代わりにロケーターベースのLocator.getAttribute()を使用してください。ロケーターについて詳しくはこちら。

要素の属性値を返します。

使用法

ElementHandle.getAttribute(name);

引数

name String #

値を取得する属性名。

戻り値

null | String #

hover

v1.9より前に追加

elementHandle.hover

非推奨

代わりにロケーターベースのLocator.hover()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは以下の手順を実行して要素にホバーします。

setForceオプションが設定されていない限り、要素に対するactionabilityチェックを待機します。
必要に応じて要素をビューにスクロールします。
Page.mouse()を使用して要素の中心、または指定されたsetPositionにホバーします。

アクション中に要素がDOMからデタッチされた場合、このメソッドは例外をスローします。

使用法

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

引数

options ElementHandle.HoverOptions (任意)
- setForce boolean (任意)#
  
  操作可能性チェックをバイパスするかどうか。デフォルトは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
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の表示されているいずれかの点を使用します。
- setTimeout double (任意)#
  
  最大ミリ秒単位の時間。デフォルトは30000（30秒）です。タイムアウトを無効にするには0を渡します。デフォルト値はBrowserContext.setDefaultTimeout()またはPage.setDefaultTimeout()メソッドを使用して変更できます。
- setTrial boolean (任意)追加されたバージョン: v1.11#
  
  設定した場合、このメソッドは操作可能性チェックのみを実行し、アクションはスキップします。デフォルトはfalseです。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

void #

innerHTML

v1.9より前に追加

elementHandle.innerHTML

非推奨

代わりにロケーターベースのLocator.innerHTML()を使用してください。ロケーターについて詳しくはこちら。

element.innerHTMLを返します。

使用法

ElementHandle.innerHTML();

戻り値

String #

innerText

v1.9より前に追加

elementHandle.innerText

非推奨

代わりにロケーターベースのLocator.innerText()を使用してください。ロケーターについて詳しくはこちら。

element.innerTextを返します。

使用法

ElementHandle.innerText();

戻り値

String #

inputValue

追加されたバージョン: v1.13

elementHandle.inputValue

非推奨

代わりにロケーターベースのLocator.inputValue()を使用してください。ロケーターについて詳しくはこちら。

選択した<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.isChecked()を使用してください。ロケーターについて詳しくはこちら。

要素がチェックされているかどうかを返します。要素がチェックボックスまたはラジオ入力でない場合、例外をスローします。

使用法

ElementHandle.isChecked();

戻り値

boolean #

isDisabled

v1.9より前に追加

elementHandle.isDisabled

非推奨

代わりにロケーターベースのLocator.isDisabled()を使用してください。ロケーターについて詳しくはこちら。

要素が無効になっているかどうか、つまり有効の反対を返します。

使用法

ElementHandle.isDisabled();

戻り値

boolean #

isEditable

v1.9より前に追加

elementHandle.isEditable

非推奨

代わりにロケーターベースのLocator.isEditable()を使用してください。ロケーターについて詳しくはこちら。

要素が編集可能かどうかを返します。

使用法

ElementHandle.isEditable();

戻り値

boolean #

isEnabled

v1.9より前に追加

elementHandle.isEnabled

非推奨

代わりにロケーターベースのLocator.isEnabled()を使用してください。ロケーターについて詳しくはこちら。

要素が有効かどうかを返します。

使用法

ElementHandle.isEnabled();

戻り値

boolean #

isHidden

v1.9より前に追加

elementHandle.isHidden

非推奨

代わりにロケーターベースのLocator.isHidden()を使用してください。ロケーターについて詳しくはこちら。

要素が非表示かどうか、つまり表示の反対を返します。

使用法

ElementHandle.isHidden();

戻り値

boolean #

isVisible

v1.9より前に追加

elementHandle.isVisible

非推奨

代わりにロケーターベースのLocator.isVisible()を使用してください。ロケーターについて詳しくはこちら。

要素が表示されているかどうかを返します。

使用法

ElementHandle.isVisible();

戻り値

boolean #

press

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"などのショートカットもサポートされています。修飾キーを指定した場合、修飾キーが押されたまま、後続のキーが押されます。

使用法

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

非推奨

代わりにロケーターベースのPage.locator()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは、ElementHandleのサブツリー内で指定されたセレクターに一致する要素を見つけます。セレクターに一致する要素がない場合、nullを返します。

使用法

ElementHandle.querySelector(selector);

引数

selector String #

クエリ対象のセレクター。

戻り値

null | ElementHandle #

querySelectorAll

追加されたバージョン: v1.9

elementHandle.querySelectorAll

非推奨

代わりにロケーターベースのPage.locator()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは、ElementHandleのサブツリー内で指定されたセレクターに一致するすべての要素を見つけます。セレクターに一致する要素がない場合、空の配列を返します。

使用法

ElementHandle.querySelectorAll(selector);

引数

selector String #

クエリ対象のセレクター。

戻り値

List<ElementHandle>#

screenshot

v1.9より前に追加

elementHandle.screenshot

非推奨

代わりにロケーターベースのLocator.screenshot()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは、ページ全体のスクリーンショットを、この特定の要素のサイズと位置にクリップしてキャプチャします。要素が他の要素に覆われている場合、スクリーンショットには実際には表示されません。要素がスクロール可能なコンテナである場合、スクリーンショットには現在スクロールされているコンテンツのみが表示されます。

このメソッドは、操作可能性チェックを待ち、スクリーンショットを撮る前に要素をビューにスクロールします。要素が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> (任意)#
  
  スクリーンショットを撮る際にマスクするロケーターを指定します。マスクされた要素は、その境界ボックスを完全に覆うピンク色のボックス#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ピクセルにつき1ピクセルを持ちます。高DPIデバイスの場合、これによりスクリーンショットが小さく保たれます。"device"オプションを使用すると、各デバイスピクセルにつき1ピクセルが生成されるため、高DPIデバイスのスクリーンショットは2倍以上大きくなる可能性があります。
  
  デフォルトは"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.scrollIntoViewIfNeeded()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは操作可能性チェックを待ち、その後、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.selectOption()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは、操作可能性チェックを待ち、指定されたすべてのオプションが<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 (任意)追加されたバージョン: v1.13#
  
  操作可能性チェックをバイパスするかどうか。デフォルトはfalseです。
- setNoWaitAfter boolean (任意)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- setTimeout double (任意)#
  
  最大ミリ秒単位の時間。デフォルトは30000（30秒）です。タイムアウトを無効にするには0を渡します。デフォルト値はBrowserContext.setDefaultTimeout()またはPage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

List<String>#

selectText

v1.9より前に追加

elementHandle.selectText

非推奨

代わりにロケーターベースのLocator.selectText()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは操作可能性チェックを待ち、その後要素にフォーカスし、そのテキストコンテンツ全体を選択します。

要素が関連付けられたコントロールを持つ<label>要素内にある場合、代わりにそのコントロールにフォーカスし、テキストを選択します。

使用法

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

引数

options ElementHandle.SelectTextOptions (任意)
- setForce boolean (任意)追加されたバージョン: v1.13#
  
  操作可能性チェックをバイパスするかどうか。デフォルトはfalseです。
- setTimeout double (任意)#
  
  最大ミリ秒単位の時間。デフォルトは30000（30秒）です。タイムアウトを無効にするには0を渡します。デフォルト値はBrowserContext.setDefaultTimeout()またはPage.setDefaultTimeout()メソッドを使用して変更できます。

戻り値

void #

setChecked

追加されたバージョン: v1.15

elementHandle.setChecked

非推奨

代わりにロケーターベースのLocator.setChecked()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは以下の手順を実行して要素をチェックまたはアンチェックします。

要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドは例外をスローします。
要素がすでに正しいチェック状態にある場合、このメソッドは直ちに返ります。
setForceオプションが設定されていない限り、一致した要素に対するactionabilityチェックを待機します。チェック中に要素がデタッチされた場合、アクション全体が再試行されます。
必要に応じて要素をビューにスクロールします。
Page.mouse()を使用して要素の中心をクリックします。
要素がチェックまたはアンチェックされていることを確認します。そうでない場合、このメソッドは例外をスローします。

使用法

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

引数

checked boolean #

チェックボックスをチェックするか、アンチェックするか。
options ElementHandle.SetCheckedOptions (任意)
- setForce boolean (任意)#
  
  操作可能性チェックをバイパスするかどうか。デフォルトはfalseです。
- setNoWaitAfter boolean (任意)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- setPosition Position (任意)#
  - setX double
  - setY double
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の表示されているいずれかの点を使用します。
- setTimeout double (任意)#
  
  最大ミリ秒単位の時間。デフォルトは30000（30秒）です。タイムアウトを無効にするには0を渡します。デフォルト値はBrowserContext.setDefaultTimeout()またはPage.setDefaultTimeout()メソッドを使用して変更できます。
- setTrial boolean (任意)#
  
  設定した場合、このメソッドは操作可能性チェックのみを実行し、アクションはスキップします。デフォルトはfalseです。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

void #

setInputFiles

v1.9より前に追加

elementHandle.setInputFiles

非推奨

代わりにロケーターベースのLocator.setInputFiles()を使用してください。ロケーターについて詳しくはこちら。

ファイル入力の値をこれらのファイルパスまたはファイルに設定します。filePathsの一部が相対パスの場合、現在の作業ディレクトリを基準に解決されます。空の配列の場合、選択されたファイルをクリアします。[webkitdirectory]属性を持つ入力の場合、単一のディレクトリパスのみがサポートされます。

このメソッドは、ElementHandleが入力要素を指していることを期待します。ただし、要素が関連付けられたコントロールを持つ<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.tap()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは以下の手順を実行して要素をタップします。

setForceオプションが設定されていない限り、要素に対するactionabilityチェックを待機します。
必要に応じて要素をビューにスクロールします。
Page.touchscreen()を使用して要素の中心、または指定されたsetPositionをタップします。

アクション中に要素がDOMからデタッチされた場合、このメソッドは例外をスローします。

注記

elementHandle.tap()は、ブラウザコンテキストのhasTouchオプションがtrueに設定されている必要があります。

使用法

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

引数

options ElementHandle.TapOptions (任意)
- setForce boolean (任意)#
  
  操作可能性チェックをバイパスするかどうか。デフォルトはfalseです。
- setModifiers List<enum KeyboardModifier { ALT, CONTROL, CONTROLORMETA, META, SHIFT }> (任意)#
  
  押す修飾キー。操作中にこれらの修飾キーのみが押され、その後現在の修飾キーが元に戻されることを保証します。指定されていない場合、現在押されている修飾キーが使用されます。"ControlOrMeta"はWindowsおよびLinuxでは"Control"に、macOSでは"Meta"に解決されます。
- setNoWaitAfter boolean (任意)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- setPosition Position (任意)#
  - setX double
  - setY double
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の表示されているいずれかの点を使用します。
- setTimeout double (任意)#
  
  最大ミリ秒単位の時間。デフォルトは30000（30秒）です。タイムアウトを無効にするには0を渡します。デフォルト値はBrowserContext.setDefaultTimeout()またはPage.setDefaultTimeout()メソッドを使用して変更できます。
- setTrial boolean (任意)追加されたバージョン: v1.11#
  
  設定した場合、このメソッドは操作可能性チェックのみを実行し、アクションはスキップします。デフォルトはfalseです。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

void #

textContent

v1.9より前に追加

elementHandle.textContent

非推奨

代わりにロケーターベースのLocator.textContent()を使用してください。ロケーターについて詳しくはこちら。

node.textContentを返します。

使用法

ElementHandle.textContent();

戻り値

null | String #

type

v1.9より前に追加

elementHandle.type

非推奨

ほとんどの場合、代わりにLocator.fill()を使用する必要があります。ページに特別なキーボード処理がある場合にのみ、キーを1つずつ押す必要があります。その場合は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.uncheck()を使用してください。ロケーターについて詳しくはこちら。

このメソッドは以下の手順を実行して要素をチェックします。

要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドは例外をスローします。要素がすでにアンチェックされている場合、このメソッドは直ちに返ります。
操作可能性チェックが要素に対して行われるのを待機します。ただし、setForceオプションが設定されている場合は除きます。
必要に応じて要素をビューにスクロールします。
Page.mouse()を使用して要素の中心をクリックします。
要素がチェックされていない状態であることを確認します。そうでない場合、このメソッドは例外をスローします。

アクション中に要素がDOMからデタッチされた場合、このメソッドは例外をスローします。

指定されたsetTimeout期間中にすべてのステップが完了しなかった場合、このメソッドはTimeoutErrorをスローします。タイムアウトにゼロを渡すと、これを無効にできます。

使用法

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

引数

options ElementHandle.UncheckOptions (任意)
- setForce boolean (任意)#
  
  操作可能性チェックをバイパスするかどうか。デフォルトはfalseです。
- setNoWaitAfter boolean (任意)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- setPosition Position (任意)追加されたバージョン: v1.11#
  - setX double
  - setY double
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の表示されているいずれかの点を使用します。
- setTimeout double (任意)#
  
  最大ミリ秒単位の時間。デフォルトは30000（30秒）です。タイムアウトを無効にするには0を渡します。デフォルト値はBrowserContext.setDefaultTimeout()またはPage.setDefaultTimeout()メソッドを使用して変更できます。
- setTrial boolean (任意)追加されたバージョン: v1.11#
  
  設定した場合、このメソッドは操作可能性チェックのみを実行し、アクションはスキップします。デフォルトはfalseです。アクションを実行せずに、要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

void #

waitForSelector

v1.9より前に追加

elementHandle.waitForSelector

非推奨

可視性をアサートするウェブアサーション、またはロケーターベースのLocator.waitFor()を使用してください。

セレクターによって指定された要素がsetStateオプションを満たしたときに要素を返します。hiddenまたはdetachedを待機している場合はnullを返します。

要素ハンドルに対するセレクターがsetStateオプション（DOMに表示/非表示になる、または可視/非可視になる）を満たすのを待機します。メソッド呼び出し時にセレクターがすでに条件を満たしている場合、メソッドは直ちに返します。セレクターが指定された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 #

クエリ対象のセレクター。
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の場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- 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