跳到主内容

句柄

介绍

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 优先断言。

如果需要使用 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"));

将句柄作为参数

句柄可以传递给 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();

句柄生命周期

句柄可以使用页面方法获取,例如 Page.EvaluateHandleAsync()Page.QuerySelectorAsync()Page.QuerySelectorAllAsync(),或者其框架对应方法 Frame.EvaluateHandleAsync()Frame.QuerySelectorAsync()Frame.QuerySelectorAllAsync()。创建后,除非页面导航或通过 JsHandle.DisposeAsync() 方法手动释放句柄,否则句柄会阻止对象被 垃圾回收

API 参考

定位器与元素句柄

注意

我们只在极少数需要对静态页面进行大量 DOM 遍历的情况下推荐使用 ElementHandle。对于所有用户操作和断言,请改用定位器。

Locator 和 ElementHandle 的区别在于,后者指向一个特定的元素,而 Locator 捕获了如何检索该元素的逻辑。

在下面的示例中,句柄指向页面中的一个特定 DOM 元素。如果该元素更改了文本或被 React 用于渲染一个完全不同的组件,句柄仍然指向那个陈旧的 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();