ElementHandle

extends: JSHandle

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

非推奨

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

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

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

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

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

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

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

ロケーターを使用すると、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 ノードを参照する要素ハンドルに対してコンテンツフレームを返します。それ以外の場合は 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 - タイムアウトなし。デフォルト値は、構成の 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

非推奨

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

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

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 オプションが設定されていない限り、要素の actionability チェックを待機します。
必要に応じて、要素をビューにスクロールします。
page.mouse を使用して、要素の中央をクリックします。
要素がチェックされたことを確認します。そうでない場合、このメソッドは例外をスローします。

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

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

使用例

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

引数

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

戻り値

Promise<void>#

click

v1.9 より前に追加

elementHandle.click

非推奨

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

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

force オプションが設定されていない限り、要素の actionability チェックを待機します。
必要に応じて、要素をビューにスクロールします。
page.mouse を使用して、要素の中央、または指定された position をクリックします。
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 (オプション)#
  
  actionability チェックをバイパスするかどうか。デフォルトは 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 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- trial boolean (オプション)v1.11 で追加#
  
  設定すると、このメソッドは actionability チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに、要素がアクションの準備が整うまで待機する場合に役立ちます。

戻り値

Promise<void>#

dblclick

v1.9 より前に追加

elementHandle.dblclick

非推奨

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

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

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

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

note

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 (オプション)#
  
  actionability チェックをバイパスするかどうか。デフォルトは 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 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- trial boolean (オプション)v1.11 で追加#
  
  設定すると、このメソッドは actionability チェックのみを実行し、アクションをスキップします。デフォルトは 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 ベースの locator.fill() を代わりに使用してください。locator についてはこちらをご覧ください。

このメソッドは、操作可能性のチェックを待ってから、要素をフォーカスし、値を入力し、入力後に 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 で追加#
  
  actionability チェックをバイパスするかどうか。デフォルトは false です。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- timeout number (オプション)#
  
  最大時間 (ミリ秒単位)。デフォルトは 0 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

focus

v1.9 より前に追加

elementHandle.focus

非推奨

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

要素上で focus を呼び出します。

使用例

await elementHandle.focus();

戻り値

Promise<void>#

getAttribute

v1.9 より前に追加

elementHandle.getAttribute

非推奨

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

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

使用例

await elementHandle.getAttribute(name);

引数

name string #

値を取得する属性の名前。

戻り値

Promise<null | string>#

hover

v1.9 より前に追加

elementHandle.hover

非推奨

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

このメソッドは、次の手順を実行して要素の上にマウスカーソルを合わせます。

force オプションが設定されていない限り、要素の操作可能性チェックを待ちます。
必要に応じて、要素をビューにスクロールします。
page.mouse を使用して、要素の中央、または指定された position の上にマウスカーソルを合わせます。

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

使用例

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

引数

options Object (オプション)
- force boolean (オプション)#
  
  actionability チェックをバイパスするかどうか。デフォルトは 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 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- trial boolean (オプション)v1.11 で追加#
  
  設定すると、このメソッドは actionability チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに、要素がアクションの準備が整うまで待機する場合に役立ちます。

戻り値

Promise<void>#

innerHTML

v1.9 より前に追加

elementHandle.innerHTML

非推奨

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

element.innerHTML を返します。

使用例

await elementHandle.innerHTML();

戻り値

Promise<string>#

innerText

v1.9 より前に追加

elementHandle.innerText

非推奨

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

element.innerText を返します。

使用例

await elementHandle.innerText();

戻り値

Promise<string>#

inputValue

バージョン v1.13 で追加

elementHandle.inputValue

非推奨

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

選択された <input>、<textarea>、または <select> 要素の input.value を返します。

input 要素以外の場合はエラーをスローします。ただし、要素が関連付けられたコントロールを持つ <label> 要素内にある場合、コントロールの値を返します。

使用例

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

引数

options Object (オプション)
- timeout number (オプション)#
  
  最大時間 (ミリ秒単位)。デフォルトは 0 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<string>#

isChecked

v1.9 より前に追加

elementHandle.isChecked

非推奨

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

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

使用例

await elementHandle.isChecked();

戻り値

Promise<boolean>#

isDisabled

v1.9 より前に追加

elementHandle.isDisabled

非推奨

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

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

使用例

await elementHandle.isDisabled();

戻り値

Promise<boolean>#

isEditable

v1.9 より前に追加

elementHandle.isEditable

非推奨

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

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

使用例

await elementHandle.isEditable();

戻り値

Promise<boolean>#

isEnabled

v1.9 より前に追加

elementHandle.isEnabled

非推奨

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

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

使用例

await elementHandle.isEnabled();

戻り値

Promise<boolean>#

isHidden

v1.9 より前に追加

elementHandle.isHidden

非推奨

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

要素が非表示になっているかどうかを返します。表示の反対です。

使用例

await elementHandle.isHidden();

戻り値

Promise<boolean>#

isVisible

v1.9 より前に追加

elementHandle.isVisible

非推奨

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

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

使用例

await elementHandle.isVisible();

戻り値

Promise<boolean>#

press

v1.9 より前に追加

elementHandle.press

非推奨

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

要素をフォーカスし、keyboard.down() と keyboard.up() を使用します。

key は、意図された keyboardEvent.key 値、またはテキストを生成するための単一の文字を指定できます。key 値のスーパーセットは、こちらにあります。キーの例を以下に示します。

F1 - F12, Digit0- Digit9, KeyA- KeyZ, Backquote, Minus, Equal, Backslash, Backspace, Tab, Delete, Escape, ArrowDown, End, Enter, Home, Insert, PageDown, PageUp, ArrowRight, ArrowUp など。

次の修飾子ショートカットもサポートされています。Shift、Control、Alt、Meta、ShiftLeft、ControlOrMeta。

Shift キーを押したままにすると、key に対応するテキストが大文字で入力されます。

key が単一の文字の場合、大文字と小文字が区別されるため、値 a と A はそれぞれ異なるテキストを生成します。

key: "Control+o"、key: "Control++、または key: "Control+Shift+T" などのショートカットもサポートされています。修飾子を指定すると、修飾子が押され、その後のキーが押されている間保持されます。

使用例

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

引数

key string #

押すキーの名前、または生成する文字 (ArrowLeft や a など)。
options Object (オプション)
- delay number (オプション)#
  
  keydown と keyup の間の待機時間 (ミリ秒単位)。デフォルトは 0 です。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは、将来デフォルトで true になります。
  
  ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページがロードを開始するのを待機しています。このフラグを設定すると、待機をオプトアウトできます。このオプションが必要になるのは、アクセスできないページに移動する場合などの例外的なケースのみです。デフォルトは false です。
- timeout number (オプション)#
  
  最大時間 (ミリ秒単位)。デフォルトは 0 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

screenshot

v1.9 より前に追加

elementHandle.screenshot

非推奨

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

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

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

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

使用例

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

引数

options Object (オプション)
- animations "disabled" | "allow" (オプション)#
  
  "disabled" に設定すると、CSS アニメーション、CSS トランジション、および Web Animations が停止します。アニメーションは、その期間に応じて異なる扱いを受けます。
  - 有限のアニメーションは完了まで早送りされるため、transitionend イベントが発生します。
  - 無限のアニメーションは初期状態にキャンセルされ、スクリーンショット後に再度再生されます。
  デフォルトは "allow" で、アニメーションはそのままです。
- caret "hide" | "initial" (オプション)#
  
  "hide" に設定すると、スクリーンショットはテキストカーソルを非表示にします。"initial" に設定すると、テキストカーソルの動作は変更されません。デフォルトは "hide" です。
- mask Array<Locator> (オプション)#
  
  スクリーンショットを撮るときにマスクするロケーターを指定します。マスクされた要素は、ピンク色のボックス #FF00FF (maskColor でカスタマイズ) でオーバーレイされ、そのバウンディングボックスを完全に覆います。マスクは非表示の要素にも適用されます。表示要素のみをマッチングを参照して、それを無効にしてください。
- maskColor string (オプション)バージョン v1.35 で追加#
  
  マスクされた要素のオーバーレイボックスの色を、CSS カラー形式で指定します。デフォルトの色はピンク #FF00FF です。
- omitBackground boolean (オプション)#
  
  デフォルトの白い背景を非表示にし、透明度のあるスクリーンショットをキャプチャできるようにします。jpeg 画像には適用されません。デフォルトは false です。
- path string (オプション)#
  
  画像を保存するファイルパス。スクリーンショットのタイプは、ファイル拡張子から推測されます。path が相対パスの場合、現在の作業ディレクトリからの相対パスとして解決されます。パスが指定されていない場合、画像はディスクに保存されません。
- quality number (オプション)#
  
  画像の品質 (0～100)。png 画像には適用されません。
- scale "css" | "device" (オプション)#
  
  "css" に設定すると、スクリーンショットはページ上の CSS ピクセルごとに 1 ピクセルになります。高 DPI デバイスの場合、これによりスクリーンショットのサイズが小さく保たれます。"device" オプションを使用すると、デバイスピクセルごとに 1 ピクセルが生成されるため、高 DPI デバイスのスクリーンショットは 2 倍以上に大きくなります。
  
  デフォルトは "device" です。
- style string (オプション)バージョン v1.41 で追加#
  
  スクリーンショットを作成中に適用するスタイルシートのテキスト。これは、動的な要素を非表示にしたり、要素を非表示にしたり、プロパティを変更して再現可能なスクリーンショットを作成するのに役立ちます。このスタイルシートは Shadow DOM を貫通し、内部フレームに適用されます。
- timeout number (オプション)#
  
  最大時間 (ミリ秒単位)。デフォルトは 0 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- type "png" | "jpeg" (オプション)#
  
  スクリーンショットのタイプを指定します。デフォルトは png です。

戻り値

Promise<Buffer>#

scrollIntoViewIfNeeded

v1.9 より前に追加

elementHandle.scrollIntoViewIfNeeded

非推奨

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

このメソッドは、操作可能性チェックを待ってから、要素をビューにスクロールしようとします。IntersectionObserver の ratio で定義されているように、完全に表示されている場合はスクロールしません。

elementHandle がドキュメントまたは ShadowRoot に接続されている要素を指していない場合、エラーをスローします。

スクロールの代替方法については、スクロールを参照してください。

使用例

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

引数

options Object (オプション)
- timeout number (オプション)#
  
  最大時間 (ミリ秒単位)。デフォルトは 0 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

selectOption

v1.9 より前に追加

elementHandle.selectOption

非推奨

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

このメソッドは、操作可能性チェックを待ってから、指定されたすべてのオプションが <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 で追加#
  
  actionability チェックをバイパスするかどうか。デフォルトは false です。
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- timeout number (オプション)#
  
  最大時間 (ミリ秒単位)。デフォルトは 0 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<Array<string>>#

selectText

v1.9 より前に追加

elementHandle.selectText

非推奨

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

このメソッドは、操作可能性チェックを待ってから、要素をフォーカスし、そのテキストコンテンツをすべて選択します。

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

使用例

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

引数

options Object (オプション)
- force boolean (オプション)バージョン v1.13 で追加#
  
  actionability チェックをバイパスするかどうか。デフォルトは false です。
- timeout number (オプション)#
  
  最大時間 (ミリ秒単位)。デフォルトは 0 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

setChecked

バージョン v1.15 で追加

elementHandle.setChecked

非推奨

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

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

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

使用例

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

引数

checked boolean #

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

戻り値

Promise<void>#

setInputFiles

v1.9 より前に追加

elementHandle.setInputFiles

非推奨

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

ファイルインプットの値を、これらのファイルパスまたはファイルに設定します。filePathsの一部が相対パスの場合、それらは現在のワーキングディレクトリからの相対パスとして解決されます。空の配列の場合、選択されたファイルはクリアされます。[webkitdirectory]属性を持つinput要素では、単一のディレクトリパスのみがサポートされます。

このメソッドは、ElementHandleがinput要素を指していることを期待します。ただし、要素が関連付けられたcontrolを持つ<label>要素内にある場合、代わりにcontrolをターゲットにします。

使用例

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

引数

files string | Array<string> | Object | Array<Object>#
- name string
  
  ファイル名
- mimeType string
  
  ファイルタイプ
- buffer Buffer
  
  ファイルの内容
options Object (オプション)
- noWaitAfter boolean (任意)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- timeout number (任意)#
  
  最大時間 (ミリ秒単位)。デフォルトは 0 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

tap

v1.9 より前に追加

elementHandle.tap

非推奨

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

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

操作性チェックが要素に対して実行されるのを待ちます。ただし、forceオプションが設定されている場合は除きます。
必要に応じて、要素をビューにスクロールします。
要素の中央、または指定されたpositionをタップするには、page.touchscreenを使用します。

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

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

note

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

使用例

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

引数

options Object (オプション)
- force boolean (任意)#
  
  actionability チェックをバイパスするかどうか。デフォルトは 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 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- trial boolean (オプション)v1.11 で追加#
  
  設定すると、このメソッドは actionability チェックのみを実行し、アクションをスキップします。デフォルトは 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 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

uncheck

v1.9 より前に追加

elementHandle.uncheck

非推奨

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

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

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

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

使用例

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

引数

options Object (オプション)
- force boolean (任意)#
  
  actionability チェックをバイパスするかどうか。デフォルトは false です。
- noWaitAfter boolean (任意)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- position Object (オプション)v1.11 で追加#
  - x number
  - y number
  要素のパディングボックスの左上隅を基準に使用するポイント。指定しない場合、要素の可視ポイントの一部を使用します。
- timeout number (任意)#
  
  最大時間 (ミリ秒単位)。デフォルトは 0 - タイムアウトなし。デフォルト値は、構成の actionTimeout オプションを使用するか、browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。
- trial boolean (オプション)v1.11 で追加#
  
  設定すると、このメソッドは actionability チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに、要素がアクションの準備が整うまで待機する場合に役立ちます。

戻り値

Promise<void>#

waitForSelector

v1.9 より前に追加

elementHandle.waitForSelector

非推奨

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

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

要素ハンドルを基準としたselectorが、stateオプション（DOMに現れる/消える、または可視/非表示になる）を満たすのを待ちます。メソッド呼び出しの時点でselectorがすでに条件を満たしている場合、メソッドはすぐに戻ります。セレクターがtimeoutミリ秒の間、条件を満たさない場合、関数は例外をスローします。

使用例

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

note

このメソッドはナビゲーションをまたいでは機能しません。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 - タイムアウトなし。デフォルト値は、構成の 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