Skip to main content

控制代碼 (Handles)

簡介​

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

  • JSHandle 參考頁面中的任意 JavaScript 物件
  • ElementHandle 參考頁面中的 DOM 元素，它有額外的方法允許對元素執行操作並斷言它們的屬性。

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

操作柄用於對頁面中的那些實際物件進行操作。你可以在操作柄上進行評估，獲取操作柄屬性，將操作柄作為評估參數傳遞，將頁面物件序列化為 JSON 等等。請參閱 JSHandle 類別 API 以了解這些和方法。

API 參考​

這是獲取 JSHandle 的最簡單方法。

var jsHandle = await page.EvaluateHandleAsync("window");
//  Use jsHandle for evaluations.

元素處理器​

不建議

不建議使用 ElementHandle，請改用 Locator 物件和 web-first 斷言。

當需要 ElementHandle 時，建議使用 Page.WaitForSelectorAsync() 或 Frame.WaitForSelectorAsync() 方法來獲取。這些 API 會等待元素被附加並可見。

// Get the element handle
var jsHandle = await page.WaitForSelectorAsync("#box");
var elementHandle = jsHandle as ElementHandle;

// Assert bounding box for the element
var boundingBox = await elementHandle.BoundingBoxAsync();
Assert.AreEqual(100, boundingBox.Width);

// Assert attribute for the element
var classNames = await elementHandle.GetAttributeAsync("class");
Assert.True(classNames.Contains("highlighted"));

Handles as parameters​

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

// Create new array in page.
var myArrayHandle = await page.EvaluateHandleAsync(@"() => {
    window.myArray = [1];
    return myArray;
}");

// Get the length of the array.
var length = await page.EvaluateAsync<int>("a => a.length", myArrayHandle);

// Add one more element to the array using the handle
await page.EvaluateAsync("arg => arg.myArray.add(arg.newElement)",
    new { myArray = myArrayHandle, newElement = 2 });

// Release the object when it is no longer needed.
await myArrayHandle.DisposeAsync();

Handle Lifecycle​

控制代碼 (Handles) 可以使用頁面方法獲取，例如 Page.EvaluateHandleAsync()、Page.QuerySelectorAsync() 或 Page.QuerySelectorAllAsync()，或其框架對應方法 Frame.EvaluateHandleAsync()、Frame.QuerySelectorAsync() 或 Frame.QuerySelectorAllAsync()。一旦建立，控制代碼 (Handles) 將保留物件，防止 垃圾回收，除非頁面導航或通過 JsHandle.DisposeAsync() 方法手動處置控制代碼 (Handles) 。

API 參考​

定位器 vs ElementHandle​

caution

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

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

在以下範例中，handle 指向頁面上的特定 DOM 元素。如果該元素更改了文本或被 React 用於渲染完全不同的組件，handle 仍然指向那個非常過時的 DOM 元素。這可能會導致意外的行為。

var handle = await page.QuerySelectorAsync("text=Submit");
await handle.HoverAsync();
await handle.ClickAsync();

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

var locator = page.GetByText("Submit");
await locator.HoverAsync();
await locator.ClickAsync();