句柄 (Handles)

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

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

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

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

API 参考

这是获取 JSHandle 的最简单方法。

const jsHandle = await page.evaluateHandle('window');
//  使用 jsHandle 进行评估。

元素句柄 (Element Handles)

不推荐

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

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

// 获取元素句柄
const elementHandle = page.waitForSelector('#box');

// 断言元素的边界框
const boundingBox = await elementHandle.boundingBox();
expect(boundingBox.width).toBe(100);

// 断言元素的属性
const classNames = await elementHandle.getAttribute('class');
expect(classNames.includes('highlighted')).toBeTruthy();

句柄作为参数

句柄可以传递给 page.evaluate(pageFunction[, arg]) 和类似方法。以下代码段在页面中创建一个新数组，使用数据对其进行初始化，并将指向此数组的句柄返回给 Playwright。然后在随后的评估中使用该句柄：

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

// 获取数组的长度。
const length = await page.evaluate(a => a.length, myArrayHandle);

// 使用句柄向数组添加一个元素
await page.evaluate(arg => arg.myArray.push(arg.newElement), {
  myArray: myArrayHandle,
  newElement: 2
});

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

句柄生命周期

可以使用页面方法获取句柄，例如 page.evaluateHandle(pageFunction[, arg])、page.$(selector[, options]) 或 page.$$(selector) 或其帧对应方法 frame.evaluateHandle(pageFunction[, arg])、frame.$(selector[, options]) 或 frame.$$(selector)。一旦创建，句柄将保留对象以防垃圾回收，除非页面导航或通过 jsHandle.dispose() 方法手动释放句柄。

API 参考

定位器 vs 元素句柄

caution

我们只建议在极少数情况下使用 ElementHandle，即当您需要在静态页面上执行广泛的 DOM 遍历时。对于所有用户操作和断言，请改用定位器。

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 参考​

元素句柄 (Element Handles)​

句柄作为参数​

句柄生命周期​

API 参考​

定位器 vs 元素句柄​

API 参考

元素句柄 (Element Handles)

句柄作为参数

句柄生命周期

API 参考

定位器 vs 元素句柄