Options
All
  • Public
  • Public/Protected
  • All
Menu

Interface ElementHandle<E>

Represents an in-page DOM element. ElementHandles can be created with the page.$ method.

Type parameters

  • E: Element = Element

Hierarchy

Index

Methods

Methods

$

  • The method runs element.querySelector within the page. If no element matches the selector, the return value resolve to null.

    since

    0.13.0

    Parameters

    • selector: string

      A selector to query element for

    Returns Promise<null | ElementHandle<Element>>

$$

  • The method runs element.querySelectorAll within the page. If no elements match the selector, the return value resolve to [].

    since

    0.13.0

    Parameters

    • selector: string

      A selector to query element for

    Returns Promise<ElementHandle<Element>[]>

$$eval

  • This method runs Array.from(document.querySelectorAll(selector)) within the context and passes it as the first argument to pageFunction.

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

    Type parameters

    • R

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (elements: Element[]) => R | Promise<R>

      Function to be evaluated in browser context

        • (elements: Element[]): R | Promise<R>

        • Parameters

          • elements: Element[]

          Returns R | Promise<R>

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs Array.from(document.querySelectorAll(selector)) within the context and passes it as the first argument to pageFunction.

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

    Type parameters

    • R

    • X1

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (elements: Element[], x1: UnwrapElementHandle<X1>) => R | Promise<R>

      Function to be evaluated in browser context

    • x1: X1

      First argument to pass to pageFunction

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs Array.from(document.querySelectorAll(selector)) within the context and passes it as the first argument to pageFunction.

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

    Type parameters

    • R

    • X1

    • X2

    Parameters

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs Array.from(document.querySelectorAll(selector)) within the context and passes it as the first argument to pageFunction.

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

    Type parameters

    • R

    • X1

    • X2

    • X3

    Parameters

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs Array.from(document.querySelectorAll(selector)) within the context and passes it as the first argument to pageFunction.

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

    Type parameters

    • R

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (elements: Element[], ...args: any[]) => R | Promise<R>

      Function to be evaluated in browser context

        • (elements: Element[], ...args: any[]): R | Promise<R>

        • Parameters

          • elements: Element[]
          • Rest ...args: any[]

          Returns R | Promise<R>

    • Rest ...args: SerializableOrJSHandle[]

      Arguments to pass to pageFunction

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

$eval

  • This method runs document.querySelector within the context and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

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

    Type parameters

    • R

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (element: Element) => R | Promise<R>

      Function to be evaluated in browser context

        • (element: Element): R | Promise<R>

        • Parameters

          • element: Element

          Returns R | Promise<R>

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs document.querySelector within the context and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

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

    Type parameters

    • R

    • X1

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (element: Element, x1: UnwrapElementHandle<X1>) => R | Promise<R>

      Function to be evaluated in browser context

    • x1: X1

      First argument to pass to pageFunction

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs document.querySelector within the context and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

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

    Type parameters

    • R

    • X1

    • X2

    Parameters

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs document.querySelector within the context and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

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

    Type parameters

    • R

    • X1

    • X2

    • X3

    Parameters

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

  • This method runs document.querySelector within the context and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.

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

    Type parameters

    • R

    Parameters

    • selector: string

      A selector to query for

    • pageFunction: (element: Element, ...args: any[]) => R | Promise<R>

      Function to be evaluated in browser context

        • (element: Element, ...args: any[]): R | Promise<R>

        • Parameters

          • element: Element
          • Rest ...args: any[]

          Returns R | Promise<R>

    • Rest ...args: SerializableOrJSHandle[]

      Arguments to pass to pageFunction

    Returns Promise<WrapElementHandle<R>>

    Promise which resolves to the return value of pageFunction

$x

  • Parameters

    • expression: string

    Returns Promise<ElementHandle<Element>[]>

asElement

  • Returns a ElementHandle

    Returns null | ElementHandle<Element>

boundingBox

  • This method returns the value resolve to the bounding box of the element (relative to the main frame), or null if the element is not visible.

    Returns Promise<null | BoundingBox>

boxModel

  • This method returns boxes of the element, or null if the element is not visible. Boxes are represented as an array of points; each Point is an object {x, y}. Box points are sorted clock-wise.

    Returns Promise<null | BoxModel>

click

  • This method scrolls element into view if needed, and then uses page.mouse to click in the center of the element. If the element is detached from DOM, the method throws an error.

    since

    0.9.0

    Parameters

    Returns Promise<void>

contentFrame

  • contentFrame(): Promise<null | Frame>
  • since

    1.2.0

    Returns Promise<null | Frame>

    Resolves to the content frame for element handles referencing iframe nodes, or null otherwise.

dispose

  • dispose(): Promise<void>

  • Stops referencing the element handle.

    Returns Promise<void>

evaluate

  • Evaluates a function in the browser context. If the function, passed to the frame.evaluate, returns a Promise, then frame.evaluate would wait for the promise to resolve and return its value. If the function passed into frame.evaluate returns a non-Serializable value, then frame.evaluate resolves to undefined.

    Type parameters

    Parameters

    Returns Promise<EvaluateFnReturnType<T> extends PromiseLike<U> ? U : EvaluateFnReturnType<T>>

evaluateHandle

  • evaluateHandle<HandlerType>(pageFunction: string | ((arg1: E, ...args: any[]) => any), ...args: SerializableOrJSHandle[]): Promise<HandlerType>

  • The only difference between evaluate and evaluateHandle is that evaluateHandle returns in-page object (JSHandle). If the function, passed to the evaluateHandle, returns a Promise, then evaluateHandle would wait for the promise to resolve and return its value. The TypeScript definitions assume that evaluateHandle returns a JSHandle, but if you know it's going to return an ElementHandle, pass it as the generic argument:

    Type parameters

    Parameters

    • pageFunction: string | ((arg1: E, ...args: any[]) => any)

      a function that is run within the page

    • Rest ...args: SerializableOrJSHandle[]

      arguments to be passed to the pageFunction

    Returns Promise<HandlerType>

executionContext

focus

  • focus(): Promise<void>

  • Calls focus on the element.

    Returns Promise<void>

getProperties

  • getProperties(): Promise<Map<string, JSHandle<any>>>

  • Returns a map with property names as keys and JSHandle instances for the property values.

    Returns Promise<Map<string, JSHandle<any>>>

getProperty

  • getProperty(propertyName: string): Promise<JSHandle<any>>

  • Fetches a single property from the objectHandle.

    Parameters

    • propertyName: string

      The property to get.

    Returns Promise<JSHandle<any>>

hover

  • hover(): Promise<void>

  • This method scrolls element into view if needed, and then uses page.mouse to hover over the center of the element. If the element is detached from DOM, the method throws an error.

    Returns Promise<void>

isIntersectingViewport

  • isIntersectingViewport(): Promise<boolean>

  • Resolves to true if the element is visible in the current viewport.

    Returns Promise<boolean>

jsonValue

  • jsonValue(): Promise<unknown>

  • Returns a JSON representation of the object. The JSON is generated by running JSON.stringify on the object in page and consequent JSON.parse in puppeteer.

    throws

    The method will throw if the referenced object is not stringifiable.

    Returns Promise<unknown>

press

  • press(key: string, options?: { delay?: number; text?: string }): Promise<void>

  • Focuses the element, and then uses keyboard.down and keyboard.up.

    Parameters

    • key: string

      Name of key to press, such as ArrowLeft. See USKeyboardLayout for a list of all key names.

    • Optional options: { delay?: number; text?: string }

      The text and delay options.

      • Optional delay?: number
      • Optional text?: string

    Returns Promise<void>

screenshot

  • This method scrolls element into view if needed, and then uses page.screenshot to take a screenshot of the element. If the element is detached from DOM, the method throws an error.

    Parameters

    Returns Promise<string>

  • Parameters

    Returns Promise<Buffer>

  • Parameters

    Returns Promise<string | Buffer>

select

  • select(...values: string[]): Promise<string[]>

  • Triggers a change and input event once all the provided options have been selected. If there's no has the multiple attribute, all values are considered, otherwise only the first one is taken into account.

Returns Promise<string[]>

An array of option values that have been successfully selected.

tap

  • tap(): Promise<void>

  • This method scrolls element into view if needed, and then uses touchscreen.tap to tap in the center of the element. If the element is detached from DOM, the method throws an error.

    Returns Promise<void>

toString

  • toString(): string

  • Returns string

type

  • type(text: string, options?: { delay: number }): Promise<void>

  • Focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the text.

    Parameters

    • text: string

      A text to type into a focused element.

    • Optional options: { delay: number }

      The typing options.

      • delay: number

    Returns Promise<void>

uploadFile

  • uploadFile(...filePaths: string[]): Promise<void>

  • This method expects elementHandle to point to an input element.

    Parameters

    • Rest ...filePaths: string[]

      Sets the value of the file input these paths. If some of the filePaths are relative paths, then they are resolved relative to current working directory.

    Returns Promise<void>

Generated using TypeDoc