class: ElementHandle

未匹配的标注
  • extends: [JSHandle]

ElementHandle 表示页内 DOM 元素。可以使用 page.$ 方法创建ElementHandles。

const puppeteer = require('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();
  // ...
})();

除非句柄被 disposed,否则 ElementHandle 将阻止 DOM 进行垃圾收集。ElementHandles 在其原始帧被导航时自动释放。

ElementHandles 实例可以用作 page.$eval()page.evaluate() 方法。

elementHandle.$(selector)

  • selector <[string]> 元素选择器
  • returns: <[Promise]<?[ElementHandle]>>

该方法运行 element.querySelector 在页面内。如果没有元素与选择器匹配,则返回值将解析为 null

elementHandle.$$(selector)

  • selector <[string]> 元素选择器
  • returns: <[Promise]<[Array]<[ElementHandle]>>>

该方法运行 element.querySelectorAll 在页面内。如果没有元素与选择器匹配,则返回值将解析为 []

elementHandle.$$eval(selector, pageFunction[, ...args])

  • selector <[string]> 元素选择器
  • pageFunction <[function]([Array]<[Element]>)> 在浏览器上下文中评估的函数
  • ...args <...[Serializable]|[JSHandle]> Arguments to pass to pageFunction
  • returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of pageFunction

本方法在元素内执行 document.querySelectorAll 并将其作为第一个参数传递给pageFunction。如果没有与 selector 匹配的元素,则该方法将抛出个错误。

If pageFunction returns a [Promise], then frame.$$eval would wait for the promise to resolve and return its value.

如果 pageFunction 返回一个 [Promise],则 frame。$$ eval 将等待 promise 解析并返回它的值。

Examples:

<div class="feed">
  <div class="tweet">Hello!</div>
  <div class="tweet">Hi!</div>
</div>
const feedHandle = await page.$('.feed');
expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText))).toEqual(['Hello!', 'Hi!']);

elementHandle.$eval(selector, pageFunction[, ...args])

  • selector <[string]> A [selector] to query page for
  • pageFunction <[function]([Element])> Function to be evaluated in browser context
  • ...args <...[Serializable]|[JSHandle]> Arguments to pass to pageFunction
  • returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of pageFunction

此方法在元素内运行document.querySelector并将其作为第一个参数传递给pageFunction。如果没有与selector匹配的元素,则该方法将引发错误。

如果pageFunction返回一个「 Promise 」,则frame。$ eval将等待promise 解析并返回其值。

例子:

const tweetHandle = await page.$('.tweet');
expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');

elementHandle.$x(expression)

  • expression <[string]> 执行的表达式。
  • returns: <[Promise]<[Array]<[ElementHandle]>>>

该方法计算相对于 elementHandle 的 XPath 表达式。如果没有这样的元素,则该方法将解析为空数组。

elementHandle.asElement()

  • returns: <[ElementHandle]>

elementHandle.boundingBox()

  • returns: <[Promise]<?[Object]>>
    • x <[number]> 元素的x坐标,以像素为单位。
    • y <[number]> 元素的y坐标,以像素为单位。
    • width <[number]> 元素的宽度,以像素为单位。
    • height <[number]> 元素的高度,以像素为单位。

此方法返回元素的边界框(相对于主 frame ),如果元素不可见,则返回null

elementHandle.boxModel()

  • returns: <[Promise]<?[Object]>>
    • content <[Array]<[Object]>> Content box.
    • x <[number]>
    • y <[number]>
    • padding <[Array]<[Object]>> Padding box.
    • x <[number]>
    • y <[number]>
    • border <[Array]<[Object]>> Border box.
    • x <[number]>
    • y <[number]>
    • margin <[Array]<[Object]>> Margin box.
    • x <[number]>
    • y <[number]>
    • width <[number]> 元素的宽度。
    • height <[number]> 元素的高度。

此方法返回元素的盒模型,如果元素不可见,则返回 null。 盒模型被表示为一组点;每个 Point 都是一个对象 {x,y}。 盒模型的点按顺时针排序。

elementHandle.click([options])

  • options <[Object]>
    • button <[string]> left, right, 或 middle, 默认是 left
    • clickCount <[number]> 默认是 1. 见 [UIEvent.detail].
    • delay <[number]> mousedownmouseup 之间等待的时间。 默认是 0。
  • returns: <[Promise]> Promise which resolves when the element is successfully clicked. Promise gets rejected if the element is detached from DOM.

如果需要,此方法将元素滚动到视野中,然后使用 page.mouse 单击元素的中心。
如果该元素从 DOM 中分离,则该方法将引发错误。

elementHandle.contentFrame()

  • returns: <[Promise]<?[Frame]>> 解析为引用 iframe 节点的元素句柄的内容框架,否则为空

elementHandle.dispose()

  • returns: <[Promise]> Promise which resolves when the element handle is successfully disposed.

elementHandle.dispose 方法用于停止引用元素的句柄。

elementHandle.executionContext()

  • returns: [ExecutionContext]

elementHandle.focus()

  • returns: <[Promise]>

在元素上调用 focus

elementHandle.getProperties()

  • returns: <[Promise]<[Map]<[string], [JSHandle]>>>

该方法返回一个包含属性名称作为键的映射和属性值的 JSHandle 实例。

const listHandle = await page.evaluateHandle(() => document.body.children);
const properties = await listHandle.getProperties();
const children = [];
for (const property of properties.values()) {
  const element = property.asElement();
  if (element)
    children.push(element);
}
children; // body持有 elementHandles 给 document.body 的所有子项。

elementHandle.getProperty(propertyName)

  • propertyName <[string]> property to get
  • returns: <[Promise]<[JSHandle]>>

从 objectHandle 中获取一个属性。

elementHandle.hover()

  • returns: <[Promise]> Promise which resolves when the element is successfully hovered.

如果需要,此方法将元素滚动到视野中,然后使用 page.mouse 将鼠标悬停在元素的中心。
如果元素从 DOM 中分离(不存在),则该方法将抛出一个错误。

elementHandle.isIntersectingViewport()

  • returns: <[Promise]<[boolean]>> Resolves to true if the element is visible in the current viewport.

elementHandle.jsonValue()

  • returns: <[Promise]<[Object]>>

返回对象的 JSON 表示。 JSON 是通过对页面上的对象运行 JSON.stringify 生成的,因此 JSON.parse 在 puppeteer 中。

注意 如果引用的对象不可字符串化,该方法将抛出(一个错误)。

elementHandle.press(key[, options])

  • key <[string]> 按键的名称,例如 ArrowLeft。 见 [USKeyboardLayout] 以获取所有键名称的列表。
  • options <[Object]>
    • text <[string]> 如果指定,则使用此文本生成输入事件。
    • delay <[number]> keydownkeyup 之间等待的时间。默认是 0。
  • returns: <[Promise]>

聚焦元素,然后使用 keyboard.downkeyboard.up

如果 key 是一个单独的字符,并且除了 Shift 之外没有(其他)修饰键被按下,keypress / input 事件也会被生成。 可以指定 text 选项来强制生成输入事件。

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

elementHandle.screenshot([options])

  • options <[Object]> 与 page.screenshot 选项相同。
  • returns: <[Promise]<[Buffer]>> Promise which resolves to buffer with captured screenshot.

如果需要,此方法将元素滚动到视图中,然后使用 page.screenshot 截取元素的屏幕截图。
如果该元素从 DOM 中分离,则该方法将抛出一个错误。

elementHandle.tap()

  • returns: <[Promise]> Promise which resolves when the element is successfully tapped. Promise gets rejected if the element is detached from DOM.

如果需要,此方法将元素滚动到视野中,然后使用 touchscreen.tap 在元素的中心点击。
如果该元素从 DOM 中分离,则该方法将抛出一个错误。

elementHandle.toString()

  • returns: <[string]>

elementHandle.type(text[, options])

  • text <[string]> 要输入到焦点元素中的文本。
  • options <[Object]>
    • delay <[number]> 按键之间的等待时间,默认是 0。
  • returns: <[Promise]>

聚焦元素,然后为文本中的每个字符发送 keydownkeypress / inputkeyup 事件。

按一个特殊的键,像 ControlArrowDown,使用 elementHandle.press

elementHandle.type('Hello'); // 立即输入
elementHandle.type('World', {delay: 100}); // 慢点输入,像一个用户

键入文本字段然后提交表单的例子:

const elementHandle = await page.$('input');
await elementHandle.type('some text');
await elementHandle.press('Enter');

elementHandle.uploadFile(...filePaths)

  • ...filePaths <...[string]> 设置输入这些路径的文件的值。如果某些 filePaths 是相对路径,那么它们将被解析为相对于 当前工作目录
  • returns: <[Promise]>

此个方法期望 elementHandle 指向一个 输入元素

如果需要,此方法将元素滚动到视图中,然后使用 page.mouse 单击元素的中心。
如果元素与 DOM 分离,则该方法将引发错误。

本文章首发在 LearnKu.com 网站上。

本译文仅用于学习和交流目的,转载请务必注明文章译者、出处、和本文链接
我们的翻译工作遵照 CC 协议,如果我们的工作有侵犯到您的权益,请及时联系我们。
上一篇 下一篇
贡献者:4
讨论数量: 0
发起讨论 只看当前版本


暂无话题~