Frame | /mod.ts | puppeteer@16.2.0

class Frame

Re-export

import { Frame } from "https://deno.land/x/puppeteer@16.2.0/mod.ts";

Represents a DOM frame.

To understand frames, you can think of frames as <iframe> elements. Just like iframes, frames can be nested, and when JavaScript is executed in a frame, the JavaScript does not effect frames inside the ambient frame the JavaScript executes in.

Examples

At any point in time, Page | pages expose their current frame tree via the Page.mainFrame and Frame.childFrames methods.

An example of dumping frame tree:

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch();
  const page = await browser.newPage();
  await page.goto('https://www.google.com/chrome/browser/canary.html');
  dumpFrameTree(page.mainFrame(), '');
  await browser.close();

  function dumpFrameTree(frame, indent) {
    console.log(indent + frame.url());
    for (const child of frame.childFrames()) {
      dumpFrameTree(child, indent + '  ');
    }
  }
})();

An example of getting text from an iframe element:

const frame = page.frames().find(frame => frame.name() === 'myframe');
const text = await frame.$eval('.selector', element => element.textContent);
console.log(text);

Constructors

new

Frame(

frameManager: FrameManager,

parentFrame: Frame | null,

frameId: string,

client: CDPSession,

)

Properties

_childFrames: Set<Frame>

_frameManager: FrameManager

_hasStartedLoading: boolean

_id: string

_lifecycleEvents: Set<string>

_loaderId: string

optional

_name: string

worlds: IsolatedWorldChart

Methods

_client(): CDPSession

_detach(): void

_navigated(framePayload: Protocol.Page.Frame): void

_navigatedWithinDocument(url: string): void

_onLifecycleEvent(loaderId: string, name: string): void

_onLoadingStarted(): void

_onLoadingStopped(): void

$<Selector extends string>(selector: Selector): Promise<ElementHandle<NodeFor<Selector>> | null>

Queries the frame for an element matching the given selector.

$$<Selector extends string>(selector: Selector): Promise<Array<ElementHandle<NodeFor<Selector>>>>

Queries the frame for all elements matching the given selector.

$$eval<Selector extends string, Params extends unknown[], Func extends EvaluateFunc<[Array<NodeFor<Selector>>, ...Params]> = EvaluateFunc<[Array<NodeFor<Selector>>, ...Params]>>(

selector: Selector,

pageFunction: Func | string,

...args: Params,

): Promise<Awaited<ReturnType<Func>>>

Runs the given function on an array of elements matching the given selector in the frame.

If the given function returns a promise, then this method will wait till the promise resolves.

$eval<Selector extends string, Params extends unknown[], Func extends EvaluateFunc<[ElementHandle<NodeFor<Selector>>, ...Params]> = EvaluateFunc<[ElementHandle<NodeFor<Selector>>, ...Params]>>(

selector: Selector,

pageFunction: Func | string,

...args: Params,

): Promise<Awaited<ReturnType<Func>>>

Runs the given function on the first element matching the given selector in the frame.

If the given function returns a promise, then this method will wait till the promise resolves.

deprecated

$x(expression: string): Promise<Array<ElementHandle<any>>>

addScriptTag(options: FrameAddScriptTagOptions): Promise<ElementHandle<any>>

Adds a <script> tag into the page with the desired url or content.

addStyleTag(options: FrameAddStyleTagOptions): Promise<ElementHandle<any>>

Adds a <link rel="stylesheet"> tag into the page with the desired url or a <style type="text/css"> tag with the content.

childFrames(): Frame[]

click(selector: string, options?: { delay?: number; button?: MouseButton; clickCount?: number; }): Promise<void>

Clicks the first element found that matches selector.

content(): Promise<string>

evaluate<Params extends unknown[], Func extends EvaluateFunc<Params> = EvaluateFunc<Params>>(pageFunction: Func | string, ...args: Params): Promise<Awaited<ReturnType<Func>>>

Behaves identically to Page.evaluate except it's run within the the context of this frame.

evaluateHandle<Params extends unknown[], Func extends EvaluateFunc<Params> = EvaluateFunc<Params>>(pageFunction: Func | string, ...args: Params): Promise<HandleFor<Awaited<ReturnType<Func>>>>

Behaves identically to Page.evaluateHandle except it's run within the context of this frame.

deprecated

executionContext(): Promise<ExecutionContext>

focus(selector: string): Promise<void>

Focuses the first element that matches the selector.

goto(url: string, options?: { referer?: string; timeout?: number; waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[]; }): Promise<HTTPResponse | null>

Navigates a frame to the given url.

hover(selector: string): Promise<void>

Hovers the pointer over the center of the first element that matches the selector.

isDetached(): boolean

isOOPFrame(): boolean

name(): string

page(): Page

parentFrame(): Frame | null

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

Selects a set of value on the first <select> element that matches the selector.

setContent(html: string, options?: { timeout?: number; waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[]; }): Promise<void>

Set the content of the frame.

tap(selector: string): Promise<void>

Taps the first element that matches the selector.

title(): Promise<string>

type(

selector: string,

text: string,

options?: { delay: number; },

): Promise<void>

Sends a keydown, keypress/input, and keyup event for each character in the text.

updateClient(client: CDPSession): void

url(): string

waitForFunction<Params extends unknown[], Func extends EvaluateFunc<Params> = EvaluateFunc<Params>>(

pageFunction: Func | string,

options?: FrameWaitForFunctionOptions,

...args: Params,

): Promise<HandleFor<Awaited<ReturnType<Func>>>>

waitForNavigation(options?: { timeout?: number; waitUntil?: PuppeteerLifeCycleEvent | PuppeteerLifeCycleEvent[]; }): Promise<HTTPResponse | null>

Waits for the frame to navigate. It is useful for when you run code which will indirectly cause the frame to navigate.

Usage of the History API to change the URL is considered a navigation.

waitForSelector<Selector extends string>(selector: Selector, options?: WaitForSelectorOptions): Promise<ElementHandle<NodeFor<Selector>> | null>

Waits for an element matching the given selector to appear in the frame.

This method works across navigations.

deprecated

waitForTimeout(milliseconds: number): Promise<void>

deprecated

waitForXPath(xpath: string, options?: WaitForSelectorOptions): Promise<ElementHandle<any> | null>