From 5b6d2bfb0e2a4034f6395ca02895947abf3a3b37 Mon Sep 17 00:00:00 2001 From: Jack Franklin Date: Thu, 25 Jun 2020 10:56:55 +0100 Subject: [PATCH] docs(new): add TSDoc comments to Keyboard (#6099) Co-authored-by: Tim van der Lippe --- new-docs/puppeteer.keyboard._client.md | 11 -- new-docs/puppeteer.keyboard._constructor_.md | 20 --- new-docs/puppeteer.keyboard._modifiers.md | 11 -- new-docs/puppeteer.keyboard._pressedkeys.md | 11 -- new-docs/puppeteer.keyboard.down.md | 14 +- new-docs/puppeteer.keyboard.md | 55 ++++++-- new-docs/puppeteer.keyboard.press.md | 12 +- new-docs/puppeteer.keyboard.sendcharacter.md | 16 ++- new-docs/puppeteer.keyboard.type.md | 21 ++- new-docs/puppeteer.keyboard.up.md | 4 +- new-docs/puppeteer.md | 2 +- src/common/Input.ts | 136 ++++++++++++++++++- 12 files changed, 233 insertions(+), 80 deletions(-) delete mode 100644 new-docs/puppeteer.keyboard._client.md delete mode 100644 new-docs/puppeteer.keyboard._constructor_.md delete mode 100644 new-docs/puppeteer.keyboard._modifiers.md delete mode 100644 new-docs/puppeteer.keyboard._pressedkeys.md diff --git a/new-docs/puppeteer.keyboard._client.md b/new-docs/puppeteer.keyboard._client.md deleted file mode 100644 index d45c2b918d719..0000000000000 --- a/new-docs/puppeteer.keyboard._client.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Keyboard](./puppeteer.keyboard.md) > [\_client](./puppeteer.keyboard._client.md) - -## Keyboard.\_client property - -Signature: - -```typescript -_client: CDPSession; -``` diff --git a/new-docs/puppeteer.keyboard._constructor_.md b/new-docs/puppeteer.keyboard._constructor_.md deleted file mode 100644 index e8c4f668b84a7..0000000000000 --- a/new-docs/puppeteer.keyboard._constructor_.md +++ /dev/null @@ -1,20 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Keyboard](./puppeteer.keyboard.md) > [(constructor)](./puppeteer.keyboard._constructor_.md) - -## Keyboard.(constructor) - -Constructs a new instance of the `Keyboard` class - -Signature: - -```typescript -constructor(client: CDPSession); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| client | [CDPSession](./puppeteer.cdpsession.md) | | - diff --git a/new-docs/puppeteer.keyboard._modifiers.md b/new-docs/puppeteer.keyboard._modifiers.md deleted file mode 100644 index c65e5a09a63e1..0000000000000 --- a/new-docs/puppeteer.keyboard._modifiers.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Keyboard](./puppeteer.keyboard.md) > [\_modifiers](./puppeteer.keyboard._modifiers.md) - -## Keyboard.\_modifiers property - -Signature: - -```typescript -_modifiers: number; -``` diff --git a/new-docs/puppeteer.keyboard._pressedkeys.md b/new-docs/puppeteer.keyboard._pressedkeys.md deleted file mode 100644 index 81f67a3ecb21b..0000000000000 --- a/new-docs/puppeteer.keyboard._pressedkeys.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Keyboard](./puppeteer.keyboard.md) > [\_pressedKeys](./puppeteer.keyboard._pressedkeys.md) - -## Keyboard.\_pressedKeys property - -Signature: - -```typescript -_pressedKeys: Set; -``` diff --git a/new-docs/puppeteer.keyboard.down.md b/new-docs/puppeteer.keyboard.down.md index 340caccc3c66c..5135cc6f1561c 100644 --- a/new-docs/puppeteer.keyboard.down.md +++ b/new-docs/puppeteer.keyboard.down.md @@ -4,6 +4,8 @@ ## Keyboard.down() method +Dispatches a `keydown` event. + Signature: ```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 ArrowLeft. 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. | Returns: Promise<void> +## 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. + diff --git a/new-docs/puppeteer.keyboard.md b/new-docs/puppeteer.keyboard.md index 56bda00fc7a5f..ede7de729a121 100644 --- a/new-docs/puppeteer.keyboard.md +++ b/new-docs/puppeteer.keyboard.md @@ -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. + Signature: ```typescript export declare class Keyboard ``` -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(client)](./puppeteer.keyboard._constructor_.md) | | Constructs a new instance of the Keyboard 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. + +On MacOS, keyboard shortcuts like `⌘ A` -> Select All do not work. See [\#1313](https://github.com/puppeteer/puppeteer/issues/1313). + +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'); -## Properties +await page.keyboard.down('Shift'); +for (let i = 0; i < ' World'.length; i++) + await page.keyboard.press('ArrowLeft'); +await page.keyboard.up('Shift'); -| 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<string> | | +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 keydown 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 keypress and input event. This does not send a keydown or keyup event. | +| [type(text, options)](./puppeteer.keyboard.type.md) | | Sends a keydown, keypress/input, and keyup event for each character in the text. | +| [up(key)](./puppeteer.keyboard.up.md) | | Dispatches a keyup event. | diff --git a/new-docs/puppeteer.keyboard.press.md b/new-docs/puppeteer.keyboard.press.md index e460e158d8d75..3f82fdea1e333 100644 --- a/new-docs/puppeteer.keyboard.press.md +++ b/new-docs/puppeteer.keyboard.press.md @@ -4,6 +4,8 @@ ## Keyboard.press() method +Shortcut for [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md). + Signature: ```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 ArrowLeft. 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 keydown and keyup in milliseconds. Defaults to 0. | Returns: Promise<void> +## 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. + diff --git a/new-docs/puppeteer.keyboard.sendcharacter.md b/new-docs/puppeteer.keyboard.sendcharacter.md index bf3aa5e5ce216..9f5bdf1b44459 100644 --- a/new-docs/puppeteer.keyboard.sendcharacter.md +++ b/new-docs/puppeteer.keyboard.sendcharacter.md @@ -4,6 +4,8 @@ ## Keyboard.sendCharacter() method +Dispatches a `keypress` and `input` event. This does not send a `keydown` or `keyup` event. + Signature: ```typescript @@ -14,9 +16,21 @@ sendCharacter(char: string): Promise; | Parameter | Type | Description | | --- | --- | --- | -| char | string | | +| char | string | Character to send into the page. | Returns: Promise<void> +## 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('嗨'); + +``` + diff --git a/new-docs/puppeteer.keyboard.type.md b/new-docs/puppeteer.keyboard.type.md index b1d5d78a9ac32..442d7e5fb71de 100644 --- a/new-docs/puppeteer.keyboard.type.md +++ b/new-docs/puppeteer.keyboard.type.md @@ -4,6 +4,8 @@ ## Keyboard.type() method +Sends a `keydown`, `keypress`/`input`, and `keyup` event for each character in the text. + Signature: ```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 keydown and keyup in milliseconds. Defaults to 0. | Returns: Promise<void> +## 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 + +``` + diff --git a/new-docs/puppeteer.keyboard.up.md b/new-docs/puppeteer.keyboard.up.md index 5740664f9e2f3..412cd2dc18258 100644 --- a/new-docs/puppeteer.keyboard.up.md +++ b/new-docs/puppeteer.keyboard.up.md @@ -4,6 +4,8 @@ ## Keyboard.up() method +Dispatches a `keyup` event. + Signature: ```typescript @@ -14,7 +16,7 @@ up(key: KeyInput): Promise; | Parameter | Type | Description | | --- | --- | --- | -| key | [KeyInput](./puppeteer.keyinput.md) | | +| key | [KeyInput](./puppeteer.keyinput.md) | Name of key to release, such as ArrowLeft. See [KeyInput](./puppeteer.keyinput.md) for a list of all key names. | Returns: diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index bf0119dd5a7ee..8b2c127a43936 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -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. | diff --git a/src/common/Input.ts b/src/common/Input.ts index 0f52d700471ed..4dae85a39b6df 100644 --- a/src/common/Input.ts +++ b/src/common/Input.ts @@ -22,15 +22,81 @@ type KeyDescription = Required< Pick >; +/** + * 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(); + private _pressedKeys = new Set(); + /** @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 { 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 { 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 { - 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 } = {}