Frame class

At every point of time, page exposes its current frame tree via the page.mainFrame and frame.childFrames methods.

Frame object's lifecycle is controlled by three events, dispatched on the page object:

  • Page.onFrameAttached - fired when the frame gets attached to the page. A Frame can be attached to the page only once.
  • Page.onFrameNavigated - fired when the frame commits navigation to a different URL.
  • Page.onFrameDetached - fired when the frame gets detached from the page. A Frame can be detached from the page only once.

An example of dumping frame tree:

void dumpFrameTree(Frame frame, String indent) {
  print(indent + frame.url);
  for (var child in frame.childFrames) {
    dumpFrameTree(child, indent + '  ');
  }
}

var browser = await puppeteer.launch();
var page = await browser.newPage();
await page.goto('https://example.com');
dumpFrameTree(page.mainFrame, '');
await browser.close();

An example of getting text from an iframe element:

var frame = page.frames.firstWhere((frame) => frame.name == 'myframe');
var text = await frame.$eval('.selector', 'el => el.textContent');
print(text);

Constructors

Frame(FrameManager frameManager, Client client, Frame? _parent, FrameId _id)

Properties

childFrames → List<Frame>
final
client → Client
final
content → Future<String?>
Gets the full HTML contents of the frame, including the doctype.
no setter
executionContext → Future<ExecutionContext>
Returns promise that resolves to the frame's default execution context.
no setter
frameManager → FrameManager
final
hashCode → int
The hash code for this object.
no setterinherited
id → FrameId
no setter
isDetached → bool
Returns true if the frame has been detached, or false otherwise.
no setter
lifecycleEvents → Set<String?>
final
loaderId → LoaderId?
no setter
name → String?
Returns frame's name attribute as specified in the tag.
no setter
parentFrame → Frame?
Parent frame, if any. Detached frames and main frames return null.
no setter
runtimeType → Type
A representation of the runtime type of the object.
no setterinherited
title → Future<String?>
The page's title.
no setter
url → String
Returns frame's url.
no setter

Methods

$(String selector) → Future<ElementHandle>
The method queries frame for the selector. If there's no such element within the frame, the method will throw an Exception.
$$(String selector) → Future<List<ElementHandle>>
The method runs document.querySelectorAll within the frame. If no elements match the selector, the return value resolves to [].
$$eval<T>(String selector, String pageFunction, {List? args}) → Future<T?>
This method runs Array.from(document.querySelectorAll(selector)) within the frame and passes it as the first argument to pageFunction.
$eval<T>(String selector, String pageFunction, {List? args}) → Future<T?>
This method runs document.querySelector within the frame 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?>
The method queries frame for the selector. If there's no such element within the frame, the method will resolve to null.
$x(String expression) → Future<List<ElementHandle>>
Evaluates the XPath expression.
addScriptTag({String? url, File? file, String? content, String? type}) → Future<ElementHandle>
Adds a <script> tag into the page with the desired url or content.
addStyleTag({String? url, File? file, String? content}) → Future<ElementHandle>
Adds a <link rel="stylesheet"> tag into the page with the desired url or a <style type="text/css"> tag with the content.
click(String selector, {Duration? delay, MouseButton? button, int? clickCount}) → Future<void>
This method fetches an element with selector, scrolls it into view if needed, and then uses Page.mouse to click in the center of the element. If there's no element matching selector, the method throws an error.
evaluate<T>(String pageFunction, {List? args}) → Future<T>
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.
evaluateHandle<T extends JsHandle>(String pageFunction, {List? args}) → Future<T>
The only difference between Frame.evaluate and Frame.evaluateHandle is that Frame.evaluateHandle returns in-page object (JSHandle).
focus(String selector) → Future<void>
This method fetches an element with selector and focuses it. If there's no element matching selector, the method throws an error.
goto(String url, {String? referrer, Duration? timeout, Until? wait}) → Future<Response>
The Frame.goto will throw an error if:
hover(String selector) → Future<void>
This method fetches an element with selector, scrolls it into view if needed, and then uses Page.mouse to hover over the center of the element. If there's no element matching selector, the method throws an error.
noSuchMethod(Invocation invocation) → dynamic
Invoked when a nonexistent method or property is accessed.
inherited
select(String selector, 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.
setContent(String html, {Duration? timeout, Until? wait}) → Future<void>
Parameters:
tap(String selector) → Future<void>
This method fetches an element with selector, scrolls it into view if needed, and then uses page.touchscreen to tap in the center of the element. If there's no element matching selector, the method throws an error.
toString() → String
A string representation of this object.
inherited
type(String selector, String text, {Duration? delay}) → Future<void>
Sends a keydown, keypress/input, and keyup event for each character in the text.
waitForFunction(String pageFunction, {List? args, Duration? timeout, Polling? polling}) → Future<JsHandle>
Parameters:
waitForNavigation({Duration? timeout, Until? wait}) → Future<Response>
waitForSelector(String selector, {bool? visible, bool? hidden, Duration? timeout}) → Future<ElementHandle?>
Wait for the selector to appear in page. If at the moment of calling the method the selector already exists, the method will return immediately. If the selector doesn't appear after the timeout of waiting, the function will throw.
waitForXPath(String xpath, {bool? visible, bool? hidden, Duration? timeout}) → Future<ElementHandle?>
Wait for the xpath to appear in page. If at the moment of calling the method the xpath already exists, the method will return immediately. If the xpath doesn't appear after the timeout of waiting, the function will throw.

Operators

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