跳到主要内容

句柄

介绍​

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

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

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

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

API 参考​

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

js_handle = page.evaluate_handle('window')
#  使用 jsHandle 进行求值。

元素句柄​

不推荐使用

建议不要使用 ElementHandle，请改用 Locator 对象和面向用户的断言。

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

# 获取元素句柄
element_handle = page.wait_for_selector('#box')

# 断言元素的边界框
bounding_box = element_handle.bounding_box()
assert bounding_box.width == 100

# 断言元素的属性
class_names = element_handle.get_attribute('class')
assert 'highlighted' in class_names

将句柄作为参数​

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

# 在页面中创建新数组。
my_array_handle = page.evaluate_handle("""() => {
  window.myArray = [1];
  return myArray;
}""")

# 获取数组的当前长度。
length = page.evaluate("a => a.length", my_array_handle)

# 使用句柄向数组中添加一个新元素
page.evaluate("(arg) => arg.myArray.push(arg.newElement)", {
  'myArray': my_array_handle,
  'newElement': 2
})

# 在不再需要对象时释放它。
my_array_handle.dispose()

句柄生命周期​

可以通过页面方法如 page.evaluate_handle()、page.query_selector() 或 page.query_selector_all() 或它们的框架对应方法 frame.evaluate_handle()、frame.query_selector() 或 frame.query_selector_all() 来获取句柄。一旦创建，句柄将在页面导航之前或通过 js_handle.dispose() 方法手动释放之前，防止对象被垃圾回收。

API 参考​

Locator 与 ElementHandle​

警告

我们仅建议在需要对静态页面执行大量 DOM 遍历的极少情况下使用 ElementHandle。对于所有用户操作和断言，请改用 locator。

Locator 和 ElementHandle 的区别在于后者指向特定的元素，而 Locator 捕获了检索该元素的逻辑。

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

handle = page.query_selector("text=提交")
handle.hover()
handle.click()

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

locator = page.get_by_text("提交")
locator.hover()
locator.click()