跳到主要内容

句柄

介绍

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

注意

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

LocatorElementHandle 的区别在于,后者指向一个特定的元素,而 Locator 捕获的是如何检索该元素的逻辑。

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

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

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

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