ElementHandle

extends: JSHandle

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

非推奨

ElementHandle の使用は推奨されません。Locator オブジェクトと Web-first アサーションを代わりに使用してください。

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" 要素が visible になるまで待機します。
"hidden" 要素が非表示になるか、アタッチされなくなるまで待機します。非表示の待機は、要素がデタッチされても例外をスローしないことに注意してください。
"stable" 要素が visible と stable の両方になるまで待機します。
"enabled" 要素が enabled になるまで待機します。
"disabled" 要素が disabled になるまで待機します。

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

戻り値

void #

dispatchEvent

v1.9 より前に追加

elementHandle.dispatchEvent

非推奨

代わりにロケーターベースの Locator.dispatchEvent() を使用してください。ロケーターの詳細をお読みください。

以下のスニペットは、要素の 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 (オプション)#

オプションのイベント固有の初期化プロパティ。

戻り値

void #

evalOnSelector

追加: v1.9

elementHandle.evalOnSelector

非推奨

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

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 ヘルパーメソッド、および Web-first アサーションの方が適しています。

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] 要素でない場合、このメソッドはエラーをスローします。ただし、要素が関連付けられた control を持つ <label> 要素内にある場合、代わりにコントロールが入力されます。

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

使用法

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

引数

value String #

<input>、<textarea>、または [contenteditable] 要素に設定する値。
options ElementHandle.FillOptions (オプション)
- setForce boolean (オプション)追加: v1.13#
  
  actionability チェックをバイパスするかどうか。デフォルトは 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 (オプション)#
  
  actionability チェックをバイパスするかどうか。デフォルトは 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#
  
  設定すると、このメソッドは actionability チェックのみを実行し、アクションをスキップします。デフォルトは 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() を使用してください。ロケーターの詳細をご覧ください。

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

このメソッドは、操作可能性チェックを待ってから、スクリーンショットを撮る前に要素をビューにスクロールします。要素が 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 がドキュメントまたは 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#
  
  actionability チェックをバイパスするかどうか。デフォルトは 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#
  
  actionability チェックをバイパスするかどうか。デフォルトは false です。
- setTimeout double (任意)#
  
  最大時間 (ミリ秒単位)。デフォルトは 30000 (30 秒) です。タイムアウトを無効にするには、0 を渡します。デフォルト値は、BrowserContext.setDefaultTimeout() または Page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

void #

setChecked

v1.15 で追加

elementHandle.setChecked

非推奨

代わりにロケーターベースの Locator.setChecked() を使用してください。ロケーターの詳細をご覧ください。

このメソッドは、次の手順を実行して要素をチェックまたはチェック解除します。

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

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

使用法

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

引数

checked boolean #

チェックボックスをチェックするかチェック解除するか。
options ElementHandle.SetCheckedOptions (任意)
- setForce boolean (任意)#
  
  actionability チェックをバイパスするかどうか。デフォルトは false です。
- setNoWaitAfter boolean (任意)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- setPosition 位置 (任意)#
  - setX double
  - setY double
  要素のパディングボックスの左上隅を基準に使用するポイント。指定しない場合、要素の表示されているポイントの一部を使用します。
- setTimeout double (任意)#
  
  最大時間 (ミリ秒単位)。デフォルトは 30000 (30 秒) です。タイムアウトを無効にするには、0 を渡します。デフォルト値は、BrowserContext.setDefaultTimeout() または Page.setDefaultTimeout() メソッドを使用して変更できます。
- setTrial boolean (任意)#
  
  設定すると、このメソッドは actionability チェックのみを実行し、アクションをスキップします。デフォルトは 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 オプションが設定されていない限り、要素の操作可能性チェックを待機します。
必要に応じて、要素をビューにスクロールします。
Page.touchscreen() を使用して、要素の中央、または指定された setPosition をタップします。

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

注

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

戻り値

void #

waitForSelector

v1.9 より前に追加

elementHandle.waitForSelector

非推奨

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

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

要素ハンドルに対する相対的な selector が setState オプション（DOM に出現/消滅するか、または可視/非可視になるか）を満たすまで待機します。メソッド呼び出しの時点で 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 #

クエリするセレクター。
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