github/puppeteer
0
0
Fork 0
mirror of https://github.com/puppeteer/puppeteer synced 2024-06-14 14:02:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs(new): add TSDoc comments to Keyboard (#6099)

Browse Source 
Co-authored-by: Tim van der Lippe <tvanderlippe@google.com>
This commit is contained in:
Jack Franklin 2020-06-25 10:56:55 +01:00 committed by Mathias Bynens
parent 4696f7abda
commit 5b6d2bfb0e
12 changed files with 233 additions and 80 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
new-docs/puppeteer.keyboard._client.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Keyboard](./puppeteer.keyboard.md) &gt; [\_client](./puppeteer.keyboard._client.md)
## Keyboard.\_client property
<b>Signature:</b>
```typescript
_client: CDPSession;
```

20
new-docs/puppeteer.keyboard._constructor_.md
View File

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

11
new-docs/puppeteer.keyboard._modifiers.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Keyboard](./puppeteer.keyboard.md) &gt; [\_modifiers](./puppeteer.keyboard._modifiers.md)
## Keyboard.\_modifiers property
<b>Signature:</b>
```typescript
_modifiers: number;
```

11
new-docs/puppeteer.keyboard._pressedkeys.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Keyboard](./puppeteer.keyboard.md) &gt; [\_pressedKeys](./puppeteer.keyboard._pressedkeys.md)
## Keyboard.\_pressedKeys property
<b>Signature:</b>
```typescript
_pressedKeys: Set<string>;
```

14
new-docs/puppeteer.keyboard.down.md
View File

@ -4,6 +4,8 @@
## Keyboard.down() method
Dispatches a `keydown` event.
<b>Signature:</b>
```typescript
@ -16,10 +18,18 @@ down(key: KeyInput, options?: {
| Parameter | Type | Description |
| --- | --- | --- |
| key | [KeyInput](./puppeteer.keyinput.md) | |
| options | { text?: string; } | |
| key | [KeyInput](./puppeteer.keyinput.md) | Name of key to press, such as <code>ArrowLeft</code>. See [KeyInput](./puppeteer.keyinput.md) for a list of all key names. |
| options | { text?: string; } | An object of options. Accepts text which, if specified, generates an input event with this text. |
<b>Returns:</b>
Promise&lt;void&gt;
## Remarks
If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`<!-- -->/`input` event will also generated. The `text` option can be specified to force an input event to be generated. If `key` is a modifier key, `Shift`<!-- -->, `Meta`<!-- -->, `Control`<!-- -->, or `Alt`<!-- -->, subsequent key presses will be sent with that modifier active. To release the modifier key, use [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->.
After the key is pressed once, subsequent calls to [Keyboard.down()](./puppeteer.keyboard.down.md) will have [repeat](https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat) set to true. To release the key, use [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->.
Modifier keys DO influence [Keyboard.down()](./puppeteer.keyboard.down.md)<!-- -->. Holding down `Shift` will type the text in upper case.

55
new-docs/puppeteer.keyboard.md
View File

@ -4,33 +4,58 @@
## Keyboard class
Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md)<!-- -->, which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page.
<b>Signature:</b>
```typescript
export declare class Keyboard
```
## Constructors
## Remarks
| Constructor | Modifiers | Description |
| --- | --- | --- |
| [(constructor)(client)](./puppeteer.keyboard._constructor_.md) | | Constructs a new instance of the <code>Keyboard</code> class |
For finer control, you can use [Keyboard.down()](./puppeteer.keyboard.down.md)<!-- -->, [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->, and [Keyboard.sendCharacter()](./puppeteer.keyboard.sendcharacter.md) to manually fire events as if they were generated from a real keyboard.
## Properties
On MacOS, keyboard shortcuts like `⌘ A` -<!-- -->&gt; Select All do not work. See [\#1313](https://github.com/puppeteer/puppeteer/issues/1313)<!-- -->.
| Property | Modifiers | Type | Description |
| --- | --- | --- | --- |
| [\_client](./puppeteer.keyboard._client.md) | | [CDPSession](./puppeteer.cdpsession.md) | |
| [\_modifiers](./puppeteer.keyboard._modifiers.md) | | number | |
| [\_pressedKeys](./puppeteer.keyboard._pressedkeys.md) | | Set&lt;string&gt; | |
The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Keyboard` class.
## Example 1
An example of holding down `Shift` in order to select and delete some text:
```js
await page.keyboard.type('Hello World!');
await page.keyboard.press('ArrowLeft');
await page.keyboard.down('Shift');
for (let i = 0; i < ' World'.length; i++)
await page.keyboard.press('ArrowLeft');
await page.keyboard.up('Shift');
await page.keyboard.press('Backspace');
// Result text will end up saying 'Hello!'
```
## Example 2
An example of pressing `A`
```js
await page.keyboard.down('Shift');
await page.keyboard.press('KeyA');
await page.keyboard.up('Shift');
```
## Methods
| Method | Modifiers | Description |
| --- | --- | --- |
| [down(key, options)](./puppeteer.keyboard.down.md) | | |
| [press(key, options)](./puppeteer.keyboard.press.md) | | |
| [sendCharacter(char)](./puppeteer.keyboard.sendcharacter.md) | | |
| [type(text, options)](./puppeteer.keyboard.type.md) | | |
| [up(key)](./puppeteer.keyboard.up.md) | | |
| [down(key, options)](./puppeteer.keyboard.down.md) | | Dispatches a <code>keydown</code> event. |
| [press(key, options)](./puppeteer.keyboard.press.md) | | Shortcut for [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->. |
| [sendCharacter(char)](./puppeteer.keyboard.sendcharacter.md) | | Dispatches a <code>keypress</code> and <code>input</code> event. This does not send a <code>keydown</code> or <code>keyup</code> event. |
| [type(text, options)](./puppeteer.keyboard.type.md) | | Sends a <code>keydown</code>, <code>keypress</code>/<code>input</code>, and <code>keyup</code> event for each character in the text. |
| [up(key)](./puppeteer.keyboard.up.md) | | Dispatches a <code>keyup</code> event. |

12
new-docs/puppeteer.keyboard.press.md
View File

@ -4,6 +4,8 @@
## Keyboard.press() method
Shortcut for [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->.
<b>Signature:</b>
```typescript
@ -17,10 +19,16 @@ press(key: KeyInput, options?: {
| Parameter | Type | Description |
| --- | --- | --- |
| key | [KeyInput](./puppeteer.keyinput.md) | |
| options | { delay?: number; text?: string; } | |
| key | [KeyInput](./puppeteer.keyinput.md) | Name of key to press, such as <code>ArrowLeft</code>. See [KeyInput](./puppeteer.keyinput.md) for a list of all key names. |
| options | { delay?: number; text?: string; } | An object of options. Accepts text which, if specified, generates an input event with this text. Accepts delay which, if specified, is the time to wait between <code>keydown</code> and <code>keyup</code> in milliseconds. Defaults to 0. |
<b>Returns:</b>
Promise&lt;void&gt;
## Remarks
If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`<!-- -->/`input` event will also generated. The `text` option can be specified to force an input event to be generated.
Modifier keys DO effect [Keyboard.press()](./puppeteer.keyboard.press.md)<!-- -->. Holding down `Shift` will type the text in upper case.

16
new-docs/puppeteer.keyboard.sendcharacter.md
View File

@ -4,6 +4,8 @@
## Keyboard.sendCharacter() method
Dispatches a `keypress` and `input` event. This does not send a `keydown` or `keyup` event.
<b>Signature:</b>
```typescript
@ -14,9 +16,21 @@ sendCharacter(char: string): Promise<void>;
| Parameter | Type | Description |
| --- | --- | --- |
| char | string | |
| char | string | Character to send into the page. |
<b>Returns:</b>
Promise&lt;void&gt;
## Remarks
Modifier keys DO NOT effect [Keyboard.sendCharacter](./puppeteer.keyboard.sendcharacter.md)<!-- -->. Holding down `Shift` will not type the text in upper case.
## Example
```js
page.keyboard.sendCharacter('嗨');
```

21
new-docs/puppeteer.keyboard.type.md
View File

@ -4,6 +4,8 @@
## Keyboard.type() method
Sends a `keydown`<!-- -->, `keypress`<!-- -->/`input`<!-- -->, and `keyup` event for each character in the text.
<b>Signature:</b>
```typescript
@ -16,10 +18,25 @@ type(text: string, options?: {
| Parameter | Type | Description |
| --- | --- | --- |
| text | string | |
| options | { delay?: number; } | |
| text | string | A text to type into a focused element. |
| options | { delay?: number; } | An object of options. Accepts delay which, if specified, is the time to wait between <code>keydown</code> and <code>keyup</code> in milliseconds. Defaults to 0. |
<b>Returns:</b>
Promise&lt;void&gt;
## Remarks
To press a special key, like `Control` or `ArrowDown`<!-- -->, use [Keyboard.press()](./puppeteer.keyboard.press.md)<!-- -->.
Modifier keys DO NOT effect `keyboard.type`<!-- -->. Holding down `Shift` will not type the text in upper case.
## Example
```js
await page.keyboard.type('Hello'); // Types instantly
await page.keyboard.type('World', {delay: 100}); // Types slower, like a user
```

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

@ -4,6 +4,8 @@
## Keyboard.up() method
Dispatches a `keyup` event.
<b>Signature:</b>
```typescript
@ -14,7 +16,7 @@ up(key: KeyInput): Promise<void>;
| Parameter | Type | Description |
| --- | --- | --- |
| key | [KeyInput](./puppeteer.keyinput.md) | |
| key | [KeyInput](./puppeteer.keyinput.md) | Name of key to release, such as <code>ArrowLeft</code>. See [KeyInput](./puppeteer.keyinput.md) for a list of all key names. |
<b>Returns:</b>

2
new-docs/puppeteer.md
View File

@ -26,7 +26,7 @@
| [HTTPRequest](./puppeteer.httprequest.md) | |
| [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. |
| [JSHandle](./puppeteer.jshandle.md) | |
| [Keyboard](./puppeteer.keyboard.md) | |
| [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md)<!-- -->, which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. |
| [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 Puppeteer module provides a method to launch a browser instance. |

136
src/common/Input.ts
View File

@ -22,15 +22,81 @@ type KeyDescription = Required<
Pick<KeyDefinition, 'keyCode' | 'key' | 'text' | 'code' | 'location'>
>;
/**
* Keyboard provides an api for managing a virtual keyboard.
* The high level api is {@link Keyboard."type"},
* which takes raw characters and generates proper keydown, keypress/input,
* and keyup events on your page.
*
* @remarks
* For finer control, you can use {@link Keyboard.down},
* {@link Keyboard.up}, and {@link Keyboard.sendCharacter}
* to manually fire events as if they were generated from a real keyboard.
*
* On MacOS, keyboard shortcuts like `⌘ A` -> Select All do not work.
* See {@link https://github.com/puppeteer/puppeteer/issues/1313 | #1313}.
*
* @example
* An example of holding down `Shift` in order to select and delete some text:
* ```js
* await page.keyboard.type('Hello World!');
* await page.keyboard.press('ArrowLeft');
*
* await page.keyboard.down('Shift');
* for (let i = 0; i < ' World'.length; i++)
* await page.keyboard.press('ArrowLeft');
* await page.keyboard.up('Shift');
*
* await page.keyboard.press('Backspace');
* // Result text will end up saying 'Hello!'
* ```
*
* @example
* An example of pressing `A`
* ```js
* await page.keyboard.down('Shift');
* await page.keyboard.press('KeyA');
* await page.keyboard.up('Shift');
* ```
*
* @public
*/
export class Keyboard {
_client: CDPSession;
private _client: CDPSession;
/** @internal */
_modifiers = 0;
_pressedKeys = new Set<string>();
private _pressedKeys = new Set<string>();
/** @internal */
constructor(client: CDPSession) {
this._client = client;
}
/**
* Dispatches a `keydown` event.
*
* @remarks
* If `key` is a single character and no modifier keys besides `Shift`
* are being held down, a `keypress`/`input` event will also generated.
* The `text` option can be specified to force an input event to be generated.
* If `key` is a modifier key, `Shift`, `Meta`, `Control`, or `Alt`,
* subsequent key presses will be sent with that modifier active.
* To release the modifier key, use {@link Keyboard.up}.
*
* After the key is pressed once, subsequent calls to
* {@link Keyboard.down} will have
* {@link https://developer.mozilla.org/en-US/docs/Web/API/KeyboardEvent/repeat | repeat}
* set to true. To release the key, use {@link Keyboard.up}.
*
* Modifier keys DO influence {@link Keyboard.down}.
* Holding down `Shift` will type the text in upper case.
*
* @param key - Name of key to press, such as `ArrowLeft`.
* See {@link KeyInput} for a list of all key names.
*
* @param options - An object of options. Accepts text which, if specified,
* generates an input event with this text.
*/
async down(
key: KeyInput,
options: { text?: string } = { text: undefined }
@ -99,6 +165,13 @@ export class Keyboard {
return description;
}
/**
* Dispatches a `keyup` event.
*
* @param key - Name of key to release, such as `ArrowLeft`.
* See {@link KeyInput | KeyInput}
* for a list of all key names.
*/
async up(key: KeyInput): Promise<void> {
const description = this._keyDescriptionForString(key);
@ -114,6 +187,21 @@ export class Keyboard {
});
}
/**
* Dispatches a `keypress` and `input` event.
* This does not send a `keydown` or `keyup` event.
*
* @remarks
* Modifier keys DO NOT effect {@link Keyboard.sendCharacter | Keyboard.sendCharacter}.
* Holding down `Shift` will not type the text in upper case.
*
* @example
* ```js
* page.keyboard.sendCharacter('嗨');
* ```
*
* @param char - Character to send into the page.
*/
async sendCharacter(char: string): Promise<void> {
await this._client.send('Input.insertText', { text: char });
}
@ -122,8 +210,30 @@ export class Keyboard {
return !!keyDefinitions[char];
}
/**
* Sends a `keydown`, `keypress`/`input`,
* and `keyup` event for each character in the text.
*
* @remarks
* To press a special key, like `Control` or `ArrowDown`,
* use {@link Keyboard.press}.
*
* Modifier keys DO NOT effect `keyboard.type`.
* Holding down `Shift` will not type the text in upper case.
*
* @example
* ```js
* await page.keyboard.type('Hello'); // Types instantly
* await page.keyboard.type('World', {delay: 100}); // Types slower, like a user
* ```
*
* @param text - A text to type into a focused element.
* @param options - An object of options. Accepts delay which,
* if specified, is the time to wait between `keydown` and `keyup` in milliseconds.
* Defaults to 0.
*/
async type(text: string, options: { delay?: number } = {}): Promise<void> {
const delay = (options && options.delay) || null;
const delay = options.delay || null;
for (const char of text) {
if (this.charIsKey(char)) {
await this.press(char, { delay });
@ -134,6 +244,26 @@ export class Keyboard {
}
}
/**
* Shortcut for {@link Keyboard.down}
* and {@link Keyboard.up}.
*
* @remarks
* If `key` is a single character and no modifier keys besides `Shift`
* are being held down, a `keypress`/`input` event will also generated.
* The `text` option can be specified to force an input event to be generated.
*
* Modifier keys DO effect {@link Keyboard.press}.
* Holding down `Shift` will type the text in upper case.
*
* @param key - Name of key to press, such as `ArrowLeft`.
* See {@link KeyInput} for a list of all key names.
*
* @param options - An object of options. Accepts text which, if specified,
* generates an input event with this text. Accepts delay which,
* if specified, is the time to wait between `keydown` and `keyup` in milliseconds.
* Defaults to 0.
*/
async press(
key: KeyInput,
options: { delay?: number; text?: string } = {}