Skip to main content

控制代碼

簡介​

Playwright 可以建立頁面 DOM 元素或頁面內任何其他物件的控制代碼。這些控制代碼存在於 Playwright 程序中，而實際物件存在於瀏覽器中。有兩種類型的控制代碼：

  • JSHandle 用於參考頁面中的任何 JavaScript 物件
  • ElementHandle 用於參考頁面中的 DOM 元素，它具有額外的方法，允許對元素執行動作和斷言其屬性。

由於頁面中的任何 DOM 元素也是 JavaScript 物件，因此任何 ElementHandle 也是 JSHandle。

控制代碼用於對頁面中的實際物件執行操作。您可以對控制代碼進行求值、取得控制代碼屬性、將控制代碼作為求值參數傳遞、將頁面物件序列化為 JSON 等。請參閱 JSHandle 類別 API 以了解這些方法。

API 參考​

以下是取得 JSHandle 的最簡單方法。

js_handle = page.evaluate_handle('window')
#  使用 jsHandle 進行求值

元素控制代碼​

Discouraged

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

當需要 ElementHandle 時，建議使用 page.wait_for_selector() 或 frame.wait_for_selector() 方法來取得它。這些 API 會等待元素附加且可見。

# 取得元素控制代碼
element_handle = page.wait_for_selector('#box')

# 斷言元素的邊界框
bounding_box = element_handle.bounding_box()
assert bounding_box.width == 100

# 斷言元素的屬性
class_names = element_handle.get_attribute('class')
assert 'highlighted' in class_names

控制代碼作為參數​

控制代碼可以傳遞到 page.evaluate() 和類似的方法中。以下程式碼片段在頁面中建立一個新陣列，用資料初始化它，並將該陣列的控制代碼返回到 Playwright。然後在後續的求值中使用該控制代碼：

# 在頁面中建立新陣列
my_array_handle = page.evaluate_handle("""() => {
  window.myArray = [1];
  return myArray;
}""")

# 取得陣列的當前長度
length = page.evaluate("a => a.length", my_array_handle)

# 使用控制代碼向陣列新增一個元素
page.evaluate("(arg) => arg.myArray.push(arg.newElement)", {
  'myArray': my_array_handle,
  'newElement': 2
})

# 當不再需要物件時釋放它
my_array_handle.dispose()

控制代碼生命週期​

控制代碼可以使用頁面方法（如 page.evaluate_handle()、page.query_selector() 或 page.query_selector_all()）或其框架對應方法（frame.evaluate_handle()、frame.query_selector() 或 frame.query_selector_all()）取得。一旦建立，控制代碼將保留物件不被垃圾回收，除非頁面導航或通過 js_handle.dispose() 方法手動處置控制代碼。

API 參考​

定位器與元素控制代碼的比較​

caution

我們只建議在需要對靜態頁面執行大量 DOM 遍歷的罕見情況下使用 ElementHandle。對於所有使用者動作和斷言，請改用定位器。

Locator 和 ElementHandle 的區別在於，後者指向特定元素，而定位器捕獲如何檢索該元素的邏輯。

在下面的範例中，控制代碼指向頁面上的特定 DOM 元素。如果該元素更改文字或被 React 用來呈現完全不同的元件，控制代碼仍然指向那個非常過時的 DOM 元素。這可能導致意外的行為。

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

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

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