ElementHandle

拡張: JSHandle

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

非推奨

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

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

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

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

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

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

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

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

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 ノードを参照する ElementHandle のコンテンツフレームを返します。それ以外の場合は 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 パラメータに応じて、このメソッドは actionability (操作可能状態) チェックのいずれかが合格するのを待ちます。"hidden" 状態を待つ場合を除き、待機中に要素がデタッチされると、このメソッドは例外をスローします。

"visible" 要素が可視になるまで待機します。
"hidden" 要素が非可視になるか、デタッチされるまで待機します。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 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

非推奨

$

追加: v1.9

elementHandle.$

非推奨

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

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

使用法

await elementHandle.$(selector);

引数

selector string #

クエリするセレクター。

戻り値

Promise<null | ElementHandle>#

$$

追加: v1.9

elementHandle.$$

非推奨

代わりにロケーターベースの page.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.check() を使用してください。ロケーターについてさらに詳しくはこちら。

このメソッドは、以下のステップを実行して要素をチェックします。

要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドは例外をスローします。要素がすでにチェックされている場合、このメソッドはすぐに戻ります。
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
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の何らかの可視点を使用します。
- timeout number (オプション)#
  
  最大時間（ミリ秒）。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- trial boolean (オプション)追加: v1.11#
  
  設定されている場合、このメソッドは操作可能状態チェックのみを実行し、アクションはスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

Promise<void>#

click

v1.9より前に追加

elementHandle.click

非推奨

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

このメソッドは、以下のステップを実行して要素をクリックします。

force オプションが設定されていない限り、要素に対する操作可能状態チェックが完了するまで待機します。
必要に応じて要素をビューにスクロールします。
page.mouse を使用して、要素の中心、または指定された位置をクリックします。
noWaitAfter オプションが設定されていない限り、開始されたナビゲーションが成功するか失敗するまで待機します。

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

使用法

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
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の何らかの可視点を使用します。
- timeout number (オプション)#
  
  最大時間（ミリ秒）。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- trial boolean (オプション)追加: v1.11#
  
  設定されている場合、このメソッドは操作可能状態チェックのみを実行し、アクションはスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

Promise<void>#

dblclick

v1.9より前に追加

elementHandle.dblclick

非推奨

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

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

force オプションが設定されていない限り、要素に対する操作可能状態チェックが完了するまで待機します。
必要に応じて要素をビューにスクロールします。
page.mouse を使用して、要素の中心、または指定された位置をダブルクリックします。

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

注

elementHandle.dblclick() は 2 つの click イベントと 1 つの 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
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の何らかの可視点を使用します。
- timeout number (オプション)#
  
  最大時間（ミリ秒）。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- trial boolean (オプション)追加: v1.11#
  
  設定されている場合、このメソッドは操作可能状態チェックのみを実行し、アクションはスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

Promise<void>#

dispatchEvent

v1.9より前に追加

elementHandle.dispatchEvent

非推奨

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

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

使用法

await elementHandle.dispatchEvent('click');

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

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>#

fill

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 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

focus

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>#

hover

v1.9より前に追加

elementHandle.hover

非推奨

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

このメソッドは、以下のステップを実行して要素にホバーします。

force オプションが設定されていない限り、要素に対する操作可能状態チェックが完了するまで待機します。
必要に応じて要素をビューにスクロールします。
page.mouse を使用して、要素の中心、または指定された位置にホバーします。

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

使用法

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
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の何らかの可視点を使用します。
- timeout number (オプション)#
  
  最大時間（ミリ秒）。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、config の 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 (タイムアウトなし) です。デフォルト値は、config の 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>#

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" などのショートカットもサポートされています。修飾子とともに指定された場合、修飾子が押され、その後のキーが押されている間も保持されます。

使用法

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 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

screenshot

v1.9より前に追加

elementHandle.screenshot

非推奨

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

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

このメソッドは、操作可能状態チェックを待ち、その後スクリーンショットを撮る前に要素をビューにスクロールします。要素が DOM からデタッチされている場合、このメソッドはエラーをスローします。

キャプチャされたスクリーンショットを含むバッファを返します。

使用法

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

引数

options Object (オプション)
- animations "disabled" | "allow" (オプション)#
  
  "disabled" に設定すると、CSS アニメーション、CSS トランジション、および Web アニメーションが停止します。アニメーションは、その期間に応じて異なる処理を受けます。
  - 有限のアニメーションは完了まで早送りされ、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 デバイスのスクリーンショットは 2 倍以上大きくなります。
  
  デフォルトは "device" です。
- style string (オプション)追加: v1.41#
  
  スクリーンショットを作成する際に適用するスタイルシートのテキスト。ここで、動的要素を非表示にしたり、要素を不可視にしたり、そのプロパティを変更して、再現可能なスクリーンショットの作成に役立てることができます。このスタイルシートは Shadow DOM を貫通し、内部フレームにも適用されます。
- timeout number (オプション)#
  
  最大時間（ミリ秒）。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、config の 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 (タイムアウトなし) です。デフォルト値は、config の 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 (タイムアウトなし) です。デフォルト値は、config の 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 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

setChecked

追加: v1.15

elementHandle.setChecked

非推奨

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

このメソッドは、以下のステップを実行して要素をチェックまたはチェック解除します。

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

使用法

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

引数

checked boolean #

チェックボックスをチェックまたはチェック解除するかどうか。
options Object (オプション)
- force boolean (オプション)#
  
  操作可能状態チェックをバイパスするかどうか。デフォルトは false です。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- position Object (オプション)#
  - x number
  - y number
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の何らかの可視点を使用します。
- timeout number (オプション)#
  
  最大時間（ミリ秒）。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- trial boolean (オプション)#
  
  設定されている場合、このメソッドは操作可能状態チェックのみを実行し、アクションはスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

Promise<void>#

setInputFiles

v1.9より前に追加

elementHandle.setInputFiles

非推奨

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

ファイル入力の値をこれらのファイルパスまたはファイルに設定します。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 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

tap

v1.9より前に追加

elementHandle.tap

非推奨

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

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

force オプションが設定されていない限り、要素に対する操作可能状態チェックが完了するまで待機します。
必要に応じて要素をビューにスクロールします。
page.touchscreen を使用して、要素の中心、または指定された位置をタップします。

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

注

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
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の何らかの可視点を使用します。
- timeout number (オプション)#
  
  最大時間（ミリ秒）。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- trial boolean (オプション)追加: v1.11#
  
  設定されている場合、このメソッドは操作可能状態チェックのみを実行し、アクションはスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

Promise<void>#

textContent

v1.9より前に追加

elementHandle.textContent

非推奨

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

node.textContent を返します。

使用法

await elementHandle.textContent();

戻り値

Promise<null | string>#

type

v1.9より前に追加

elementHandle.type

非推奨

ほとんどの場合、locator.fill() を使用してください。ページに特別なキーボード処理がある場合にのみ、キーを1つずつ押す必要があります。この場合、locator.pressSequentially() を使用してください。

要素にフォーカスを当て、次にテキスト内の各文字に対して keydown、keypress/input、および keyup イベントを送信します。

Control や ArrowDown のような特殊なキーを押すには、elementHandle.press() を使用してください。

使用法

引数

text string #

フォーカスされた要素に入力するテキスト。
options Object (オプション)
- delay number (オプション)#
  
  ミリ秒単位でキー入力間に待機する時間。デフォルトは0です。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- timeout number (オプション)#
  
  最大時間（ミリ秒）。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

uncheck

v1.9より前に追加

elementHandle.uncheck

非推奨

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

このメソッドは、以下のステップを実行して要素をチェックします。

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

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

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

使用法

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

引数

options Object (オプション)
- force boolean (オプション)#
  
  操作可能状態チェックをバイパスするかどうか。デフォルトは false です。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- position Object (オプション)追加: v1.11#
  - x number
  - y number
  要素のパディングボックスの左上隅を基準に使用する点。指定されていない場合、要素の何らかの可視点を使用します。
- timeout number (オプション)#
  
  最大時間（ミリ秒）。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- trial boolean (オプション)追加: v1.11#
  
  設定されている場合、このメソッドは操作可能状態チェックのみを実行し、アクションはスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備ができるまで待機する場合に便利です。

戻り値

Promise<void>#

waitForSelector

v1.9より前に追加

elementHandle.waitForSelector

非推奨

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

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

要素ハンドルに対するセレクターがstateオプション（DOMからの出現/消失、または可視/非可視になること）を満たすまで待機します。メソッド呼び出し時にセレクターが既に条件を満たしている場合、メソッドは直ちに返されます。タイムアウトミリ秒間、セレクターが条件を満たさない場合、関数は例外をスローします。

使用法

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の場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- timeout number (オプション)#
  
  最大時間（ミリ秒）。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<null | ElementHandle>#

メソッド​

boundingBox​

contentFrame​

ownerFrame​

waitForElementState​

非推奨​

$​

$$​

$eval​

$$eval​

check​

click​

dblclick​

dispatchEvent​

fill​

focus​

getAttribute​

hover​

innerHTML​

innerText​

inputValue​

isChecked​

isDisabled​

isEditable​

isEnabled​

isHidden​

isVisible​

press​

screenshot​

scrollIntoViewIfNeeded​

selectOption​

selectText​

setChecked​

setInputFiles​

tap​

textContent​

type​

uncheck​

waitForSelector​

メソッド

boundingBox

contentFrame

ownerFrame

waitForElementState

非推奨

$

$$

$eval

$$eval

check

click

dblclick

dispatchEvent

fill

focus

getAttribute

hover

innerHTML

innerText

inputValue

isChecked

isDisabled

isEditable

isEnabled

isHidden

isVisible

press

screenshot

scrollIntoViewIfNeeded

selectOption

selectText

setChecked

setInputFiles

tap

textContent

type

uncheck

waitForSelector