句柄
简介
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"));
作为参数的句柄
句柄可以传递给 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 对应方法 Frame.EvaluateHandleAsync()、Frame.QuerySelectorAsync() 或 Frame.QuerySelectorAllAsync()。一旦创建,除非页面导航或句柄通过 JsHandle.DisposeAsync() 方法手动释放,否则句柄将保留对象以防止 垃圾回收。
API 参考
- JSHandle
- ElementHandle
- ElementHandle.BoundingBoxAsync()
- ElementHandle.GetAttributeAsync()
- ElementHandle.InnerTextAsync()
- ElementHandle.InnerHTMLAsync()
- ElementHandle.TextContentAsync()
- JsHandle.EvaluateAsync()
- Page.EvaluateHandleAsync()
- Page.QuerySelectorAsync()
- Page.QuerySelectorAllAsync()
Locator vs ElementHandle
我们只建议在极少数情况下使用 ElementHandle,即当您需要在静态页面上执行大量的 DOM 遍历时。对于所有用户操作和断言,请改用定位器。
定位器 (Locator) 和 元素句柄 (ElementHandle) 之间的区别在于,后者指向特定的元素,而定位器则捕获如何检索该元素的逻辑。
在下面的示例中,句柄指向页面上的特定 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();