/** * Copyright 2023 Google Inc. All rights reserved. * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ import {Protocol} from 'devtools-protocol'; import {Frame} from '../common/Frame.js'; import {WaitForSelectorOptions} from '../common/IsolatedWorld.js'; import {JSHandle} from './JSHandle.js'; import {ScreenshotOptions} from './Page.js'; import {ElementFor, EvaluateFunc, HandleFor, NodeFor} from '../common/types.js'; import {KeyInput} from '../common/USKeyboardLayout.js'; import {MouseButton} from '../common/Input.js'; import {ExecutionContext} from '../common/ExecutionContext.js'; import {CDPSession} from '../common/Connection.js'; /** * @public */ export interface BoxModel { content: Point[]; padding: Point[]; border: Point[]; margin: Point[]; width: number; height: number; } /** * @public */ export interface BoundingBox extends Point { /** * the width of the element in pixels. */ width: number; /** * the height of the element in pixels. */ height: number; } /** * @public */ export interface Offset { /** * x-offset for the clickable point relative to the top-left corner of the border box. */ x: number; /** * y-offset for the clickable point relative to the top-left corner of the border box. */ y: number; } /** * @public */ export interface ClickOptions { /** * Time to wait between `mousedown` and `mouseup` in milliseconds. * * @defaultValue 0 */ delay?: number; /** * @defaultValue 'left' */ button?: MouseButton; /** * @defaultValue 1 */ clickCount?: number; /** * Offset for the clickable point relative to the top-left corner of the border box. */ offset?: Offset; } /** * @public */ export interface PressOptions { /** * Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0. */ delay?: number; /** * If specified, generates an input event with this text. */ text?: string; } /** * @public */ export interface Point { x: number; y: number; } /** * ElementHandle represents an in-page DOM element. * * @remarks * ElementHandles can be created with the {@link Page.$} method. * * ```ts * 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 prevents the DOM element from being garbage-collected unless the * handle is {@link JSHandle.dispose | disposed}. ElementHandles are auto-disposed * when their origin frame gets navigated. * * ElementHandle instances can be used as arguments in {@link Page.$eval} and * {@link Page.evaluate} methods. * * If you're using TypeScript, ElementHandle takes a generic argument that * denotes the type of element the handle is holding within. For example, if you * have a handle to a `` element matching `selector`, the method * throws an error. * * @example * * ```ts * handle.select('blue'); // single selection * handle.select('red', 'green', 'blue'); // multiple selections * ``` * * @param values - Values of options to select. If the `