句柄(Handles)
简介
Playwright 可以创建对页面 DOM 元素或页面内任何其他对象的句柄。这些句柄存在于 Playwright 进程中,而实际对象存在于浏览器中。句柄有两种类型:
- JSHandle 用于引用页面中的任何 JavaScript 对象
- ElementHandle 用于引用页面中的 DOM 元素,它具有额外的方法可以对这些元素执行操作并断言其属性
由于页面中的任何 DOM 元素同时也是 JavaScript 对象,因此任何 ElementHandle 同时也是 JSHandle。
句柄用于对这些页面中的实际对象执行操作。您可以在句柄上进行求值、获取句柄属性、将句柄作为求值参数传递、将页面对象序列化为 JSON 等。有关这些方法和更多信息,请参阅 JSHandle 类 API。
API 参考
以下是获取 JSHandle 的最简单方式:
const jsHandle = await page.evaluateHandle('window');
// 使用 jsHandle 进行求值操作
元素句柄
不建议使用 ElementHandle,请改用 Locator 对象和面向 web 的断言。
当需要 ElementHandle 时,建议使用 page.waitForSelector() 或 frame.waitForSelector() 方法来获取。这些 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() 及类似方法。以下代码片段在页面中创建了一个新数组,用数据初始化它,并将该数组的句柄返回到 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()、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 对比
我们仅推荐在极少数需要对静态页面进行大量 DOM 遍历的情况下使用 ElementHandle。对于所有用户操作和断言,请改用定位器(locator)。
Locator 和 ElementHandle 的区别在于:后者指向特定的页面元素,而定位器捕获的是如何检索该元素的逻辑。
在下面的示例中,handle 指向页面上的特定 DOM 元素。如果该元素的文本发生变化,或者被 React 用来渲染完全不同的组件,handle 仍然指向那个过时的 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();