ElementHandle

拡張元: JSHandle

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

推奨されません

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

var handle = await page.QuerySelectorAsync("a");
await handle.ClickAsync();

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

ElementHandle インスタンスは、Page.EvalOnSelectorAsync() メソッドと Page.EvaluateAsync() メソッドの引数として使用できます。

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

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

var handle = await page.QuerySelectorAsync("text=Submit");
await handle.HoverAsync();
await handle.ClickAsync();

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

var locator = page.GetByText("Submit");
await locator.HoverAsync();
await locator.ClickAsync();

メソッド

BoundingBoxAsync

v1.9より前に追加

elementHandle.BoundingBoxAsync

このメソッドは、要素のバウンディングボックスを返します。要素が非表示の場合は null を返します。バウンディングボックスは、メインフレームのビューポート（通常はブラウザウィンドウと同じ）を基準に計算されます。

スクロールは、Element.getBoundingClientRect と同様に、返される境界ボックスに影響を与えます。つまり、x および/または y が負になる可能性があります。

子フレームの要素は、Element.getBoundingClientRect とは異なり、メインフレームを基準とした境界ボックスを返します。

ページが静的であると仮定すると、境界ボックスの座標を使用して入力を実行するのは安全です。たとえば、次のスニペットは要素の中心をクリックするはずです。

使用法

var box = await elementHandle.BoundingBoxAsync();
await page.Mouse.ClickAsync(box.X + box.Width / 2, box.Y + box.Height / 2);

戻り値

BoundingBox?#
- x [float]
  
  要素の x 座標 (ピクセル単位)。
- y [float]
  
  要素の y 座標 (ピクセル単位)。
- width [float]
  
  要素の幅 (ピクセル単位)。
- height [float]
  
  要素の高さ (ピクセル単位)。

ContentFrameAsync

v1.9より前に追加

elementHandle.ContentFrameAsync

iframe ノードを参照する要素ハンドルのコンテンツフレームを返します。それ以外の場合は null を返します。

使用法

await ElementHandle.ContentFrameAsync();

戻り値

Frame?#

OwnerFrameAsync

v1.9より前に追加

elementHandle.OwnerFrameAsync

指定された要素を含むフレームを返します。

使用法

await ElementHandle.OwnerFrameAsync();

戻り値

Frame?#

WaitForElementStateAsync

v1.9より前に追加

elementHandle.WaitForElementStateAsync

要素がstateを満たしたときに返ります。

state パラメータに応じて、このメソッドはアクション可能性チェックのいずれかがパスするまで待機します。"hidden" 状態を待機する場合を除き、待機中に要素がデタッチされると、このメソッドは例外をスローします。

"visible" 要素が表示されるまで待機します。
"hidden" 要素が非表示になるか、アタッチされていない状態になるまで待機します。要素がデタッチされても、hidden 状態の待機では例外がスローされないことに注意してください。
"stable" 要素が表示され、かつ安定するまで待機します。
"enabled" 要素が有効になるまで待機します。
"disabled" 要素が無効になるまで待機します。
"editable" 要素が編集可能になるまで待機します。

要素がTimeoutミリ秒間条件を満たさない場合、このメソッドは例外をスローします。

使用法

await ElementHandle.WaitForElementStateAsync(state, options);

引数

state enum ElementState { Visible, Hidden, Stable, Enabled, Disabled, Editable }#

待機する状態。詳細については下記を参照してください。
options ElementHandleWaitForElementStateOptions? (オプション)
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。

戻り値

void #

非推奨

CheckAsync

v1.9より前に追加

elementHandle.CheckAsync

推奨されません

ロケーターベースのLocator.CheckAsync()を使用してください。ロケーターについて詳しく読む。

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

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

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

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

使用法

await ElementHandle.CheckAsync(options);

引数

options ElementHandleCheckOptions? (オプション)
- Force bool? (オプション)#
  
  実行可能性チェックをバイパスするかどうか。デフォルトは false です。
- NoWaitAfter bool? (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- Position Position? (optional)追加されたバージョン: v1.11#
  - X [float]
  - Y [float]
  要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
- Trial bool? (optional)追加されたバージョン: v1.11#
  
  設定されている場合、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトはfalseです。アクションを実行せずに要素がアクションの準備ができるまで待機するのに便利です。

戻り値

void #

ClickAsync

v1.9より前に追加

elementHandle.ClickAsync

推奨されません

ロケーターベースのLocator.ClickAsync()を使用してください。ロケーターについて詳しく読む。

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

Force オプションが設定されていない限り、要素に対するアクション可能性チェックを待ちます。
必要に応じて要素を表示するためにスクロールします。
要素の中心、または指定されたPositionでクリックするには、Page.Mouseを使用します。
NoWaitAfter オプションが設定されていない限り、開始されたナビゲーションが成功または失敗するまで待ちます。

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

使用法

await ElementHandle.ClickAsync(options);

引数

options ElementHandleClickOptions? (オプション)
- Button enum MouseButton { Left, Right, Middle }? (オプション)#
  
  デフォルトは left です。
- ClickCount int? (オプション)#
  
  デフォルトは 1 です。UIEvent.detail を参照してください。
- Delay [float]? (オプション)#
  
  mousedown と mouseup の間の待機時間 (ミリ秒単位)。デフォルトは 0 です。
- Force bool? (オプション)#
  
  実行可能性チェックをバイパスするかどうか。デフォルトは false です。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (オプション)#
  
  押す修飾キー。操作中にこれらの修飾キーのみが押されていることを保証し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows と Linux では "Control" に、macOS では "Meta" に解決されます。
- NoWaitAfter bool? (オプション)#
  
  非推奨
  このオプションは将来 true になります。
  
  ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページがロードを開始するのを待機します。このフラグを設定することで、待機をオプトアウトできます。これは、アクセスできないページにナビゲートするなどの例外的な場合にのみ必要です。デフォルトは false です。
- Position Position? (オプション)#
  - X [float]
  - Y [float]
  要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
- Trial bool? (optional)追加されたバージョン: v1.11#
  
  設定されている場合、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトはfalseです。アクションを実行せずに要素がアクションの準備ができるまで待機するのに便利です。

戻り値

void #

DblClickAsync

v1.9より前に追加

elementHandle.DblClickAsync

推奨されません

ロケーターベースのLocator.DblClickAsync()を使用してください。ロケーターについて詳しく読む。

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

Force オプションが設定されていない限り、要素に対するアクション可能性チェックを待ちます。
必要に応じて要素を表示するためにスクロールします。
要素の中心、または指定されたPositionでダブルクリックするには、Page.Mouseを使用します。

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

注

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

使用法

await ElementHandle.DblClickAsync(options);

引数

options ElementHandleDblClickOptions? (オプション)
- Button enum MouseButton { Left, Right, Middle }? (オプション)#
  
  デフォルトは left です。
- Delay [float]? (オプション)#
  
  mousedown と mouseup の間の待機時間 (ミリ秒単位)。デフォルトは 0 です。
- Force bool? (オプション)#
  
  実行可能性チェックをバイパスするかどうか。デフォルトは false です。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (オプション)#
  
  押す修飾キー。操作中にこれらの修飾キーのみが押されていることを保証し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows と Linux では "Control" に、macOS では "Meta" に解決されます。
- NoWaitAfter bool? (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- Position Position? (オプション)#
  - X [float]
  - Y [float]
  要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
- Trial bool? (optional)追加されたバージョン: v1.11#
  
  設定されている場合、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトはfalseです。アクションを実行せずに要素がアクションの準備ができるまで待機するのに便利です。

戻り値

void #

DispatchEventAsync

v1.9より前に追加

elementHandle.DispatchEventAsync

推奨されません

ロケーターベースのLocator.DispatchEventAsync()を使用してください。ロケーターについて詳しく読む。

以下のスニペットは、要素に対して click イベントをディスパッチします。要素の表示状態にかかわらず、click がディスパッチされます。これは element.click() を呼び出すことと同等です。

使用法

await elementHandle.DispatchEventAsync("click");

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

eventInitはイベント固有であるため、初期プロパティのリストについてはイベントのドキュメントを参照してください。

ライブオブジェクトをイベントに渡したい場合は、JSHandle をプロパティ値として指定することもできます。

var dataTransfer = await page.EvaluateHandleAsync("() => new DataTransfer()");
await elementHandle.DispatchEventAsync("dragstart", new Dictionary<string, object>
{
    { "dataTransfer", dataTransfer }
});

引数

type string #

DOM イベントタイプ: "click"、"dragstart" など。
eventInit EvaluationArgument? (オプション)#

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

戻り値

void #

EvalOnSelectorAsync

追加バージョン: v1.9

elementHandle.EvalOnSelectorAsync

推奨されません

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

expression の戻り値を返します。

このメソッドは、ElementHandleのサブツリー内で指定されたセレクターに一致する要素を見つけ、それをexpressionの最初の引数として渡します。セレクターに一致する要素がない場合、このメソッドはエラーをスローします。

expression が Promise を返す場合、ElementHandle.EvalOnSelectorAsync() はその Promise が解決されるのを待ち、その値を返します。

使用法

var tweetHandle = await page.QuerySelectorAsync(".tweet");
Assert.AreEqual("100", await tweetHandle.EvalOnSelectorAsync(".like", "node => node.innerText"));
Assert.AreEqual("10", await tweetHandle.EvalOnSelectorAsync(".retweets", "node => node.innerText"));

引数

selector string #

クエリするセレクター。
expression string #

ブラウザーコンテキストで評価される JavaScript 式。式が関数に評価される場合、その関数は自動的に呼び出されます。
arg EvaluationArgument? (オプション)#

expressionに渡すオプション引数です。

戻り値

[object]#

EvalOnSelectorAllAsync

追加バージョン: v1.9

elementHandle.EvalOnSelectorAllAsync

推奨されません

ほとんどの場合、Locator.EvaluateAllAsync()、その他のLocatorヘルパーメソッド、およびウェブファーストアサーションの方が優れています。

expression の戻り値を返します。

このメソッドは、ElementHandle のサブツリー内で指定されたセレクターに一致するすべての要素を見つけ、一致した要素の配列をexpressionの最初の引数として渡します。

expression が Promise を返す場合、ElementHandle.EvalOnSelectorAllAsync() はその Promise が解決されるのを待ち、その値を返します。

使用法

<div class="feed">
  <div class="tweet">Hello!</div>
  <div class="tweet">Hi!</div>
</div>

var feedHandle = await page.QuerySelectorAsync(".feed");
Assert.AreEqual(new [] { "Hello!", "Hi!" }, await feedHandle.EvalOnSelectorAllAsync<string[]>(".tweet", "nodes => nodes.map(n => n.innerText)"));

引数

selector string #

クエリするセレクター。
expression string #

ブラウザーコンテキストで評価される JavaScript 式。式が関数に評価される場合、その関数は自動的に呼び出されます。
arg EvaluationArgument? (オプション)#

expressionに渡すオプション引数です。

戻り値

[object]#

FillAsync

v1.9より前に追加

elementHandle.FillAsync

推奨されません

ロケーターベースのLocator.FillAsync()を使用してください。ロケーターについて詳しく読む。

このメソッドは、アクション可能性チェックを待ち、要素にフォーカスし、入力して、入力後にinputイベントをトリガーします。入力フィールドをクリアするために空の文字列を渡すことができることに注意してください。

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

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

使用法

await ElementHandle.FillAsync(value, options);

引数

value string #

<input>、<textarea>、または [contenteditable] 要素に設定する値。
options ElementHandleFillOptions? (オプション)
- Force bool? (optional)追加バージョン: v1.13#
  
  実行可能性チェックをバイパスするかどうか。デフォルトは false です。
- NoWaitAfter bool? (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。

戻り値

void #

FocusAsync

v1.9より前に追加

elementHandle.FocusAsync

推奨されません

ロケーターベースのLocator.FocusAsync()を使用してください。ロケーターについて詳しく読む。

要素に対して focus を呼び出します。

使用法

await ElementHandle.FocusAsync();

戻り値

void #

GetAttributeAsync

v1.9より前に追加

elementHandle.GetAttributeAsync

推奨されません

ロケーターベースのLocator.GetAttributeAsync()を使用してください。ロケーターについて詳しく読む。

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

使用法

await ElementHandle.GetAttributeAsync(name);

引数

name string #

値を取得する属性名。

戻り値

string?#

HoverAsync

v1.9より前に追加

elementHandle.HoverAsync

推奨されません

ロケーターベースのLocator.HoverAsync()を使用してください。ロケーターについて詳しく読む。

このメソッドは、次の手順を実行して要素にホバーします。

Force オプションが設定されていない限り、要素に対するアクション可能性チェックを待ちます。
必要に応じて要素を表示するためにスクロールします。
要素の中心、または指定されたPositionの上にカーソルを置くには、Page.Mouseを使用します。

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

使用法

await ElementHandle.HoverAsync(options);

引数

options ElementHandleHoverOptions? (オプション)
- Force bool? (オプション)#
  
  実行可能性チェックをバイパスするかどうか。デフォルトは false です。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (オプション)#
  
  押す修飾キー。操作中にこれらの修飾キーのみが押されていることを保証し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows と Linux では "Control" に、macOS では "Meta" に解決されます。
- NoWaitAfter bool? (任意)#追加バージョン: v1.28#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- Position Position? (オプション)#
  - X [float]
  - Y [float]
  要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
- Trial bool? (optional)追加されたバージョン: v1.11#
  
  設定されている場合、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトはfalseです。アクションを実行せずに要素がアクションの準備ができるまで待機するのに便利です。

戻り値

void #

InnerHTMLAsync

v1.9より前に追加

elementHandle.InnerHTMLAsync

推奨されません

ロケーターベースのLocator.InnerHTMLAsync()を使用してください。ロケーターについて詳しく読む。

element.innerHTML を返します。

使用法

await ElementHandle.InnerHTMLAsync();

戻り値

string #

InnerTextAsync

v1.9より前に追加

elementHandle.InnerTextAsync

推奨されません

ロケーターベースのLocator.InnerTextAsync()を使用してください。ロケーターについて詳しく読む。

element.innerText を返します。

使用法

await ElementHandle.InnerTextAsync();

戻り値

string #

InputValueAsync

追加バージョン: v1.13

elementHandle.InputValueAsync

推奨されません

ロケーターベースのLocator.InputValueAsync()を使用してください。ロケーターについて詳しく読む。

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

非入力要素の場合はスローされます。ただし、要素が関連するコントロールを持つ <label> 要素内にある場合は、コントロールの値を返します。

使用法

await ElementHandle.InputValueAsync(options);

引数

options ElementHandleInputValueOptions? (オプション)
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。

戻り値

string #

IsCheckedAsync

v1.9より前に追加

elementHandle.IsCheckedAsync

推奨されません

ロケーターベースのLocator.IsCheckedAsync()を使用してください。ロケーターについて詳しく読む。

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

使用法

await ElementHandle.IsCheckedAsync();

戻り値

bool #

IsDisabledAsync

v1.9より前に追加

elementHandle.IsDisabledAsync

推奨されません

ロケーターベースのLocator.IsDisabledAsync()を使用してください。ロケーターについて詳しく読む。

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

使用法

await ElementHandle.IsDisabledAsync();

戻り値

bool #

IsEditableAsync

v1.9より前に追加

elementHandle.IsEditableAsync

推奨されません

ロケーターベースのLocator.IsEditableAsync()を使用してください。ロケーターについて詳しく読む。

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

使用法

await ElementHandle.IsEditableAsync();

戻り値

bool #

IsEnabledAsync

v1.9より前に追加

elementHandle.IsEnabledAsync

推奨されません

代わりにロケーターベースのLocator.IsEnabledAsync()を使用してください。ロケーターについて詳しく読む。

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

使用法

await ElementHandle.IsEnabledAsync();

戻り値

bool #

IsHiddenAsync

v1.9より前に追加

elementHandle.IsHiddenAsync

推奨されません

ロケーターベースのLocator.IsHiddenAsync()を使用してください。ロケーターについて詳しく読む。

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

使用法

await ElementHandle.IsHiddenAsync();

戻り値

bool #

IsVisibleAsync

v1.9より前に追加

elementHandle.IsVisibleAsync

推奨されません

ロケーターベースのLocator.IsVisibleAsync()を使用してください。ロケーターについて詳しく読む。

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

使用法

await ElementHandle.IsVisibleAsync();

戻り値

bool #

PressAsync

v1.9より前に追加

elementHandle.PressAsync

推奨されません

ロケーターベースのLocator.PressAsync()を使用してください。ロケーターについて詳しく読む。

要素にフォーカスし、Keyboard.DownAsync()とKeyboard.UpAsync()を使用します。

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.PressAsync(key, options);

引数

key string #

押すキーの名前、または ArrowLeft や a などの生成する文字。
options ElementHandlePressOptions? (オプション)
- Delay [float]? (オプション)#
  
  keydown と keyup の間の待機時間 (ミリ秒)。デフォルトは 0 です。
- NoWaitAfter bool? (オプション)#
  
  非推奨
  このオプションは将来 true になります。
  
  ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページがロードを開始するのを待機します。このフラグを設定することで、待機をオプトアウトできます。これは、アクセスできないページにナビゲートするなどの例外的な場合にのみ必要です。デフォルトは false です。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。

戻り値

void #

QuerySelectorAsync

追加バージョン: v1.9

elementHandle.QuerySelectorAsync

推奨されません

代わりにロケーターベースのPage.Locator()を使用してください。ロケーターについて詳しく読む。

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

使用法

await ElementHandle.QuerySelectorAsync(selector);

引数

selector string #

クエリするセレクター。

戻り値

ElementHandle?#

QuerySelectorAllAsync

追加バージョン: v1.9

elementHandle.QuerySelectorAllAsync

推奨されません

代わりにロケーターベースのPage.Locator()を使用してください。ロケーターについて詳しく読む。

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

使用法

await ElementHandle.QuerySelectorAllAsync(selector);

引数

selector string #

クエリするセレクター。

戻り値

IReadOnlyList<ElementHandle>#

ScreenshotAsync

v1.9より前に追加

elementHandle.ScreenshotAsync

推奨されません

代わりにロケーターベースのLocator.ScreenshotAsync()を使用してください。ロケーターについて詳しく読む。

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

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

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

使用法

await ElementHandle.ScreenshotAsync(options);

引数

options ElementHandleScreenshotOptions? (オプション)
- Animations enum ScreenshotAnimations { Disabled, Allow }? (オプション)#
  
  "disabled"に設定すると、CSSアニメーション、CSSトランジション、Webアニメーションが停止します。アニメーションは期間によって異なる扱いを受けます。
  - 有限のアニメーションは完了まで早送りされ、transitionendイベントが発生します。
  - 無限のアニメーションは初期状態にキャンセルされ、スクリーンショットの後に再生されます。
  デフォルトは"allow"で、アニメーションはそのまま残されます。
- Caret enum ScreenshotCaret { Hide, Initial }? (オプション)#
  
  "hide"に設定すると、スクリーンショットはテキストキャレットを非表示にします。"initial"に設定すると、テキストキャレットの動作は変更されません。デフォルトは"hide"です。
- Mask IEnumerable?<Locator> (オプション)#
  
  スクリーンショットを撮るときにマスクされるべきロケーターを指定します。マスクされた要素は、そのバウンディングボックスを完全に覆うピンク色のボックス#FF00FF（MaskColorでカスタマイズ）でオーバーレイされます。マスクは不可視の要素にも適用されます。これを無効にするには、可視要素のみを一致させるを参照してください。
- MaskColor string? (optional)追加されたバージョン: v1.35#
  
  CSSカラー形式で、マスクされた要素のオーバーレイボックスの色を指定します。デフォルトの色はピンク#FF00FFです。
- OmitBackground bool? (オプション)#
  
  デフォルトの白い背景を非表示にし、透過性のあるスクリーンショットをキャプチャできるようにします。jpeg画像には適用されません。デフォルトはfalseです。
- Path string? (オプション)#
  
  画像を保存するファイルパス。スクリーンショットの種類はファイル拡張子から推測されます。Pathが相対パスの場合、現在の作業ディレクトリを基準にして解決されます。パスが指定されない場合、画像はディスクに保存されません。
- Quality int? (オプション)#
  
  画像の品質（0～100）。png画像には適用されません。
- Scale enum ScreenshotScale { Css, Device }? (オプション)#
  
  "css"に設定すると、スクリーンショットはページ上の各CSSピクセルにつき1ピクセルになります。高DPIデバイスの場合、これによりスクリーンショットが小さく保たれます。"device"オプションを使用すると、各デバイスピクセルにつき1ピクセルが生成されるため、高DPIデバイスのスクリーンショットは2倍以上大きくなります。
  
  デフォルトは"device"です。
- Style string? (optional)追加日: v1.41#
  
  スクリーンショット作成時に適用するスタイルシートのテキスト。これにより、動的な要素を非表示にしたり、要素を見えなくしたり、プロパティを変更したりして、再現性のあるスクリーンショットを作成するのに役立ちます。このスタイルシートはShadow DOMを貫通し、内部フレームにも適用されます。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
- Type enum ScreenshotType { Png, Jpeg }? (オプション)#
  
  スクリーンショットの種類を指定します。デフォルトはpngです。

戻り値

byte[]#

ScrollIntoViewIfNeededAsync

v1.9より前に追加

elementHandle.ScrollIntoViewIfNeededAsync

推奨されません

代わりにロケーターベースのLocator.ScrollIntoViewIfNeededAsync()を使用してください。ロケーターについて詳しく読む。

このメソッドはアクション可能性チェックを待ち、IntersectionObserverのratioによって定義される完全に表示されている場合を除き、要素をビューにスクロールしようとします。

elementHandle が Document または ShadowRoot に接続されていない要素を指している場合にエラーをスローします。

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

使用法

await ElementHandle.ScrollIntoViewIfNeededAsync(options);

引数

options ElementHandleScrollIntoViewIfNeededOptions? (オプション)
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。

戻り値

void #

SelectOptionAsync

v1.9より前に追加

elementHandle.SelectOptionAsync

推奨されません

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

このメソッドは、アクション可能性チェックを待ち、指定されたすべてのオプションが<select>要素に存在し、それらのオプションを選択するまで待ちます。

ターゲット要素が<select>要素でない場合、このメソッドはエラーをスローします。ただし、要素が関連するコントロールを持つ<label>要素内にある場合、代わりにそのコントロールが使用されます。

正常に選択されたオプション値の配列を返します。

提供されたすべてのオプションが選択されると、changeおよびinputイベントをトリガーします。

使用法

// Single selection matching the value or label
await handle.SelectOptionAsync(new[] { "blue" });
// single selection matching the label
await handle.SelectOptionAsync(new[] { new SelectOptionValue() { Label = "blue" } });
// multiple selection
await handle.SelectOptionAsync(new[] { "red", "green", "blue" });
// multiple selection for blue, red and second option
await handle.SelectOptionAsync(new[] {
    new SelectOptionValue() { Label = "blue" },
    new SelectOptionValue() { Index = 2 },
    new SelectOptionValue() { Value = "red" }});

引数

values string | ElementHandle | IEnumerable | SelectOption | IEnumerable | IEnumerable?#
- Value string? (オプション)
  
  option.value で一致します。任意。
- Label string? (オプション)
  
  option.label で一致します。任意。
- Index int? (オプション)
  
  インデックスで一致します。任意。
選択するオプション。 <select> に multiple 属性がある場合、一致するすべてのオプションが選択され、そうでない場合は、渡されたオプションのいずれかに一致する最初のオプションのみが選択されます。文字列値は値とラベルの両方に一致します。すべての指定されたプロパティが一致する場合、オプションは一致すると見なされます。
options ElementHandleSelectOptionOptions? (オプション)
- Force bool? (optional)追加バージョン: v1.13#
  
  実行可能性チェックをバイパスするかどうか。デフォルトは false です。
- NoWaitAfter bool? (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。

戻り値

IReadOnlyList<string>#

SelectTextAsync

v1.9より前に追加

elementHandle.SelectTextAsync

推奨されません

代わりにロケーターベースのLocator.SelectTextAsync()を使用してください。ロケーターについて詳しく読む。

このメソッドはアクション可能性チェックを待ち、要素にフォーカスしてそのテキストコンテンツをすべて選択します。

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

使用法

await ElementHandle.SelectTextAsync(options);

引数

options ElementHandleSelectTextOptions? (オプション)
- Force bool? (optional)追加バージョン: v1.13#
  
  実行可能性チェックをバイパスするかどうか。デフォルトは false です。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。

戻り値

void #

SetCheckedAsync

追加されたバージョン: v1.15

elementHandle.SetCheckedAsync

推奨されません

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

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

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

使用法

await ElementHandle.SetCheckedAsync(checked, options);

引数

checkedState bool #

チェックボックスをチェックするか、チェックを外すか。
options ElementHandleSetCheckedOptions? (オプション)
- Force bool? (オプション)#
  
  実行可能性チェックをバイパスするかどうか。デフォルトは false です。
- NoWaitAfter bool? (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- Position Position? (オプション)#
  - X [float]
  - Y [float]
  要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
- Trial bool? (オプション)#
  
  設定されている場合、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトはfalseです。アクションを実行せずに要素がアクションの準備ができるまで待機するのに便利です。

戻り値

void #

SetInputFilesAsync

v1.9より前に追加

elementHandle.SetInputFilesAsync

推奨されません

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

ファイル入力の値を、これらのファイルパスまたはファイルに設定します。filePaths の一部が相対パスである場合、現在の作業ディレクトリを基準に解決されます。空の配列の場合、選択されたファイルをクリアします。[webkitdirectory] 属性を持つ入力の場合、単一のディレクトリパスのみがサポートされます。

このメソッドは、ElementHandleがinput要素を指していることを想定しています。ただし、要素が関連するコントロールを持つ<label>要素内にある場合、代わりにコントロールを対象とします。

使用法

await ElementHandle.SetInputFilesAsync(files, options);

引数

files string | IEnumerable<string> | FilePayload | IEnumerable<FilePayload>#
- Name string
  
  ファイル名
- MimeType string
  
  ファイルタイプ
- Buffer byte[]
  
  ファイル内容
options ElementHandleSetInputFilesOptions? (オプション)
- NoWaitAfter bool? (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。

戻り値

void #

TapAsync

v1.9より前に追加

elementHandle.TapAsync

推奨されません

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

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

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

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

注

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

使用法

await ElementHandle.TapAsync(options);

引数

options ElementHandleTapOptions? (オプション)
- Force bool? (オプション)#
  
  実行可能性チェックをバイパスするかどうか。デフォルトは false です。
- Modifiers IEnumerable?<enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }> (オプション)#
  
  押す修飾キー。操作中にこれらの修飾キーのみが押されていることを保証し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows と Linux では "Control" に、macOS では "Meta" に解決されます。
- NoWaitAfter bool? (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- Position Position? (オプション)#
  - X [float]
  - Y [float]
  要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
- Trial bool? (optional)追加されたバージョン: v1.11#
  
  設定されている場合、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトはfalseです。アクションを実行せずに要素がアクションの準備ができるまで待機するのに便利です。

戻り値

void #

TextContentAsync

v1.9より前に追加

elementHandle.TextContentAsync

推奨されません

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

node.textContent を返します。

使用法

await ElementHandle.TextContentAsync();

戻り値

string?#

TypeAsync

v1.9より前に追加

elementHandle.TypeAsync

非推奨

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

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

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

使用法

引数

text string #

フォーカスされた要素に入力するテキスト。
options ElementHandleTypeOptions? (オプション)
- Delay [float]? (オプション)#
  
  キー押下間の待機時間（ミリ秒）。デフォルトは0です。
- NoWaitAfter bool? (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。

戻り値

void #

UncheckAsync

v1.9より前に追加

elementHandle.UncheckAsync

推奨されません

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

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

要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドはエラーをスローします。要素がすでにチェックされていない場合、このメソッドはすぐに戻ります。
Forceオプションが設定されていない限り、要素に対するアクション可能性チェックを待ちます。
必要に応じて要素を表示するためにスクロールします。
Page.Mouseを使用して要素の中央をクリックします。
要素がチェックされていないことを確認します。そうでない場合、このメソッドはエラーをスローします。

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

使用法

await ElementHandle.UncheckAsync(options);

引数

options ElementHandleUncheckOptions? (オプション)
- Force bool? (オプション)#
  
  実行可能性チェックをバイパスするかどうか。デフォルトは false です。
- NoWaitAfter bool? (オプション)#
  
  非推奨
  このオプションは効果がありません。
  
  このオプションは効果がありません。
- Position Position? (optional)追加されたバージョン: v1.11#
  - X [float]
  - Y [float]
  要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
- Trial bool? (optional)追加されたバージョン: v1.11#
  
  設定されている場合、このメソッドはアクション実行可能性チェックのみを実行し、アクションをスキップします。デフォルトはfalseです。アクションを実行せずに要素がアクションの準備ができるまで待機するのに便利です。

戻り値

void #

WaitForSelectorAsync

v1.9より前に追加

elementHandle.WaitForSelectorAsync

推奨されません

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

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

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

使用法

await page.SetContentAsync("<div><span></span></div>");
var div = await page.QuerySelectorAsync("div");
// Waiting for the "span" selector relative to the div.
var span = await page.WaitForSelectorAsync("span", WaitForSelectorState.Attached);

注

このメソッドはナビゲーションをまたがって機能しません。代わりにPage.WaitForSelectorAsync()を使用してください。

引数

selector string #

クエリするセレクター。
options ElementHandleWaitForSelectorOptions? (オプション)
- State enum WaitForSelectorState { Attached, Detached, Visible, Hidden }? (オプション)#
  
  デフォルトは'visible'です。以下のいずれかになります。
  - 'attached' - 要素がDOMに存在することを待ちます。
  - 'detached' - 要素がDOMに存在しないことを待ちます。
  - 'visible' - 要素が空でない境界ボックスを持ち、visibility:hiddenがないことを待ちます。コンテンツがない要素やdisplay:noneの要素は空の境界ボックスを持つため、可視とはみなされないことに注意してください。
  - 'hidden' - 要素がDOMからデタッチされているか、空の境界ボックスを持つか、またはvisibility:hiddenを持つことを待ちます。これは'visible'オプションとは逆です。
- Strict bool? (任意)追加されたバージョン: v1.15#
  
  trueの場合、呼び出しはセレクターが単一の要素に解決されることを必要とします。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
- Timeout [float]? (オプション)#
  
  ミリ秒単位の最大時間。デフォルトは30000 (30秒) です。タイムアウトを無効にするには0 を渡します。デフォルト値は、BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。

戻り値

ElementHandle?#

メソッド​

BoundingBoxAsync​

ContentFrameAsync​

OwnerFrameAsync​

WaitForElementStateAsync​

非推奨​

CheckAsync​

ClickAsync​

DblClickAsync​

DispatchEventAsync​

EvalOnSelectorAsync​

EvalOnSelectorAllAsync​

FillAsync​

FocusAsync​

GetAttributeAsync​

HoverAsync​

InnerHTMLAsync​

InnerTextAsync​

InputValueAsync​

IsCheckedAsync​

IsDisabledAsync​

IsEditableAsync​

IsEnabledAsync​

IsHiddenAsync​

IsVisibleAsync​

PressAsync​

QuerySelectorAsync​

QuerySelectorAllAsync​

ScreenshotAsync​

ScrollIntoViewIfNeededAsync​

SelectOptionAsync​

SelectTextAsync​

SetCheckedAsync​

SetInputFilesAsync​

TapAsync​

TextContentAsync​

TypeAsync​

UncheckAsync​

WaitForSelectorAsync​

メソッド

BoundingBoxAsync

ContentFrameAsync

OwnerFrameAsync

WaitForElementStateAsync

非推奨

CheckAsync

ClickAsync

DblClickAsync

DispatchEventAsync

EvalOnSelectorAsync

EvalOnSelectorAllAsync

FillAsync

FocusAsync

GetAttributeAsync

HoverAsync

InnerHTMLAsync

InnerTextAsync

InputValueAsync

IsCheckedAsync

IsDisabledAsync

IsEditableAsync

IsEnabledAsync

IsHiddenAsync

IsVisibleAsync

PressAsync

QuerySelectorAsync

QuerySelectorAllAsync

ScreenshotAsync

ScrollIntoViewIfNeededAsync

SelectOptionAsync

SelectTextAsync

SetCheckedAsync

SetInputFilesAsync

TapAsync

TextContentAsync

TypeAsync

UncheckAsync

WaitForSelectorAsync