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

ElementHandle

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

非推奨

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

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()

Locator を使用すると、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 ノードを参照する ElementHandle のコンテンツフレームを返します。それ以外の場合は 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 を満たすときに戻ります。

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

  • "visible" 要素が visible になるまで待ちます。
  • "hidden" 要素が visible でなくなる か、またはアタッチされなくなるまで待ちます。hidden の待機は、要素がデタッチされても例外をスローしないことに注意してください。
  • "stable" 要素が visible かつ stable になるまで待ちます。
  • "enabled" 要素が enabled になるまで待ちます。
  • "disabled" 要素が enabled でなくなる まで待ちます。
  • "editable" 要素が editable になるまで待ちます。

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

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

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

使用例

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

引数

  • force bool (オプション)#

    actionability チェックをバイパスするかどうか。デフォルトは 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#

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

戻り値

click​

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

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

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

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

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

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

使用例

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 (オプション)#

    actionability チェックをバイパスするかどうか。デフォルトは 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#

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

戻り値

dblclick​

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

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

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

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

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

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

注

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 (オプション)#

    actionability チェックをバイパスするかどうか。デフォルトは 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#

    設定すると、このメソッドは actionability チェックのみを実行し、アクションをスキップします。デフォルトは 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
非推奨

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

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

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() を使用してください。ロケーターの詳細をご覧ください。

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

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

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

使用例

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

引数

  • value str#

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

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

    actionability チェックをバイパスするかどうか。デフォルトは false です。

  • no_wait_after bool (任意)#

    非推奨

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

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

  • timeout float (任意)#

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

戻り値

フォーカス​

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#

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

戻り値

ホバー​

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

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

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

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

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

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

使用例

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

引数

  • force bool (任意)#

    actionability チェックをバイパスするかどうか。デフォルトは 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#

    設定すると、このメソッドは actionability チェックのみを実行し、アクションをスキップします。デフォルトは 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 を返します。

入力要素以外の場合、エラーをスローします。ただし、要素が、関連付けられた control を持つ <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 値、またはテキストを生成するための単一の文字を指定できます。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" などのショートカットもサポートされています。修飾子付きで指定すると、修飾子が押され、後続のキーが押されている間、保持されます。

使用例

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 がドキュメントまたは 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> 要素でない場合、このメソッドはエラーをスローします。ただし、要素が、関連付けられた control を持つ <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#

    actionability チェックをバイパスするかどうか。デフォルトは 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() を代わりに使用してください。ロケーターの詳細をお読みください。

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

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

使用例

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

引数

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

    actionability チェックをバイパスするかどうか。デフォルトは 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 をスローします。タイムアウトにゼロを渡すと、これは無効になります。

使用例

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

引数

  • checked bool#

    チェックボックスをチェックまたはチェック解除するかどうか。

  • force bool (任意)#

    actionability チェックをバイパスするかどうか。デフォルトは false です。

  • no_wait_after bool (任意)#

    非推奨

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

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

  • position Dict (任意)#

    要素のパディングボックスの左上隅を基準に使用するポイント。指定しない場合は、要素の表示可能なポイントを使用します。

  • timeout float (任意)#

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

  • trial bool (任意)#

    設定すると、このメソッドは actionability チェックのみを実行し、アクションをスキップします。デフォルトは 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 をスローします。タイムアウトにゼロを渡すと、これは無効になります。

注

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

使用例

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

引数

  • force bool (任意)#

    actionability チェックをバイパスするかどうか。デフォルトは 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#

    設定すると、このメソッドは actionability チェックのみを実行し、アクションをスキップします。デフォルトは 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 をスローします。タイムアウトにゼロを渡すと、これは無効になります。

使用例

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

引数

  • force bool (任意)#

    actionability チェックをバイパスするかどうか。デフォルトは 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#

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

戻り値

wait_for_selector​

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

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

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

要素ハンドルを基準とした selector が state オプション（DOM に出現/消失、または可視/非表示になる）を満たすのを待ちます。メソッドを呼び出した時点で selector がすでに条件を満たしている場合、メソッドはすぐに戻ります。セレクターが 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' - 要素が空でない bounding box を持ち、visibility:hidden でないことを待ちます。コンテンツがない要素や display:none が設定された要素は空の bounding box を持ち、可視とは見なされないことに注意してください。
    • 'hidden' - 要素が DOM からデタッチされるか、空の bounding box を持つか、visibility:hidden であるかのいずれかになるのを待ちます。これは 'visible' オプションの反対です。

  • strict bool (任意)バージョン v1.15 で追加#

    true の場合、この呼び出しでは、セレクターが単一の要素に解決される必要があります。指定されたセレクターが複数の要素に解決される場合、呼び出しは例外をスローします。

  • timeout float (任意)#

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

戻り値