docs(new): migrate JSHandle docs to TSDoc (#6102)
This commit is contained in:
Mathias Bynens
GitHub
parent
1c0009d2c0
commit
df96f16921
@ -4,7 +4,6 @@
|
||||
|
||||
## BoxModel interface
|
||||
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
## ElementHandle.$() method
|
||||
|
||||
The method runs `element.querySelector` within the page. If no element matches the selector, the return value resolves to `null`<!-- -->.
|
||||
Runs `element.querySelector` within the page. If no element matches the selector, the return value resolves to `null`<!-- -->.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
## ElementHandle.$$() method
|
||||
|
||||
The method runs `element.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`<!-- -->.
|
||||
Runs `element.querySelectorAll` within the page. If no elements match the selector, the return value resolves to `[]`<!-- -->.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
|
||||
@ -30,7 +30,7 @@ const puppeteer = require('puppeteer');
|
||||
})();
|
||||
|
||||
```
|
||||
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 prevents the DOM element from being garbage-collected 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.
|
||||
|
||||
@ -40,8 +40,8 @@ The constructor for this class is marked as internal. Third-party code should no
|
||||
|
||||
| Method | Modifiers | Description |
|
||||
| --- | --- | --- |
|
||||
| [$(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>. |
|
||||
| [$(selector)](./puppeteer.elementhandle._.md) | | 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) | | 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. |
|
||||
|
||||
@ -4,6 +4,8 @@
|
||||
|
||||
## JSHandle.asElement() method
|
||||
|
||||
Returns either `null` or the object handle itself, if the object handle is an instance of [ElementHandle](./puppeteer.elementhandle.md)<!-- -->.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
## JSHandle.dispose() method
|
||||
|
||||
The method stops referencing the element handle.
|
||||
Stops referencing the element handle, and resolves when the object handle is successfully disposed of.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
|
||||
@ -25,9 +25,9 @@ Promise<[JSHandle](./puppeteer.jshandle.md)<!-- -->>
|
||||
|
||||
## Remarks
|
||||
|
||||
The only difference between `evaluateHandle.evaluate` and `evaluateHandle.evaluateHandle` is that `executionContext.evaluateHandle` returns in-page object (JSHandle).
|
||||
The only difference between `jsHandle.evaluate` and `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle` returns an 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.
|
||||
If the function passed to `jsHandle.evaluateHandle` returns a Promise, then `evaluateHandle.evaluateHandle` waits for the promise to resolve and returns its value.
|
||||
|
||||
See [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md) for more details.
|
||||
|
||||
|
||||
@ -4,6 +4,8 @@
|
||||
|
||||
## JSHandle.executionContext() method
|
||||
|
||||
Returns the execution context the handle belongs to.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
|
||||
@ -4,6 +4,8 @@
|
||||
|
||||
## JSHandle.getProperty() method
|
||||
|
||||
Fetches a single property from the referenced object.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
|
||||
@ -17,5 +17,5 @@ Promise<{}>
|
||||
|
||||
## 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.
|
||||
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 throws if the referenced object is not stringifiable.
|
||||
|
||||
|
||||
@ -4,6 +4,7 @@
|
||||
|
||||
## JSHandle class
|
||||
|
||||
Represents an in-page JavaScript object. JSHandles can be created with the [page.evaluateHandle](./puppeteer.page.evaluatehandle.md) method.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
@ -11,6 +12,17 @@
|
||||
export declare class JSHandle
|
||||
```
|
||||
|
||||
## Example
|
||||
|
||||
|
||||
```js
|
||||
const windowHandle = await page.evaluateHandle(() => window);
|
||||
|
||||
```
|
||||
JSHandle prevents the referenced JavaScript object from being garbage-collected unless the handle is [disposed](./puppeteer.jshandle.dispose.md)<!-- -->. JSHandles are auto- disposed when their origin frame gets navigated or the parent context gets destroyed.
|
||||
|
||||
JSHandle instances can be used as arguments for [Page.$eval()](./puppeteer.page._eval.md)<!-- -->, [Page.evaluate()](./puppeteer.page.evaluate.md)<!-- -->, and [Page.evaluateHandle()](./puppeteer.page.evaluatehandle.md)<!-- -->.
|
||||
|
||||
## Constructors
|
||||
|
||||
| Constructor | Modifiers | Description |
|
||||
@ -30,13 +42,13 @@ export declare class JSHandle
|
||||
|
||||
| Method | Modifiers | Description |
|
||||
| --- | --- | --- |
|
||||
| [asElement()](./puppeteer.jshandle.aselement.md) | | |
|
||||
| [dispose()](./puppeteer.jshandle.dispose.md) | | The method stops referencing the element handle. |
|
||||
| [asElement()](./puppeteer.jshandle.aselement.md) | | Returns either <code>null</code> or the object handle itself, if the object handle is an instance of [ElementHandle](./puppeteer.elementhandle.md)<!-- -->. |
|
||||
| [dispose()](./puppeteer.jshandle.dispose.md) | | Stops referencing the element handle, and resolves when the object handle is successfully disposed of. |
|
||||
| [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) | | |
|
||||
| [executionContext()](./puppeteer.jshandle.executioncontext.md) | | Returns the execution context the handle belongs to. |
|
||||
| [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) | | |
|
||||
| [getProperty(propertyName)](./puppeteer.jshandle.getproperty.md) | | Fetches a single property from the referenced object. |
|
||||
| [jsonValue()](./puppeteer.jshandle.jsonvalue.md) | | Returns a JSON representation of the object. |
|
||||
| [toString()](./puppeteer.jshandle.tostring.md) | | |
|
||||
| [toString()](./puppeteer.jshandle.tostring.md) | | Returns a string representation of the JSHandle. |
|
||||
|
||||
|
||||
@ -4,6 +4,8 @@
|
||||
|
||||
## JSHandle.toString() method
|
||||
|
||||
Returns a string representation of the JSHandle.
|
||||
|
||||
<b>Signature:</b>
|
||||
|
||||
```typescript
|
||||
@ -13,3 +15,7 @@ toString(): string;
|
||||
|
||||
string
|
||||
|
||||
## Remarks
|
||||
|
||||
Useful during debugging.
|
||||
|
||||
|
||||
@ -25,7 +25,7 @@
|
||||
| [FrameManager](./puppeteer.framemanager.md) | |
|
||||
| [HTTPRequest](./puppeteer.httprequest.md) | |
|
||||
| [HTTPResponse](./puppeteer.httpresponse.md) | The HTTPResponse class represents responses which are received by the [Page](./puppeteer.page.md) class. |
|
||||
| [JSHandle](./puppeteer.jshandle.md) | |
|
||||
| [JSHandle](./puppeteer.jshandle.md) | Represents an in-page JavaScript object. JSHandles can be created with the [page.evaluateHandle](./puppeteer.page.evaluatehandle.md) method. |
|
||||
| [Keyboard](./puppeteer.keyboard.md) | Keyboard provides an api for managing a virtual keyboard. The high level api is [Keyboard.type()](./puppeteer.keyboard.type.md)<!-- -->, which takes raw characters and generates proper keydown, keypress/input, and keyup events on your page. |
|
||||
| [Mouse](./puppeteer.mouse.md) | The Mouse class operates in main-frame CSS pixels relative to the top-left corner of the viewport. |
|
||||
| [Page](./puppeteer.page.md) | Page provides methods to interact with a single tab or \[extension background page\](https://developer.chrome.com/extensions/background\_pages) in Chromium. One \[Browser\] instance might have multiple \[Page\] instances. |
|
||||
|
||||
@ -29,9 +29,6 @@ import {
|
||||
EvaluateFnReturnType,
|
||||
} from './EvalTypes';
|
||||
|
||||
/**
|
||||
* @public
|
||||
*/
|
||||
export interface BoxModel {
|
||||
content: Array<{ x: number; y: number }>;
|
||||
padding: Array<{ x: number; y: number }>;
|
||||
@ -85,6 +82,21 @@ export function createJSHandle(
|
||||
}
|
||||
|
||||
/**
|
||||
* Represents an in-page JavaScript object. JSHandles can be created with the
|
||||
* {@link Page.evaluateHandle | page.evaluateHandle} method.
|
||||
*
|
||||
* @example
|
||||
* ```js
|
||||
* const windowHandle = await page.evaluateHandle(() => window);
|
||||
* ```
|
||||
*
|
||||
* JSHandle prevents the referenced JavaScript object from being garbage-collected
|
||||
* unless the handle is {@link JSHandle.dispose | disposed}. JSHandles are auto-
|
||||
* disposed when their origin frame gets navigated or the parent context gets destroyed.
|
||||
*
|
||||
* JSHandle instances can be used as arguments for {@link Page.$eval},
|
||||
* {@link Page.evaluate}, and {@link Page.evaluateHandle}.
|
||||
*
|
||||
* @public
|
||||
*/
|
||||
export class JSHandle {
|
||||
@ -103,6 +115,8 @@ export class JSHandle {
|
||||
this._remoteObject = remoteObject;
|
||||
}
|
||||
|
||||
/** Returns the execution context the handle belongs to.
|
||||
*/
|
||||
executionContext(): ExecutionContext {
|
||||
return this._context;
|
||||
}
|
||||
@ -135,13 +149,13 @@ export class JSHandle {
|
||||
*
|
||||
* @remarks
|
||||
*
|
||||
* The only difference between `evaluateHandle.evaluate` and
|
||||
* `evaluateHandle.evaluateHandle` is that `executionContext.evaluateHandle`
|
||||
* returns in-page object (JSHandle).
|
||||
* The only difference between `jsHandle.evaluate` and
|
||||
* `jsHandle.evaluateHandle` is that `jsHandle.evaluateHandle`
|
||||
* returns an 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.
|
||||
* If the function passed to `jsHandle.evaluateHandle` returns a Promise,
|
||||
* then `evaluateHandle.evaluateHandle` waits for the promise to resolve and
|
||||
* returns its value.
|
||||
*
|
||||
* See {@link Page.evaluateHandle} for more details.
|
||||
*/
|
||||
@ -156,6 +170,8 @@ export class JSHandle {
|
||||
);
|
||||
}
|
||||
|
||||
/** Fetches a single property from the referenced object.
|
||||
*/
|
||||
async getProperty(propertyName: string): Promise<JSHandle | undefined> {
|
||||
const objectHandle = await this.evaluateHandle(
|
||||
(object: HTMLElement, propertyName: string) => {
|
||||
@ -208,7 +224,7 @@ export class JSHandle {
|
||||
*
|
||||
* 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.
|
||||
* **NOTE** The method throws if the referenced object is not stringifiable.
|
||||
*/
|
||||
async jsonValue(): Promise<{}> {
|
||||
if (this._remoteObject.objectId) {
|
||||
@ -223,13 +239,19 @@ export class JSHandle {
|
||||
return helper.valueFromRemoteObject(this._remoteObject);
|
||||
}
|
||||
|
||||
/* This always returns null but children can define this and return an ElementHandle */
|
||||
/**
|
||||
* Returns either `null` or the object handle itself, if the object handle is
|
||||
* an instance of {@link ElementHandle}.
|
||||
*/
|
||||
asElement(): ElementHandle | null {
|
||||
// This always returns null, but subclasses can override this and return an
|
||||
// ElementHandle.
|
||||
return null;
|
||||
}
|
||||
|
||||
/**
|
||||
* The method stops referencing the element handle.
|
||||
* Stops referencing the element handle, and resolves when the object handle is
|
||||
* successfully disposed of.
|
||||
*/
|
||||
async dispose(): Promise<void> {
|
||||
if (this._disposed) return;
|
||||
@ -237,6 +259,11 @@ export class JSHandle {
|
||||
await helper.releaseObject(this._client, this._remoteObject);
|
||||
}
|
||||
|
||||
/**
|
||||
* Returns a string representation of the JSHandle.
|
||||
*
|
||||
* @remarks Useful during debugging.
|
||||
*/
|
||||
toString(): string {
|
||||
if (this._remoteObject.objectId) {
|
||||
const type = this._remoteObject.subtype || this._remoteObject.type;
|
||||
@ -266,9 +293,9 @@ export class JSHandle {
|
||||
* })();
|
||||
* ```
|
||||
*
|
||||
* 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 prevents the DOM element from being garbage-collected 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.
|
||||
@ -719,8 +746,8 @@ export class ElementHandle extends JSHandle {
|
||||
}
|
||||
|
||||
/**
|
||||
* The method runs `element.querySelector` within the page. If no element matches
|
||||
* the selector, the return value resolves to `null`.
|
||||
* 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) =>
|
||||
@ -738,8 +765,8 @@ export class ElementHandle extends JSHandle {
|
||||
}
|
||||
|
||||
/**
|
||||
* The method runs `element.querySelectorAll` within the page. If no elements match
|
||||
* the selector, the return value resolves to `[]`.
|
||||
* 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) =>
|
||||
|
||||
Loading…
Reference in New Issue
Block a user