句柄

简介

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

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

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

句柄用于对页面上的这些实际对象执行操作。您可以在句柄上进行评估、获取句柄属性、将句柄作为评估参数传递、将页面对象序列化为 JSON 等。有关这些方法和更多方法的详细信息，请参阅 JSHandle 类 API。

API 参考

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

const jsHandle = await page.evaluateHandle('window');
//  Use jsHandle for evaluations.

元素句柄

不推荐

不鼓励使用 ElementHandle，请改用 Locator 对象和 web-first 断言。

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

// Get the element handle
const elementHandle = page.waitForSelector('#box');

// Assert bounding box for the element
const boundingBox = await elementHandle.boundingBox();
expect(boundingBox.width).toBe(100);

// Assert attribute for the element
const classNames = await elementHandle.getAttribute('class');
expect(classNames.includes('highlighted')).toBeTruthy();

作为参数的句柄

句柄可以传递给 page.evaluate() 和类似的方法。以下代码片段在页面中创建一个新数组，用数据初始化它，并将其句柄返回给 Playwright。然后它在后续评估中使用该句柄

// Create new array in page.
const myArrayHandle = await page.evaluateHandle(() => {
  window.myArray = [1];
  return myArray;
});

// Get the length of the array.
const length = await page.evaluate(a => a.length, myArrayHandle);

// Add one more element to the array using the handle
await page.evaluate(arg => arg.myArray.push(arg.newElement), {
  myArray: myArrayHandle,
  newElement: 2
});

// Release the object when it's no longer needed.
await myArrayHandle.dispose();

句柄生命周期

句柄可以使用页面方法获取，例如 page.evaluateHandle()、page.$() 或 page.$$()，或它们的框架对应方法 frame.evaluateHandle()、frame.$() 或 frame.$$()。创建后，句柄将保留对象以防止垃圾回收，除非页面导航或通过 jsHandle.dispose() 方法手动处理句柄。

API 参考

Locator vs ElementHandle

注意

我们只建议在极少数需要对静态页面执行大量 DOM 遍历的情况下使用 ElementHandle。对于所有用户操作和断言，请使用定位器 (locator) 代替。

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

在下面的示例中，句柄指向页面上的一个特定 DOM 元素。如果该元素的文本发生变化或被 React 用于渲染一个完全不同的组件，句柄仍然指向那个陈旧的 DOM 元素。这可能会导致意外行为。

const handle = await page.$('text=Submit');
// ...
await handle.hover();
await handle.click();

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

const locator = page.getByText('Submit');
// ...
await locator.hover();
await locator.click();

简介​

API 参考​

元素句柄​

作为参数的句柄​

句柄生命周期​

API 参考​

Locator vs ElementHandle​

简介

API 参考

元素句柄

作为参数的句柄

句柄生命周期

API 参考

Locator vs ElementHandle