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 開發人員工具協定連線時，它會傳回元素的 DOM.BackendNodeId。
boundingBox()		此方法會傳回元素的邊界框（相對於主框架），如果元素不是佈局的一部分（例如：display: none），則傳回 null。
boxModel()		此方法會傳回元素的方塊，如果元素不是佈局的一部分（例如：display: none），則傳回 null。 備註 方塊表示為點陣列；每個點都是一個 {x, y} 物件。方塊點以順時針方向排序。
click(this, options)		如果需要，此方法會將元素捲動到檢視區中，然後使用 Page.mouse 在元素的中心點擊。如果元素從 DOM 中分離，則此方法會擲回錯誤。
clickablePoint(offset)		傳回元素內的中心點，除非提供特定的位移。
contentFrame(this)		解析與元素關聯的框架（如果有的話）。HTMLIFrameElements 總是存在。
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 中分離，則此方法也不會工作。