メインコンテンツにスキップ

ElementHandle

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

推奨されません

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

href_element = page.query_selector("a")
href_element.click()

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

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

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

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

handle = page.query_selector("text=Submit")
handle.hover()
handle.click()

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

locator = page.get_by_text("Submit")
locator.hover()
locator.click()

メソッド​

bounding_box​

v1.9より前に追加 elementHandle.bounding_box

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

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

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

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

使用法

box = element_handle.bounding_box()
page.mouse.click(box["x"] + box["width"] / 2, box["y"] + box["height"] / 2)

戻り値

  • NoneType | Dict#

    • x float

      要素の x 座標 (ピクセル単位)。

    • y float

      要素の y 座標 (ピクセル単位)。

    • width float

      要素の幅 (ピクセル単位)。

    • height float

      要素の高さ (ピクセル単位)。

content_frame​

v1.9より前に追加 elementHandle.content_frame

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

使用法

element_handle.content_frame()

戻り値

owner_frame​

v1.9より前に追加 elementHandle.owner_frame

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

使用法

element_handle.owner_frame()

戻り値

wait_for_element_state​

v1.9より前に追加 elementHandle.wait_for_element_state

要素が状態を満たすまで待機し、満たしたら返します。

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

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

使用法

element_handle.wait_for_element_state(state)
element_handle.wait_for_element_state(state, **kwargs)

引数

  • state "visible" | "hidden" | "stable" | "enabled" | "disabled" | "editable"#

    待機する状態。詳細については下記を参照してください。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

非推奨​

check​

v1.9より前に追加 elementHandle.check
推奨されません

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

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

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

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

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

使用法

element_handle.check()
element_handle.check(**kwargs)

引数

  • force bool (オプション)#

    アクション性チェックをバイパスするかどうか。デフォルトは false です。

  • no_wait_after bool (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Dict (オプション)追加されたバージョン: v1.11#

    要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)追加されたバージョン: v1.11#

    設定すると、このメソッドは アクション性 チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備が整うまで待機するのに役立ちます。

戻り値

click​

v1.9より前に追加 elementHandle.click
推奨されません

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

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

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

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

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

使用法

element_handle.click()
element_handle.click(**kwargs)

引数

  • button "left" | "right" | "middle" (オプション)#

    デフォルトは left です。

  • click_count int (オプション)#

    デフォルトは 1 です。UIEvent.detail を参照してください。

  • delay float (オプション)#

    mousedown と mouseup の間の待機時間 (ミリ秒単位)。デフォルトは 0 です。

  • force bool (オプション)#

    アクション性チェックをバイパスするかどうか。デフォルトは false です。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (オプション)#

    押す修飾キー。操作中にこれらの修飾キーのみが押されていることを保証し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows と Linux では "Control" に、macOS では "Meta" に解決されます。

  • no_wait_after bool (オプション)#

    非推奨

    このオプションは将来 true になります。

    ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページがロードを開始するのを待機します。このフラグを設定することで、待機をオプトアウトできます。これは、アクセスできないページにナビゲートするなどの例外的な場合にのみ必要です。デフォルトは false です。

  • position Dict (オプション)#

    要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)追加されたバージョン: v1.11#

    設定すると、このメソッドは アクション性 チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備が整うまで待機するのに役立ちます。

戻り値

dblclick​

v1.9より前に追加 elementHandle.dblclick
推奨されません

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

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

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

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

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

注

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

使用法

element_handle.dblclick()
element_handle.dblclick(**kwargs)

引数

  • button "left" | "right" | "middle" (オプション)#

    デフォルトは left です。

  • delay float (オプション)#

    mousedown と mouseup の間の待機時間 (ミリ秒単位)。デフォルトは 0 です。

  • force bool (オプション)#

    アクション性チェックをバイパスするかどうか。デフォルトは false です。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (オプション)#

    押す修飾キー。操作中にこれらの修飾キーのみが押されていることを保証し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows と Linux では "Control" に、macOS では "Meta" に解決されます。

  • no_wait_after bool (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Dict (オプション)#

    要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)追加されたバージョン: v1.11#

    設定すると、このメソッドは アクション性 チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備が整うまで待機するのに役立ちます。

戻り値

dispatch_event​

v1.9より前に追加 elementHandle.dispatch_event
推奨されません

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

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

使用法

element_handle.dispatch_event("click")

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

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

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

# note you can only create data_transfer in chromium and firefox
data_transfer = page.evaluate_handle("new DataTransfer()")
element_handle.dispatch_event("#source", "dragstart", {"dataTransfer": data_transfer})

引数

  • type str#

    DOM イベントタイプ: "click"、"dragstart" など。

  • event_init EvaluationArgument (オプション)#

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

戻り値

eval_on_selector​

追加バージョン: v1.9 elementHandle.eval_on_selector
推奨されません

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

expressionの戻り値を返します。

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

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

使用法

tweet_handle = page.query_selector(".tweet")
assert tweet_handle.eval_on_selector(".like", "node => node.innerText") == "100"
assert tweet_handle.eval_on_selector(".retweets", "node => node.innerText") == "10"

引数

  • selector str#

    クエリするセレクター。

  • expression str#

    ブラウザーコンテキストで評価される JavaScript 式。式が関数に評価される場合、その関数は自動的に呼び出されます。

  • arg EvaluationArgument (オプション)#

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

戻り値

eval_on_selector_all​

追加バージョン: v1.9 elementHandle.eval_on_selector_all
推奨されません

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

expressionの戻り値を返します。

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

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

使用法

<div class="feed">
  <div class="tweet">Hello!</div>
  <div class="tweet">Hi!</div>
</div>
feed_handle = page.query_selector(".feed")
assert feed_handle.eval_on_selector_all(".tweet", "nodes => nodes.map(n => n.innerText)") == ["hello!", "hi!"]

引数

  • selector str#

    クエリするセレクター。

  • expression str#

    ブラウザーコンテキストで評価される JavaScript 式。式が関数に評価される場合、その関数は自動的に呼び出されます。

  • arg EvaluationArgument (オプション)#

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

戻り値

fill​

v1.9より前に追加 elementHandle.fill
推奨されません

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

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

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

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

使用法

element_handle.fill(value)
element_handle.fill(value, **kwargs)

引数

  • value str#

    <input>、<textarea>、または [contenteditable] 要素に設定する値。

  • force bool (オプション)追加バージョン: v1.13#

    アクション性チェックをバイパスするかどうか。デフォルトは false です。

  • no_wait_after bool (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

focus​

v1.9より前に追加 elementHandle.focus
推奨されません

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

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

使用法

element_handle.focus()

戻り値

get_attribute​

v1.9より前に追加 elementHandle.get_attribute
推奨されません

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

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

使用法

element_handle.get_attribute(name)

引数

  • name str#

    値を取得する属性名。

戻り値

hover​

v1.9より前に追加 elementHandle.hover
推奨されません

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

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

  1. forceオプションが設定されていない限り、要素に対するアクション可能性チェックを待機します。
  2. 必要に応じて要素を表示するためにスクロールします。
  3. page.mouseを使用して、要素の中心、または指定されたpositionにカーソルを合わせます。

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

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

使用法

element_handle.hover()
element_handle.hover(**kwargs)

引数

  • force bool (オプション)#

    アクション性チェックをバイパスするかどうか。デフォルトは false です。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (オプション)#

    押す修飾キー。操作中にこれらの修飾キーのみが押されていることを保証し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows と Linux では "Control" に、macOS では "Meta" に解決されます。

  • no_wait_after bool (オプション)追加バージョン: v1.28#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Dict (オプション)#

    要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)追加されたバージョン: v1.11#

    設定すると、このメソッドは アクション性 チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備が整うまで待機するのに役立ちます。

戻り値

inner_html​

v1.9より前に追加 elementHandle.inner_html
推奨されません

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

element.innerHTML を返します。

使用法

element_handle.inner_html()

戻り値

inner_text​

v1.9より前に追加 elementHandle.inner_text
推奨されません

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

element.innerText を返します。

使用法

element_handle.inner_text()

戻り値

input_value​

追加バージョン: v1.13 elementHandle.input_value
推奨されません

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

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

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

使用法

element_handle.input_value()
element_handle.input_value(**kwargs)

引数

戻り値

is_checked​

v1.9より前に追加 elementHandle.is_checked
推奨されません

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

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

使用法

element_handle.is_checked()

戻り値

is_disabled​

v1.9より前に追加 elementHandle.is_disabled
推奨されません

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

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

使用法

element_handle.is_disabled()

戻り値

is_editable​

v1.9より前に追加 elementHandle.is_editable
推奨されません

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

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

使用法

element_handle.is_editable()

戻り値

is_enabled​

v1.9より前に追加 elementHandle.is_enabled
推奨されません

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

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

使用法

element_handle.is_enabled()

戻り値

is_hidden​

v1.9より前に追加 elementHandle.is_hidden
推奨されません

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

要素が非表示であるか、表示されているの反対を返します。

使用法

element_handle.is_hidden()

戻り値

is_visible​

v1.9より前に追加 elementHandle.is_visible
推奨されません

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

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

使用法

element_handle.is_visible()

戻り値

press​

v1.9より前に追加 elementHandle.press
推奨されません

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

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

keyは、意図したkeyboardEvent.key値を指定するか、テキストを生成するための1文字を指定できます。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が1文字の場合、大文字と小文字を区別するため、値aとAでは異なるテキストが生成されます。

key: "Control+o"、key: "Control++、key: "Control+Shift+T"のようなショートカットもサポートされています。修飾キーを指定した場合、修飾キーは押し続けられ、その後に続くキーが押されます。

使用法

element_handle.press(key)
element_handle.press(key, **kwargs)

引数

  • key str#

    押すキーの名前、または ArrowLeft や a などの生成する文字。

  • delay float (オプション)#

    keydown と keyup の間の待機時間 (ミリ秒)。デフォルトは 0 です。

  • no_wait_after bool (オプション)#

    非推奨

    このオプションは将来 true になります。

    ナビゲーションを開始するアクションは、これらのナビゲーションが発生し、ページがロードを開始するのを待機します。このフラグを設定することで、待機をオプトアウトできます。これは、アクセスできないページにナビゲートするなどの例外的な場合にのみ必要です。デフォルトは false です。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

query_selector​

追加バージョン: v1.9 elementHandle.query_selector
推奨されません

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

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

使用法

element_handle.query_selector(selector)

引数

  • selector str#

    クエリするセレクター。

戻り値

query_selector_all​

追加バージョン: v1.9 elementHandle.query_selector_all
推奨されません

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

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

使用法

element_handle.query_selector_all(selector)

引数

  • selector str#

    クエリするセレクター。

戻り値

screenshot​

v1.9より前に追加 elementHandle.screenshot
推奨されません

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

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

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

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

使用法

element_handle.screenshot()
element_handle.screenshot(**kwargs)

引数

  • animations "disabled" | "allow" (オプション)#

    "disabled"に設定すると、CSSアニメーション、CSSトランジション、Webアニメーションが停止します。アニメーションは期間によって異なる扱いを受けます。

    • 有限のアニメーションは完了まで早送りされ、transitionendイベントが発生します。
    • 無限のアニメーションは初期状態にキャンセルされ、スクリーンショットの後に再生されます。

    デフォルトは"allow"で、アニメーションはそのまま残されます。

  • caret "hide" | "initial" (オプション)#

    "hide"に設定すると、スクリーンショットはテキストキャレットを非表示にします。"initial"に設定すると、テキストキャレットの動作は変更されません。デフォルトは"hide"です。

  • mask List[Locator] (オプション)#

    スクリーンショット撮影時にマスクされるロケーターを指定します。マスクされた要素は、境界ボックスを完全に覆うピンク色のボックス#FF00FF（mask_colorでカスタマイズ可能）で重ねて表示されます。マスクは非表示の要素にも適用されます。表示されている要素のみに一致を無効にするには、こちらを参照してください。

  • mask_color str (オプション)追加されたバージョン: v1.35#

    CSSカラー形式で、マスクされた要素のオーバーレイボックスの色を指定します。デフォルトの色はピンク#FF00FFです。

  • omit_background bool (オプション)#

    デフォルトの白い背景を非表示にし、透過性のあるスクリーンショットをキャプチャできるようにします。jpeg画像には適用されません。デフォルトはfalseです。

  • path Union[str, pathlib.Path] (オプション)#

    画像を保存するファイルパスです。スクリーンショットのタイプはファイル拡張子から推測されます。pathが相対パスの場合、現在の作業ディレクトリを基準に解決されます。パスが指定されていない場合、画像はディスクに保存されません。

  • quality int (オプション)#

    画像の品質（0～100）。png画像には適用されません。

  • scale "css" | "device" (オプション)#

    "css"に設定すると、スクリーンショットはページ上の各CSSピクセルにつき1ピクセルになります。高DPIデバイスの場合、これによりスクリーンショットが小さく保たれます。"device"オプションを使用すると、各デバイスピクセルにつき1ピクセルが生成されるため、高DPIデバイスのスクリーンショットは2倍以上大きくなります。

    デフォルトは"device"です。

  • style str (オプション)追加日: v1.41#

    スクリーンショット作成時に適用するスタイルシートのテキスト。これにより、動的な要素を非表示にしたり、要素を見えなくしたり、プロパティを変更したりして、再現性のあるスクリーンショットを作成するのに役立ちます。このスタイルシートはShadow DOMを貫通し、内部フレームにも適用されます。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • type "png" | "jpeg" (オプション)#

    スクリーンショットの種類を指定します。デフォルトはpngです。

戻り値

scroll_into_view_if_needed​

v1.9より前に追加 elementHandle.scroll_into_view_if_needed
推奨されません

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

このメソッドはアクション可能性チェックを待機し、その後、IntersectionObserverのratioで定義されるように完全に表示されていない限り、要素をビューにスクロールしようとします。

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

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

使用法

element_handle.scroll_into_view_if_needed()
element_handle.scroll_into_view_if_needed(**kwargs)

引数

戻り値

select_option​

v1.9より前に追加 elementHandle.select_option
推奨されません

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

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

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

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

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

使用法

# Single selection matching the value or label
handle.select_option("blue")
# single selection matching both the label
handle.select_option(label="blue")
# multiple selection
handle.select_option(value=["red", "green", "blue"])

引数

  • force bool (オプション)追加バージョン: v1.13#

    アクション性チェックをバイパスするかどうか。デフォルトは false です。

  • no_wait_after bool (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • element ElementHandle | List[ElementHandle] (オプション)#

    選択するオプション要素。オプション。

  • index int | List[int] (オプション)#

    インデックスで選択するオプション。オプション。

  • value str | List[str] (オプション)#

    値で選択するオプション。<select>にmultiple属性がある場合、指定されたすべてのオプションが選択され、そうでない場合は、渡されたオプションのいずれかに一致する最初のオプションのみが選択されます。オプション。

  • label str | List[str] (オプション)#

    ラベルで選択するオプション。<select>にmultiple属性がある場合、指定されたすべてのオプションが選択され、そうでない場合は、渡されたオプションのいずれかに一致する最初のオプションのみが選択されます。オプション。

戻り値

select_text​

v1.9より前に追加 elementHandle.select_text
推奨されません

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

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

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

使用法

element_handle.select_text()
element_handle.select_text(**kwargs)

引数

  • force bool (オプション)追加バージョン: v1.13#

    アクション性チェックをバイパスするかどうか。デフォルトは false です。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

set_checked​

追加されたバージョン: v1.15 elementHandle.set_checked
推奨されません

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

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

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

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

使用法

element_handle.set_checked(checked)
element_handle.set_checked(checked, **kwargs)

引数

  • checked bool#

    チェックボックスをチェックするか、チェックを外すか。

  • force bool (オプション)#

    アクション性チェックをバイパスするかどうか。デフォルトは false です。

  • no_wait_after bool (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Dict (オプション)#

    要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)#

    設定すると、このメソッドは アクション性 チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備が整うまで待機するのに役立ちます。

戻り値

set_input_files​

v1.9より前に追加 elementHandle.set_input_files
推奨されません

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

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

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

使用法

element_handle.set_input_files(files)
element_handle.set_input_files(files, **kwargs)

引数

戻り値

tap​

v1.9より前に追加 elementHandle.tap
推奨されません

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

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

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

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

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

注

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

使用法

element_handle.tap()
element_handle.tap(**kwargs)

引数

  • force bool (オプション)#

    アクション性チェックをバイパスするかどうか。デフォルトは false です。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (オプション)#

    押す修飾キー。操作中にこれらの修飾キーのみが押されていることを保証し、現在の修飾キーを元に戻します。指定しない場合、現在押されている修飾キーが使用されます。"ControlOrMeta" は、Windows と Linux では "Control" に、macOS では "Meta" に解決されます。

  • no_wait_after bool (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Dict (オプション)#

    要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)追加されたバージョン: v1.11#

    設定すると、このメソッドは アクション性 チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備が整うまで待機するのに役立ちます。

戻り値

text_content​

v1.9より前に追加 elementHandle.text_content
推奨されません

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

node.textContent を返します。

使用法

element_handle.text_content()

戻り値

type​

v1.9より前に追加 elementHandle.type
非推奨

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

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

ControlやArrowDownのような特殊キーを押すには、element_handle.press()を使用します。

使用法

引数

  • text str#

    フォーカスされた要素に入力するテキスト。

  • delay float (オプション)#

    キー押下間の待機時間（ミリ秒）。デフォルトは0です。

  • no_wait_after bool (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値

uncheck​

v1.9より前に追加 elementHandle.uncheck
推奨されません

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

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

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

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

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

使用法

element_handle.uncheck()
element_handle.uncheck(**kwargs)

引数

  • force bool (オプション)#

    アクション性チェックをバイパスするかどうか。デフォルトは false です。

  • no_wait_after bool (オプション)#

    非推奨

    このオプションは効果がありません。

    このオプションは効果がありません。

  • position Dict (オプション)追加されたバージョン: v1.11#

    要素のパディングボックスの左上隅を基準に使用する点。指定しない場合は、要素の可視点の一部が使用されます。

  • timeout float (オプション)#

    最大時間 (ミリ秒)。デフォルトは 30000 (30秒) です。タイムアウトを無効にするには 0 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

  • trial bool (オプション)追加されたバージョン: v1.11#

    設定すると、このメソッドは アクション性 チェックのみを実行し、アクションをスキップします。デフォルトは false です。アクションを実行せずに要素がアクションの準備が整うまで待機するのに役立ちます。

戻り値

wait_for_selector​

v1.9より前に追加 elementHandle.wait_for_selector
推奨されません

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

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

要素ハンドルに対するセレクターがstateオプション（domへの出現/消失、または表示/非表示になる）を満たすまで待機します。メソッド呼び出し時にセレクターが既に条件を満たしている場合、メソッドは直ちに返されます。セレクターがtimeoutミリ秒の間条件を満たさない場合、関数はエラーをスローします。

使用法

page.set_content("<div><span></span></div>")
div = page.query_selector("div")
# waiting for the "span" selector relative to the div.
span = div.wait_for_selector("span", state="attached")
注

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

引数

  • selector str#

    クエリするセレクター。

  • state "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 を渡します。デフォルト値は browser_context.set_default_timeout() または page.set_default_timeout() メソッドを使用して変更できます。

戻り値