Puppeteer 元素處理

class:elementhandle

class: ElementHandle v0.9.0

注意ElementHandle 類繼承自 JSHandle。

ElementHandle 表示一個頁內(nèi)的 DOM 元素。ElementHandles 可以通過 page.$ 方法創(chuàng)建。

除非處理了句柄 disposed，否則 ElementHandle 會阻止垃圾收集中的 DOM 元素。 ElementHandles 在其原始幀被導(dǎo)航時將會自動處理。 ElementHandle 實(shí)例可以在 page.$eval() 和 page.evaluate() 方法中作為參數(shù)。

Methods

• elementHandle.$(selector)v0.9.0
• elementHandle.$$(selector)v0.9.0
• elementHandle.$eval(selector, pageFunction, ...args)v0.9.0
• elementHandle.$$eval(selector, pageFunction, ...args)v0.9.0
• elementHandle.$x(expression)v0.9.0
• elementHandle.asElement()v0.9.0
• elementHandle.boundingBox()v0.9.0
• elementHandle.boxModel()v0.9.0
• elementHandle.click([options])v0.9.0
• elementHandle.contentFrame()v0.9.0
• elementHandle.dispose()v0.9.0
• elementHandle.executionContext()v0.9.0
• elementHandle.focus()v0.9.0
• elementHandle.getProperties()v0.9.0
• elementHandle.getProperty(propertyName)v0.9.0
• elementHandle.hover()v0.9.0
• elementHandle.isIntersectingViewport()v0.9.0
• elementHandle.jsonValue()v0.9.0
• elementHandle.press(key[, options])v0.9.0
• elementHandle.screenshot([options])v0.9.0
• elementHandle.tap()v0.9.0
• elementHandle.toString()v0.9.0
• elementHandle.type(text[, options])v0.9.0
• elementHandle.uploadFile(...filePaths)v0.9.0

Methods

elementHandle.$(selector)v0.9.0

• selector <string> 用于選取頁面 DOM 元素的 CSS Selector
• returns: <Promise<?ElementHandle>> 該方法在頁面內(nèi)運(yùn)行 element.querySelector。 如果沒有元素匹配選擇器，則返回值為 null。

elementHandle.$$(selector)v0.9.0

selector <string> 用于選取頁面 DOM 元素的 CSS Selector returns: <Promise<Array<ElementHandle>>> 該方法在頁面內(nèi)運(yùn)行 element.querySelectorAll。 如果沒有元素匹配選擇器，則返回值為 []。

elementHandle.$eval(selector, pageFunction, ...args)v0.9.0

• selector <string> 用于選取頁面 DOM 元素的 CSS Selector
• pageFunction <function> 在瀏覽器上下文中執(zhí)行的函數(shù)
• ...args <...Serializable|JSHandle> 傳遞給 pageFunction 的參數(shù)
• returns: <Promise<Serializable>> Promise which resolves to the return value of pageFunction 這個方法在元素中運(yùn)行 document.querySelector 并將它作為第一個參數(shù)傳遞給 pageFunction。 如果沒有與 selector 匹配的元素，則該方法將拋出個錯誤。 如果 pageFunction 返回一個 Promise，那么 frame.$eval 將等待承諾解析并返回它的值。

例子:

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.$$eval(selector, pageFunction, ...args)v0.9.0

• selector <string> 用于選取頁面 DOM 元素的 CSS Selector
• pageFunction <function> 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

• selector <string> 用于選取頁面 DOM 元素的 CSS Selector
• pageFunction <function> 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

該方法在元素內(nèi)運(yùn)行 document.querySelectorAll，并將其作為第一個參數(shù)傳遞給 pageFunction。 如果沒有與 selector 匹配的元素，則該方法將拋出一個錯誤。 如果 pageFunction 返回 Promise，那么frame.$$eval 將等待 promise 解析并返回其值。 例子:

<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.$x(expression)v0.9.0

• expression <string> Expression to evaluate.
• returns: <Promise<Array<ElementHandle>>>

elementHandle.asElement()v0.9.0

• returns: <ElementHandle>

elementHandle.boundingBox()v0.9.0

• returns: <Promise<?Object>>
  • x <number> 元素的 x 坐標(biāo)（以像素為單位）。
  • y <number> 元素的 y 坐標(biāo)（以像素為單位）。
  • width <number> 元素的像素寬度。
  • height <number> 元素的像素高度。

此方法返回元素的邊界框（相對于主框架），如果元素不可見，則返回 null。

elementHandle.boxModel()v0.9.0

• returns: <Promise<?Object>>

  • content <Array<Object>> Content box, represented as an array of {x, y} points.
  • padding <Array<Object>> Padding box, represented as an array of {x, y} points.
  • border <Array<Object>> Border box, represented as an array of {x, y} points.
  • margin <Array<Object>> Margin box, - represented as an array of {x, y} points.
  • width <number> 元素的寬度.
  • height <number> 元素的高度.

  該方法返回元素的盒模型，如果元素不可見，則返回 null。 盒模型被表示為一組點(diǎn)；每個 Point 都是一個對象 {x，y}。 盒模型的點(diǎn)按順時針排序。

  elementHandle.click([options])v0.9.0

• options <Object>
  • button <string> left, right, 或 middle, 默認(rèn)是 left。
  • clickCount <number> 默認(rèn)是 1. 見 UIEvent.detail.
  • delay <number> mousedown 和 mouseup 之間等待的時間。 默認(rèn)是 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 中分離，則該方法將引發(fā)錯誤。

elementHandle.contentFrame()v0.9.0

• returns: <Promise<?Frame>> 解析為引用 iframe 節(jié)點(diǎn)的元素句柄的內(nèi)容框架，否則為空

elementHandle.dispose()v0.9.0

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

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

elementHandle.executionContext()v0.9.0

• returns: ExecutionContext

elementHandle.focus()v0.9.0

• returns: <Promise>

在元素上調(diào)用 focus。

elementHandle.getProperties()v0.9.0

• returns: <Promise<Map<string, JSHandle>>> 該方法返回一個包含屬性名稱作為鍵的映射和屬性值的 JSHandle 實(shí)例。

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 的所有子項(xiàng)。

elementHandle.getProperty(propertyName)v0.9.0

• propertyName <string> property to get
• returns: <Promise<JSHandle>> 從 objectHandle 中獲取一個屬性。

elementHandle.hover()v0.9.0

• returns: <Promise> Promise which resolves when the element is successfully hovered. 如果需要，此方法將元素滾動到視野中，然后使用 page.mouse 將鼠標(biāo)懸停在元素的中心。如果元素從 DOM 中分離（不存在），則該方法將拋出一個錯誤。

elementHandle.isIntersectingViewport()v0.9.0

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

elementHandle.jsonValue()v0.9.0

• returns: <Promise<Object>> 返回對象的JSON表示。 JSON是通過對頁面上的對象運(yùn)行 JSON.stringify 生成的，因此 JSON.parse 在puppeteer中。

注意 如果引用的對象不可字符串化，該
方法將拋出（一個錯誤）。

elementHandle.press(key[, options])v0.9.0

• key <string> 按鍵的名稱，例如 ArrowLeft。 見 USKeyboardLayout 以獲取所有鍵名稱的列表。
• options <Object>
  • text <string> 如果指定，則使用此文本生成輸入事件。
  • delay <number> keydown 和 keyup 之間等待的時間。默認(rèn)是 0。
• returns: <Promise> 聚焦元素，然后使用 keyboard.down 和 keyboard.up。 如果 key 是一個單獨(dú)的字符，并且除了 Shift 之外沒有（其他）修飾鍵被按下，keypress / input 事件也會被生成。 可以指定 text 選項(xiàng)來強(qiáng)制生成輸入事件。

  注意 修飾鍵 DO 會影響 elementHandle.press。 按住 Shift 鍵將以大寫形式輸入文本。

elementHandle.screenshot([options])v0.9.0

• options <Object> 與 page.screenshot 選項(xiàng)相同。
• returns: <Promise<Buffer>> Promise which resolves to buffer with captured screenshot. 如果需要，此方法將元素滾動到視圖中，然后使用 page.screenshot 截取元素的屏幕截圖。 如果該元素從 DOM 中分離，則該方法將拋出一個錯誤。

elementHandle.tap()v0.9.0

returns: <Promise> Promise which resolves when the element is successfully tapped. Promise gets rejected if the element is detached from DOM. 如果需要，此方法將元素滾動到視野中，然后使用 touchscreen.tap 在元素的中心點(diǎn)擊。 如果該元素從 DOM 中分離，則該方法將拋出一個錯誤。

elementHandle.toString()v0.9.0

returns: <string>

elementHandle.type(text[, options])v0.9.0

text <string> 要輸入到焦點(diǎn)元素中的文本。 options <Object> delay <number> 按鍵之間的等待時間，默認(rèn)是 0。 returns: <Promise>

聚焦元素，然后為文本中的每個字符發(fā)送 keydown，keypress / input 和 keyup 事件。 按一個特殊的鍵，像 Control 或 ArrowDown，使用 elementHandle.press。 elementHandle.type('Hello'); // 立即輸入elementHandle.type('World', {delay: 100}); // 慢點(diǎn)輸入，像一個用戶

鍵入文本字段然后提交表單的例子：

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

elementHandle.uploadFile(...filePaths)v0.9.0

• ...filePaths <...string> 設(shè)置輸入這些路徑的文件的值。如果某些 filePaths 是相對路徑，那么它們將被解析為相對于 當(dāng)前工作目錄。
• returns: <Promise> 這個方法期望 elementHandle 指向一個 輸入元素。