Puppeteer 中文文档v25.8.0

ElementHandle 类

ElementHandle 表示页面内的 DOM 元素。

签名

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

继承自： JSHandle<ElementType>

备注

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

import puppeteer from 'puppeteer';

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

readonly

Frame

与当前句柄对应的框架。

方法

方法

修饰符

说明

$(selector)

在当前元素中查询与给定选择器匹配的元素。

$$(selector, options)

在当前元素中查询与给定选择器匹配的所有元素。

$$eval(selector, pageFunction, args)

在当前元素中，对匹配给定选择器的元素数组运行给定函数。

如果给定函数返回 Promise，则此方法将等待该 Promise 解析。

$eval(selector, pageFunction, args)

在当前元素中，对匹配给定选择器的第一个元素运行给定函数。

如果给定函数返回 Promise，则此方法将等待该 Promise 解析。

asLocator(this)

基于 ElementHandle 创建定位器。如果元素句柄已失效，此方法不允许刷新该元素句柄，但允许复用其他定位器前置条件。

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 Protocol 连接时，它会为该元素返回一个 DOM.BackendNodeId。

boundingBox()

此方法返回元素的边界框（相对于主框架），如果元素不属于布局（例如：display: none），则返回 null。

boxModel()

此方法返回元素的盒子，如果元素不属于布局（例如：display: none），则返回 null。

备注：

盒子以点数组的形式表示；每个 Point 都是一个 {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()

如果满足以下任一条件，则认为元素是隐藏的：

isIntersectingViewport(this, options)

如果元素在当前视口中可见，则解析为 true。如果元素是 SVG，则改为检查 svg 所有者元素是否在视口中。参见 https://crbug.com/963246。

isVisible()

如果满足以下所有条件，则认为元素是可见的：

press(key, options)

聚焦该元素，然后使用 Keyboard.down() 和 Keyboard.up()。

备注：

如果 key 是单个字符，并且除 Shift 之外没有按住其他修饰键，则还会生成 keypress/input 事件。可以指定 text 选项以强制生成 input 事件。

注意 修饰键确实会影响 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 中分离时无法工作。