diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index cf0b3262..758e4966 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -27,7 +27,7 @@ | [HTTPResponse](./puppeteer.httpresponse.md) | | | [JSHandle](./puppeteer.jshandle.md) | | | [Keyboard](./puppeteer.keyboard.md) | | -| [Mouse](./puppeteer.mouse.md) | | +| [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. | | [Page](./puppeteer.page.md) | Page provides methods to interact with a single tab or \[extension background page\](https://developer.chrome.com/extensions/background\_pages) in Chromium. One \[Browser\] instance might have multiple \[Page\] instances. | | [Puppeteer](./puppeteer.puppeteer.md) | The main Puppeteer class | | [SecurityDetails](./puppeteer.securitydetails.md) | The SecurityDetails class represents the security details of a response that was received over a secure connection. | diff --git a/new-docs/puppeteer.mouse._constructor_.md b/new-docs/puppeteer.mouse._constructor_.md deleted file mode 100644 index a1ffc3d1..00000000 --- a/new-docs/puppeteer.mouse._constructor_.md +++ /dev/null @@ -1,21 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Mouse](./puppeteer.mouse.md) > [(constructor)](./puppeteer.mouse._constructor_.md) - -## Mouse.(constructor) - -Constructs a new instance of the `Mouse` class - -Signature: - -```typescript -constructor(client: CDPSession, keyboard: Keyboard); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| client | [CDPSession](./puppeteer.cdpsession.md) | | -| keyboard | [Keyboard](./puppeteer.keyboard.md) | | - diff --git a/new-docs/puppeteer.mouse.click.md b/new-docs/puppeteer.mouse.click.md index bdf8d5ca..4fa9645f 100644 --- a/new-docs/puppeteer.mouse.click.md +++ b/new-docs/puppeteer.mouse.click.md @@ -4,6 +4,8 @@ ## Mouse.click() method +Shortcut for `mouse.move`, `mouse.down` and `mouse.up`. + Signature: ```typescript @@ -16,9 +18,9 @@ click(x: number, y: number, options?: MouseOptions & { | Parameter | Type | Description | | --- | --- | --- | -| x | number | | -| y | number | | -| options | MouseOptions & { delay?: number; } | | +| x | number | Horizontal position of the mouse. | +| y | number | Vertical position of the mouse. | +| options | MouseOptions & { delay?: number; } | Optional MouseOptions. | Returns: diff --git a/new-docs/puppeteer.mouse.down.md b/new-docs/puppeteer.mouse.down.md index 6ca173bf..b4c0f464 100644 --- a/new-docs/puppeteer.mouse.down.md +++ b/new-docs/puppeteer.mouse.down.md @@ -4,6 +4,8 @@ ## Mouse.down() method +Dispatches a `mousedown` event. + Signature: ```typescript @@ -14,7 +16,7 @@ down(options?: MouseOptions): Promise; | Parameter | Type | Description | | --- | --- | --- | -| options | MouseOptions | | +| options | MouseOptions | Optional MouseOptions. | Returns: diff --git a/new-docs/puppeteer.mouse.md b/new-docs/puppeteer.mouse.md index 26f7737f..a3ecd2b3 100644 --- a/new-docs/puppeteer.mouse.md +++ b/new-docs/puppeteer.mouse.md @@ -4,17 +4,74 @@ ## Mouse class +The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. + Signature: ```typescript export declare class Mouse ``` -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(client, keyboard)](./puppeteer.mouse._constructor_.md) | | Constructs a new instance of the Mouse class | +Every `page` object has its own Mouse, accessible with \[`page.mouse`\](\#pagemouse). + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Mouse` class. + +## Example 1 + + +```js +// Using ‘page.mouse’ to trace a 100x100 square. +await page.mouse.move(0, 0); +await page.mouse.down(); +await page.mouse.move(0, 100); +await page.mouse.move(100, 100); +await page.mouse.move(100, 0); +await page.mouse.move(0, 0); +await page.mouse.up(); + +``` +\*\*Note\*\*: The mouse events trigger synthetic `MouseEvent`s. This means that it does not fully replicate the functionality of what a normal user would be able to do with their mouse. + +For example, dragging and selecting text is not possible using `page.mouse`. Instead, you can use the [\`DocumentOrShadowRoot.getSelection()\`](https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/getSelection) functionality implemented in the platform. + +## Example 2 + +For example, if you want to select all content between nodes: + +```js +await page.evaluate((from, to) => { + const selection = from.getRootNode().getSelection(); + const range = document.createRange(); + range.setStartBefore(from); + range.setEndAfter(to); + selection.removeAllRanges(); + selection.addRange(range); +}, fromJSHandle, toJSHandle); + +``` +If you then would want to copy-paste your selection, you can use the clipboard api: + +```js +// The clipboard api does not allow you to copy, unless the tab is focused. +await page.bringToFront(); +await page.evaluate(() => { + // Copy the selected content to the clipboard + document.execCommand('copy'); + // Obtain the content of the clipboard as a string + return navigator.clipboard.readText(); +}); + +``` +\*\*Note\*\*: If you want access to the clipboard API, you have to give it permission to do so: + +```js +await browser.defaultBrowserContext().overridePermissions( + '', ['clipboard-read', 'clipboard-write'] +); + +``` ## Properties @@ -30,8 +87,8 @@ export declare class Mouse | Method | Modifiers | Description | | --- | --- | --- | -| [click(x, y, options)](./puppeteer.mouse.click.md) | | | -| [down(options)](./puppeteer.mouse.down.md) | | | -| [move(x, y, options)](./puppeteer.mouse.move.md) | | | -| [up(options)](./puppeteer.mouse.up.md) | | | +| [click(x, y, options)](./puppeteer.mouse.click.md) | | Shortcut for mouse.move, mouse.down and mouse.up. | +| [down(options)](./puppeteer.mouse.down.md) | | Dispatches a mousedown event. | +| [move(x, y, options)](./puppeteer.mouse.move.md) | | Dispatches a mousemove event. | +| [up(options)](./puppeteer.mouse.up.md) | | Dispatches a mouseup event. | diff --git a/new-docs/puppeteer.mouse.move.md b/new-docs/puppeteer.mouse.move.md index 0a6e3929..12a3b35b 100644 --- a/new-docs/puppeteer.mouse.move.md +++ b/new-docs/puppeteer.mouse.move.md @@ -4,6 +4,8 @@ ## Mouse.move() method +Dispatches a `mousemove` event. + Signature: ```typescript @@ -16,9 +18,9 @@ move(x: number, y: number, options?: { | Parameter | Type | Description | | --- | --- | --- | -| x | number | | -| y | number | | -| options | { steps?: number; } | | +| x | number | Horizontal position of the mouse. | +| y | number | Vertical position of the mouse. | +| options | { steps?: number; } | Optional object. If specified, the steps property sends intermediate mousemove events when set to 1 (default). | Returns: diff --git a/new-docs/puppeteer.mouse.up.md b/new-docs/puppeteer.mouse.up.md index 0fb1d50b..d8a4071f 100644 --- a/new-docs/puppeteer.mouse.up.md +++ b/new-docs/puppeteer.mouse.up.md @@ -4,6 +4,8 @@ ## Mouse.up() method +Dispatches a `mouseup` event. + Signature: ```typescript @@ -14,7 +16,7 @@ up(options?: MouseOptions): Promise; | Parameter | Type | Description | | --- | --- | --- | -| options | MouseOptions | | +| options | MouseOptions | Optional MouseOptions. | Returns: diff --git a/src/common/Input.ts b/src/common/Input.ts index d9c89757..0f52d700 100644 --- a/src/common/Input.ts +++ b/src/common/Input.ts @@ -153,6 +153,63 @@ interface MouseOptions { clickCount?: number; } +/** + * The Mouse class operates in main-frame CSS pixels + * relative to the top-left corner of the viewport. + * @remarks + * Every `page` object has its own Mouse, accessible with [`page.mouse`](#pagemouse). + * + * @example + * ```js + * // Using ‘page.mouse’ to trace a 100x100 square. + * await page.mouse.move(0, 0); + * await page.mouse.down(); + * await page.mouse.move(0, 100); + * await page.mouse.move(100, 100); + * await page.mouse.move(100, 0); + * await page.mouse.move(0, 0); + * await page.mouse.up(); + * ``` + * + * **Note**: The mouse events trigger synthetic `MouseEvent`s. + * This means that it does not fully replicate the functionality of what a normal user + * would be able to do with their mouse. + * + * For example, dragging and selecting text is not possible using `page.mouse`. + * Instead, you can use the {@link https://developer.mozilla.org/en-US/docs/Web/API/DocumentOrShadowRoot/getSelection | `DocumentOrShadowRoot.getSelection()`} functionality implemented in the platform. + * + * @example + * For example, if you want to select all content between nodes: + * ```js + * await page.evaluate((from, to) => { + * const selection = from.getRootNode().getSelection(); + * const range = document.createRange(); + * range.setStartBefore(from); + * range.setEndAfter(to); + * selection.removeAllRanges(); + * selection.addRange(range); + * }, fromJSHandle, toJSHandle); + * ``` + * If you then would want to copy-paste your selection, you can use the clipboard api: + * ```js + * // The clipboard api does not allow you to copy, unless the tab is focused. + * await page.bringToFront(); + * await page.evaluate(() => { + * // Copy the selected content to the clipboard + * document.execCommand('copy'); + * // Obtain the content of the clipboard as a string + * return navigator.clipboard.readText(); + * }); + * ``` + * **Note**: If you want access to the clipboard API, + * you have to give it permission to do so: + * ```js + * await browser.defaultBrowserContext().overridePermissions( + * '', ['clipboard-read', 'clipboard-write'] + * ); + * ``` + * @public + */ export class Mouse { _client: CDPSession; _keyboard: Keyboard; @@ -160,14 +217,20 @@ export class Mouse { _y = 0; _button: MouseButton = 'none'; /** - * @param {CDPSession} client - * @param {!Keyboard} keyboard + * @internal */ constructor(client: CDPSession, keyboard: Keyboard) { this._client = client; this._keyboard = keyboard; } + /** + * Dispatches a `mousemove` event. + * @param x - Horizontal position of the mouse. + * @param y - Vertical position of the mouse. + * @param options - Optional object. If specified, the `steps` property + * sends intermediate `mousemove` events when set to `1` (default). + */ async move( x: number, y: number, @@ -189,6 +252,12 @@ export class Mouse { } } + /** + * Shortcut for `mouse.move`, `mouse.down` and `mouse.up`. + * @param x - Horizontal position of the mouse. + * @param y - Vertical position of the mouse. + * @param options - Optional `MouseOptions`. + */ async click( x: number, y: number, @@ -208,6 +277,10 @@ export class Mouse { } } + /** + * Dispatches a `mousedown` event. + * @param options - Optional `MouseOptions`. + */ async down(options: MouseOptions = {}): Promise { const { button = 'left', clickCount = 1 } = options; this._button = button; @@ -222,7 +295,8 @@ export class Mouse { } /** - * @param {!{button?: "left"|"right"|"middle", clickCount?: number}=} options + * Dispatches a `mouseup` event. + * @param options - Optional `MouseOptions`. */ async up(options: MouseOptions = {}): Promise { const { button = 'left', clickCount = 1 } = options;