From 60904da4cdcca659909187c2c662009d5f6fcaaa Mon Sep 17 00:00:00 2001 From: Martin Splitt Date: Wed, 24 Jun 2020 12:18:53 +0200 Subject: [PATCH] docs(new): migrate FileChooser docs to TSDoc (#6092) Co-authored-by: martinsplitt --- .../puppeteer.filechooser._constructor_.md | 21 ------------- new-docs/puppeteer.filechooser.accept.md | 4 ++- new-docs/puppeteer.filechooser.cancel.md | 2 ++ new-docs/puppeteer.filechooser.ismultiple.md | 2 ++ new-docs/puppeteer.filechooser.md | 30 +++++++++++++----- new-docs/puppeteer.md | 2 +- src/common/FileChooser.ts | 31 +++++++++++++++++++ 7 files changed, 62 insertions(+), 30 deletions(-) delete mode 100644 new-docs/puppeteer.filechooser._constructor_.md diff --git a/new-docs/puppeteer.filechooser._constructor_.md b/new-docs/puppeteer.filechooser._constructor_.md deleted file mode 100644 index 7c657039..00000000 --- a/new-docs/puppeteer.filechooser._constructor_.md +++ /dev/null @@ -1,21 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [FileChooser](./puppeteer.filechooser.md) > [(constructor)](./puppeteer.filechooser._constructor_.md) - -## FileChooser.(constructor) - -Constructs a new instance of the `FileChooser` class - -Signature: - -```typescript -constructor(element: ElementHandle, event: Protocol.Page.fileChooserOpenedPayload); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| element | [ElementHandle](./puppeteer.elementhandle.md) | | -| event | Protocol.Page.fileChooserOpenedPayload | | - diff --git a/new-docs/puppeteer.filechooser.accept.md b/new-docs/puppeteer.filechooser.accept.md index 61bc0c5f..bce69665 100644 --- a/new-docs/puppeteer.filechooser.accept.md +++ b/new-docs/puppeteer.filechooser.accept.md @@ -4,6 +4,8 @@ ## FileChooser.accept() method +Accept the file chooser request with given paths. + Signature: ```typescript @@ -14,7 +16,7 @@ accept(filePaths: string[]): Promise; | Parameter | Type | Description | | --- | --- | --- | -| filePaths | string\[\] | | +| filePaths | string\[\] | If some of the filePaths are relative paths, then they are resolved relative to the [current working directory](https://nodejs.org/api/process.html#process_process_cwd). | Returns: diff --git a/new-docs/puppeteer.filechooser.cancel.md b/new-docs/puppeteer.filechooser.cancel.md index 6d58d645..9e8fe652 100644 --- a/new-docs/puppeteer.filechooser.cancel.md +++ b/new-docs/puppeteer.filechooser.cancel.md @@ -4,6 +4,8 @@ ## FileChooser.cancel() method +Closes the file chooser without selecting any files. + Signature: ```typescript diff --git a/new-docs/puppeteer.filechooser.ismultiple.md b/new-docs/puppeteer.filechooser.ismultiple.md index 2875a325..b4d2da8c 100644 --- a/new-docs/puppeteer.filechooser.ismultiple.md +++ b/new-docs/puppeteer.filechooser.ismultiple.md @@ -4,6 +4,8 @@ ## FileChooser.isMultiple() method +Whether file chooser allow for [multiple](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-multiple) file selection. + Signature: ```typescript diff --git a/new-docs/puppeteer.filechooser.md b/new-docs/puppeteer.filechooser.md index 71522b0d..8165b170 100644 --- a/new-docs/puppeteer.filechooser.md +++ b/new-docs/puppeteer.filechooser.md @@ -4,23 +4,39 @@ ## FileChooser class +File choosers let you react to the page requesting for a file. + Signature: ```typescript export declare class FileChooser ``` -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(element, event)](./puppeteer.filechooser._constructor_.md) | | Constructs a new instance of the FileChooser class | +`FileChooser` objects are returned via the `page.waitForFileChooser` method. + +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `FileChooser` class. + +## Example + +An example of using `FileChooser`: + +```js +const [fileChooser] = await Promise.all([ + page.waitForFileChooser(), + page.click('#upload-file-button'), // some button that triggers file selection +]); +await fileChooser.accept(['/tmp/myfile.pdf']); + +``` +\*\*NOTE\*\* In browsers, only one file chooser can be opened at a time. All file choosers must be accepted or canceled. Not doing so will prevent subsequent file choosers from appearing. ## Methods | Method | Modifiers | Description | | --- | --- | --- | -| [accept(filePaths)](./puppeteer.filechooser.accept.md) | | | -| [cancel()](./puppeteer.filechooser.cancel.md) | | | -| [isMultiple()](./puppeteer.filechooser.ismultiple.md) | | | +| [accept(filePaths)](./puppeteer.filechooser.accept.md) | | Accept the file chooser request with given paths. | +| [cancel()](./puppeteer.filechooser.cancel.md) | | Closes the file chooser without selecting any files. | +| [isMultiple()](./puppeteer.filechooser.ismultiple.md) | | Whether file chooser allow for [multiple](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-multiple) file selection. | diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 758e4966..3bba9f24 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -20,7 +20,7 @@ | [ElementHandle](./puppeteer.elementhandle.md) | ElementHandle represents an in-page DOM element. | | [EventEmitter](./puppeteer.eventemitter.md) | The EventEmitter class that many Puppeteer classes extend. | | [ExecutionContext](./puppeteer.executioncontext.md) | | -| [FileChooser](./puppeteer.filechooser.md) | | +| [FileChooser](./puppeteer.filechooser.md) | File choosers let you react to the page requesting for a file. | | [Frame](./puppeteer.frame.md) | | | [FrameManager](./puppeteer.framemanager.md) | | | [HTTPRequest](./puppeteer.httprequest.md) | | diff --git a/src/common/FileChooser.ts b/src/common/FileChooser.ts index d23ab7c4..22eed356 100644 --- a/src/common/FileChooser.ts +++ b/src/common/FileChooser.ts @@ -18,11 +18,31 @@ import { ElementHandle } from './JSHandle'; import Protocol from '../protocol'; import { assert } from './assert'; +/** + * File choosers let you react to the page requesting for a file. + * @remarks + * `FileChooser` objects are returned via the `page.waitForFileChooser` method. + * @example + * An example of using `FileChooser`: + * ```js + * const [fileChooser] = await Promise.all([ + * page.waitForFileChooser(), + * page.click('#upload-file-button'), // some button that triggers file selection + * ]); + * await fileChooser.accept(['/tmp/myfile.pdf']); + * ``` + * **NOTE** In browsers, only one file chooser can be opened at a time. + * All file choosers must be accepted or canceled. Not doing so will prevent + * subsequent file choosers from appearing. + */ export class FileChooser { private _element: ElementHandle; private _multiple: boolean; private _handled = false; + /** + * @internal + */ constructor( element: ElementHandle, event: Protocol.Page.fileChooserOpenedPayload @@ -31,10 +51,18 @@ export class FileChooser { this._multiple = event.mode !== 'selectSingle'; } + /** + * Whether file chooser allow for {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input/file#attr-multiple | multiple} file selection. + */ isMultiple(): boolean { return this._multiple; } + /** + * Accept the file chooser request with given paths. + * @param filePaths - If some of the `filePaths` are relative paths, + * then they are resolved relative to the {@link https://nodejs.org/api/process.html#process_process_cwd | current working directory}. + */ async accept(filePaths: string[]): Promise { assert( !this._handled, @@ -44,6 +72,9 @@ export class FileChooser { await this._element.uploadFile(...filePaths); } + /** + * Closes the file chooser without selecting any files. + */ async cancel(): Promise { assert( !this._handled,