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): migrate ElementHandle to TSDoc (#6073)

Browse Source 
* docs(new): migrate ElementHandle to TSDoc

Co-authored-by: Alex Rudenko <alexrudenko@chromium.org>
This commit is contained in:
Alex Rudenko 2020-06-22 17:21:57 +02:00 committed by GitHub
parent 7025f1c5ea
commit 6657364364
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
71 changed files with 973 additions and 267 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

13
new-docs/puppeteer.boundingbox.height.md Normal file
View File

@ -0,0 +1,13 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoundingBox](./puppeteer.boundingbox.md) &gt; [height](./puppeteer.boundingbox.height.md)
## BoundingBox.height property
the height of the element in pixels.
<b>Signature:</b>
```typescript
height: number;
```

22
new-docs/puppeteer.boundingbox.md Normal file
View File

@ -0,0 +1,22 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoundingBox](./puppeteer.boundingbox.md)
## BoundingBox interface
<b>Signature:</b>
```typescript
export interface BoundingBox
```
## Properties
| Property | Type | Description |
| --- | --- | --- |
| [height](./puppeteer.boundingbox.height.md) | number | the height of the element in pixels. |
| [width](./puppeteer.boundingbox.width.md) | number | the width of the element in pixels. |
| [x](./puppeteer.boundingbox.x.md) | number | the x coordinate of the element in pixels. |
| [y](./puppeteer.boundingbox.y.md) | number | the y coordinate of the element in pixels. |

13
new-docs/puppeteer.boundingbox.width.md Normal file
View File

@ -0,0 +1,13 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoundingBox](./puppeteer.boundingbox.md) &gt; [width](./puppeteer.boundingbox.width.md)
## BoundingBox.width property
the width of the element in pixels.
<b>Signature:</b>
```typescript
width: number;
```

13
new-docs/puppeteer.boundingbox.x.md Normal file
View File

@ -0,0 +1,13 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoundingBox](./puppeteer.boundingbox.md) &gt; [x](./puppeteer.boundingbox.x.md)
## BoundingBox.x property
the x coordinate of the element in pixels.
<b>Signature:</b>
```typescript
x: number;
```

13
new-docs/puppeteer.boundingbox.y.md Normal file
View File

@ -0,0 +1,13 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoundingBox](./puppeteer.boundingbox.md) &gt; [y](./puppeteer.boundingbox.y.md)
## BoundingBox.y property
the y coordinate of the element in pixels.
<b>Signature:</b>
```typescript
y: number;
```

14
new-docs/puppeteer.boxmodel.border.md Normal file
View File

@ -0,0 +1,14 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoxModel](./puppeteer.boxmodel.md) &gt; [border](./puppeteer.boxmodel.border.md)
## BoxModel.border property
<b>Signature:</b>
```typescript
border: Array<{
x: number;
y: number;
}>;
```

14
new-docs/puppeteer.boxmodel.content.md Normal file
View File

@ -0,0 +1,14 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoxModel](./puppeteer.boxmodel.md) &gt; [content](./puppeteer.boxmodel.content.md)
## BoxModel.content property
<b>Signature:</b>
```typescript
content: Array<{
x: number;
y: number;
}>;
```

11
new-docs/puppeteer.boxmodel.height.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoxModel](./puppeteer.boxmodel.md) &gt; [height](./puppeteer.boxmodel.height.md)
## BoxModel.height property
<b>Signature:</b>
```typescript
height: number;
```

14
new-docs/puppeteer.boxmodel.margin.md Normal file
View File

@ -0,0 +1,14 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoxModel](./puppeteer.boxmodel.md) &gt; [margin](./puppeteer.boxmodel.margin.md)
## BoxModel.margin property
<b>Signature:</b>
```typescript
margin: Array<{
x: number;
y: number;
}>;
```

24
new-docs/puppeteer.boxmodel.md Normal file
View File

@ -0,0 +1,24 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoxModel](./puppeteer.boxmodel.md)
## BoxModel interface
<b>Signature:</b>
```typescript
export interface BoxModel
```
## Properties
| Property | Type | Description |
| --- | --- | --- |
| [border](./puppeteer.boxmodel.border.md) | Array&lt;{ x: number; y: number; }&gt; | |
| [content](./puppeteer.boxmodel.content.md) | Array&lt;{ x: number; y: number; }&gt; | |
| [height](./puppeteer.boxmodel.height.md) | number | |
| [margin](./puppeteer.boxmodel.margin.md) | Array&lt;{ x: number; y: number; }&gt; | |
| [padding](./puppeteer.boxmodel.padding.md) | Array&lt;{ x: number; y: number; }&gt; | |
| [width](./puppeteer.boxmodel.width.md) | number | |

14
new-docs/puppeteer.boxmodel.padding.md Normal file
View File

@ -0,0 +1,14 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoxModel](./puppeteer.boxmodel.md) &gt; [padding](./puppeteer.boxmodel.padding.md)
## BoxModel.padding property
<b>Signature:</b>
```typescript
padding: Array<{
x: number;
y: number;
}>;
```

11
new-docs/puppeteer.boxmodel.width.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [BoxModel](./puppeteer.boxmodel.md) &gt; [width](./puppeteer.boxmodel.width.md)
## BoxModel.width property
<b>Signature:</b>
```typescript
width: number;
```

11
new-docs/puppeteer.clickoptions.button.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ClickOptions](./puppeteer.clickoptions.md) &gt; [button](./puppeteer.clickoptions.button.md)
## ClickOptions.button property
<b>Signature:</b>
```typescript
button?: 'left' | 'right' | 'middle';
```

11
new-docs/puppeteer.clickoptions.clickcount.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ClickOptions](./puppeteer.clickoptions.md) &gt; [clickCount](./puppeteer.clickoptions.clickcount.md)
## ClickOptions.clickCount property
<b>Signature:</b>
```typescript
clickCount?: number;
```

13
new-docs/puppeteer.clickoptions.delay.md Normal file
View File

@ -0,0 +1,13 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ClickOptions](./puppeteer.clickoptions.md) &gt; [delay](./puppeteer.clickoptions.delay.md)
## ClickOptions.delay property
Time to wait between `mousedown` and `mouseup` in milliseconds.
<b>Signature:</b>
```typescript
delay?: number;
```

21
new-docs/puppeteer.clickoptions.md Normal file
View File

@ -0,0 +1,21 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ClickOptions](./puppeteer.clickoptions.md)
## ClickOptions interface
<b>Signature:</b>
```typescript
export interface ClickOptions
```
## Properties
| Property | Type | Description |
| --- | --- | --- |
| [button](./puppeteer.clickoptions.button.md) | 'left' \| 'right' \| 'middle' | |
| [clickCount](./puppeteer.clickoptions.clickcount.md) | number | |
| [delay](./puppeteer.clickoptions.delay.md) | number | Time to wait between <code>mousedown</code> and <code>mouseup</code> in milliseconds. |

23
new-docs/puppeteer.createjshandle.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; [createJSHandle](./puppeteer.createjshandle.md)
## createJSHandle() function
<b>Signature:</b>
```typescript
export declare function createJSHandle(context: ExecutionContext, remoteObject: Protocol.Runtime.RemoteObject): JSHandle;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| context | [ExecutionContext](./puppeteer.executioncontext.md) | |
| remoteObject | Protocol.Runtime.RemoteObject | |
<b>Returns:</b>
[JSHandle](./puppeteer.jshandle.md)

2
new-docs/puppeteer.elementhandle._.md
View File

@ -4,6 +4,8 @@
## ElementHandle.$() method
The method runs `element.querySelector` within the page. If no element matches the selector, the return value resolves to `null`<!-- -->.
<b>Signature:</b>
```typescript

2
new-docs/puppeteer.elementhandle.__.md
View File

@ -4,6 +4,8 @@
## ElementHandle.$$() method
The method runs `element.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`<!-- -->.
<b>Signature:</b>
```typescript

25
new-docs/puppeteer.elementhandle.__eval.md
View File

@ -4,6 +4,10 @@
## ElementHandle.$$eval() method
This method runs `document.querySelectorAll` within the element and passes it as the first argument to `pageFunction`<!-- -->. If there's no element matching `selector`<!-- -->, the method throws an error.
If `pageFunction` returns a Promise, then `frame.$$eval` would wait for the promise to resolve and return its value.
<b>Signature:</b>
```typescript
@ -22,3 +26,24 @@ $$eval<ReturnType extends any>(selector: string, pageFunction: Function | string
Promise&lt;ReturnType&gt;
## Example 1
```html
<div class="feed">
<div class="tweet">Hello!</div>
<div class="tweet">Hi!</div>
</div>
```
## Example 2
```js
const feedHandle = await page.$('.feed');
expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText)))
.toEqual(['Hello!', 'Hi!']);
```

18
new-docs/puppeteer.elementhandle._clickablepoint.md
View File

@ -1,18 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ElementHandle](./puppeteer.elementhandle.md) &gt; [\_clickablePoint](./puppeteer.elementhandle._clickablepoint.md)
## ElementHandle.\_clickablePoint() method
<b>Signature:</b>
```typescript
_clickablePoint(): Promise<{
x: number;
y: number;
}>;
```
<b>Returns:</b>
Promise&lt;{ x: number; y: number; }&gt;

24
new-docs/puppeteer.elementhandle._constructor_.md
View File

@ -1,24 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ElementHandle](./puppeteer.elementhandle.md) &gt; [(constructor)](./puppeteer.elementhandle._constructor_.md)
## ElementHandle.(constructor)
Constructs a new instance of the `ElementHandle` class
<b>Signature:</b>
```typescript
constructor(context: ExecutionContext, client: CDPSession, remoteObject: Protocol.Runtime.RemoteObject, page: Page, frameManager: FrameManager);
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| context | [ExecutionContext](./puppeteer.executioncontext.md) | |
| client | [CDPSession](./puppeteer.cdpsession.md) | |
| remoteObject | Protocol.Runtime.RemoteObject | |
| page | [Page](./puppeteer.page.md) | |
| frameManager | [FrameManager](./puppeteer.framemanager.md) | |

14
new-docs/puppeteer.elementhandle._eval.md
View File

@ -4,6 +4,10 @@
## ElementHandle.$eval() method
This method runs `document.querySelector` within the element and passes it as the first argument to `pageFunction`<!-- -->. If there's no element matching `selector`<!-- -->, the method throws an error.
If `pageFunction` returns a Promise, then `frame.$eval` would wait for the promise to resolve and return its value.
<b>Signature:</b>
```typescript
@ -22,3 +26,13 @@ $eval<ReturnType extends any>(selector: string, pageFunction: Function | string,
Promise&lt;ReturnType&gt;
## Example
```js
const tweetHandle = await page.$('.tweet');
expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
```

11
new-docs/puppeteer.elementhandle._framemanager.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ElementHandle](./puppeteer.elementhandle.md) &gt; [\_frameManager](./puppeteer.elementhandle._framemanager.md)
## ElementHandle.\_frameManager property
<b>Signature:</b>
```typescript
_frameManager: FrameManager;
```

25
new-docs/puppeteer.elementhandle._fromprotocolquad.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; [ElementHandle](./puppeteer.elementhandle.md) &gt; [\_fromProtocolQuad](./puppeteer.elementhandle._fromprotocolquad.md)
## ElementHandle.\_fromProtocolQuad() method
<b>Signature:</b>
```typescript
_fromProtocolQuad(quad: number[]): Array<{
x: number;
y: number;
}>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| quad | number\[\] | |
<b>Returns:</b>
Array&lt;{ x: number; y: number; }&gt;

15
new-docs/puppeteer.elementhandle._getboxmodel.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; [ElementHandle](./puppeteer.elementhandle.md) &gt; [\_getBoxModel](./puppeteer.elementhandle._getboxmodel.md)
## ElementHandle.\_getBoxModel() method
<b>Signature:</b>
```typescript
_getBoxModel(): Promise<void | Protocol.DOM.getBoxModelReturnValue>;
```
<b>Returns:</b>
Promise&lt;void \| Protocol.DOM.getBoxModelReturnValue&gt;

30
new-docs/puppeteer.elementhandle._intersectquadwithviewport.md
View File

@ -1,30 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ElementHandle](./puppeteer.elementhandle.md) &gt; [\_intersectQuadWithViewport](./puppeteer.elementhandle._intersectquadwithviewport.md)
## ElementHandle.\_intersectQuadWithViewport() method
<b>Signature:</b>
```typescript
_intersectQuadWithViewport(quad: Array<{
x: number;
y: number;
}>, width: number, height: number): Array<{
x: number;
y: number;
}>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| quad | Array&lt;{ x: number; y: number; }&gt; | |
| width | number | |
| height | number | |
<b>Returns:</b>
Array&lt;{ x: number; y: number; }&gt;

11
new-docs/puppeteer.elementhandle._page.md
View File

@ -1,11 +0,0 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [ElementHandle](./puppeteer.elementhandle.md) &gt; [\_page](./puppeteer.elementhandle._page.md)
## ElementHandle.\_page property
<b>Signature:</b>
```typescript
_page: Page;
```

15
new-docs/puppeteer.elementhandle._scrollintoviewifneeded.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; [ElementHandle](./puppeteer.elementhandle.md) &gt; [\_scrollIntoViewIfNeeded](./puppeteer.elementhandle._scrollintoviewifneeded.md)
## ElementHandle.\_scrollIntoViewIfNeeded() method
<b>Signature:</b>
```typescript
_scrollIntoViewIfNeeded(): Promise<void>;
```
<b>Returns:</b>
Promise&lt;void&gt;

4
new-docs/puppeteer.elementhandle._x.md
View File

@ -4,6 +4,8 @@
## ElementHandle.$x() method
The method evaluates the XPath expression relative to the elementHandle. If there are no such elements, the method will resolve to an empty array.
<b>Signature:</b>
```typescript
@ -14,7 +16,7 @@ $x(expression: string): Promise<ElementHandle[]>;
| Parameter | Type | Description |
| --- | --- | --- |
| expression | string | |
| expression | string | Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate) |
<b>Returns:</b>

11
new-docs/puppeteer.elementhandle.boundingbox.md
View File

@ -4,17 +4,14 @@
## ElementHandle.boundingBox() method
This method returns the bounding box of the element (relative to the main frame), or `null` if the element is not visible.
<b>Signature:</b>
```typescript
boundingBox(): Promise<{
x: number;
y: number;
width: number;
height: number;
}>;
boundingBox(): Promise<BoundingBox | null>;
```
<b>Returns:</b>
Promise&lt;{ x: number; y: number; width: number; height: number; }&gt;
Promise&lt;[BoundingBox](./puppeteer.boundingbox.md) \| null&gt;

8
new-docs/puppeteer.elementhandle.boxmodel.md
View File

@ -4,6 +4,8 @@
## ElementHandle.boxModel() method
This method returns boxes of the element, or `null` if the element is not visible.
<b>Signature:</b>
```typescript
@ -11,7 +13,9 @@ boxModel(): Promise<BoxModel | null>;
```
<b>Returns:</b>
Promise&lt;BoxModel \| null&gt;
Promise&lt;[BoxModel](./puppeteer.boxmodel.md) \| null&gt;
{<!-- -->!Promise<!-- -->&lt;<!-- -->?BoxModel<!-- -->&gt;<!-- -->}
## Remarks
Boxes are represented as an array of points; Each Point is an object `{x, y}`<!-- -->. Box points are sorted clock-wise.

10
new-docs/puppeteer.elementhandle.click.md
View File

@ -4,21 +4,19 @@
## ElementHandle.click() method
This method scrolls element into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to click in the center of the element. If the element is detached from DOM, the method throws an error.
<b>Signature:</b>
```typescript
click(options: {
delay?: number;
button?: 'left' | 'right' | 'middle';
clickCount?: number;
}): Promise<void>;
click(options: ClickOptions): Promise<void>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| options | { delay?: number; button?: 'left' \| 'right' \| 'middle'; clickCount?: number; } | |
| options | [ClickOptions](./puppeteer.clickoptions.md) | |
<b>Returns:</b>

2
new-docs/puppeteer.elementhandle.contentframe.md
View File

@ -4,6 +4,8 @@
## ElementHandle.contentFrame() method
Resolves to the content frame for element handles referencing iframe nodes, or null otherwise
<b>Signature:</b>
```typescript

2
new-docs/puppeteer.elementhandle.focus.md
View File

@ -4,6 +4,8 @@
## ElementHandle.focus() method
Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element.
<b>Signature:</b>
```typescript

2
new-docs/puppeteer.elementhandle.hover.md
View File

@ -4,6 +4,8 @@
## ElementHandle.hover() method
This method scrolls element into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to hover over the center of the element. If the element is detached from DOM, the method throws an error.
<b>Signature:</b>
```typescript

2
new-docs/puppeteer.elementhandle.isintersectingviewport.md
View File

@ -4,6 +4,8 @@
## ElementHandle.isIntersectingViewport() method
Resolves to true if the element is visible in the current viewport.
<b>Signature:</b>
```typescript

71
new-docs/puppeteer.elementhandle.md
View File

@ -4,6 +4,8 @@
## ElementHandle class
ElementHandle represents an in-page DOM element.
<b>Signature:</b>
```typescript
@ -11,45 +13,50 @@ export declare class ElementHandle extends JSHandle
```
<b>Extends:</b> [JSHandle](./puppeteer.jshandle.md)
## Constructors
## Remarks
| Constructor | Modifiers | Description |
| --- | --- | --- |
| [(constructor)(context, client, remoteObject, page, frameManager)](./puppeteer.elementhandle._constructor_.md) | | Constructs a new instance of the <code>ElementHandle</code> class |
ElementHandles can be created with the [Page.$()](./puppeteer.page._.md) method.
## Properties
```js
const puppeteer = require('puppeteer');
| Property | Modifiers | Type | Description |
| --- | --- | --- | --- |
| [\_frameManager](./puppeteer.elementhandle._framemanager.md) | | [FrameManager](./puppeteer.framemanager.md) | |
| [\_page](./puppeteer.elementhandle._page.md) | | [Page](./puppeteer.page.md) | |
(async () => {
const browser = await puppeteer.launch();
const page = await browser.newPage();
await page.goto('https://example.com');
const hrefElement = await page.$('a');
await hrefElement.click();
// ...
})();
```
ElementHandle prevents DOM element from garbage collection unless the handle is [disposed](./puppeteer.jshandle.dispose.md)<!-- -->. ElementHandles are auto-disposed when their origin frame gets navigated.
ElementHandle instances can be used as arguments in [Page.$eval()](./puppeteer.page._eval.md) and [Page.evaluate()](./puppeteer.page.evaluate.md) methods.
The constructor for this class is marked as internal. Third-party code should not call the constructor directly or create subclasses that extend the `ElementHandle` class.
## Methods
| Method | Modifiers | Description |
| --- | --- | --- |
| [\_clickablePoint()](./puppeteer.elementhandle._clickablepoint.md) | | |
| [\_fromProtocolQuad(quad)](./puppeteer.elementhandle._fromprotocolquad.md) | | |
| [\_getBoxModel()](./puppeteer.elementhandle._getboxmodel.md) | | |
| [\_intersectQuadWithViewport(quad, width, height)](./puppeteer.elementhandle._intersectquadwithviewport.md) | | |
| [\_scrollIntoViewIfNeeded()](./puppeteer.elementhandle._scrollintoviewifneeded.md) | | |
| [$(selector)](./puppeteer.elementhandle._.md) | | |
| [$$(selector)](./puppeteer.elementhandle.__.md) | | |
| [$$eval(selector, pageFunction, args)](./puppeteer.elementhandle.__eval.md) | | |
| [$eval(selector, pageFunction, args)](./puppeteer.elementhandle._eval.md) | | |
| [$x(expression)](./puppeteer.elementhandle._x.md) | | |
| [$(selector)](./puppeteer.elementhandle._.md) | | The method runs <code>element.querySelector</code> within the page. If no element matches the selector, the return value resolves to <code>null</code>. |
| [$$(selector)](./puppeteer.elementhandle.__.md) | | The method runs <code>element.querySelectorAll</code> within the page. If no elements match the selector, the return value resolves to <code>[]</code>. |
| [$$eval(selector, pageFunction, args)](./puppeteer.elementhandle.__eval.md) | | This method runs <code>document.querySelectorAll</code> within the element and passes it as the first argument to <code>pageFunction</code>. If there's no element matching <code>selector</code>, the method throws an error.<!-- -->If <code>pageFunction</code> returns a Promise, then <code>frame.$$eval</code> would wait for the promise to resolve and return its value. |
| [$eval(selector, pageFunction, args)](./puppeteer.elementhandle._eval.md) | | This method runs <code>document.querySelector</code> within the element and passes it as the first argument to <code>pageFunction</code>. If there's no element matching <code>selector</code>, the method throws an error.<!-- -->If <code>pageFunction</code> returns a Promise, then <code>frame.$eval</code> would wait for the promise to resolve and return its value. |
| [$x(expression)](./puppeteer.elementhandle._x.md) | | The method evaluates the XPath expression relative to the elementHandle. If there are no such elements, the method will resolve to an empty array. |
| [asElement()](./puppeteer.elementhandle.aselement.md) | | |
| [boundingBox()](./puppeteer.elementhandle.boundingbox.md) | | |
| [boxModel()](./puppeteer.elementhandle.boxmodel.md) | | |
| [click(options)](./puppeteer.elementhandle.click.md) | | |
| [contentFrame()](./puppeteer.elementhandle.contentframe.md) | | |
| [focus()](./puppeteer.elementhandle.focus.md) | | |
| [hover()](./puppeteer.elementhandle.hover.md) | | |
| [isIntersectingViewport()](./puppeteer.elementhandle.isintersectingviewport.md) | | |
| [press(key, options)](./puppeteer.elementhandle.press.md) | | |
| [screenshot(options)](./puppeteer.elementhandle.screenshot.md) | | |
| [select(values)](./puppeteer.elementhandle.select.md) | | |
| [tap()](./puppeteer.elementhandle.tap.md) | | |
| [type(text, options)](./puppeteer.elementhandle.type.md) | | |
| [uploadFile(filePaths)](./puppeteer.elementhandle.uploadfile.md) | | |
| [boundingBox()](./puppeteer.elementhandle.boundingbox.md) | | This method returns the bounding box of the element (relative to the main frame), or <code>null</code> if the element is not visible. |
| [boxModel()](./puppeteer.elementhandle.boxmodel.md) | | This method returns boxes of the element, or <code>null</code> if the element is not visible. |
| [click(options)](./puppeteer.elementhandle.click.md) | | This method scrolls element into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to click in the center of the element. If the element is detached from DOM, the method throws an error. |
| [contentFrame()](./puppeteer.elementhandle.contentframe.md) | | Resolves to the content frame for element handles referencing iframe nodes, or null otherwise |
| [focus()](./puppeteer.elementhandle.focus.md) | | Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element. |
| [hover()](./puppeteer.elementhandle.hover.md) | | This method scrolls element into view if needed, and then uses [Page.mouse](./puppeteer.page.mouse.md) to hover over the center of the element. If the element is detached from DOM, the method throws an error. |
| [isIntersectingViewport()](./puppeteer.elementhandle.isintersectingviewport.md) | | Resolves to true if the element is visible in the current viewport. |
| [press(key, options)](./puppeteer.elementhandle.press.md) | | Focuses the element, and then uses [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->. |
| [screenshot(options)](./puppeteer.elementhandle.screenshot.md) | | This method scrolls element into view if needed, and then uses [Page.screenshot()](./puppeteer.page.screenshot.md) to take a screenshot of the element. If the element is detached from DOM, the method throws an error. |
| [select(values)](./puppeteer.elementhandle.select.md) | | Triggers a <code>change</code> and <code>input</code> event once all the provided options have been selected. If there's no <code>&lt;select&gt;</code> element matching <code>selector</code>, the method throws an error. |
| [tap()](./puppeteer.elementhandle.tap.md) | | This method scrolls element into view if needed, and then uses [Touchscreen.tap()](./puppeteer.touchscreen.tap.md) to tap in the center of the element. If the element is detached from DOM, the method throws an error. |
| [type(text, options)](./puppeteer.elementhandle.type.md) | | Focuses the element, and then sends a <code>keydown</code>, <code>keypress</code>/<code>input</code>, and <code>keyup</code> event for each character in the text.<!-- -->To press a special key, like <code>Control</code> or <code>ArrowDown</code>, use [ElementHandle.press()](./puppeteer.elementhandle.press.md)<!-- -->. |
| [uploadFile(filePaths)](./puppeteer.elementhandle.uploadfile.md) | | This method expects <code>elementHandle</code> to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)<!-- -->. |

17
new-docs/puppeteer.elementhandle.press.md
View File

@ -4,23 +4,28 @@
## ElementHandle.press() method
Focuses the element, and then uses [Keyboard.down()](./puppeteer.keyboard.down.md) and [Keyboard.up()](./puppeteer.keyboard.up.md)<!-- -->.
<b>Signature:</b>
```typescript
press(key: KeyInput, options?: {
delay?: number;
text?: string;
}): Promise<void>;
press(key: KeyInput, options?: PressOptions): Promise<void>;
```
## Parameters
| Parameter | Type | Description |
| --- | --- | --- |
| key | KeyInput | |
| options | { delay?: number; text?: string; } | |
| key | [KeyInput](./puppeteer.keyinput.md) | Name of key to press, such as <code>ArrowLeft</code>. See [KeyInput](./puppeteer.keyinput.md) for a list of all key names. |
| options | [PressOptions](./puppeteer.pressoptions.md) | |
<b>Returns:</b>
Promise&lt;void&gt;
## Remarks
If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`<!-- -->/`input` event will also be generated. The `text` option can be specified to force an input event to be generated.
\*\*NOTE\*\* Modifier keys DO affect `elementHandle.press`<!-- -->. Holding down `Shift` will type the text in upper case.

2
new-docs/puppeteer.elementhandle.screenshot.md
View File

@ -4,6 +4,8 @@
## ElementHandle.screenshot() method
This method scrolls element into view if needed, and then uses [Page.screenshot()](./puppeteer.page.screenshot.md) to take a screenshot of the element. If the element is detached from DOM, the method throws an error.
<b>Signature:</b>
```typescript

13
new-docs/puppeteer.elementhandle.select.md
View File

@ -4,6 +4,8 @@
## ElementHandle.select() method
Triggers a `change` and `input` event once all the provided options have been selected. If there's no `<select>` element matching `selector`<!-- -->, the method throws an error.
<b>Signature:</b>
```typescript
@ -14,9 +16,18 @@ select(...values: string[]): Promise<string[]>;
| Parameter | Type | Description |
| --- | --- | --- |
| values | string\[\] | |
| values | string\[\] | Values of options to select. If the <code>&lt;select&gt;</code> has the <code>multiple</code> attribute, all values are considered, otherwise only the first one is taken into account. |
<b>Returns:</b>
Promise&lt;string\[\]&gt;
## Example
```js
handle.select('blue'); // single selection
handle.select('red', 'green', 'blue'); // multiple selections
```

2
new-docs/puppeteer.elementhandle.tap.md
View File

@ -4,6 +4,8 @@
## ElementHandle.tap() method
This method scrolls element into view if needed, and then uses [Touchscreen.tap()](./puppeteer.touchscreen.tap.md) to tap in the center of the element. If the element is detached from DOM, the method throws an error.
<b>Signature:</b>
```typescript

24
new-docs/puppeteer.elementhandle.type.md
View File

@ -4,6 +4,10 @@
## ElementHandle.type() method
Focuses the element, and then sends a `keydown`<!-- -->, `keypress`<!-- -->/`input`<!-- -->, and `keyup` event for each character in the text.
To press a special key, like `Control` or `ArrowDown`<!-- -->, use [ElementHandle.press()](./puppeteer.elementhandle.press.md)<!-- -->.
<b>Signature:</b>
```typescript
@ -23,3 +27,23 @@ type(text: string, options?: {
Promise&lt;void&gt;
## Example 1
```js
await elementHandle.type('Hello'); // Types instantly
await elementHandle.type('World', {delay: 100}); // Types slower, like a user
```
## Example 2
An example of typing into a text field and then submitting the form:
```js
const elementHandle = await page.$('input');
await elementHandle.type('some text');
await elementHandle.press('Enter');
```

4
new-docs/puppeteer.elementhandle.uploadfile.md
View File

@ -4,6 +4,8 @@
## ElementHandle.uploadFile() method
This method expects `elementHandle` to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)<!-- -->.
<b>Signature:</b>
```typescript
@ -14,7 +16,7 @@ uploadFile(...filePaths: string[]): Promise<void>;
| Parameter | Type | Description |
| --- | --- | --- |
| filePaths | string\[\] | |
| filePaths | string\[\] | Sets the value of the file input to these paths. If some of the <code>filePaths</code> are relative paths, then they are resolved relative to the [current working directory](https://nodejs.org/api/process.html#process_process_cwd) |
<b>Returns:</b>

2
new-docs/puppeteer.jshandle.dispose.md
View File

@ -4,6 +4,8 @@
## JSHandle.dispose() method
The method stops referencing the element handle.
<b>Signature:</b>
```typescript

11
new-docs/puppeteer.jshandle.evaluate.md
View File

@ -4,6 +4,8 @@
## JSHandle.evaluate() method
This method passes this handle as the first argument to `pageFunction`<!-- -->. If `pageFunction` returns a Promise, then `handle.evaluate` would wait for the promise to resolve and return its value.
<b>Signature:</b>
```typescript
@ -21,3 +23,12 @@ evaluate<ReturnType extends any>(pageFunction: Function | string, ...args: unkno
Promise&lt;ReturnType&gt;
## Example
```js
const tweetHandle = await page.$('.tweet .retweets');
expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10');
```

10
new-docs/puppeteer.jshandle.evaluatehandle.md
View File

@ -4,6 +4,8 @@
## JSHandle.evaluateHandle() method
This method passes this handle as the first argument to `pageFunction`<!-- -->.
<b>Signature:</b>
```typescript
@ -21,3 +23,11 @@ evaluateHandle(pageFunction: Function | string, ...args: unknown[]): Promise<JSH
Promise&lt;[JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;
## Remarks
The only difference between `evaluateHandle.evaluate` and `evaluateHandle.evaluateHandle` is that `executionContext.evaluateHandle` returns in-page object (JSHandle).
If the function passed to the `evaluateHandle.evaluateHandle` returns a Promise, then `evaluateHandle.evaluateHandle` would wait for the promise to resolve and return its value.
See [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md) for more details.

18
new-docs/puppeteer.jshandle.getproperties.md
View File

@ -4,6 +4,8 @@
## JSHandle.getProperties() method
The method returns a map with property names as keys and JSHandle instances for the property values.
<b>Signature:</b>
```typescript
@ -13,3 +15,19 @@ getProperties(): Promise<Map<string, JSHandle>>;
Promise&lt;Map&lt;string, [JSHandle](./puppeteer.jshandle.md)<!-- -->&gt;&gt;
## Example
```js
const listHandle = await page.evaluateHandle(() => document.body.children);
const properties = await listHandle.getProperties();
const children = [];
for (const property of properties.values()) {
const element = property.asElement();
if (element)
children.push(element);
}
children; // holds elementHandles to all children of document.body
```

6
new-docs/puppeteer.jshandle.jsonvalue.md
View File

@ -4,6 +4,8 @@
## JSHandle.jsonValue() method
Returns a JSON representation of the object.
<b>Signature:</b>
```typescript
@ -13,3 +15,7 @@ jsonValue(): Promise<{}>;
Promise&lt;{}&gt;
## Remarks
The JSON is generated by running [JSON.stringify](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify) on the object in page and consequent [JSON.parse](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse) in puppeteer. \*\*NOTE\*\* The method will throw if the referenced object is not stringifiable.

11
new-docs/puppeteer.jshandle.md
View File

@ -4,6 +4,7 @@
## JSHandle class
<b>Signature:</b>
```typescript
@ -30,12 +31,12 @@ export declare class JSHandle
| Method | Modifiers | Description |
| --- | --- | --- |
| [asElement()](./puppeteer.jshandle.aselement.md) | | |
| [dispose()](./puppeteer.jshandle.dispose.md) | | |
| [evaluate(pageFunction, args)](./puppeteer.jshandle.evaluate.md) | | |
| [evaluateHandle(pageFunction, args)](./puppeteer.jshandle.evaluatehandle.md) | | |
| [dispose()](./puppeteer.jshandle.dispose.md) | | The method stops referencing the element handle. |
| [evaluate(pageFunction, args)](./puppeteer.jshandle.evaluate.md) | | This method passes this handle as the first argument to <code>pageFunction</code>. If <code>pageFunction</code> returns a Promise, then <code>handle.evaluate</code> would wait for the promise to resolve and return its value. |
| [evaluateHandle(pageFunction, args)](./puppeteer.jshandle.evaluatehandle.md) | | This method passes this handle as the first argument to <code>pageFunction</code>. |
| [executionContext()](./puppeteer.jshandle.executioncontext.md) | | |
| [getProperties()](./puppeteer.jshandle.getproperties.md) | | |
| [getProperties()](./puppeteer.jshandle.getproperties.md) | | The method returns a map with property names as keys and JSHandle instances for the property values. |
| [getProperty(propertyName)](./puppeteer.jshandle.getproperty.md) | | |
| [jsonValue()](./puppeteer.jshandle.jsonvalue.md) | | |
| [jsonValue()](./puppeteer.jshandle.jsonvalue.md) | | Returns a JSON representation of the object. |
| [toString()](./puppeteer.jshandle.tostring.md) | | |

2
new-docs/puppeteer.keyboard.down.md
View File

@ -16,7 +16,7 @@ down(key: KeyInput, options?: {
| Parameter | Type | Description |
| --- | --- | --- |
| key | KeyInput | |
| key | [KeyInput](./puppeteer.keyinput.md) | |
| options | { text?: string; } | |
<b>Returns:</b>

2
new-docs/puppeteer.keyboard.press.md
View File

@ -17,7 +17,7 @@ press(key: KeyInput, options?: {
| Parameter | Type | Description |
| --- | --- | --- |
| key | KeyInput | |
| key | [KeyInput](./puppeteer.keyinput.md) | |
| options | { delay?: number; text?: string; } | |
<b>Returns:</b>

2
new-docs/puppeteer.keyboard.up.md
View File

@ -14,7 +14,7 @@ up(key: KeyInput): Promise<void>;
| Parameter | Type | Description |
| --- | --- | --- |
| key | KeyInput | |
| key | [KeyInput](./puppeteer.keyinput.md) | |
<b>Returns:</b>

11
new-docs/puppeteer.keydefinition.code.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [KeyDefinition](./puppeteer.keydefinition.md) &gt; [code](./puppeteer.keydefinition.code.md)
## KeyDefinition.code property
<b>Signature:</b>
```typescript
code?: string;
```

11
new-docs/puppeteer.keydefinition.key.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [KeyDefinition](./puppeteer.keydefinition.md) &gt; [key](./puppeteer.keydefinition.key.md)
## KeyDefinition.key property
<b>Signature:</b>
```typescript
key?: string;
```

11
new-docs/puppeteer.keydefinition.keycode.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [KeyDefinition](./puppeteer.keydefinition.md) &gt; [keyCode](./puppeteer.keydefinition.keycode.md)
## KeyDefinition.keyCode property
<b>Signature:</b>
```typescript
keyCode?: number;
```

11
new-docs/puppeteer.keydefinition.location.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [KeyDefinition](./puppeteer.keydefinition.md) &gt; [location](./puppeteer.keydefinition.location.md)
## KeyDefinition.location property
<b>Signature:</b>
```typescript
location?: number;
```

33
new-docs/puppeteer.keydefinition.md Normal file
View File

@ -0,0 +1,33 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [KeyDefinition](./puppeteer.keydefinition.md)
## KeyDefinition interface
Copyright 2017 Google Inc. All rights reserved.
Licensed under the Apache License, Version 2.0 (the 'License'); you may not use this file except in compliance with the License. You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.
<b>Signature:</b>
```typescript
export interface KeyDefinition
```
## Properties
| Property | Type | Description |
| --- | --- | --- |
| [code](./puppeteer.keydefinition.code.md) | string | |
| [key](./puppeteer.keydefinition.key.md) | string | |
| [keyCode](./puppeteer.keydefinition.keycode.md) | number | |
| [location](./puppeteer.keydefinition.location.md) | number | |
| [shiftKey](./puppeteer.keydefinition.shiftkey.md) | string | |
| [shiftKeyCode](./puppeteer.keydefinition.shiftkeycode.md) | number | |
| [shiftText](./puppeteer.keydefinition.shifttext.md) | string | |
| [text](./puppeteer.keydefinition.text.md) | string | |

11
new-docs/puppeteer.keydefinition.shiftkey.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [KeyDefinition](./puppeteer.keydefinition.md) &gt; [shiftKey](./puppeteer.keydefinition.shiftkey.md)
## KeyDefinition.shiftKey property
<b>Signature:</b>
```typescript
shiftKey?: string;
```

11
new-docs/puppeteer.keydefinition.shiftkeycode.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [KeyDefinition](./puppeteer.keydefinition.md) &gt; [shiftKeyCode](./puppeteer.keydefinition.shiftkeycode.md)
## KeyDefinition.shiftKeyCode property
<b>Signature:</b>
```typescript
shiftKeyCode?: number;
```

11
new-docs/puppeteer.keydefinition.shifttext.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [KeyDefinition](./puppeteer.keydefinition.md) &gt; [shiftText](./puppeteer.keydefinition.shifttext.md)
## KeyDefinition.shiftText property
<b>Signature:</b>
```typescript
shiftText?: string;
```

11
new-docs/puppeteer.keydefinition.text.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [KeyDefinition](./puppeteer.keydefinition.md) &gt; [text](./puppeteer.keydefinition.text.md)
## KeyDefinition.text property
<b>Signature:</b>
```typescript
text?: string;
```

11
new-docs/puppeteer.keydefinitions.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [keyDefinitions](./puppeteer.keydefinitions.md)
## keyDefinitions variable
<b>Signature:</b>
```typescript
keyDefinitions: Readonly<Record<KeyInput, KeyDefinition>>
```

11
new-docs/puppeteer.keyinput.md Normal file
View File

@ -0,0 +1,11 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [KeyInput](./puppeteer.keyinput.md)
## KeyInput type
<b>Signature:</b>
```typescript
export declare type KeyInput = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' | 'Power' | 'Eject' | 'Abort' | 'Help' | 'Backspace' | 'Tab' | 'Numpad5' | 'NumpadEnter' | 'Enter' | '\r' | '\n' | 'ShiftLeft' | 'ShiftRight' | 'ControlLeft' | 'ControlRight' | 'AltLeft' | 'AltRight' | 'Pause' | 'CapsLock' | 'Escape' | 'Convert' | 'NonConvert' | 'Space' | 'Numpad9' | 'PageUp' | 'Numpad3' | 'PageDown' | 'End' | 'Numpad1' | 'Home' | 'Numpad7' | 'ArrowLeft' | 'Numpad4' | 'Numpad8' | 'ArrowUp' | 'ArrowRight' | 'Numpad6' | 'Numpad2' | 'ArrowDown' | 'Select' | 'Open' | 'PrintScreen' | 'Insert' | 'Numpad0' | 'Delete' | 'NumpadDecimal' | 'Digit0' | 'Digit1' | 'Digit2' | 'Digit3' | 'Digit4' | 'Digit5' | 'Digit6' | 'Digit7' | 'Digit8' | 'Digit9' | 'KeyA' | 'KeyB' | 'KeyC' | 'KeyD' | 'KeyE' | 'KeyF' | 'KeyG' | 'KeyH' | 'KeyI' | 'KeyJ' | 'KeyK' | 'KeyL' | 'KeyM' | 'KeyN' | 'KeyO' | 'KeyP' | 'KeyQ' | 'KeyR' | 'KeyS' | 'KeyT' | 'KeyU' | 'KeyV' | 'KeyW' | 'KeyX' | 'KeyY' | 'KeyZ' | 'MetaLeft' | 'MetaRight' | 'ContextMenu' | 'NumpadMultiply' | 'NumpadAdd' | 'NumpadSubtract' | 'NumpadDivide' | 'F1' | 'F2' | 'F3' | 'F4' | 'F5' | 'F6' | 'F7' | 'F8' | 'F9' | 'F10' | 'F11' | 'F12' | 'F13' | 'F14' | 'F15' | 'F16' | 'F17' | 'F18' | 'F19' | 'F20' | 'F21' | 'F22' | 'F23' | 'F24' | 'NumLock' | 'ScrollLock' | 'AudioVolumeMute' | 'AudioVolumeDown' | 'AudioVolumeUp' | 'MediaTrackNext' | 'MediaTrackPrevious' | 'MediaStop' | 'MediaPlayPause' | 'Semicolon' | 'Equal' | 'NumpadEqual' | 'Comma' | 'Minus' | 'Period' | 'Slash' | 'Backquote' | 'BracketLeft' | 'Backslash' | 'BracketRight' | 'Quote' | 'AltGraph' | 'Props' | 'Cancel' | 'Clear' | 'Shift' | 'Control' | 'Alt' | 'Accept' | 'ModeChange' | ' ' | 'Print' | 'Execute' | '\u0000' | 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z' | 'Meta' | '*' | '+' | '-' | '/' | ';' | '=' | ',' | '.' | '`' | '[' | '\\' | ']' | "'" | 'Attn' | 'CrSel' | 'ExSel' | 'EraseEof' | 'Play' | 'ZoomOut' | ')' | '!' | '@' | '#' | '$' | '%' | '^' | '&' | '(' | 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z' | ':' | '<' | '_' | '>' | '?' | '~' | '{' | '|' | '}' | '"' | 'SoftLeft' | 'SoftRight' | 'Camera' | 'Call' | 'EndCall' | 'VolumeDown' | 'VolumeUp';
```

15
new-docs/puppeteer.md
View File

@ -17,7 +17,7 @@
| [ConsoleMessage](./puppeteer.consolemessage.md) | ConsoleMessage objects are dispatched by page via the 'console' event. |
| [Coverage](./puppeteer.coverage.md) | |
| [Dialog](./puppeteer.dialog.md) | Dialog instances are dispatched by the [Page](./puppeteer.page.md) via the <code>dialog</code> event. |
| [ElementHandle](./puppeteer.elementhandle.md) | |
| [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) | |
@ -43,18 +43,17 @@
| --- | --- |
| [PageEmittedEvents](./puppeteer.pageemittedevents.md) | All the events that a page instance may emit. |
## Functions
| Function | Description |
| --- | --- |
| [createJSHandle(context, remoteObject)](./puppeteer.createjshandle.md) | |
## Interfaces
| Interface | Description |
| --- | --- |
| [BoundingBox](./puppeteer.boundingbox.md) | |
| [BoxModel](./puppeteer.boxmodel.md) | |
| [BrowserFetcherOptions](./puppeteer.browserfetcheroptions.md) | |
| [ClickOptions](./puppeteer.clickoptions.md) | |
| [ConsoleMessageLocation](./puppeteer.consolemessagelocation.md) | |
| [KeyDefinition](./puppeteer.keydefinition.md) | Copyright 2017 Google Inc. All rights reserved.<!-- -->Licensed under the Apache License, Version 2.0 (the 'License'); you may not use this file except in compliance with the License. You may obtain a copy of the License at<!-- -->http://www.apache.org/licenses/LICENSE-2.0<!-- -->Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an 'AS IS' BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. |
| [PressOptions](./puppeteer.pressoptions.md) | |
| [SerializedAXNode](./puppeteer.serializedaxnode.md) | Represents a Node and the properties of it that are relevant to Accessibility. |
| [SnapshotOptions](./puppeteer.snapshotoptions.md) | |
@ -63,6 +62,7 @@
| Variable | Description |
| --- | --- |
| [EVALUATION\_SCRIPT\_URL](./puppeteer.evaluation_script_url.md) | |
| [keyDefinitions](./puppeteer.keydefinitions.md) | |
| [puppeteerErrors](./puppeteer.puppeteererrors.md) | |
## Type Aliases
@ -70,6 +70,7 @@
| Type Alias | Description |
| --- | --- |
| [ConsoleMessageType](./puppeteer.consolemessagetype.md) | The supported types for console messages. |
| [KeyInput](./puppeteer.keyinput.md) | |
| [MouseButtonInput](./puppeteer.mousebuttoninput.md) | |
| [PuppeteerErrors](./puppeteer.puppeteererrors.md) | |

13
new-docs/puppeteer.pressoptions.delay.md Normal file
View File

@ -0,0 +1,13 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PressOptions](./puppeteer.pressoptions.md) &gt; [delay](./puppeteer.pressoptions.delay.md)
## PressOptions.delay property
Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
<b>Signature:</b>
```typescript
delay?: number;
```

20
new-docs/puppeteer.pressoptions.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; [PressOptions](./puppeteer.pressoptions.md)
## PressOptions interface
<b>Signature:</b>
```typescript
export interface PressOptions
```
## Properties
| Property | Type | Description |
| --- | --- | --- |
| [delay](./puppeteer.pressoptions.delay.md) | number | Time to wait between <code>keydown</code> and <code>keyup</code> in milliseconds. Defaults to 0. |
| [text](./puppeteer.pressoptions.text.md) | string | If specified, generates an input event with this text. |

13
new-docs/puppeteer.pressoptions.text.md Normal file
View File

@ -0,0 +1,13 @@
<!-- Do not edit this file. It is automatically generated by API Documenter. -->
[Home](./index.md) &gt; [puppeteer](./puppeteer.md) &gt; [PressOptions](./puppeteer.pressoptions.md) &gt; [text](./puppeteer.pressoptions.text.md)
## PressOptions.text property
If specified, generates an input event with this text.
<b>Signature:</b>
```typescript
text?: string;
```

1
src/api-docs-entry.ts
View File

@ -47,3 +47,4 @@ export * from './common/Target';
export * from './common/Errors';
export * from './common/Tracing';
export * from './common/WebWorker';
export * from './common/USKeyboardLayout';

336
src/common/JSHandle.ts
View File

@ -24,7 +24,10 @@ import { FrameManager, Frame } from './FrameManager';
import { getQueryHandlerAndSelector } from './QueryHandler';
import Protocol from '../protocol';
interface BoxModel {
/**
* @public
*/
export interface BoxModel {
content: Array<{ x: number; y: number }>;
padding: Array<{ x: number; y: number }>;
border: Array<{ x: number; y: number }>;
@ -33,6 +36,31 @@ interface BoxModel {
height: number;
}
/**
* @public
*/
export interface BoundingBox {
/**
* the x coordinate of the element in pixels.
*/
x: number;
/**
* the y coordinate of the element in pixels.
*/
y: number;
/**
* the width of the element in pixels.
*/
width: number;
/**
* the height of the element in pixels.
*/
height: number;
}
/**
* @internal
*/
export function createJSHandle(
context: ExecutionContext,
remoteObject: Protocol.Runtime.RemoteObject
@ -51,6 +79,9 @@ export function createJSHandle(
return new JSHandle(context, context._client, remoteObject);
}
/**
* @public
*/
export class JSHandle {
_context: ExecutionContext;
_client: CDPSession;
@ -71,6 +102,17 @@ export class JSHandle {
return this._context;
}
/**
* This method passes this handle as the first argument to `pageFunction`.
* If `pageFunction` returns a Promise, then `handle.evaluate` would wait
* for the promise to resolve and return its value.
*
* @example
* ```js
* const tweetHandle = await page.$('.tweet .retweets');
* expect(await tweetHandle.evaluate(node => node.innerText)).toBe('10');
* ```
*/
async evaluate<ReturnType extends any>(
pageFunction: Function | string,
...args: unknown[]
@ -82,6 +124,21 @@ export class JSHandle {
);
}
/**
* This method passes this handle as the first argument to `pageFunction`.
*
* @remarks
*
* The only difference between `evaluateHandle.evaluate` and
* `evaluateHandle.evaluateHandle` is that `executionContext.evaluateHandle`
* returns in-page object (JSHandle).
*
* If the function passed to the `evaluateHandle.evaluateHandle` returns a Promise,
* then `evaluateHandle.evaluateHandle` would wait for the promise to resolve and
* return its value.
*
* See {@link Page.evaluateHandle} for more details.
*/
async evaluateHandle(
pageFunction: Function | string,
...args: unknown[]
@ -108,6 +165,23 @@ export class JSHandle {
return result;
}
/**
* The method returns a map with property names as keys and JSHandle
* instances for the property values.
*
* @example
* ```js
* const listHandle = await page.evaluateHandle(() => document.body.children);
* const properties = await listHandle.getProperties();
* const children = [];
* for (const property of properties.values()) {
* const element = property.asElement();
* if (element)
* children.push(element);
* }
* children; // holds elementHandles to all children of document.body
* ```
*/
async getProperties(): Promise<Map<string, JSHandle>> {
const response = await this._client.send('Runtime.getProperties', {
objectId: this._remoteObject.objectId,
@ -121,6 +195,15 @@ export class JSHandle {
return result;
}
/**
* Returns a JSON representation of the object.
*
* @remarks
*
* The JSON is generated by running {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify | JSON.stringify}
* on the object in page and consequent {@link https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/parse | JSON.parse} in puppeteer.
* **NOTE** The method will throw if the referenced object is not stringifiable.
*/
async jsonValue(): Promise<{}> {
if (this._remoteObject.objectId) {
const response = await this._client.send('Runtime.callFunctionOn', {
@ -139,6 +222,9 @@ export class JSHandle {
return null;
}
/**
* The method stops referencing the element handle.
*/
async dispose(): Promise<void> {
if (this._disposed) return;
this._disposed = true;
@ -154,9 +240,42 @@ export class JSHandle {
}
}
/**
* ElementHandle represents an in-page DOM element.
*
* @remarks
*
* ElementHandles can be created with the {@link Page.$} method.
*
* ```js
* const puppeteer = require('puppeteer');
*
* (async () => {
* const browser = await puppeteer.launch();
* const page = await browser.newPage();
* await page.goto('https://example.com');
* const hrefElement = await page.$('a');
* await hrefElement.click();
* // ...
* })();
* ```
*
* ElementHandle prevents DOM element from garbage collection unless the handle is
* {@link JSHandle.dispose | disposed}. ElementHandles are auto-disposed when their
* origin frame gets navigated.
*
* ElementHandle instances can be used as arguments in {@link Page.$eval} and
* {@link Page.evaluate} methods.
*
* @public
*/
export class ElementHandle extends JSHandle {
_page: Page;
_frameManager: FrameManager;
private _page: Page;
private _frameManager: FrameManager;
/**
* @internal
*/
constructor(
context: ExecutionContext,
client: CDPSession,
@ -175,6 +294,10 @@ export class ElementHandle extends JSHandle {
return this;
}
/**
* Resolves to the content frame for element handles referencing
* iframe nodes, or null otherwise
*/
async contentFrame(): Promise<Frame | null> {
const nodeInfo = await this._client.send('DOM.describeNode', {
objectId: this._remoteObject.objectId,
@ -183,7 +306,7 @@ export class ElementHandle extends JSHandle {
return this._frameManager.frame(nodeInfo.node.frameId);
}
async _scrollIntoViewIfNeeded(): Promise<void> {
private async _scrollIntoViewIfNeeded(): Promise<void> {
const error = await this.evaluate<Promise<string | false>>(
async (element: HTMLElement, pageJavascriptEnabled: boolean) => {
if (!element.isConnected) return 'Node is detached from document';
@ -228,7 +351,7 @@ export class ElementHandle extends JSHandle {
if (error) throw new Error(error);
}
async _clickablePoint(): Promise<{ x: number; y: number }> {
private async _clickablePoint(): Promise<{ x: number; y: number }> {
const [result, layoutMetrics] = await Promise.all([
this._client
.send('DOM.getContentQuads', {
@ -263,7 +386,7 @@ export class ElementHandle extends JSHandle {
};
}
_getBoxModel(): Promise<void | Protocol.DOM.getBoxModelReturnValue> {
private _getBoxModel(): Promise<void | Protocol.DOM.getBoxModelReturnValue> {
return this._client
.send('DOM.getBoxModel', {
objectId: this._remoteObject.objectId,
@ -271,7 +394,7 @@ export class ElementHandle extends JSHandle {
.catch((error) => debugError(error));
}
_fromProtocolQuad(quad: number[]): Array<{ x: number; y: number }> {
private _fromProtocolQuad(quad: number[]): Array<{ x: number; y: number }> {
return [
{ x: quad[0], y: quad[1] },
{ x: quad[2], y: quad[3] },
@ -280,7 +403,7 @@ export class ElementHandle extends JSHandle {
];
}
_intersectQuadWithViewport(
private _intersectQuadWithViewport(
quad: Array<{ x: number; y: number }>,
width: number,
height: number
@ -291,22 +414,42 @@ export class ElementHandle extends JSHandle {
}));
}
/**
* This method scrolls element into view if needed, and then
* uses {@link Page.mouse} to hover over the center of the element.
* If the element is detached from DOM, the method throws an error.
*/
async hover(): Promise<void> {
await this._scrollIntoViewIfNeeded();
const { x, y } = await this._clickablePoint();
await this._page.mouse.move(x, y);
}
async click(options: {
delay?: number;
button?: 'left' | 'right' | 'middle';
clickCount?: number;
}): Promise<void> {
/**
* This method scrolls element into view if needed, and then
* uses {@link Page.mouse} to click in the center of the element.
* If the element is detached from DOM, the method throws an error.
*/
async click(options: ClickOptions): Promise<void> {
await this._scrollIntoViewIfNeeded();
const { x, y } = await this._clickablePoint();
await this._page.mouse.click(x, y, options);
}
/**
* Triggers a `change` and `input` event once all the provided options have been
* selected. If there's no `<select>` element matching `selector`, the method
* throws an error.
*
* @example
* ```js
* handle.select('blue'); // single selection
* handle.select('red', 'green', 'blue'); // multiple selections
* ```
* @param values - Values of options to select. If the `<select>` has the
* `multiple` attribute, all values are considered, otherwise only the first
* one is taken into account.
*/
async select(...values: string[]): Promise<string[]> {
for (const value of values)
assert(
@ -340,6 +483,13 @@ export class ElementHandle extends JSHandle {
}, values);
}
/**
* This method expects `elementHandle` to point to an
* {@link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input | input element}.
* @param filePaths - Sets the value of the file input to these paths.
* 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 uploadFile(...filePaths: string[]): Promise<void> {
const isMultiple = await this.evaluate<boolean>(
(element: HTMLInputElement) => element.multiple
@ -397,35 +547,75 @@ export class ElementHandle extends JSHandle {
}
}
/**
* This method scrolls element into view if needed, and then uses
* {@link Touchscreen.tap} to tap in the center of the element.
* If the element is detached from DOM, the method throws an error.
*/
async tap(): Promise<void> {
await this._scrollIntoViewIfNeeded();
const { x, y } = await this._clickablePoint();
await this._page.touchscreen.tap(x, y);
}
/**
* Calls {@link https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus | focus} on the element.
*/
async focus(): Promise<void> {
await this.evaluate((element) => element.focus());
}
/**
* Focuses the element, and then sends a `keydown`, `keypress`/`input`, and
* `keyup` event for each character in the text.
*
* To press a special key, like `Control` or `ArrowDown`,
* use {@link ElementHandle.press}.
*
* @example
* ```js
* await elementHandle.type('Hello'); // Types instantly
* await elementHandle.type('World', {delay: 100}); // Types slower, like a user
* ```
*
* @example
* An example of typing into a text field and then submitting the form:
*
* ```js
* const elementHandle = await page.$('input');
* await elementHandle.type('some text');
* await elementHandle.press('Enter');
* ```
*/
async type(text: string, options?: { delay: number }): Promise<void> {
await this.focus();
await this._page.keyboard.type(text, options);
}
async press(
key: KeyInput,
options?: { delay?: number; text?: string }
): Promise<void> {
/**
* Focuses the element, and then uses {@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 be generated.
* The `text` option can be specified to force an input event to be generated.
*
* **NOTE** Modifier keys DO affect `elementHandle.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.
*/
async press(key: KeyInput, options?: PressOptions): Promise<void> {
await this.focus();
await this._page.keyboard.press(key, options);
}
async boundingBox(): Promise<{
x: number;
y: number;
width: number;
height: number;
}> {
/**
* This method returns the bounding box of the element (relative to the main frame),
* or `null` if the element is not visible.
*/
async boundingBox(): Promise<BoundingBox | null> {
const result = await this._getBoxModel();
if (!result) return null;
@ -440,7 +630,12 @@ export class ElementHandle extends JSHandle {
}
/**
* @returns {!Promise<?BoxModel>}
* This method returns boxes of the element, or `null` if the element is not visible.
*
* @remarks
*
* Boxes are represented as an array of points;
* Each Point is an object `{x, y}`. Box points are sorted clock-wise.
*/
async boxModel(): Promise<BoxModel | null> {
const result = await this._getBoxModel();
@ -458,6 +653,11 @@ export class ElementHandle extends JSHandle {
};
}
/**
* This method scrolls element into view if needed, and then uses
* {@link Page.screenshot} to take a screenshot of the element.
* If the element is detached from DOM, the method throws an error.
*/
async screenshot(options = {}): Promise<string | Buffer | void> {
let needsViewportReset = false;
@ -510,6 +710,10 @@ export class ElementHandle extends JSHandle {
return imageData;
}
/**
* The method runs `element.querySelector` within the page. If no element matches
* the selector, the return value resolves to `null`.
*/
async $(selector: string): Promise<ElementHandle | null> {
const defaultHandler = (element: Element, selector: string) =>
element.querySelector(selector);
@ -525,6 +729,10 @@ export class ElementHandle extends JSHandle {
return null;
}
/**
* The method runs `element.querySelectorAll` within the page. If no elements match
* the selector, the return value resolves to `[]`.
*/
async $$(selector: string): Promise<ElementHandle[]> {
const defaultHandler = (element: Element, selector: string) =>
element.querySelectorAll(selector);
@ -547,6 +755,21 @@ export class ElementHandle extends JSHandle {
return result;
}
/**
* This method runs `document.querySelector` within the element and passes it as
* the first argument to `pageFunction`. If there's no element matching `selector`,
* the method throws an error.
*
* If `pageFunction` returns a Promise, then `frame.$eval` would wait for the promise
* to resolve and return its value.
*
* @example
* ```js
* const tweetHandle = await page.$('.tweet');
* expect(await tweetHandle.$eval('.like', node => node.innerText)).toBe('100');
* expect(await tweetHandle.$eval('.retweets', node => node.innerText)).toBe('10');
* ```
*/
async $eval<ReturnType extends any>(
selector: string,
pageFunction: Function | string,
@ -565,6 +788,29 @@ export class ElementHandle extends JSHandle {
return result;
}
/**
* This method runs `document.querySelectorAll` within the element and passes it as
* the first argument to `pageFunction`. If there's no element matching `selector`,
* the method throws an error.
*
* If `pageFunction` returns a Promise, then `frame.$$eval` would wait for the
* promise to resolve and return its value.
*
* @example
* ```html
* <div class="feed">
* <div class="tweet">Hello!</div>
* <div class="tweet">Hi!</div>
* </div>
* ```
*
* @example
* ```js
* const feedHandle = await page.$('.feed');
* expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText)))
* .toEqual(['Hello!', 'Hi!']);
* ```
*/
async $$eval<ReturnType extends any>(
selector: string,
pageFunction: Function | string,
@ -589,6 +835,11 @@ export class ElementHandle extends JSHandle {
return result;
}
/**
* The method evaluates the XPath expression relative to the elementHandle.
* If there are no such elements, the method will resolve to an empty array.
* @param expression - Expression to {@link https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate | evaluate}
*/
async $x(expression: string): Promise<ElementHandle[]> {
const arrayHandle = await this.evaluateHandle((element, expression) => {
const document = element.ownerDocument || element;
@ -613,6 +864,9 @@ export class ElementHandle extends JSHandle {
return result;
}
/**
* Resolves to true if the element is visible in the current viewport.
*/
async isIntersectingViewport(): Promise<boolean> {
return await this.evaluate<Promise<boolean>>(async (element) => {
const visibleRatio = await new Promise((resolve) => {
@ -627,6 +881,40 @@ export class ElementHandle extends JSHandle {
}
}
/**
* @public
*/
export interface ClickOptions {
/**
* Time to wait between `mousedown` and `mouseup` in milliseconds.
*
* @defaultValue 0
*/
delay?: number;
/**
* @defaultValue 'left'
*/
button?: 'left' | 'right' | 'middle';
/**
* @defaultValue 1
*/
clickCount?: number;
}
/**
* @public
*/
export interface PressOptions {
/**
* Time to wait between `keydown` and `keyup` in milliseconds. Defaults to 0.
*/
delay?: number;
/**
* If specified, generates an input event with this text.
*/
text?: string;
}
function computeQuadArea(quad: Array<{ x: number; y: number }>): number {
// Compute sum of all directed areas of adjacent triangles
// https://en.wikipedia.org/wiki/Polygon#Simple_polygons

14
utils/doclint/check_public_api/index.js
View File

@ -345,6 +345,20 @@ function compareDocumentations(actual, expected) {
expectedName: 'CommandParameters[T]',
},
],
[
'Method ElementHandle.click() options',
{
actualName: 'Object',
expectedName: 'ClickOptions',
},
],
[
'Method ElementHandle.press() options',
{
actualName: 'Object',
expectedName: 'PressOptions',
},
],
[
'Method ElementHandle.press() key',
{