ElementHandle class

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

import 'package:puppeteer/puppeteer.dart';

void main() async {
  var browser = await puppeteer.launch();

  var page = await browser.newPage();
  await page.goto('https://example.com');
  var hrefElement = await page.$('a');
  await hrefElement.click();

  await browser.close();
}

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

ElementHandle instances can be used as arguments in page.$eval and page.evaluate methods.

Inheritance

Object
JsHandle
ElementHandle

Constructors

ElementHandle(ExecutionContext context, RemoteObject remoteObject, Frame? frame, FrameManager frameManager)

Properties

asElement → ElementHandle: Returns either null or the object handle itself, if the object handle is an instance of ElementHandle.
no setteroverride
boundingBox → Future<Rectangle<num>?>: This method returns the bounding box of the element (relative to the main frame), or null if the element is not visible.
no setter
boxModel → Future<BoxModel?>: This method returns boxes of the element, or null if the element is not visible. Boxes are represented as an array of points; Box points are sorted clock-wise.
no setter
contentFrame → Future<Frame?>: Resolves to the content frame for element handles referencing iframe nodes, or null otherwise
no setter
executionContext → ExecutionContext: Returns execution context the handle belongs to.
finalinherited
frame → Frame?: final
frameManager → FrameManager: final
hashCode → int: The hash code for this object.
no setterinherited
isDisposed → bool: no setterinherited
isIntersectingViewport → Future<bool?>: Resolves to true if the element is visible in the current viewport.
no setter
jsonValue → Future: Returns a JSON representation of the object. If the object has a toJSON function, it will not be called.
no setterinherited
page → Page: no setter
properties → Future<Map<String, JsHandle>>: The method returns a map with property names as keys and JSHandle instances for the property values.
no setterinherited
remoteObject → RemoteObject: finalinherited
runtimeType → Type: A representation of the runtime type of the object.
no setterinherited

Methods

$(String selector) → Future<ElementHandle>: The method runs element.querySelector within the page. If no element matches the selector, an exception is thrown.
$$(String selector) → Future<List<ElementHandle>>: The method runs element.querySelectorAll within the page. If no elements match the selector, the return value resolves to [].
$$eval<T>(String selector, String pageFunction, {List? args}) → Future<T?>: This method runs document.querySelectorAll within the element and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.
$eval<T>(String selector, String pageFunction, {List? args}) → Future<T?>: This method runs document.querySelector within the element and passes it as the first argument to pageFunction. If there's no element matching selector, the method throws an error.
$OrNull(String selector) → Future<ElementHandle?>
$x(String expression) → Future<List<ElementHandle>>: The method evaluates the XPath expression relative to the elementHandle. If there are no such elements, the method will resolve to an empty array.
click({Duration? delay, MouseButton? button, int? clickCount}) → Future<void>: 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.
dispose() → Future<void>: Stops referencing the element handle.
inherited
drag(Point<num> target) → Future<DragData>: This method creates and captures a dragevent from the element.
dragAndDrop(ElementHandle target, {Duration? delay}) → Future<void>: This method triggers a dragenter, dragover, and drop on the element.
dragEnter(DragData data) → Future<void>: This method creates a dragenter event on the element.
dragOver(DragData data) → Future<void>: This method creates a dragover event on the element.
drop(DragData data) → Future<void>: This method triggers a drop on the element.
evaluate<T>(String pageFunction, {List? args}) → Future<T?>: This method passes this handle as the first argument to pageFunction.
inherited
evaluateHandle<T extends JsHandle>(String pageFunction, {List? args}) → Future<T>: This method passes this handle as the first argument to pageFunction.
inherited
focus() → Future<void>: Calls focus on the element.
hover() → Future<void>
noSuchMethod(Invocation invocation) → dynamic: Invoked when a nonexistent method or property is accessed.
inherited
press(Key key, {Duration? delay, String? text}) → Future<void>: Focuses the element, and then uses `keyboard.down` and `keyboard.up`.
property<T extends JsHandle>(String propertyName) → Future<T>: Fetches a single property from the referenced object.
inherited
propertyValue<T>(String propertyName) → Future<T>: Fetches the jsonValue of a single property from the referenced object.
inherited
screenshot({ScreenshotFormat? format, int? quality, bool? omitBackground}) → Future<List<int>>: 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.
select(List<String> values) → Future<List<String>>: Triggers a change and input event once all the provided options have been selected. If there's no <select> element matching selector, the method throws an error.
tap() → Future<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.
toString() → String: A string representation of this object.
inherited
type(String text, {Duration? delay}) → Future<void>: Focuses the element, and then sends a keydown, keypress/input, and keyup event for each character in the text.
uploadFile(List<File> files) → Future<void>: This method expects elementHandle to point to an input element.

Operators

operator ==(Object other) → bool: The equality operator.
inherited

Static Methods

quadToPoints(Quad quad) → List<Point<num>>