句柄

简介

Playwright 可以创建对页面 DOM 元素或页面内任何其他对象的句柄。这些句柄存在于 Playwright 进程中，而实际对象存在于浏览器中。句柄有两种类型：

JSHandle 用于引用页面中的任何 JavaScript 对象
ElementHandle 用于引用页面中的 DOM 元素，它有额外的方法，可用于对元素执行操作并断言其属性。

由于页面中的任何 DOM 元素也是 JavaScript 对象，因此任何 ElementHandle 也是 JSHandle。

句柄用于对页面中的实际对象执行操作。你可以在句柄上进行求值，获取句柄属性，将句柄作为求值参数传递，将页面对象序列化为 JSON 等。有关这些及其他方法，请参阅 JSHandle 类 API。

API 参考

以下是获取 JSHandle 的最简单方法。

var jsHandle = await page.EvaluateHandleAsync("window");
// 使用 jsHandle 进行求值。

元素句柄

不推荐

不推荐使用 ElementHandle，请改用 Locator 对象和以网页为优先的断言。

当需要 ElementHandle 时，建议使用 Page.WaitForSelectorAsync() 或 Frame.WaitForSelectorAsync() 方法获取它。这些 API 会等待元素附加并可见。

// 获取元素句柄
var jsHandle = await page.WaitForSelectorAsync("#box");
var elementHandle = jsHandle as ElementHandle;

// 断言元素的边界框
var boundingBox = await elementHandle.BoundingBoxAsync();
Assert.AreEqual(100, boundingBox.Width);

// 断言元素的属性
var classNames = await elementHandle.GetAttributeAsync("class");
Assert.True(classNames.Contains("highlighted"));

将句柄作为参数

句柄可以传递到 Page.EvaluateAsync() 及类似方法中。以下代码片段在页面中创建一个新数组，使用数据对其进行初始化，并将该数组的句柄返回给 Playwright。然后，它在后续的计算中使用该句柄：

// 在页面中创建新数组。
var myArrayHandle = await page.EvaluateHandleAsync(@"() => {
    window.myArray = [1];
    return myArray;
}");

// 获取数组的长度。
var length = await page.EvaluateAsync<int>("a => a.length", myArrayHandle);

// 使用句柄向数组中再添加一个元素
await page.EvaluateAsync("arg => arg.myArray.add(arg.newElement)",
    new { myArray = myArrayHandle, newElement = 2 });

// 当不再需要该对象时，释放它。
await myArrayHandle.DisposeAsync();

句柄生命周期

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

API 参考

Locator 与 ElementHandle

警告

我们仅在极少数需要在静态页面上进行大量 DOM 遍历的情况下，才推荐使用 ElementHandle。对于所有用户操作和断言，请使用 locator。

Locator 与 ElementHandle 之间的区别在于，后者指向特定的元素，而 Locator 则记录了如何检索该元素的逻辑。

在下面的示例中，handle 指向页面上的特定 DOM 元素。如果该元素更改了文本，或者 React 使用它来渲染完全不同的组件，handle 仍然指向那个过时的 DOM 元素。这可能会导致意外行为。

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

使用 locator 时，每次使用 locator，都会使用选择器在页面中定位最新的 DOM 元素。因此在下面的代码片段中，底层的 DOM 元素将被定位两次。

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

简介​

API 参考​

元素句柄​

将句柄作为参数​

句柄生命周期​

API 参考​

Locator 与 ElementHandle​

简介

API 参考

元素句柄

将句柄作为参数

句柄生命周期

API 参考

Locator 与 ElementHandle