ElementHandle
- 継承元: JSHandle
ElementHandle はページ内の DOM 要素を表します。ElementHandle は Page.QuerySelectorAsync() メソッドで作成できます。
ElementHandle の使用は非推奨です。Locator オブジェクトと Web ファーストのアサーションを使用してください。
var handle = await page.QuerySelectorAsync("a");
await handle.ClickAsync();
ElementHandle は、JsHandle.DisposeAsync() でハンドルが破棄されない限り、DOM 要素のガベージコレクションを防止します。ElementHandle は、元のフレームがナビゲートされると自動的に破棄されます。
ElementHandle インスタンスは、Page.EvalOnSelectorAsync() メソッドおよび Page.EvaluateAsync() メソッドの引数として使用できます。
Locator と ElementHandle の違いは、ElementHandle が特定の要素を指すのに対し、Locator は要素を取得する方法のロジックをキャプチャする点です。
以下の例では、ハンドルはページの特定の DOM 要素を指します。その要素のテキストが変更されたり、React によって全く異なるコンポーネントがレンダリングされたりしても、ハンドルはその 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 以前に追加このメソッドは、要素の境界ボックスを返します。要素が非表示の場合は `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 以前に追加iframe ノードを参照する要素ハンドルのコンテンツフレームを返します。それ以外の場合は `null` を返します。
使用法
await ElementHandle.ContentFrameAsync();
戻り値
OwnerFrameAsync
v1.9 以前に追加指定された要素を含むフレームを返します。
使用法
await ElementHandle.OwnerFrameAsync();
戻り値
WaitForElementStateAsync
v1.9 以前に追加要素が 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() メソッドを使用して変更できます。
-
戻り値
非推奨
CheckAsync
v1.9 以前に追加代わりにロケーターベースの Locator.CheckAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
このメソッドは、以下のステップを実行して要素をチェックします
- 要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドはスローします。要素がすでにチェックされている場合、このメソッドはすぐに戻ります。
- Force オプションが設定されていない限り、要素に対する アクション可能性 チェックを待機します。
- 必要に応じて、要素を表示されるようにスクロールします。
- Page.Mouse を使用して、要素の中心をクリックします。
- 要素が現在チェックされていることを確認します。そうでない場合、このメソッドはスローします。
アクション中に要素が DOM からデタッチされた場合、このメソッドはスローします。
すべてのステップを合わせて指定された Timeout 内に完了しない場合、このメソッドは TimeoutError をスローします。タイムアウトをゼロに設定すると、この機能は無効になります。
使用法
await ElementHandle.CheckAsync(options);
引数
- `options`
ElementHandleCheckOptions?
(オプション)-
アクション可能性 チェックをバイパスするかどうか。デフォルトは `false` です。
-
非推奨
このオプションは効果がありません。
このオプションは効果がありません。
-
`Position` Position? (オプション)v1.11 で追加#
-
`X` [float]
-
`Y` [float]
要素のパディングボックスの左上隅を基準とする使用する点。指定しない場合、要素の何らかの可視点を使用します。
-
-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
`Trial` bool? (オプション)v1.11 で追加#
設定されている場合、このメソッドは アクション可能性 チェックのみを実行し、アクションはスキップします。デフォルトは `false` です。要素がアクションを実行せずに準備が整うまで待機するのに役立ちます。
-
戻り値
ClickAsync
v1.9 以前に追加代わりにロケーターベースの Locator.ClickAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
このメソッドは、以下のステップを実行して要素をクリックします
- Force オプションが設定されていない限り、要素に対する アクション可能性 チェックを待機します。
- 必要に応じて、要素を表示されるようにスクロールします。
- Page.Mouse を使用して、要素の中心、または指定された Position をクリックします。
- NoWaitAfter オプションが設定されていない限り、開始されたナビゲーションが成功または失敗するまで待機します。
アクション中に要素が DOM からデタッチされた場合、このメソッドはスローします。
すべてのステップを合わせて指定された Timeout 内に完了しない場合、このメソッドは TimeoutError をスローします。タイムアウトをゼロに設定すると、この機能は無効になります。
使用法
await ElementHandle.ClickAsync(options);
引数
- `options`
ElementHandleClickOptions?
(オプション)-
`Button`
enum MouseButton { Left, Right, Middle }?
(オプション)#デフォルトは `left` です。
-
デフォルトは 1 です。UIEvent.detail を参照してください。
-
`Delay` [float]? (オプション)#
`mousedown` と `mouseup` の間の待機時間 (ミリ秒)。デフォルトは 0 です。
-
アクション可能性 チェックをバイパスするかどうか。デフォルトは `false` です。
-
`Modifiers` IEnumerable?<
enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }
> (オプション)#押下する修飾キー。操作中にこれらの修飾キーのみが押下されることを保証し、その後現在の修飾キーを元に戻します。指定されていない場合、現在押下されている修飾キーが使用されます。"ControlOrMeta" は Windows および Linux では "Control" に、macOS では "Meta" に解決されます。
-
非推奨
このオプションは将来的に `true` になります。
ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページの読み込みが開始されるのを待機します。このフラグを設定することで、待機をオプトアウトできます。このオプションは、アクセスできないページへのナビゲーションなどの例外的な場合にのみ必要です。デフォルトは `false` です。
-
`Position` Position? (オプション)#
-
`X` [float]
-
`Y` [float]
要素のパディングボックスの左上隅を基準とする使用する点。指定しない場合、要素の何らかの可視点を使用します。
-
-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
`Trial` bool? (オプション)v1.11 で追加#
設定されている場合、このメソッドは アクション可能性 チェックのみを実行し、アクションはスキップします。デフォルトは `false` です。要素がアクションを実行せずに準備が整うまで待機するのに役立ちます。
-
戻り値
DblClickAsync
v1.9 以前に追加代わりにロケーターベースの Locator.DblClickAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
このメソッドは、以下のステップを実行して要素をダブルクリックします
- Force オプションが設定されていない限り、要素に対する アクション可能性 チェックを待機します。
- 必要に応じて、要素を表示されるようにスクロールします。
- Page.Mouse を使用して、要素の中心、または指定された Position をダブルクリックします。
アクション中に要素が DOM からデタッチされた場合、このメソッドはスローします。
すべてのステップを合わせて指定された Timeout 内に完了しない場合、このメソッドは TimeoutError をスローします。タイムアウトをゼロに設定すると、この機能は無効になります。
`elementHandle.dblclick()` は、2つの `click` イベントと1つの `dblclick` イベントをディスパッチします。
使用法
await ElementHandle.DblClickAsync(options);
引数
- `options`
ElementHandleDblClickOptions?
(オプション)-
`Button`
enum MouseButton { Left, Right, Middle }?
(オプション)#デフォルトは `left` です。
-
`Delay` [float]? (オプション)#
`mousedown` と `mouseup` の間の待機時間 (ミリ秒)。デフォルトは 0 です。
-
アクション可能性 チェックをバイパスするかどうか。デフォルトは `false` です。
-
`Modifiers` IEnumerable?<
enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }
> (オプション)#押下する修飾キー。操作中にこれらの修飾キーのみが押下されることを保証し、その後現在の修飾キーを元に戻します。指定されていない場合、現在押下されている修飾キーが使用されます。"ControlOrMeta" は Windows および Linux では "Control" に、macOS では "Meta" に解決されます。
-
非推奨
このオプションは効果がありません。
このオプションは効果がありません。
-
`Position` Position? (オプション)#
-
`X` [float]
-
`Y` [float]
要素のパディングボックスの左上隅を基準とする使用する点。指定しない場合、要素の何らかの可視点を使用します。
-
-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
`Trial` bool? (オプション)v1.11 で追加#
設定されている場合、このメソッドは アクション可能性 チェックのみを実行し、アクションはスキップします。デフォルトは `false` です。要素がアクションを実行せずに準備が整うまで待機するのに役立ちます。
-
戻り値
DispatchEventAsync
v1.9 以前に追加代わりにロケーターベースの Locator.DispatchEventAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
以下のスニペットは、要素に対して `click` イベントをディスパッチします。要素の可視状態に関わらず、`click` がディスパッチされます。これは element.click() を呼び出すことと同等です。
使用法
await elementHandle.DispatchEventAsync("click");
内部的には、指定された type に基づいてイベントのインスタンスを作成し、eventInit プロパティで初期化し、要素にディスパッチします。イベントはデフォルトで `composed`、`cancelable`、バブルします。
eventInit はイベント固有であるため、初期プロパティのリストについてはイベントのドキュメントを参照してください。
- DeviceMotionEvent
- DeviceOrientationEvent
- DragEvent
- Event
- FocusEvent
- KeyboardEvent
- MouseEvent
- PointerEvent
- TouchEvent
- WheelEvent
ライブオブジェクトをイベントに渡したい場合は、プロパティ値として `JSHandle` を指定することもできます。
var dataTransfer = await page.EvaluateHandleAsync("() => new DataTransfer()");
await elementHandle.DispatchEventAsync("dragstart", new Dictionary<string, object>
{
{ "dataTransfer", dataTransfer }
});
引数
-
DOM イベントタイプ: `"click"`、`"dragstart"` など。
-
`eventInit` EvaluationArgument? (オプション)#
オプションのイベント固有の初期化プロパティ。
戻り値
EvalOnSelectorAsync
v1.9 で追加このメソッドは、要素がアクション可能性チェックに合格するのを待たないため、不安定なテストにつながる可能性があります。代わりに 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"));
引数
-
クエリ対象のセレクター。
-
ブラウザコンテキストで評価される JavaScript 式。式が関数に評価される場合、その関数は自動的に呼び出されます。
-
`arg` EvaluationArgument? (オプション)#
expression に渡すオプションの引数。
戻り値
- [object]#
EvalOnSelectorAllAsync
v1.9 で追加ほとんどの場合、Locator.EvaluateAllAsync()、その他の Locator ヘルパーメソッド、および Web ファーストのアサーションの方が優れています。
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)"));
引数
-
クエリ対象のセレクター。
-
ブラウザコンテキストで評価される JavaScript 式。式が関数に評価される場合、その関数は自動的に呼び出されます。
-
`arg` EvaluationArgument? (オプション)#
expression に渡すオプションの引数。
戻り値
- [object]#
FillAsync
v1.9 以前に追加代わりにロケーターベースの Locator.FillAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
このメソッドは、アクション可能性 チェックを待機し、要素にフォーカスし、入力を行い、入力後に `input` イベントをトリガーします。入力フィールドをクリアするために空の文字列を渡すことができることに注意してください。
ターゲット要素が `<input>`、`<textarea>`、または `[contenteditable]` 要素でない場合、このメソッドはエラーをスローします。ただし、要素が関連する コントロール を持つ `<label>` 要素内にある場合、代わりにそのコントロールが入力されます。
細かいキーボードイベントを送信するには、Locator.PressSequentiallyAsync() を使用してください。
使用法
await ElementHandle.FillAsync(value, options);
引数
-
`<input>`、`<textarea>`、または `[contenteditable]` 要素に設定する値。
-
`options`
ElementHandleFillOptions?
(オプション)-
`Force` bool? (オプション)v1.13 で追加#
アクション可能性 チェックをバイパスするかどうか。デフォルトは `false` です。
-
非推奨
このオプションは効果がありません。
このオプションは効果がありません。
-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
戻り値
FocusAsync
v1.9 以前に追加代わりにロケーターベースの Locator.FocusAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
要素に対して focus を呼び出します。
使用法
await ElementHandle.FocusAsync();
戻り値
GetAttributeAsync
v1.9 以前に追加代わりにロケーターベースの Locator.GetAttributeAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
要素の属性値を返します。
使用法
await ElementHandle.GetAttributeAsync(name);
引数
戻り値
HoverAsync
v1.9 以前に追加代わりにロケーターベースの Locator.HoverAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
このメソッドは、以下のステップを実行して要素にホバーします
- Force オプションが設定されていない限り、要素に対する アクション可能性 チェックを待機します。
- 必要に応じて、要素を表示されるようにスクロールします。
- Page.Mouse を使用して、要素の中心、または指定された Position にホバーします。
アクション中に要素が DOM からデタッチされた場合、このメソッドはスローします。
すべてのステップを合わせて指定された Timeout 内に完了しない場合、このメソッドは TimeoutError をスローします。タイムアウトをゼロに設定すると、この機能は無効になります。
使用法
await ElementHandle.HoverAsync(options);
引数
- `options`
ElementHandleHoverOptions?
(オプション)-
アクション可能性 チェックをバイパスするかどうか。デフォルトは `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? (オプション)v1.11 で追加#
設定されている場合、このメソッドは アクション可能性 チェックのみを実行し、アクションはスキップします。デフォルトは `false` です。要素がアクションを実行せずに準備が整うまで待機するのに役立ちます。
-
戻り値
InnerHTMLAsync
v1.9 以前に追加代わりにロケーターベースの Locator.InnerHTMLAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
`element.innerHTML` を返します。
使用法
await ElementHandle.InnerHTMLAsync();
戻り値
InnerTextAsync
v1.9 以前に追加代わりにロケーターベースの Locator.InnerTextAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
`element.innerText` を返します。
使用法
await ElementHandle.InnerTextAsync();
戻り値
InputValueAsync
v1.13 で追加代わりにロケーターベースの Locator.InputValueAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
選択された `<input>`、`<textarea>`、または `<select>` 要素の `input.value` を返します。
入力要素ではない場合はスローします。ただし、要素が関連する コントロール を持つ `<label>` 要素内にある場合、そのコントロールの値を返します。
使用法
await ElementHandle.InputValueAsync(options);
引数
- `options`
ElementHandleInputValueOptions?
(オプション)-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
戻り値
IsCheckedAsync
v1.9 以前に追加代わりにロケーターベースの Locator.IsCheckedAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
要素がチェックされているかどうかを返します。要素がチェックボックスまたはラジオ入力でない場合はスローします。
使用法
await ElementHandle.IsCheckedAsync();
戻り値
IsDisabledAsync
v1.9 以前に追加代わりにロケーターベースの Locator.IsDisabledAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
要素が 有効 の反対である、無効かどうかを返します。
使用法
await ElementHandle.IsDisabledAsync();
戻り値
IsEditableAsync
v1.9 以前に追加代わりにロケーターベースの Locator.IsEditableAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
要素が 編集可能 かどうかを返します。
使用法
await ElementHandle.IsEditableAsync();
戻り値
IsEnabledAsync
v1.9 以前に追加代わりにロケーターベースの Locator.IsEnabledAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
要素が 有効 かどうかを返します。
使用法
await ElementHandle.IsEnabledAsync();
戻り値
IsHiddenAsync
v1.9 以前に追加代わりにロケーターベースの Locator.IsHiddenAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
要素が 可視 の反対である、非表示かどうかを返します。
使用法
await ElementHandle.IsHiddenAsync();
戻り値
IsVisibleAsync
v1.9 以前に追加代わりにロケーターベースの Locator.IsVisibleAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
要素が 可視 かどうかを返します。
使用法
await ElementHandle.IsVisibleAsync();
戻り値
PressAsync
v1.9 以前に追加代わりにロケーターベースの 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);
引数
-
押すキーの名前、または生成する文字(例: `ArrowLeft` または `a`)。
-
`options`
ElementHandlePressOptions?
(オプション)-
`Delay` [float]? (オプション)#
`keydown` と `keyup` の間の待機時間 (ミリ秒)。デフォルトは 0 です。
-
非推奨
このオプションは将来的に `true` になります。
ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページの読み込みが開始されるのを待機します。このフラグを設定することで、待機をオプトアウトできます。このオプションは、アクセスできないページへのナビゲーションなどの例外的な場合にのみ必要です。デフォルトは `false` です。
-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
戻り値
QuerySelectorAsync
v1.9 で追加代わりにロケーターベースの Page.Locator() を使用してください。ロケーターの詳細はこちらをご覧ください。
このメソッドは、`ElementHandle` のサブツリー内で指定されたセレクターに一致する要素を見つけます。セレクターに一致する要素がない場合、`null` を返します。
使用法
await ElementHandle.QuerySelectorAsync(selector);
引数
戻り値
QuerySelectorAllAsync
v1.9 で追加代わりにロケーターベースの Page.Locator() を使用してください。ロケーターの詳細はこちらをご覧ください。
このメソッドは、`ElementHandle` のサブツリー内で指定されたセレクターに一致するすべての要素を見つけます。セレクターに一致する要素がない場合、空の配列を返します。
使用法
await ElementHandle.QuerySelectorAllAsync(selector);
引数
戻り値
ScreenshotAsync
v1.9 以前に追加代わりにロケーターベースの 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? (オプション)v1.35 で追加#
マスクされた要素のオーバーレイボックスの色を CSS カラー形式 で指定します。デフォルトの色はピンクの `#FF00FF` です。
-
`OmitBackground` bool? (オプション)#
デフォルトの白い背景を非表示にし、透明性のあるスクリーンショットのキャプチャを可能にします。`jpeg` 画像には適用されません。デフォルトは `false` です。
-
画像を保存するファイルパス。スクリーンショットのタイプはファイル拡張子から推測されます。Path が相対パスの場合、現在の作業ディレクトリを基準として解決されます。パスが指定されていない場合、画像はディスクに保存されません。
-
画像の品質 (0~100)。`png` 画像には適用されません。
-
`Scale`
enum ScreenshotScale { Css, Device }?
(オプション)#`"css"` に設定すると、スクリーンショットはページの CSS ピクセルごとに1ピクセルを持ちます。高DPIデバイスの場合、これによりスクリーンショットは小さく保たれます。`"device"` オプションを使用すると、各デバイスピクセルごとに1ピクセルが生成されるため、高DPIデバイスのスクリーンショットは2倍以上大きくなります。
デフォルトは `"device"` です。
-
`Style` string? (オプション)v1.41 で追加#
スクリーンショット作成時に適用するスタイルシートのテキスト。ここでは、動的な要素を非表示にしたり、要素を不可視にしたり、そのプロパティを変更したりして、再現性のあるスクリーンショットの作成に役立てることができます。このスタイルシートは Shadow DOM を透過し、内部フレームにも適用されます。
-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
`Type`
enum ScreenshotType { Png, Jpeg }?
(オプション)#スクリーンショットのタイプを指定します。デフォルトは `png` です。
-
戻り値
ScrollIntoViewIfNeededAsync
v1.9 以前に追加代わりにロケーターベースの Locator.ScrollIntoViewIfNeededAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
このメソッドは、アクション可能性 チェックを待機し、IntersectionObserver の `ratio` で定義されているように、要素が完全に表示されていない限り、要素をビューにスクロールしようとします。
`elementHandle` が Document または ShadowRoot に 接続 された要素を指していない場合、スローします。
スクロールの代替方法については、スクロールを参照してください。
使用法
await ElementHandle.ScrollIntoViewIfNeededAsync(options);
引数
- `options`
ElementHandleScrollIntoViewIfNeededOptions?
(オプション)-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
戻り値
SelectOptionAsync
v1.9 以前に追加代わりにロケーターベースの 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?# 選択するオプション。`<select>` が `multiple` 属性を持っている場合、一致するすべてのオプションが選択されます。そうでない場合、渡されたオプションのいずれかに一致する最初のオプションのみが選択されます。文字列値は、値とラベルの両方に一致します。指定されたすべてのプロパティが一致する場合に、オプションは一致すると見なされます。 - `options`
ElementHandleSelectOptionOptions?
(オプション)-
`Force` bool? (オプション)v1.13 で追加#
アクション可能性 チェックをバイパスするかどうか。デフォルトは `false` です。
-
非推奨
このオプションは効果がありません。
このオプションは効果がありません。
-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
戻り値
SelectTextAsync
v1.9 以前に追加代わりにロケーターベースの Locator.SelectTextAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
このメソッドは、アクション可能性 チェックを待機し、要素にフォーカスを合わせ、そのすべてのテキストコンテンツを選択します。
要素が関連する コントロール を持つ `<label>` 要素内にある場合、代わりにコントロールにフォーカスを合わせ、テキストを選択します。
使用法
await ElementHandle.SelectTextAsync(options);
引数
- `options`
ElementHandleSelectTextOptions?
(オプション)-
`Force` bool? (オプション)v1.13 で追加#
アクション可能性 チェックをバイパスするかどうか。デフォルトは `false` です。
-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
戻り値
SetCheckedAsync
v1.15 で追加代わりにロケーターベースの Locator.SetCheckedAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
このメソッドは、以下のステップを実行して要素をチェックまたはアンチェックします
- 要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドはスローします。
- 要素がすでに正しいチェック状態である場合、このメソッドはすぐに戻ります。
- Force オプションが設定されていない限り、一致した要素に対する アクション可能性 チェックを待機します。チェック中に要素がデタッチされた場合、アクション全体が再試行されます。
- 必要に応じて、要素を表示されるようにスクロールします。
- Page.Mouse を使用して、要素の中心をクリックします。
- 要素が現在チェックまたはアンチェックされていることを確認します。そうでない場合、このメソッドはスローします。
すべてのステップを合わせて指定された Timeout 内に完了しない場合、このメソッドは TimeoutError をスローします。タイムアウトをゼロに設定すると、この機能は無効になります。
使用法
await ElementHandle.SetCheckedAsync(checked, options);
引数
-
チェックボックスをチェックするか、アンチェックするか。
-
`options`
ElementHandleSetCheckedOptions?
(オプション)-
アクション可能性 チェックをバイパスするかどうか。デフォルトは `false` です。
-
非推奨
このオプションは効果がありません。
このオプションは効果がありません。
-
`Position` Position? (オプション)#
-
`X` [float]
-
`Y` [float]
要素のパディングボックスの左上隅を基準とする使用する点。指定しない場合、要素の何らかの可視点を使用します。
-
-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
設定されている場合、このメソッドは アクション可能性 チェックのみを実行し、アクションはスキップします。デフォルトは `false` です。要素がアクションを実行せずに準備が整うまで待機するのに役立ちます。
-
戻り値
SetInputFilesAsync
v1.9 以前に追加代わりにロケーターベースの Locator.SetInputFilesAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
ファイル入力の値をこれらのファイルパスまたはファイルに設定します。`filePaths` の一部が相対パスの場合、現在の作業ディレクトリを基準として解決されます。空の配列の場合、選択されているファイルをクリアします。`[webkitdirectory]` 属性を持つ入力の場合、単一のディレクトリパスのみがサポートされます。
このメソッドは、ElementHandle が input 要素 を指すことを期待します。ただし、要素が関連する コントロール を持つ `<label>` 要素内にある場合、代わりにそのコントロールをターゲットにします。
使用法
await ElementHandle.SetInputFilesAsync(files, options);
引数
- `files` string | IEnumerable<string> |
FilePayload
| IEnumerable<FilePayload
># - `options`
ElementHandleSetInputFilesOptions?
(オプション)-
非推奨
このオプションは効果がありません。
このオプションは効果がありません。
-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
戻り値
TapAsync
v1.9 以前に追加代わりにロケーターベースの Locator.TapAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
このメソッドは、以下のステップを実行して要素をタップします
- Force オプションが設定されていない限り、要素に対する アクション可能性 チェックを待機します。
- 必要に応じて、要素を表示されるようにスクロールします。
- Page.Touchscreen を使用して、要素の中心、または指定された Position をタップします。
アクション中に要素が DOM からデタッチされた場合、このメソッドはスローします。
すべてのステップを合わせて指定された Timeout 内に完了しない場合、このメソッドは TimeoutError をスローします。タイムアウトをゼロに設定すると、この機能は無効になります。
`elementHandle.tap()` を使用するには、ブラウザコンテキストの `hasTouch` オプションを true に設定する必要があります。
使用法
await ElementHandle.TapAsync(options);
引数
- `options`
ElementHandleTapOptions?
(オプション)-
アクション可能性 チェックをバイパスするかどうか。デフォルトは `false` です。
-
`Modifiers` IEnumerable?<
enum KeyboardModifier { Alt, Control, ControlOrMeta, Meta, Shift }
> (オプション)#押下する修飾キー。操作中にこれらの修飾キーのみが押下されることを保証し、その後現在の修飾キーを元に戻します。指定されていない場合、現在押下されている修飾キーが使用されます。"ControlOrMeta" は Windows および Linux では "Control" に、macOS では "Meta" に解決されます。
-
非推奨
このオプションは効果がありません。
このオプションは効果がありません。
-
`Position` Position? (オプション)#
-
`X` [float]
-
`Y` [float]
要素のパディングボックスの左上隅を基準とする使用する点。指定しない場合、要素の何らかの可視点を使用します。
-
-
`Timeout` [float]? (オプション)#
最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
`Trial` bool? (オプション)v1.11 で追加#
設定されている場合、このメソッドは アクション可能性 チェックのみを実行し、アクションはスキップします。デフォルトは `false` です。要素がアクションを実行せずに準備が整うまで待機するのに役立ちます。
-
戻り値
TextContentAsync
v1.9 以前に追加代わりにロケーターベースの Locator.TextContentAsync() を使用してください。ロケーターの詳細はこちらをご覧ください。
`node.textContent` を返します。
使用法
await ElementHandle.TextContentAsync();
戻り値
TypeAsync
v1.9 以前に追加ほとんどの場合、代わりにLocator.FillAsync()を使用すべきです。ページに特殊なキーボード処理がある場合にのみ、キーを1つずつ押す必要があります。その場合はLocator.PressSequentiallyAsync()を使用してください。
要素にフォーカスし、テキスト内の各文字に対してkeydown
、keypress
/input
、およびkeyup
イベントを送信します。
Control
やArrowDown
のような特殊なキーを押すには、ElementHandle.PressAsync()を使用します。
使用法
引数
-
フォーカスされた要素に入力するテキスト。
-
options
ElementHandleTypeOptions?
(省略可能)-
Delay
[float]? (省略可能)#キー押下間の待機時間(ミリ秒単位)。デフォルトは0です。
-
非推奨
このオプションは効果がありません。
このオプションは効果がありません。
-
Timeout
[float]? (省略可能)#最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
戻り値
UncheckAsync
v1.9 以前に追加代わりにロケーターベースのLocator.UncheckAsync()を使用してください。ロケーターについて詳しくはこちらをご覧ください。
このメソッドは、以下のステップを実行して要素をチェックします
- 要素がチェックボックスまたはラジオ入力であることを確認します。そうでない場合、このメソッドは例外をスローします。要素がすでにチェック解除されている場合、このメソッドは直ちに返されます。
- Forceオプションが設定されていない限り、要素に対するアクション可能性チェックを待ちます。
- 必要に応じて、要素を表示されるようにスクロールします。
- Page.Mouse を使用して、要素の中心をクリックします。
- 要素が現在チェック解除されていることを確認します。そうでない場合、このメソッドは例外をスローします。
アクション中に要素が DOM からデタッチされた場合、このメソッドはスローします。
指定されたタイムアウト内にすべてのステップが完了しない場合、このメソッドはTimeoutErrorをスローします。タイムアウトに0を渡すと、これを無効にできます。
使用法
await ElementHandle.UncheckAsync(options);
引数
options
ElementHandleUncheckOptions?
(省略可能)-
アクション可能性 チェックをバイパスするかどうか。デフォルトは `false` です。
-
非推奨
このオプションは効果がありません。
このオプションは効果がありません。
-
`Position` Position? (オプション)v1.11 で追加#
-
`X` [float]
-
`Y` [float]
要素のパディングボックスの左上隅を基準とする使用する点。指定しない場合、要素の何らかの可視点を使用します。
-
-
Timeout
[float]? (省略可能)#最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
`Trial` bool? (オプション)v1.11 で追加#
設定されている場合、このメソッドは アクション可能性 チェックのみを実行し、アクションはスキップします。デフォルトは `false` です。要素がアクションを実行せずに準備が整うまで待機するのに役立ちます。
-
戻り値
WaitForSelectorAsync
v1.9 以前に追加代わりに、可視性をアサートするウェブアサーション、またはロケーターベースのLocator.WaitForAsync()を使用してください。
セレクターで指定された要素がStateオプションを満たす場合に、その要素を返します。hidden
またはdetached
を待機している場合はnull
を返します。
要素ハンドルに対するセレクターがStateオプションを満たす(DOMに表示/非表示になるか、可視/非表示になるか)のを待ちます。メソッド呼び出し時点でセレクターがすでに条件を満たしている場合、メソッドは直ちに返されます。セレクターがタイムアウトミリ秒間条件を満たさない場合、関数は例外をスローします。
使用法
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()を使用してください。
引数
-
クエリ対象のセレクター。
-
options
ElementHandleWaitForSelectorOptions?
(省略可能)-
State
enum WaitForSelectorState { Attached, Detached, Visible, Hidden }?
(省略可能)#デフォルトは
'visible'
です。次のいずれかを指定できます。'attached'
- 要素がDOMに存在することを確認するまで待機します。'detached'
- 要素がDOMに存在しないことを確認するまで待機します。'visible'
- 要素が空でない境界ボックスを持ち、visibility:hidden
ではないことを確認するまで待機します。コンテンツがない、またはdisplay:none
の要素は空の境界ボックスを持ち、可視とは見なされないことに注意してください。'hidden'
- 要素がDOMからデタッチされているか、空の境界ボックスを持っているか、visibility:hidden
であることを確認するまで待機します。これは'visible'
オプションとは逆です。
-
trueの場合、呼び出しはセレクターが単一の要素に解決されることを要求します。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。
-
Timeout
[float]? (省略可能)#最大時間 (ミリ秒)。デフォルトは `30000` (30 秒) です。タイムアウトを無効にするには `0` を渡します。デフォルト値は BrowserContext.SetDefaultTimeout() または Page.SetDefaultTimeout() メソッドを使用して変更できます。
-
戻り値