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 d45c2b918d7..00000000000 --- 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 e8c4f668b84..00000000000 --- 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 c65e5a09a63..00000000000 --- 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 81f67a3ecb2..00000000000 --- 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 340caccc3c6..5135cc6f156 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 56bda00fc7a..ede7de729a1 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. -## Properties +On MacOS, keyboard shortcuts like `⌘ A` -> 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<string> | | +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 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 e460e158d8d..3f82fdea1e3 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 bf3aa5e5ce2..9f5bdf1b444 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 b1d5d78a9ac..442d7e5fb71 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 5740664f9e2..412cd2dc182 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 bf0119dd5a7..8b2c127a439 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 0f52d700471..4dae85a39b6 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 } = {}