句柄（Handles）

介绍

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

  • JSHandle：用于引用页面中的任何 JavaScript 对象

  • ElementHandle：用于引用页面中的 DOM 元素，它具有额外的方法，可以对元素执行操作并断言其属性。

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

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

API 参考

  • JSHandle

  • ElementHandle

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

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

Element Handles

不推荐使用 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 参考

  • JSHandle

  • ElementHandle

  • elementHandle.boundingBox()

  • elementHandle.getAttribute()

  • elementHandle.innerText()

  • elementHandle.innerHTML()

  • elementHandle.textContent()

  • jsHandle.evaluate()

  • page.evaluateHandle()

  • page.$()

  • page.$$()

Locator 与 ElementHandle

我们仅在极少数情况下推荐使用 ElementHandle，当你需要在静态页面上进行大量 DOM 遍历时。如果是所有用户操作和断言，请使用 Locator。

Locator 和 ElementHandle 之间的区别在于，后者指向特定的元素，而 Locator 捕获了如何获取该元素的逻辑。

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

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

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

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