diff --git a/new-docs/puppeteer.boundingbox.height.md b/new-docs/puppeteer.boundingbox.height.md new file mode 100644 index 00000000..426528b0 --- /dev/null +++ b/new-docs/puppeteer.boundingbox.height.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoundingBox](./puppeteer.boundingbox.md) > [height](./puppeteer.boundingbox.height.md) + +## BoundingBox.height property + +the height of the element in pixels. + +Signature: + +```typescript +height: number; +``` diff --git a/new-docs/puppeteer.boundingbox.md b/new-docs/puppeteer.boundingbox.md new file mode 100644 index 00000000..9cb816c7 --- /dev/null +++ b/new-docs/puppeteer.boundingbox.md @@ -0,0 +1,22 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoundingBox](./puppeteer.boundingbox.md) + +## BoundingBox interface + + +Signature: + +```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. | + diff --git a/new-docs/puppeteer.boundingbox.width.md b/new-docs/puppeteer.boundingbox.width.md new file mode 100644 index 00000000..fe5d16d7 --- /dev/null +++ b/new-docs/puppeteer.boundingbox.width.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoundingBox](./puppeteer.boundingbox.md) > [width](./puppeteer.boundingbox.width.md) + +## BoundingBox.width property + +the width of the element in pixels. + +Signature: + +```typescript +width: number; +``` diff --git a/new-docs/puppeteer.boundingbox.x.md b/new-docs/puppeteer.boundingbox.x.md new file mode 100644 index 00000000..7803f442 --- /dev/null +++ b/new-docs/puppeteer.boundingbox.x.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoundingBox](./puppeteer.boundingbox.md) > [x](./puppeteer.boundingbox.x.md) + +## BoundingBox.x property + +the x coordinate of the element in pixels. + +Signature: + +```typescript +x: number; +``` diff --git a/new-docs/puppeteer.boundingbox.y.md b/new-docs/puppeteer.boundingbox.y.md new file mode 100644 index 00000000..c574ee6c --- /dev/null +++ b/new-docs/puppeteer.boundingbox.y.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoundingBox](./puppeteer.boundingbox.md) > [y](./puppeteer.boundingbox.y.md) + +## BoundingBox.y property + +the y coordinate of the element in pixels. + +Signature: + +```typescript +y: number; +``` diff --git a/new-docs/puppeteer.boxmodel.border.md b/new-docs/puppeteer.boxmodel.border.md new file mode 100644 index 00000000..f5eb3741 --- /dev/null +++ b/new-docs/puppeteer.boxmodel.border.md @@ -0,0 +1,14 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoxModel](./puppeteer.boxmodel.md) > [border](./puppeteer.boxmodel.border.md) + +## BoxModel.border property + +Signature: + +```typescript +border: Array<{ + x: number; + y: number; + }>; +``` diff --git a/new-docs/puppeteer.boxmodel.content.md b/new-docs/puppeteer.boxmodel.content.md new file mode 100644 index 00000000..a0a4723c --- /dev/null +++ b/new-docs/puppeteer.boxmodel.content.md @@ -0,0 +1,14 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoxModel](./puppeteer.boxmodel.md) > [content](./puppeteer.boxmodel.content.md) + +## BoxModel.content property + +Signature: + +```typescript +content: Array<{ + x: number; + y: number; + }>; +``` diff --git a/new-docs/puppeteer.boxmodel.height.md b/new-docs/puppeteer.boxmodel.height.md new file mode 100644 index 00000000..952ca5f8 --- /dev/null +++ b/new-docs/puppeteer.boxmodel.height.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoxModel](./puppeteer.boxmodel.md) > [height](./puppeteer.boxmodel.height.md) + +## BoxModel.height property + +Signature: + +```typescript +height: number; +``` diff --git a/new-docs/puppeteer.boxmodel.margin.md b/new-docs/puppeteer.boxmodel.margin.md new file mode 100644 index 00000000..418f1928 --- /dev/null +++ b/new-docs/puppeteer.boxmodel.margin.md @@ -0,0 +1,14 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoxModel](./puppeteer.boxmodel.md) > [margin](./puppeteer.boxmodel.margin.md) + +## BoxModel.margin property + +Signature: + +```typescript +margin: Array<{ + x: number; + y: number; + }>; +``` diff --git a/new-docs/puppeteer.boxmodel.md b/new-docs/puppeteer.boxmodel.md new file mode 100644 index 00000000..ffdd69fa --- /dev/null +++ b/new-docs/puppeteer.boxmodel.md @@ -0,0 +1,24 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoxModel](./puppeteer.boxmodel.md) + +## BoxModel interface + + +Signature: + +```typescript +export interface BoxModel +``` + +## Properties + +| Property | Type | Description | +| --- | --- | --- | +| [border](./puppeteer.boxmodel.border.md) | Array<{ x: number; y: number; }> | | +| [content](./puppeteer.boxmodel.content.md) | Array<{ x: number; y: number; }> | | +| [height](./puppeteer.boxmodel.height.md) | number | | +| [margin](./puppeteer.boxmodel.margin.md) | Array<{ x: number; y: number; }> | | +| [padding](./puppeteer.boxmodel.padding.md) | Array<{ x: number; y: number; }> | | +| [width](./puppeteer.boxmodel.width.md) | number | | + diff --git a/new-docs/puppeteer.boxmodel.padding.md b/new-docs/puppeteer.boxmodel.padding.md new file mode 100644 index 00000000..3c47ceeb --- /dev/null +++ b/new-docs/puppeteer.boxmodel.padding.md @@ -0,0 +1,14 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoxModel](./puppeteer.boxmodel.md) > [padding](./puppeteer.boxmodel.padding.md) + +## BoxModel.padding property + +Signature: + +```typescript +padding: Array<{ + x: number; + y: number; + }>; +``` diff --git a/new-docs/puppeteer.boxmodel.width.md b/new-docs/puppeteer.boxmodel.width.md new file mode 100644 index 00000000..14e7b208 --- /dev/null +++ b/new-docs/puppeteer.boxmodel.width.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [BoxModel](./puppeteer.boxmodel.md) > [width](./puppeteer.boxmodel.width.md) + +## BoxModel.width property + +Signature: + +```typescript +width: number; +``` diff --git a/new-docs/puppeteer.clickoptions.button.md b/new-docs/puppeteer.clickoptions.button.md new file mode 100644 index 00000000..d97dcca8 --- /dev/null +++ b/new-docs/puppeteer.clickoptions.button.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ClickOptions](./puppeteer.clickoptions.md) > [button](./puppeteer.clickoptions.button.md) + +## ClickOptions.button property + +Signature: + +```typescript +button?: 'left' | 'right' | 'middle'; +``` diff --git a/new-docs/puppeteer.clickoptions.clickcount.md b/new-docs/puppeteer.clickoptions.clickcount.md new file mode 100644 index 00000000..87f48934 --- /dev/null +++ b/new-docs/puppeteer.clickoptions.clickcount.md @@ -0,0 +1,11 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ClickOptions](./puppeteer.clickoptions.md) > [clickCount](./puppeteer.clickoptions.clickcount.md) + +## ClickOptions.clickCount property + +Signature: + +```typescript +clickCount?: number; +``` diff --git a/new-docs/puppeteer.clickoptions.delay.md b/new-docs/puppeteer.clickoptions.delay.md new file mode 100644 index 00000000..04f35d43 --- /dev/null +++ b/new-docs/puppeteer.clickoptions.delay.md @@ -0,0 +1,13 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ClickOptions](./puppeteer.clickoptions.md) > [delay](./puppeteer.clickoptions.delay.md) + +## ClickOptions.delay property + +Time to wait between `mousedown` and `mouseup` in milliseconds. + +Signature: + +```typescript +delay?: number; +``` diff --git a/new-docs/puppeteer.clickoptions.md b/new-docs/puppeteer.clickoptions.md new file mode 100644 index 00000000..abd5fd00 --- /dev/null +++ b/new-docs/puppeteer.clickoptions.md @@ -0,0 +1,21 @@ + + +[Home](./index.md) > [puppeteer](./puppeteer.md) > [ClickOptions](./puppeteer.clickoptions.md) + +## ClickOptions interface + + +Signature: + +```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 mousedown and mouseup in milliseconds. | + diff --git a/new-docs/puppeteer.createjshandle.md b/new-docs/puppeteer.createjshandle.md deleted file mode 100644 index 4f92a4b5..00000000 --- a/new-docs/puppeteer.createjshandle.md +++ /dev/null @@ -1,23 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [createJSHandle](./puppeteer.createjshandle.md) - -## createJSHandle() function - -Signature: - -```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 | | - -Returns: - -[JSHandle](./puppeteer.jshandle.md) - diff --git a/new-docs/puppeteer.elementhandle._.md b/new-docs/puppeteer.elementhandle._.md index f9354fc2..6be4b5ec 100644 --- a/new-docs/puppeteer.elementhandle._.md +++ b/new-docs/puppeteer.elementhandle._.md @@ -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`. + Signature: ```typescript diff --git a/new-docs/puppeteer.elementhandle.__.md b/new-docs/puppeteer.elementhandle.__.md index 16cd79aa..34bfb509 100644 --- a/new-docs/puppeteer.elementhandle.__.md +++ b/new-docs/puppeteer.elementhandle.__.md @@ -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 `[]`. + Signature: ```typescript diff --git a/new-docs/puppeteer.elementhandle.__eval.md b/new-docs/puppeteer.elementhandle.__eval.md index dc966188..62184b0b 100644 --- a/new-docs/puppeteer.elementhandle.__eval.md +++ b/new-docs/puppeteer.elementhandle.__eval.md @@ -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. + Signature: ```typescript @@ -22,3 +26,24 @@ $$eval(selector: string, pageFunction: Function | string Promise<ReturnType> +## Example 1 + + +```html +
+
Hello!
+
Hi!
+
+ +``` + +## Example 2 + + +```js +const feedHandle = await page.$('.feed'); +expect(await feedHandle.$$eval('.tweet', nodes => nodes.map(n => n.innerText))) + .toEqual(['Hello!', 'Hi!']); + +``` + diff --git a/new-docs/puppeteer.elementhandle._clickablepoint.md b/new-docs/puppeteer.elementhandle._clickablepoint.md deleted file mode 100644 index fc61c152..00000000 --- a/new-docs/puppeteer.elementhandle._clickablepoint.md +++ /dev/null @@ -1,18 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ElementHandle](./puppeteer.elementhandle.md) > [\_clickablePoint](./puppeteer.elementhandle._clickablepoint.md) - -## ElementHandle.\_clickablePoint() method - -Signature: - -```typescript -_clickablePoint(): Promise<{ - x: number; - y: number; - }>; -``` -Returns: - -Promise<{ x: number; y: number; }> - diff --git a/new-docs/puppeteer.elementhandle._constructor_.md b/new-docs/puppeteer.elementhandle._constructor_.md deleted file mode 100644 index ceb7ee2b..00000000 --- a/new-docs/puppeteer.elementhandle._constructor_.md +++ /dev/null @@ -1,24 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ElementHandle](./puppeteer.elementhandle.md) > [(constructor)](./puppeteer.elementhandle._constructor_.md) - -## ElementHandle.(constructor) - -Constructs a new instance of the `ElementHandle` class - -Signature: - -```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) | | - diff --git a/new-docs/puppeteer.elementhandle._eval.md b/new-docs/puppeteer.elementhandle._eval.md index 94111be0..51719ae1 100644 --- a/new-docs/puppeteer.elementhandle._eval.md +++ b/new-docs/puppeteer.elementhandle._eval.md @@ -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. + Signature: ```typescript @@ -22,3 +26,13 @@ $eval(selector: string, pageFunction: Function | string, Promise<ReturnType> +## 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'); + +``` + diff --git a/new-docs/puppeteer.elementhandle._framemanager.md b/new-docs/puppeteer.elementhandle._framemanager.md deleted file mode 100644 index 2409cb8b..00000000 --- a/new-docs/puppeteer.elementhandle._framemanager.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ElementHandle](./puppeteer.elementhandle.md) > [\_frameManager](./puppeteer.elementhandle._framemanager.md) - -## ElementHandle.\_frameManager property - -Signature: - -```typescript -_frameManager: FrameManager; -``` diff --git a/new-docs/puppeteer.elementhandle._fromprotocolquad.md b/new-docs/puppeteer.elementhandle._fromprotocolquad.md deleted file mode 100644 index 89669843..00000000 --- a/new-docs/puppeteer.elementhandle._fromprotocolquad.md +++ /dev/null @@ -1,25 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ElementHandle](./puppeteer.elementhandle.md) > [\_fromProtocolQuad](./puppeteer.elementhandle._fromprotocolquad.md) - -## ElementHandle.\_fromProtocolQuad() method - -Signature: - -```typescript -_fromProtocolQuad(quad: number[]): Array<{ - x: number; - y: number; - }>; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| quad | number\[\] | | - -Returns: - -Array<{ x: number; y: number; }> - diff --git a/new-docs/puppeteer.elementhandle._getboxmodel.md b/new-docs/puppeteer.elementhandle._getboxmodel.md deleted file mode 100644 index 9bfeca9e..00000000 --- a/new-docs/puppeteer.elementhandle._getboxmodel.md +++ /dev/null @@ -1,15 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ElementHandle](./puppeteer.elementhandle.md) > [\_getBoxModel](./puppeteer.elementhandle._getboxmodel.md) - -## ElementHandle.\_getBoxModel() method - -Signature: - -```typescript -_getBoxModel(): Promise; -``` -Returns: - -Promise<void \| Protocol.DOM.getBoxModelReturnValue> - diff --git a/new-docs/puppeteer.elementhandle._intersectquadwithviewport.md b/new-docs/puppeteer.elementhandle._intersectquadwithviewport.md deleted file mode 100644 index d4d27d04..00000000 --- a/new-docs/puppeteer.elementhandle._intersectquadwithviewport.md +++ /dev/null @@ -1,30 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ElementHandle](./puppeteer.elementhandle.md) > [\_intersectQuadWithViewport](./puppeteer.elementhandle._intersectquadwithviewport.md) - -## ElementHandle.\_intersectQuadWithViewport() method - -Signature: - -```typescript -_intersectQuadWithViewport(quad: Array<{ - x: number; - y: number; - }>, width: number, height: number): Array<{ - x: number; - y: number; - }>; -``` - -## Parameters - -| Parameter | Type | Description | -| --- | --- | --- | -| quad | Array<{ x: number; y: number; }> | | -| width | number | | -| height | number | | - -Returns: - -Array<{ x: number; y: number; }> - diff --git a/new-docs/puppeteer.elementhandle._page.md b/new-docs/puppeteer.elementhandle._page.md deleted file mode 100644 index cd91ed55..00000000 --- a/new-docs/puppeteer.elementhandle._page.md +++ /dev/null @@ -1,11 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ElementHandle](./puppeteer.elementhandle.md) > [\_page](./puppeteer.elementhandle._page.md) - -## ElementHandle.\_page property - -Signature: - -```typescript -_page: Page; -``` diff --git a/new-docs/puppeteer.elementhandle._scrollintoviewifneeded.md b/new-docs/puppeteer.elementhandle._scrollintoviewifneeded.md deleted file mode 100644 index 3d431283..00000000 --- a/new-docs/puppeteer.elementhandle._scrollintoviewifneeded.md +++ /dev/null @@ -1,15 +0,0 @@ - - -[Home](./index.md) > [puppeteer](./puppeteer.md) > [ElementHandle](./puppeteer.elementhandle.md) > [\_scrollIntoViewIfNeeded](./puppeteer.elementhandle._scrollintoviewifneeded.md) - -## ElementHandle.\_scrollIntoViewIfNeeded() method - -Signature: - -```typescript -_scrollIntoViewIfNeeded(): Promise; -``` -Returns: - -Promise<void> - diff --git a/new-docs/puppeteer.elementhandle._x.md b/new-docs/puppeteer.elementhandle._x.md index 33fdf279..b40a9b69 100644 --- a/new-docs/puppeteer.elementhandle._x.md +++ b/new-docs/puppeteer.elementhandle._x.md @@ -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. + Signature: ```typescript @@ -14,7 +16,7 @@ $x(expression: string): Promise; | Parameter | Type | Description | | --- | --- | --- | -| expression | string | | +| expression | string | Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate) | Returns: diff --git a/new-docs/puppeteer.elementhandle.boundingbox.md b/new-docs/puppeteer.elementhandle.boundingbox.md index 6b2d0946..89caf6ad 100644 --- a/new-docs/puppeteer.elementhandle.boundingbox.md +++ b/new-docs/puppeteer.elementhandle.boundingbox.md @@ -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. + Signature: ```typescript -boundingBox(): Promise<{ - x: number; - y: number; - width: number; - height: number; - }>; +boundingBox(): Promise; ``` Returns: -Promise<{ x: number; y: number; width: number; height: number; }> +Promise<[BoundingBox](./puppeteer.boundingbox.md) \| null> diff --git a/new-docs/puppeteer.elementhandle.boxmodel.md b/new-docs/puppeteer.elementhandle.boxmodel.md index 2f54e48c..69723632 100644 --- a/new-docs/puppeteer.elementhandle.boxmodel.md +++ b/new-docs/puppeteer.elementhandle.boxmodel.md @@ -4,6 +4,8 @@ ## ElementHandle.boxModel() method +This method returns boxes of the element, or `null` if the element is not visible. + Signature: ```typescript @@ -11,7 +13,9 @@ boxModel(): Promise; ``` Returns: -Promise<BoxModel \| null> +Promise<[BoxModel](./puppeteer.boxmodel.md) \| null> -{!Promise<?BoxModel>} +## Remarks + +Boxes are represented as an array of points; Each Point is an object `{x, y}`. Box points are sorted clock-wise. diff --git a/new-docs/puppeteer.elementhandle.click.md b/new-docs/puppeteer.elementhandle.click.md index 6cd92b90..e9e7c04e 100644 --- a/new-docs/puppeteer.elementhandle.click.md +++ b/new-docs/puppeteer.elementhandle.click.md @@ -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. + Signature: ```typescript -click(options: { - delay?: number; - button?: 'left' | 'right' | 'middle'; - clickCount?: number; - }): Promise; +click(options: ClickOptions): Promise; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| options | { delay?: number; button?: 'left' \| 'right' \| 'middle'; clickCount?: number; } | | +| options | [ClickOptions](./puppeteer.clickoptions.md) | | Returns: diff --git a/new-docs/puppeteer.elementhandle.contentframe.md b/new-docs/puppeteer.elementhandle.contentframe.md index c5709cca..c4db7ea3 100644 --- a/new-docs/puppeteer.elementhandle.contentframe.md +++ b/new-docs/puppeteer.elementhandle.contentframe.md @@ -4,6 +4,8 @@ ## ElementHandle.contentFrame() method +Resolves to the content frame for element handles referencing iframe nodes, or null otherwise + Signature: ```typescript diff --git a/new-docs/puppeteer.elementhandle.focus.md b/new-docs/puppeteer.elementhandle.focus.md index 6a622b9c..1b8077df 100644 --- a/new-docs/puppeteer.elementhandle.focus.md +++ b/new-docs/puppeteer.elementhandle.focus.md @@ -4,6 +4,8 @@ ## ElementHandle.focus() method +Calls [focus](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus) on the element. + Signature: ```typescript diff --git a/new-docs/puppeteer.elementhandle.hover.md b/new-docs/puppeteer.elementhandle.hover.md index 0f9f9a7b..1d3a35bb 100644 --- a/new-docs/puppeteer.elementhandle.hover.md +++ b/new-docs/puppeteer.elementhandle.hover.md @@ -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. + Signature: ```typescript diff --git a/new-docs/puppeteer.elementhandle.isintersectingviewport.md b/new-docs/puppeteer.elementhandle.isintersectingviewport.md index 3d497824..5c38f670 100644 --- a/new-docs/puppeteer.elementhandle.isintersectingviewport.md +++ b/new-docs/puppeteer.elementhandle.isintersectingviewport.md @@ -4,6 +4,8 @@ ## ElementHandle.isIntersectingViewport() method +Resolves to true if the element is visible in the current viewport. + Signature: ```typescript diff --git a/new-docs/puppeteer.elementhandle.md b/new-docs/puppeteer.elementhandle.md index a5b14ac0..a28c12de 100644 --- a/new-docs/puppeteer.elementhandle.md +++ b/new-docs/puppeteer.elementhandle.md @@ -4,6 +4,8 @@ ## ElementHandle class +ElementHandle represents an in-page DOM element. + Signature: ```typescript @@ -11,45 +13,50 @@ export declare class ElementHandle extends JSHandle ``` Extends: [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 ElementHandle 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 element.querySelector within the page. If no element matches the selector, the return value resolves to null. | +| [$$(selector)](./puppeteer.elementhandle.__.md) | | The method runs element.querySelectorAll within the page. If no elements match the selector, the return value resolves to []. | +| [$$eval(selector, pageFunction, args)](./puppeteer.elementhandle.__eval.md) | | 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. | +| [$eval(selector, pageFunction, args)](./puppeteer.elementhandle._eval.md) | | 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. | +| [$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 null if the element is not visible. | +| [boxModel()](./puppeteer.elementhandle.boxmodel.md) | | This method returns boxes of the element, or null 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 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. | +| [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 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). | +| [uploadFile(filePaths)](./puppeteer.elementhandle.uploadfile.md) | | This method expects elementHandle to point to an [input element](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). | diff --git a/new-docs/puppeteer.elementhandle.press.md b/new-docs/puppeteer.elementhandle.press.md index 75228f1f..288c71fd 100644 --- a/new-docs/puppeteer.elementhandle.press.md +++ b/new-docs/puppeteer.elementhandle.press.md @@ -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). + Signature: ```typescript -press(key: KeyInput, options?: { - delay?: number; - text?: string; - }): Promise; +press(key: KeyInput, options?: PressOptions): Promise; ``` ## Parameters | Parameter | Type | Description | | --- | --- | --- | -| key | KeyInput | | -| options | { delay?: number; text?: string; } | | +| key | [KeyInput](./puppeteer.keyinput.md) | Name of key to press, such as ArrowLeft. See [KeyInput](./puppeteer.keyinput.md) for a list of all key names. | +| options | [PressOptions](./puppeteer.pressoptions.md) | | Returns: Promise<void> +## Remarks + +If `key` is a single character and no modifier keys besides `Shift` are being held down, a `keypress`/`input` event will also 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. + diff --git a/new-docs/puppeteer.elementhandle.screenshot.md b/new-docs/puppeteer.elementhandle.screenshot.md index 0c8466bd..5fbb391c 100644 --- a/new-docs/puppeteer.elementhandle.screenshot.md +++ b/new-docs/puppeteer.elementhandle.screenshot.md @@ -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. + Signature: ```typescript diff --git a/new-docs/puppeteer.elementhandle.select.md b/new-docs/puppeteer.elementhandle.select.md index 6e8caee7..d29c9845 100644 --- a/new-docs/puppeteer.elementhandle.select.md +++ b/new-docs/puppeteer.elementhandle.select.md @@ -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 `` 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 `