ElementHandle 类

ElementHandle 表示页面内的 DOM 元素。

签名

export declare abstract class ElementHandle<ElementType extends Node = Element> extends JSHandle<ElementType>

继承自： JSHandle<ElementType>

备注

可以使用 Page.$() 方法创建 ElementHandle。

import puppeteer from 'puppeteer';

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://example.com');
  const hrefElement = await page.$('a');
  await hrefElement.click();
  // ...
})();

ElementHandle 会阻止 DOM 元素被垃圾回收，除非该句柄被 释放。当其原始框架发生导航时，ElementHandle 会被自动释放。

ElementHandle 实例可以作为 Page.$eval() 和 Page.evaluate() 方法中的参数使用。

如果您正在使用 TypeScript，ElementHandle 接受一个泛型参数，表示句柄内部持有的元素类型。例如，如果您有一个指向 <select> 元素的句柄，您可以将其类型设置为 ElementHandle<HTMLSelectElement>，这样您会得到更好的一些类型检查。

此类的构造函数被标记为内部的。第三方代码不应直接调用构造函数或创建扩展 ElementHandle 类的子类。

属性

属性	修饰符	类型	描述
frame	只读	Frame	对应于当前句柄的框架。

方法

方法	修饰符	描述
$(selector)		查询当前元素中与给定选择器匹配的元素。
$$(selector, options)		查询当前元素中与给定选择器匹配的所有元素。
$$eval(selector, pageFunction, args)		在当前元素中与给定选择器匹配的元素数组上运行给定的函数。 如果给定的函数返回一个 Promise，则此方法将等待直到 Promise 解析。
$eval(selector, pageFunction, args)		在当前元素中与给定选择器匹配的第一个元素上运行给定的函数。 如果给定的函数返回一个 Promise，则此方法将等待直到 Promise 解析。
autofill(data)		如果元素是表单输入，您可以使用 ElementHandle.autofill() 来测试表单是否与浏览器的自动填充实现兼容。如果表单无法自动填充，则会抛出错误。 备注 目前，Puppeteer 仅在新的无头和有头模式的 Chrome 中支持自动填充信用卡信息。 // Select an input on the credit card form. const name = await page.waitForSelector('form #name'); // Trigger autofill with the desired data. await name.autofill({ creditCard: { number: '4444444444444444', name: 'John Smith', expiryMonth: '01', expiryYear: '2030', cvc: '123', }, });
backendNodeId()		当使用 Chrome DevTools 协议连接时，它返回元素的 DOM.BackendNodeId。
boundingBox()		此方法返回元素的边界框（相对于主框架），如果元素不是布局的一部分（例如：display: none），则返回 null。
boxModel()		此方法返回元素的框，如果元素不是布局的一部分（例如：display: none），则返回 null。 备注 框表示为点的数组；每个点是一个对象 {x, y}。框点按顺时针方向排序。
click(this, options)		如果需要，此方法会将元素滚动到视图中，然后使用 Page.mouse 点击元素中心。如果元素与 DOM 分离，则该方法会抛出错误。
clickablePoint(offset)		除非提供了特定的偏移量，否则返回元素内的中心点。
contentFrame(this)		解析与元素关联的框架（如果有）。始终存在于 HTMLIFrameElement 中。
contentFrame()
drag(this, target)		将元素拖动到给定元素或点上方。
dragAndDrop(this, target, options)	已弃用	已弃用 请改用 ElementHandle.drop。
dragEnter(this, data)	已弃用	已弃用 请勿使用。dragenter 将在拖动期间自动执行。
dragOver(this, data)	已弃用	已弃用 请勿使用。dragover 将在拖动期间自动执行。
drop(this, element)		将给定元素放到当前元素上。
drop(this, data)	已弃用	已弃用 不再支持。
focus()		调用元素的 focus。
hover(this)		如果需要，此方法会将元素滚动到视图中，然后使用 Page.mouse 将鼠标悬停在元素中心。如果元素与 DOM 分离，则该方法会抛出错误。
isHidden()		如果满足以下至少一个条件，则认为元素是隐藏的 该元素没有计算样式。 该元素具有空的边界客户端矩形。 该元素的可见性为 hidden 或 collapse。
isIntersectingViewport(this, options)		如果元素在当前视口中可见，则解析为 true。如果元素是 SVG，我们会检查 svg 所有者元素是否在视口中。请参阅 https://crbug.com/963246。
isVisible()		如果满足以下所有条件，则认为元素是可见的 该元素具有计算样式。 该元素具有非空的边界客户端矩形。 该元素的可见性不是 hidden 或 collapse。
press(key, options)		聚焦元素，然后使用 Keyboard.down() 和 Keyboard.up()。 备注 如果 key 是单个字符，并且除了 Shift 之外没有按下任何修饰键，则还会生成 keypress/input 事件。可以指定 text 选项以强制生成输入事件。 注意 修饰键会影响 elementHandle.press。按住 Shift 将以大写形式键入文本。
screenshot(options)		如果需要，此方法会将元素滚动到视图中，然后使用 Page.screenshot() 来截取元素的屏幕截图。如果元素与 DOM 分离，则该方法会抛出错误。
screenshot(options)
scrollIntoView(this)		使用自动化协议客户端或通过调用 element.scrollIntoView 将元素滚动到视图中。
select(values)		选择所有提供的选项后，会触发 change 和 input 事件。如果没有与 selector 匹配的 <select> 元素，则该方法会抛出错误。
tap(this)		如果需要，此方法会将元素滚动到视图中，然后使用 Touchscreen.tap() 点击元素中心。如果元素与 DOM 分离，则该方法会抛出错误。
toElement(tagName)		将当前句柄转换为给定的元素类型。
touchEnd(this)
touchMove(this, touch)		如果需要，此方法会将元素滚动到视图中，然后将触摸移动到元素中心。
touchStart(this)		如果需要，此方法会将元素滚动到视图中，然后在元素中心开始触摸。
type(text, options)		聚焦元素，然后为文本中的每个字符发送一个 keydown、keypress/input 和 keyup 事件。 要按下特殊键（如 Control 或 ArrowDown），请使用 ElementHandle.press()。
uploadFile(this, paths)		将 input 元素 的值设置为给定的文件路径。 备注 这不会验证文件路径是否存在。此外，如果路径是相对路径，则会根据当前工作目录解析。对于连接到远程 chrome 环境的本地脚本，路径必须是绝对路径。
waitForSelector(selector, options)		等待当前元素中出现与给定选择器匹配的元素。 与 Frame.waitForSelector() 不同，此方法不适用于跨导航或如果元素与 DOM 分离的情况。