thunderstrike/puppeteer
thunderstrike/puppeteer
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

docs(new): Adds TSDoc to Mouse class (#6086)

Browse Source 
* Adds tsdoc to Mouse class

* Updates puppeteer class tsdoc

* docs(new): add TSDoc comments to BrowserFetcher (#6078)

* Adds tsdoc for Touchscreen (#6087)

Co-authored-by: martinsplitt <martin@geekonaut.de>

* Adds tsdoc to Mouse class

* Fixes tsdoc comment for Mouse class

Co-authored-by: martinsplitt <martin@geekonaut.de>
This commit is contained in:
Martin Splitt 2020-06-24 11:00:13 +02:00 committed by Mathias Bynens
parent 2ad42dc398
commit f481922175
8 changed files with 159 additions and 41 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
new-docs/puppeteer.md
View File

@ -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. |

21
new-docs/puppeteer.mouse._constructor_.md
View File

@ -1,21 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Mouse](./puppeteer.mouse.md) &gt; [(constructor)](./puppeteer.mouse._constructor_.md)
## Mouse.(constructor)
Constructs a new instance of the `Mouse` class
<b>Signature:</b>
```typescript
constructor(client: CDPSession, keyboard: Keyboard);
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| client | [CDPSession](./puppeteer.cdpsession.md) | |
| keyboard | [Keyboard](./puppeteer.keyboard.md) | |

8
new-docs/puppeteer.mouse.click.md
View File

@ -4,6 +4,8 @@
## Mouse.click() method
Shortcut for `mouse.move`<!-- -->, `mouse.down` and `mouse.up`<!-- -->.
<b>Signature:</b>
```typescript
@ -16,9 +18,9 @@ click(x: number, y: number, options?: MouseOptions & {
| Parameter | Type | Description |
| --- | --- | --- |
| x | number | |
| y | number | |
| options | MouseOptions &amp; { delay?: number; } | |
| x | number | Horizontal position of the mouse. |
| y | number | Vertical position of the mouse. |
| options | MouseOptions &amp; { delay?: number; } | Optional <code>MouseOptions</code>. |
<b>Returns:</b>

4
new-docs/puppeteer.mouse.down.md
View File

@ -4,6 +4,8 @@
## Mouse.down() method
Dispatches a `mousedown` event.
<b>Signature:</b>
```typescript
@ -14,7 +16,7 @@ down(options?: MouseOptions): Promise<void>;
| Parameter | Type | Description |
| --- | --- | --- |
| options | MouseOptions | |
| options | MouseOptions | Optional <code>MouseOptions</code>. |
<b>Returns:</b>

73
new-docs/puppeteer.mouse.md
View File

@ -4,17 +4,74 @@
## Mouse class
The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport.
<b>Signature:</b>
```typescript
export declare class Mouse
```
## Constructors
## Remarks
| Constructor | Modifiers | Description |
| --- | --- | --- |
| [(constructor)(client, keyboard)](./puppeteer.mouse._constructor_.md) | | Constructs a new instance of the <code>Mouse</code> 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(
'<your origin>', ['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 <code>mouse.move</code>, <code>mouse.down</code> and <code>mouse.up</code>. |
| [down(options)](./puppeteer.mouse.down.md) | | Dispatches a <code>mousedown</code> event. |
| [move(x, y, options)](./puppeteer.mouse.move.md) | | Dispatches a <code>mousemove</code> event. |
| [up(options)](./puppeteer.mouse.up.md) | | Dispatches a <code>mouseup</code> event. |

8
new-docs/puppeteer.mouse.move.md
View File

@ -4,6 +4,8 @@
## Mouse.move() method
Dispatches a `mousemove` event.
<b>Signature:</b>
```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 <code>steps</code> property sends intermediate <code>mousemove</code> events when set to <code>1</code> (default). |
<b>Returns:</b>

4
new-docs/puppeteer.mouse.up.md
View File

@ -4,6 +4,8 @@
## Mouse.up() method
Dispatches a `mouseup` event.
<b>Signature:</b>
```typescript
@ -14,7 +16,7 @@ up(options?: MouseOptions): Promise<void>;
| Parameter | Type | Description |
| --- | --- | --- |
| options | MouseOptions | |
| options | MouseOptions | Optional <code>MouseOptions</code>. |
<b>Returns:</b>

80
src/common/Input.ts
View File

@ -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(
* '<your origin>', ['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<void> {
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<void> {
const { button = 'left', clickCount = 1 } = options;