diff --git a/new-docs/puppeteer.md b/new-docs/puppeteer.md index 0fc29ce2..5b797ad0 100644 --- a/new-docs/puppeteer.md +++ b/new-docs/puppeteer.md @@ -27,7 +27,7 @@ | [JSHandle](./puppeteer.jshandle.md) | | | [Keyboard](./puppeteer.keyboard.md) | | | [Mouse](./puppeteer.mouse.md) | | -| [Page](./puppeteer.page.md) | | +| [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) | | | [Target](./puppeteer.target.md) | | @@ -36,6 +36,12 @@ | [Tracing](./puppeteer.tracing.md) | | | [WebWorker](./puppeteer.webworker.md) | | +## Enumerations + +| Enumeration | Description | +| --- | --- | +| [PageEmittedEvents](./puppeteer.pageemittedevents.md) | All the events that a page instance may emit. | + ## Functions | Function | Description | diff --git a/new-docs/puppeteer.page._constructor_.md b/new-docs/puppeteer.page._constructor_.md deleted file mode 100644 index 4d308809..00000000 --- a/new-docs/puppeteer.page._constructor_.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Page](./puppeteer.page.md) > [(constructor)](./puppeteer.page._constructor_.md) - -## Page.(constructor) - -Constructs a new instance of the `Page` class - -Signature: - -```typescript -constructor(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean); -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| client | [CDPSession](./puppeteer.cdpsession.md) | | -| target | [Target](./puppeteer.target.md) | | -| ignoreHTTPSErrors | boolean | | - diff --git a/new-docs/puppeteer.page._go.md b/new-docs/puppeteer.page._go.md deleted file mode 100644 index 0bfc68de..00000000 --- a/new-docs/puppeteer.page._go.md +++ /dev/null @@ -1,23 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Page](./puppeteer.page.md) > [\_go](./puppeteer.page._go.md) - -## Page.\_go() method - -Signature: - -```typescript -_go(delta: number, options: WaitForOptions): Promise; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| delta | number | | -| options | WaitForOptions | | - -Returns: - -Promise<[HTTPResponse](./puppeteer.httpresponse.md) \| null> - diff --git a/new-docs/puppeteer.page._onlogentryadded.md b/new-docs/puppeteer.page._onlogentryadded.md deleted file mode 100644 index de2632bc..00000000 --- a/new-docs/puppeteer.page._onlogentryadded.md +++ /dev/null @@ -1,22 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Page](./puppeteer.page.md) > [\_onLogEntryAdded](./puppeteer.page._onlogentryadded.md) - -## Page.\_onLogEntryAdded() method - -Signature: - -```typescript -_onLogEntryAdded(event: Protocol.Log.entryAddedPayload): void; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| event | Protocol.Log.entryAddedPayload | | - -Returns: - -void - diff --git a/new-docs/puppeteer.page._ontargetcrashed.md b/new-docs/puppeteer.page._ontargetcrashed.md deleted file mode 100644 index 43acba4d..00000000 --- a/new-docs/puppeteer.page._ontargetcrashed.md +++ /dev/null @@ -1,15 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Page](./puppeteer.page.md) > [\_onTargetCrashed](./puppeteer.page._ontargetcrashed.md) - -## Page.\_onTargetCrashed() method - -Signature: - -```typescript -_onTargetCrashed(): void; -``` -Returns: - -void - diff --git a/new-docs/puppeteer.page._screenshottask.md b/new-docs/puppeteer.page._screenshottask.md deleted file mode 100644 index b8739923..00000000 --- a/new-docs/puppeteer.page._screenshottask.md +++ /dev/null @@ -1,23 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Page](./puppeteer.page.md) > [\_screenshotTask](./puppeteer.page._screenshottask.md) - -## Page.\_screenshotTask() method - -Signature: - -```typescript -_screenshotTask(format: 'png' | 'jpeg', options?: ScreenshotOptions): Promise; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| format | 'png' \| 'jpeg' | | -| options | ScreenshotOptions | | - -Returns: - -Promise<Buffer \| string> - diff --git a/new-docs/puppeteer.page.create.md b/new-docs/puppeteer.page.create.md deleted file mode 100644 index bd3ae59f..00000000 --- a/new-docs/puppeteer.page.create.md +++ /dev/null @@ -1,25 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [Page](./puppeteer.page.md) > [create](./puppeteer.page.create.md) - -## Page.create() method - -Signature: - -```typescript -static create(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean, defaultViewport: Viewport | null): Promise; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| client | [CDPSession](./puppeteer.cdpsession.md) | | -| target | [Target](./puppeteer.target.md) | | -| ignoreHTTPSErrors | boolean | | -| defaultViewport | Viewport \| null | | - -Returns: - -Promise<[Page](./puppeteer.page.md)> - diff --git a/new-docs/puppeteer.page.md b/new-docs/puppeteer.page.md index 7b136117..f5c0cea6 100644 --- a/new-docs/puppeteer.page.md +++ b/new-docs/puppeteer.page.md @@ -4,17 +4,55 @@ ## Page class +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. + Signature: ```typescript export declare class Page extends EventEmitter ``` -## Constructors +## Remarks -| Constructor | Modifiers | Description | -| --- | --- | --- | -| [(constructor)(client, target, ignoreHTTPSErrors)](./puppeteer.page._constructor_.md) | | Constructs a new instance of the Page class | +The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `Page` class. + +## Example 1 + +This example creates a page, navigates it to a URL, and then \* saves a screenshot: + +```js +const puppeteer = require('puppeteer'); + +(async () => { + const browser = await puppeteer.launch(); + const page = await browser.newPage(); + await page.goto('https://example.com'); + await page.screenshot({path: 'screenshot.png'}); + await browser.close(); +})(); + +``` +The Page class emits various events which are documented in the [PageEmittedEvents](./puppeteer.pageemittedevents.md) enum. + +## Example 2 + +This example logs a message for a single page `load` event: + +```js +page.once('load', () => console.log('Page loaded!')); + +``` +To unsubscribe from events use the `off` method: + +```js +function logRequest(interceptedRequest) { + console.log('A request was made:', interceptedRequest.url()); +} +page.on('request', logRequest); +// Sometime later... +page.off('request', logRequest); + +``` ## Properties @@ -31,10 +69,6 @@ export declare class Page extends EventEmitter | Method | Modifiers | Description | | --- | --- | --- | -| [\_go(delta, options)](./puppeteer.page._go.md) | | | -| [\_onLogEntryAdded(event)](./puppeteer.page._onlogentryadded.md) | | | -| [\_onTargetCrashed()](./puppeteer.page._ontargetcrashed.md) | | | -| [\_screenshotTask(format, options)](./puppeteer.page._screenshottask.md) | | | | [$(selector)](./puppeteer.page._.md) | | | | [$$(selector)](./puppeteer.page.__.md) | | | | [$$eval(selector, pageFunction, args)](./puppeteer.page.__eval.md) | | | @@ -50,7 +84,6 @@ export declare class Page extends EventEmitter | [close(options)](./puppeteer.page.close.md) | | | | [content()](./puppeteer.page.content.md) | | | | [cookies(urls)](./puppeteer.page.cookies.md) | | | -| [create(client, target, ignoreHTTPSErrors, defaultViewport)](./puppeteer.page.create.md) | static | | | [deleteCookie(cookies)](./puppeteer.page.deletecookie.md) | | | | [emulate(options)](./puppeteer.page.emulate.md) | | | | [emulateMediaFeatures(features)](./puppeteer.page.emulatemediafeatures.md) | | | diff --git a/new-docs/puppeteer.pageemittedevents.md b/new-docs/puppeteer.pageemittedevents.md new file mode 100644 index 00000000..56c6c2f5 --- /dev/null +++ b/new-docs/puppeteer.pageemittedevents.md @@ -0,0 +1,20 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [PageEmittedEvents](./puppeteer.pageemittedevents.md) + +## PageEmittedEvents enum + +All the events that a page instance may emit. + +Signature: + +```typescript +export declare const enum PageEmittedEvents +``` + +## Enumeration Members + +| Member | Value | Description | +| --- | --- | --- | +| WorkerCreated | "workercreated" | Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the page. | + diff --git a/src/Page.ts b/src/Page.ts index d64c8f98..efec6bbc 100644 --- a/src/Page.ts +++ b/src/Page.ts @@ -137,6 +137,17 @@ enum VisionDeficiency { tritanopia = 'tritanopia', } +/** + * All the events that a page instance may emit. + */ +export const enum PageEmittedEvents { + /** + * Emitted when a dedicated {@link https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API | WebWorker} is spawned by the page. + * @eventProperty + */ + WorkerCreated = 'workercreated', +} + class ScreenshotTaskQueue { _chain: Promise; @@ -153,7 +164,49 @@ class ScreenshotTaskQueue { } } +/** + * 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. + * + * @remarks + * + * @example + * This example creates a page, navigates it to a URL, and then * saves a screenshot: + * ```js + * const puppeteer = require('puppeteer'); + * + * (async () => { + * const browser = await puppeteer.launch(); + * const page = await browser.newPage(); + * await page.goto('https://example.com'); + * await page.screenshot({path: 'screenshot.png'}); + * await browser.close(); + * })(); + * ``` + * + * The Page class emits various events which are documented in the {@link PageEmittedEvents} enum. + * + * @example + * This example logs a message for a single page `load` event: + * ```js + * page.once('load', () => console.log('Page loaded!')); + * ``` + * + * To unsubscribe from events use the `off` method: + * + * ```js + * function logRequest(interceptedRequest) { + * console.log('A request was made:', interceptedRequest.url()); + * } + * page.on('request', logRequest); + * // Sometime later... + * page.off('request', logRequest); + * ``` + * @public + */ export class Page extends EventEmitter { + /** + * @internal + */ static async create( client: CDPSession, target: Target, @@ -188,6 +241,9 @@ export class Page extends EventEmitter { private _disconnectPromise?: Promise; + /** + * @internal + */ constructor(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean) { super(); this._client = client; @@ -226,7 +282,7 @@ export class Page extends EventEmitter { this._handleException.bind(this) ); this._workers.set(event.sessionId, worker); - this.emit(Events.Page.WorkerCreated, worker); + this.emit(PageEmittedEvents.WorkerCreated, worker); }); client.on('Target.detachedFromTarget', (event) => { const worker = this._workers.get(event.sessionId); @@ -371,11 +427,11 @@ export class Page extends EventEmitter { return this._target.browserContext(); } - _onTargetCrashed(): void { + private _onTargetCrashed(): void { this.emit('error', new Error('Page crashed!')); } - _onLogEntryAdded(event: Protocol.Log.entryAddedPayload): void { + private _onLogEntryAdded(event: Protocol.Log.entryAddedPayload): void { const { level, text, args, source, url, lineNumber } = event.entry; if (args) args.map((arg) => helper.releaseObject(this._client, arg)); if (source !== 'worker') @@ -859,7 +915,7 @@ export class Page extends EventEmitter { return this._go(+1, options); } - async _go( + private async _go( delta: number, options: WaitForOptions ): Promise { @@ -1072,7 +1128,7 @@ export class Page extends EventEmitter { ); } - async _screenshotTask( + private async _screenshotTask( format: 'png' | 'jpeg', options?: ScreenshotOptions ): Promise {