ElementHandle

拡張元: JSHandle

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

推奨されません

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

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

jsHandle.dispose() でハンドルが破棄されない限り、ElementHandle は 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 (optional)
- 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() はそのプロミスが解決するのを待ち、その値を返します。

使用法

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() はそのプロミスが解決するのを待ち、その値を返します。

使用法

<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 (optional)
- 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 を使用して、要素の中心、または指定された position をクリックします。
noWaitAfter オプションが設定されていない限り、開始されたナビゲーションが成功するか失敗するまで待ちます。

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

使用法

await elementHandle.click();
await elementHandle.click(options);

引数

options Object (optional)
- 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 を使用して、要素の中心、または指定された position をダブルクリックします。

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

注

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

使用法

await elementHandle.dblclick();
await elementHandle.dblclick(options);

引数

options Object (optional)
- 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 (optional)
- 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 を使用して、要素の中心、または指定された position にホバーします。

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

使用法

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

引数

options Object (optional)
- force boolean (オプション)#
  
  アクション可能チェックをバイパスするかどうか。デフォルトはfalseです。
- modifiers Array<"Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"> (オプション)#
  
  押す修飾キー。操作中にこれらの修飾キーのみが押されていることを保証し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows と Linux では "Control" に、macOS では "Meta" に解決されます。
- noWaitAfter boolean (optional)追加バージョン: 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 を返します。

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

使用法

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

引数

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

要素が無効になっているか、enabled の反対であるかを返します。

使用法

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

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

使用法

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 (optional)
- 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 (optional)
- 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ピクセルにつき1ピクセルになります。高DPIデバイスの場合、これによりスクリーンショットが小さく保たれます。"device"オプションを使用すると、各デバイスピクセルにつき1ピクセルが生成されるため、高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 (optional)
- 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 (optional)
- 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 (optional)
- 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 (optional)
- 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 が入力要素を指すことを期待します。ただし、要素が関連付けられたコントロールを持つ <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 (optional)
- noWaitAfter boolean (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- timeout number (オプション)#
  
  最大タイムアウト時間（ミリ秒単位）。デフォルトは 0 (タイムアウトなし) です。デフォルト値は、config の actionTimeout オプション、または browserContext.setDefaultTimeout() または page.setDefaultTimeout() メソッドを使用して変更できます。

戻り値

Promise<void>#

tap

v1.9より前に追加

elementHandle.tap

推奨されません

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

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

force オプションが設定されていない限り、要素に対するアクション性チェックを待ちます。
必要に応じて要素を表示するためにスクロールします。
page.touchscreen を使用して、要素の中心、または指定された position をタップします。

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

注

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

使用法

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

引数

options Object (optional)
- 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 (optional)
- 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 から分離された場合、このメソッドはスローします。

使用法

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

引数

options Object (optional)
- 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への表示/非表示、または表示/非表示になる)。メソッドの呼び出し時にセレクターがすでに条件を満たしている場合、メソッドはすぐに返ります。セレクターが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' });

注

このメソッドはナビゲーションをまたいで機能しません。page.waitForSelector() を使用してください。

引数

selector string #

クエリするセレクター。
options Object (optional)
- state "attached" | "detached" | "visible" | "hidden" (任意)#
  
  デフォルトは'visible'です。以下のいずれかになります。
  - 'attached' - 要素がDOMに存在することを待ちます。
  - 'detached' - 要素がDOMに存在しないことを待ちます。
  - 'visible' - 要素が空でない境界ボックスを持ち、visibility:hiddenがないことを待ちます。コンテンツがない要素やdisplay:noneの要素は空の境界ボックスを持つため、可視とはみなされないことに注意してください。
  - 'hidden' - 要素がDOMからデタッチされているか、空の境界ボックスを持つか、またはvisibility:hiddenを持つことを待ちます。これは'visible'オプションとは逆です。
- strict boolean (optional)追加されたバージョン: 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