跳到主要内容

句柄

引言​

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

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

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

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

API 参考​

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

js_handle = page.evaluate_handle('window')
#  Use jsHandle for evaluations.

元素句柄​

不推荐

不推荐使用 ElementHandle，请改用 Locator 对象和 Web 优先断言。

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

# Get the element handle
element_handle = page.wait_for_selector('#box')

# Assert bounding box for the element
bounding_box = element_handle.bounding_box()
assert bounding_box.width == 100

# Assert attribute for the element
class_names = element_handle.get_attribute('class')
assert 'highlighted' in class_names

作为参数的句柄​

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

# Create new array in page.
my_array_handle = page.evaluate_handle("""() => {
  window.myArray = [1];
  return myArray;
}""")

# Get current length of the array.
length = page.evaluate("a => a.length", my_array_handle)

# Add one more element to the array using the handle
page.evaluate("(arg) => arg.myArray.push(arg.newElement)", {
  'myArray': my_array_handle,
  'newElement': 2
})

# Release the object when it's no longer needed.
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 参考​

定位器 与 ElementHandle​

注意

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

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

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

handle = page.query_selector("text=Submit")
handle.hover()
handle.click()

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

locator = page.get_by_text("Submit")
locator.hover()
locator.click()