Skip to main content
Version: 23.10.1

ElementHandle 类

¥ElementHandle class

ElementHandle 表示页内 DOM 元素。

¥ElementHandle represents an in-page DOM element.

签名​

¥Signature

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

Extends: JSHandle<ElementType>

备注​

¥Remarks

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

¥ElementHandles can be created with the Page.$() method.

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 元素被垃圾回收，除非句柄是 disposed。当其原始框架被导航时，ElementHandles 会被自动处理。

¥ElementHandle prevents the DOM element from being garbage-collected unless the handle is disposed. ElementHandles are auto-disposed when their origin frame gets navigated.

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

¥ElementHandle instances can be used as arguments in Page.$eval() and Page.evaluate() methods.

如果你使用的是 TypeScript，则 ElementHandle 采用通用参数来表示句柄所包含的元素类型。例如，如果你有 <select> 元素的句柄，则可以将其键入为 ElementHandle<HTMLSelectElement>，并且你会得到一些更好的类型检查。

¥If you're using TypeScript, ElementHandle takes a generic argument that denotes the type of element the handle is holding within. For example, if you have a handle to a <select> element, you can type it as ElementHandle<HTMLSelectElement> and you get some nicer type checks.

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

¥The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the ElementHandle class.

属性​

¥Properties

属性

修饰符

类型

描述

frame

readonly

框架

与当前句柄对应的帧。

方法​

¥Methods

方法

修饰符

描述

$(selector)

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

$$(选择器，选项)

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

$$eval(selector, pageFunction, args)

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

如果给定的函数返回一个 Promise，那么此方法将等待直到 Promise 解析。

$eval(selector, pageFunction, args)

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

如果给定的函数返回一个 Promise，那么此方法将等待直到 Promise 解析。

autofill(data)

如果该元素是表单输入，则可以使用 ElementHandle.autofill() 来测试表单是否与浏览器的自动填充实现兼容。如果无法自动填写表单，则会引发错误。

评论：

目前，Puppeteer 仅支持自动填充信用卡信息，并且在 Chrome 中仅支持新的 headless 和 headful 模式。

// 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()

此方法返回元素的边界框（相对于主框架），如果元素是 不是布局的一部分，则返回 null（例如：display: none).

boxModel()

此方法返回元素的框，如果元素是 不是布局的一部分，则返回 null（例如：display: none）。

评论：

盒子被表示为点数组；每个点都是一个对象 {x, y}。箱点按顺时针顺序排序。

click(this, options)

如果需要，此方法将元素滚动到视图中，然后使用 Page.mouse 单击元素的中心。如果元素与 DOM 分离，该方法会抛出错误。

clickablePoint(offset)

返回元素内的中点，除非提供了特定的偏移量。

contentFrame(this)

解析与元素关联的框架（如果有）。HTMLIFrameElements 始终存在。

contentFrame()
drag(this, target)

将元素拖动到给定元素或点上。

dragAndDrop(this, target, options)

deprecated

已弃用：

请改用 ElementHandle.drop。

dragEnter(this, data)

deprecated

已弃用：

不使用。拖动过程中会自动执行 dragenter。

dragOver(this, data)

deprecated

已弃用：

不使用。拖动过程中会自动执行 dragover。

drop(this, element)

将给定元素放到当前元素上。

drop(this, data)

deprecated

已弃用：

不再支持。

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 选项来强制生成输入事件。

注意修饰键确实会影响 elementHandle.press。按住 Shift 将以大写形式键入文本。

screenshot(options)

如果需要，此方法将元素滚动到视图中，然后使用 Page.screenshot() 截取元素的屏幕截图。如果元素与 DOM 分离，该方法会抛出错误。

screenshot(options)
scrollIntoView(this)

使用自动化协议客户端或通过调用 element.scrollIntoView 将元素滚动到视图中。

select(values)

选择所有提供的选项后，触发 change 和 input 事件。如果没有 <select> 元素与 selector 匹配，该方法将引发错误。

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)

将 输入元素 的值设置为给定的文件路径。

评论：

这不会验证文件路径是否存在。另外，如果路径是相对路径，则根据 当前工作目录 进行解析。对于连接到远程 Chrome 环境的本地脚本，路径必须是绝对路径。

waitForSelector(selector, options)

等待与给定选择器匹配的元素出现在当前元素中。

与 Frame.waitForSelector() 不同，此方法不适用于跨导航或元素与 DOM 分离的情况。