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): start documenting the Page class (#6001)

Browse Source 
This PR starts exploring the Page class and how to best document it. It explores how best to document events in the system, and I think pulling them out into an `enum` is the best solution here. It lets us end up with a page of docs that explicitly lists all the events the page class can ever emit.
This commit is contained in:
Jack Franklin 2020-06-12 11:10:12 +01:00 committed by GitHub
parent c1d7be379b
commit 23f18d8cc0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
10 changed files with 130 additions and 145 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
new-docs/puppeteer.md
View File

@ -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 |

22
new-docs/puppeteer.page._constructor_.md
View File

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

23
new-docs/puppeteer.page._go.md
View File

@ -1,23 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Page](./puppeteer.page.md) &gt; [\_go](./puppeteer.page._go.md)
## Page.\_go() method
<b>Signature:</b>
```typescript
_go(delta: number, options: WaitForOptions): Promise<HTTPResponse | null>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| delta | number | |
| options | WaitForOptions | |
<b>Returns:</b>
Promise&lt;[HTTPResponse](./puppeteer.httpresponse.md) \| null&gt;

22
new-docs/puppeteer.page._onlogentryadded.md
View File

@ -1,22 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Page](./puppeteer.page.md) &gt; [\_onLogEntryAdded](./puppeteer.page._onlogentryadded.md)
## Page.\_onLogEntryAdded() method
<b>Signature:</b>
```typescript
_onLogEntryAdded(event: Protocol.Log.entryAddedPayload): void;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| event | Protocol.Log.entryAddedPayload | |
<b>Returns:</b>
void

15
new-docs/puppeteer.page._ontargetcrashed.md
View File

@ -1,15 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Page](./puppeteer.page.md) &gt; [\_onTargetCrashed](./puppeteer.page._ontargetcrashed.md)
## Page.\_onTargetCrashed() method
<b>Signature:</b>
```typescript
_onTargetCrashed(): void;
```
<b>Returns:</b>
void

23
new-docs/puppeteer.page._screenshottask.md
View File

@ -1,23 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Page](./puppeteer.page.md) &gt; [\_screenshotTask](./puppeteer.page._screenshottask.md)
## Page.\_screenshotTask() method
<b>Signature:</b>
```typescript
_screenshotTask(format: 'png' | 'jpeg', options?: ScreenshotOptions): Promise<Buffer | string>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| format | 'png' \| 'jpeg' | |
| options | ScreenshotOptions | |
<b>Returns:</b>
Promise&lt;Buffer \| string&gt;

25
new-docs/puppeteer.page.create.md
View File

@ -1,25 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [Page](./puppeteer.page.md) &gt; [create](./puppeteer.page.create.md)
## Page.create() method
<b>Signature:</b>
```typescript
static create(client: CDPSession, target: Target, ignoreHTTPSErrors: boolean, defaultViewport: Viewport | null): Promise<Page>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| client | [CDPSession](./puppeteer.cdpsession.md) | |
| target | [Target](./puppeteer.target.md) | |
| ignoreHTTPSErrors | boolean | |
| defaultViewport | Viewport \| null | |
<b>Returns:</b>
Promise&lt;[Page](./puppeteer.page.md)<!-- -->&gt;

51
new-docs/puppeteer.page.md
View File

@ -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.
<b>Signature:</b>
```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 <code>Page</code> 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) | <code>static</code> | |
| [deleteCookie(cookies)](./puppeteer.page.deletecookie.md) | | |
| [emulate(options)](./puppeteer.page.emulate.md) | | |
| [emulateMediaFeatures(features)](./puppeteer.page.emulatemediafeatures.md) | | |

20
new-docs/puppeteer.pageemittedevents.md Normal file
View File

@ -0,0 +1,20 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PageEmittedEvents](./puppeteer.pageemittedevents.md)
## PageEmittedEvents enum
All the events that a page instance may emit.
<b>Signature:</b>
```typescript
export declare const enum PageEmittedEvents
```
## Enumeration Members
| Member | Value | Description |
| --- | --- | --- |
| WorkerCreated | <code>&quot;workercreated&quot;</code> | Emitted when a dedicated [WebWorker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API) is spawned by the page. |

66
src/Page.ts
View File

@ -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<Buffer | string | void>;
@ -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<Error>;
/**
* @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<HTTPResponse | null> {
@ -1072,7 +1128,7 @@ export class Page extends EventEmitter {
);
}
async _screenshotTask(
private async _screenshotTask(
format: 'png' | 'jpeg',
options?: ScreenshotOptions
): Promise<Buffer | string> {