Skip to main content

ElementHandle

ElementHandle 代表頁面中的 DOM 元素。ElementHandle 可以使用 page.query_selector() 方法建立。

不建議使用

不建議使用 ElementHandle，請改用 Locator 物件和網頁優先的斷言。

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

ElementHandle 會阻止 DOM 元素被垃圾回收，除非使用 js_handle.dispose() 處置控制代碼。當其原始框架導航時，ElementHandle 會自動處置。

ElementHandle 實例可以用作 page.eval_on_selector() 和 page.evaluate() 方法中的引數。

Locator 和 ElementHandle 之間的區別在於，ElementHandle 指向特定的元素，而 Locator 捕捉了如何檢索元素的邏輯。

在下面的範例中，控制代碼指向頁面上的特定 DOM 元素。如果該元素更改文字或被 React 用於渲染完全不同的組件，則控制代碼仍然指向該 DOM 元素。這可能會導致意外的行為。

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

使用 locator，每次使用 element 時，都會使用選擇器在頁面中找到最新的 DOM 元素。因此，在下面的程式碼片段中，底層 DOM 元素將被找到兩次。

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 時傳回。

根據 state 參數，此方法會等待其中一項 可操作性 檢查通過。當元素在等待時分離時，此方法會拋出錯誤，除非等待 "hidden" 狀態。

  • "visible" 等待直到元素 可見。
  • "hidden" 等待直到元素 不可見 或未附加。請注意，等待 hidden 狀態在元素分離時不會拋出錯誤。
  • "stable" 等待直到元素 可見 且 穩定。
  • "enabled" 等待直到元素 啟用。
  • "disabled" 等待直到元素 未啟用。
  • "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 的 locator.check()。閱讀更多關於 locators 的資訊。

此方法透過執行以下步驟來檢查元素

  1. 確保元素是核取方塊或單選輸入。如果不是，此方法會拋出錯誤。如果元素已勾選，此方法會立即傳回。
  2. 等待元素上的 可操作性 檢查通過，除非設定 force 選項。
  3. 如果需要，將元素滾動到視野中。
  4. 使用 page.mouse 在元素的中心點擊。
  5. 確保元素現在已勾選。如果沒有，此方法會拋出錯誤。

如果在動作期間的任何時刻元素從 DOM 中分離，此方法會拋出錯誤。

當所有步驟組合在一起在指定的 timeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

用法

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

引數

  • force bool (選填)#

    是否繞過 可操作性 檢查。預設為 false。

  • no_wait_after bool (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (選填)新增於： v1.11#

    相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。

  • 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 的 locator.click()。閱讀更多關於 locators 的資訊。

此方法透過執行以下步驟來點擊元素

  1. 等待元素上的 可操作性 檢查通過，除非設定 force 選項。
  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 (選填)#

    是否繞過 可操作性 檢查。預設為 false。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (選填)#

    要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。

  • no_wait_after bool (選填)#

    已棄用

    此選項未來將預設為 true。

    啟動導航的動作正在等待這些導航發生並等待頁面開始載入。您可以透過設定此旗標來選擇不等待。您只需要在特殊情況下使用此選項，例如導航到無法存取的頁面。預設為 false。

  • position Dict (選填)#

    相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。

  • 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 的 locator.dblclick()。閱讀更多關於 locators 的資訊。

此方法透過執行以下步驟來雙擊元素

  1. 等待元素上的 可操作性 檢查通過，除非設定 force 選項。
  2. 如果需要，將元素滾動到視野中。
  3. 使用 page.mouse 在元素的中心雙擊，或指定的 position。

如果在動作期間的任何時刻元素從 DOM 中分離，此方法會拋出錯誤。

當所有步驟組合在一起在指定的 timeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

注意

elementHandle.dblclick() 會分派兩個 click 事件和一個 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 (選填)#

    相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。

  • 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 的 locator.dispatch_event()。閱讀更多關於 locators 的資訊。

下面的程式碼片段在元素上分派 click 事件。無論元素的顯示狀態如何，都會分派 click。這相當於呼叫 element.click()。

用法

element_handle.dispatch_event("click")

在底層，它會根據給定的 type 建立事件的實例，使用 event_init 屬性初始化它，並在元素上分派它。事件預設為 composed、cancelable 和 bubble。

由於 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 的 locator.fill()。閱讀更多關於 locators 的資訊。

此方法會等待 可操作性 檢查通過，聚焦元素，填寫它，並在填寫後觸發 input 事件。請注意，您可以傳遞空字串來清除輸入欄位。

如果目標元素不是 <input>、<textarea> 或 [contenteditable] 元素，此方法會拋出錯誤。但是，如果元素位於具有關聯 control 的 <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 的 locator.focus()。閱讀更多關於 locators 的資訊。

在元素上呼叫 focus。

用法

element_handle.focus()

傳回

get_attribute​

在 v1.9 之前新增 elementHandle.get_attribute
不建議使用

改用基於 locator 的 locator.get_attribute()。閱讀更多關於 locators 的資訊。

傳回元素屬性值。

用法

element_handle.get_attribute(name)

引數

  • name str#

    要取得其值的屬性名稱。

傳回

hover​

在 v1.9 之前新增 elementHandle.hover
不建議使用

改用基於 locator 的 locator.hover()。閱讀更多關於 locators 的資訊。

此方法透過執行以下步驟來懸停在元素上方

  1. 等待元素上的 可操作性 檢查通過，除非設定 force 選項。
  2. 如果需要，將元素滾動到視野中。
  3. 使用 page.mouse 將滑鼠懸停在元素的中心上方，或指定的 position。

如果在動作期間的任何時刻元素從 DOM 中分離，此方法會拋出錯誤。

當所有步驟組合在一起在指定的 timeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零逾時會停用此功能。

用法

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 (選填)#

    相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。

  • 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 的 locator.inner_html()。閱讀更多關於 locators 的資訊。

傳回 element.innerHTML。

用法

element_handle.inner_html()

傳回

inner_text​

在 v1.9 之前新增 elementHandle.inner_text
不建議使用

改用基於 locator 的 locator.inner_text()。閱讀更多關於 locators 的資訊。

傳回 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 值或單一字元以產生文字。可以在 此處 找到 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 字串#

    要按下的按鍵名稱或要產生的字元，例如 ArrowLeft 或 a。

  • delay 浮點數 (選填)#

    keydown 和 keyup 之間等待的時間，以毫秒為單位。預設為 0。

  • no_wait_after 布林值 (選填)#

    已棄用

    此選項未來將預設為 true。

    啟動導航的動作正在等待這些導航發生並等待頁面開始載入。您可以透過設定此旗標來選擇不等待。您只需要在特殊情況下使用此選項，例如導航到無法存取的頁面。預設為 false。

  • timeout 浮點數 (選填)#

    最大等待時間，以毫秒為單位。預設為 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 字串#

    要查詢的選擇器。

傳回

query_selector_all​

新增於： v1.9 elementHandle.query_selector_all
不建議使用

請改用基於定位器的 page.locator()。閱讀更多關於 定位器 的資訊。

此方法會在 ElementHandle 的子樹中尋找所有符合指定選擇器的元素。如果沒有元素符合選擇器，則傳回空陣列。

用法

element_handle.query_selector_all(selector)

引數

  • selector 字串#

    要查詢的選擇器。

傳回

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 字串 (選填)新增於：v1.35#

    以 CSS 色彩格式 指定遮罩元素的覆蓋方塊的顏色。預設顏色為粉紅色 #FF00FF。

  • omit_background 布林值 (選填)#

    隱藏預設的白色背景，並允許擷取具有透明度的螢幕截圖。不適用於 jpeg 影像。預設為 false。

  • path Union[字串, pathlib.Path] (選填)#

    儲存影像的檔案路徑。螢幕截圖類型將會從檔案副檔名推斷。如果 path 是相對路徑，則會相對於目前的工作目錄解析。如果未提供路徑，則影像將不會儲存到磁碟。

  • quality 整數 (選填)#

    影像品質，介於 0-100 之間。不適用於 png 影像。

  • scale "css" | "device" (選填)#

    設定為 "css" 時，螢幕截圖的每個 css 像素將會有單一像素。對於高 dpi 裝置，這將使螢幕截圖保持較小。使用 "device" 選項將會為每個裝置像素產生單一像素，因此高 dpi 裝置的螢幕截圖將會大兩倍甚至更大。

    預設為 "device"。

  • style 字串 (選填)新增於：v1.41#

    在製作螢幕截圖時要套用的樣式表文字。您可以在此處隱藏動態元素、使元素不可見或變更其屬性，以協助您建立可重複的螢幕截圖。此樣式表會穿透 Shadow DOM 並套用至內部框架。

  • timeout 浮點數 (選填)#

    最大等待時間，以毫秒為單位。預設為 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 布林值 (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • timeout 浮點數 (選填)#

    最大等待時間，以毫秒為單位。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • element ElementHandle | List[ElementHandle] (選填)#

    要選取的選項元素。選填。

  • index 整數 | List[整數] (選填)#

    要依索引選取的選項。選填。

  • value 字串 | List[字串] (選填)#

    要依值選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有給定的選項，否則只會選取符合其中一個傳遞選項的第一個選項。選填。

  • label 字串 | List[字串] (選填)#

    要依標籤選取的選項。如果 <select> 具有 multiple 屬性，則會選取所有給定的選項，否則只會選取符合其中一個傳遞選項的第一個選項。選填。

傳回

select_text​

在 v1.9 之前新增 elementHandle.select_text
不建議使用

請改用基於定位器的 locator.select_text()。閱讀更多關於 定位器 的資訊。

此方法會等待 可操作性 檢查，然後聚焦元素並選取其所有文字內容。

如果元素位於具有相關 控制項 的 <label> 元素內，則會改為聚焦並選取控制項中的文字。

用法

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

引數

傳回

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 布林值#

    是否勾選或取消勾選核取方塊。

  • force 布林值 (選填)#

    是否繞過 可操作性 檢查。預設為 false。

  • no_wait_after 布林值 (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (選填)#

    相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。

  • timeout 浮點數 (選填)#

    最大等待時間，以毫秒為單位。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

  • trial 布林值 (選填)#

    設定後，此方法僅執行 可操作性 檢查並跳過動作。預設為 false。在執行動作之前等待元素準備就緒時很有用。

傳回

set_input_files​

在 v1.9 之前新增 elementHandle.set_input_files
不建議使用

請改用基於定位器的 locator.set_input_files()。閱讀更多關於 定位器 的資訊。

將檔案輸入的值設定為這些檔案路徑或檔案。如果某些 filePaths 是相對路徑，則會相對於目前的工作目錄解析。對於空陣列，會清除選取的檔案。對於具有 [webkitdirectory] 屬性的輸入，僅支援單一目錄路徑。

此方法預期 ElementHandle 指向 input 元素。但是，如果元素位於具有相關 控制項 的 <label> 元素內，則會改為以控制項為目標。

用法

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 布林值 (選填)#

    是否繞過 可操作性 檢查。預設為 false。

  • modifiers List["Alt" | "Control" | "ControlOrMeta" | "Meta" | "Shift"] (選填)#

    要按下的修飾鍵。確保在操作期間僅按下這些修飾鍵，然後恢復目前的修飾鍵。如果未指定，則使用目前按下的修飾鍵。"ControlOrMeta" 在 Windows 和 Linux 上解析為 "Control"，在 macOS 上解析為 "Meta"。

  • no_wait_after 布林值 (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (選填)#

    相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。

  • timeout 浮點數 (選填)#

    最大等待時間，以毫秒為單位。預設為 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() 來代替。只有在頁面上有特殊的鍵盤處理時，才需要逐個按鍵 - 在這種情況下，請使用 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() 方法變更預設值。

傳回

取消勾選​

在 v1.9 之前新增 elementHandle.uncheck
不建議使用

請改用基於 locator 的 locator.uncheck()。閱讀更多關於 locators 的資訊。

此方法透過執行以下步驟來檢查元素

  1. 確保元素是一個核取方塊或選項按鈕輸入。如果不是，此方法會拋出錯誤。如果元素已經取消勾選，此方法會立即返回。
  2. 等待元素上的 可操作性 檢查，除非設定了 force 選項。
  3. 如果需要，將元素滾動到視野中。
  4. 使用 page.mouse 在元素的中心點擊。
  5. 確保元素現在已取消勾選。如果不是，此方法會拋出錯誤。

如果在動作期間的任何時刻元素從 DOM 中分離，此方法會拋出錯誤。

當所有步驟組合起來在指定的 timeout 期間未完成時，此方法會拋出 TimeoutError。傳遞零 timeout 會停用此功能。

用法

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

引數

  • force bool (選填)#

    是否繞過 可操作性 檢查。預設為 false。

  • no_wait_after bool (選填)#

    已棄用

    此選項無效。

    此選項無效。

  • position Dict (選填)新增於： v1.11#

    相對於元素 padding 框左上角的點。如果未指定，則使用元素的某些可見點。

  • 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
不建議使用

請改用 Web 斷言來斷言可見性，或基於 locator 的 locator.wait_for()。

當 selector 指定的元素滿足 state 選項時，返回該元素。如果等待 hidden 或 detached，則返回 null。

等待相對於元素句柄的 selector 滿足 state 選項（在 DOM 中出現/消失，或變為可見/隱藏）。如果在呼叫方法時 selector 已經滿足條件，則該方法將立即返回。如果 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' - 等待元素具有非空的邊界框且沒有 visibility:hidden。請注意，沒有任何內容或具有 display:none 的元素具有空的邊界框，並且不被視為可見。
    • 'hidden' - 等待元素從 DOM 中分離，或具有空的邊界框或 visibility:hidden。這與 'visible' 選項相反。

  • strict bool (選填)新增於：v1.15#

    當為 true 時，呼叫需要 selector 解析為單個元素。如果給定的 selector 解析為多個元素，則呼叫會拋出例外。

  • timeout float (選填)#

    最大等待時間，以毫秒為單位。預設為 30000 (30 秒)。傳遞 0 以停用逾時。可以使用 browser_context.set_default_timeout() 或 page.set_default_timeout() 方法變更預設值。

傳回