ElementHandle

拡張元: JSHandle

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

推奨されません

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

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

ElementHandleは、JSHandle.dispose()でハンドルが破棄されない限り、DOM要素のガベージコレクションを防止します。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();

ロケーターを使用すると、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 ノードを参照する要素ハンドルのコンテンツフレームを返します。それ以外の場合は 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をスローします。タイムアウトをゼロに設定すると、この機能は無効になります。

使用法

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

引数

options ElementHandle.CheckOptions (オプション)
- setForce boolean (オプション)#
  
  アクション可能性チェックをバイパスするかどうか。デフォルトは false です。
- setNoWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- setPosition 位置 (オプション)追加されたバージョン: 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 位置 (オプション)#
  - 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 位置 (オプション)#
  - 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

推奨されません

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

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

このメソッドは、actionabilityチェックを待ち、要素にフォーカスを当て、値を入力し、入力後に`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 位置 (オプション)#
  - 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()を使用してください。ロケーターについて詳しくはこちらをご覧ください。

要素が非表示かどうかを返します。visibleの反対です。

使用法

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

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

このメソッドは、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> (オプション)#
  
  スクリーンショット撮影時にマスクされるロケーターを指定します。マスクされた要素は、その境界ボックスを完全に覆うピンクのボックス#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()を使用してください。ロケーターについて詳しくはこちらをご覧ください。

このメソッドは、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.selectOption()を使用してください。ロケーターについて詳しくはこちらをご覧ください。

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

戻り値

List<String>#

selectText

v1.9より前に追加

elementHandle.selectText

推奨されません

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

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

要素が関連するコントロールを持つ<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 位置 (オプション)#
  - 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がinput要素を指していることを期待します。ただし、要素が関連するcontrolを持つ<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 位置 (オプション)#
  - 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オプションが設定されていない限り、要素のactionabilityチェックを待ちます。
必要に応じて要素を表示するためにスクロールします。
要素の中心をクリックするには Page.mouse() を使用します。
要素がチェックされていないことを確認します。そうでない場合、このメソッドはエラーをスローします。

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

使用法

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

引数

options ElementHandle.UncheckOptions (オプション)
- setForce boolean (オプション)#
  
  アクション可能性チェックをバイパスするかどうか。デフォルトは false です。
- setNoWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- setPosition 位置 (オプション)追加されたバージョン: 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

推奨されません

代わりに、可視性を主張するWebアサーションまたはロケーターベースの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