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(api.md): Add more explanation for page.evaluateHandle() (#1867)

Browse Source 
Fixes #2062
This commit is contained in:
Lisa Gagarina 2018-02-22 01:11:24 +00:00 committed by Andrey Lushnikov
parent d75fdb7098
commit 090590a950
2 changed files with 24 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

47
docs/api.md
View File

@ -790,13 +790,13 @@ List of all available devices is available in the source code: [DeviceDescriptor
#### page.evaluate(pageFunction, ...args) #### page.evaluate(pageFunction, ...args)
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context - `pageFunction` <[function]|[string]> Function to be evaluated in the page context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Resolves to the return value of `pageFunction` - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
If the function, passed to the `page.evaluate`, returns a [Promise], then `page.evaluate` would wait for the promise to resolve and return its value. If the function passed to the `page.evaluate` returns a [Promise], then `page.evaluate` would wait for the promise to resolve and return its value.
If the function passed into `page.evaluate` returns a non-[Serializable] value, then `page.evaluate` resolves to `undefined`. If the function passed to the `page.evaluate` returns a non-[Serializable] value, then `page.evaluate` resolves to `undefined`.
Passing arguments to ```pageFunction```.
Passing arguments to `pageFunction`:
```js ```js
const result = await page.evaluate(x => { const result = await page.evaluate(x => {
return Promise.resolve(8 * x); return Promise.resolve(8 * x);
@ -804,8 +804,7 @@ const result = await page.evaluate(x => {
console.log(result); // prints "56" console.log(result); // prints "56"
``` ```
A string can also be passed in instead of a function. A string can also be passed in instead of a function:
```js ```js
console.log(await page.evaluate('1 + 2')); // prints "3" console.log(await page.evaluate('1 + 2')); // prints "3"
const x = 10; const x = 10;
@ -824,19 +823,15 @@ Shortcut for [page.mainFrame().evaluate(pageFunction, ...args)](#frameevaluatepa
#### page.evaluateHandle(pageFunction, ...args) #### page.evaluateHandle(pageFunction, ...args)
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context - `pageFunction` <[function]|[string]> Function to be evaluated in the page context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[JSHandle]>> Resolves to the return value of `pageFunction` - returns: <[Promise]<[JSHandle]>> Promise which resolves to the return value of `pageFunction` as in-page object (JSHandle)
If the function, passed to the `page.evaluateHandle`, returns a [Promise], then `page.evaluateHandle` would wait for the promise to resolve and return its value. The only difference between `page.evaluate` and `page.evaluateHandle` is that `page.evaluateHandle` returns in-page object (JSHandle).
If the function passed to the `page.evaluateHandle` returns a [Promise], then `page.evaluateHandle` would wait for the promise to resolve and return its value.
A string can also be passed in instead of a function:
```js ```js
const aWindowHandle = await page.evaluateHandle(() => Promise.resolve(window)); const aHandle = await page.evaluateHandle('document'); // Handle for the 'document'
aWindowHandle; // Handle for the window object.
```
A string can also be passed in instead of a function.
```js
const aHandle = await page.evaluateHandle('document'); // Handle for the 'document'.
``` ```
[JSHandle] instances can be passed as arguments to the `page.evaluateHandle`: [JSHandle] instances can be passed as arguments to the `page.evaluateHandle`:
@ -1756,11 +1751,11 @@ Gets the full HTML contents of the frame, including the doctype.
#### frame.evaluate(pageFunction, ...args) #### frame.evaluate(pageFunction, ...args)
- `pageFunction` <[function]|[string]> Function to be evaluated in browser context - `pageFunction` <[function]|[string]> Function to be evaluated in browser context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Promise which resolves to function return value - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
If the function, passed to the `frame.evaluate`, returns a [Promise], then `frame.evaluate` would wait for the promise to resolve and return its value. If the function passed to the `frame.evaluate` returns a [Promise], then `frame.evaluate` would wait for the promise to resolve and return its value.
If the function passed into `frame.evaluate` returns a non-[Serializable] value, then `frame.evaluate` resolves to `undefined`. If the function passed to the `frame.evaluate` returns a non-[Serializable] value, then `frame.evaluate` resolves to `undefined`.
```js ```js
const result = await frame.evaluate(() => { const result = await frame.evaluate(() => {
@ -1785,7 +1780,9 @@ await bodyHandle.dispose();
#### frame.evaluateHandle(pageFunction, ...args) #### frame.evaluateHandle(pageFunction, ...args)
- `pageFunction` <[function]|[string]> Function to be evaluated in the page context - `pageFunction` <[function]|[string]> Function to be evaluated in the page context
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[JSHandle]>> Resolves to the return value of `pageFunction` - returns: <[Promise]<[JSHandle]>> Promise which resolves to the return value of `pageFunction` as in-page object (JSHandle)
The only difference between `frame.evaluate` and `frame.evaluateHandle` is that `frame.evaluateHandle` returns in-page object (JSHandle).
If the function, passed to the `frame.evaluateHandle`, returns a [Promise], then `frame.evaluateHandle` would wait for the promise to resolve and return its value. If the function, passed to the `frame.evaluateHandle`, returns a [Promise], then `frame.evaluateHandle` would wait for the promise to resolve and return its value.
@ -1992,9 +1989,9 @@ The class represents a context for JavaScript execution. Examples of JavaScript
#### executionContext.evaluate(pageFunction, ...args) #### executionContext.evaluate(pageFunction, ...args)
- `pageFunction` <[function]|[string]> Function to be evaluated in `executionContext` - `pageFunction` <[function]|[string]> Function to be evaluated in `executionContext`
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[Serializable]>> Promise which resolves to function return value - returns: <[Promise]<[Serializable]>> Promise which resolves to the return value of `pageFunction`
If the function, passed to the `executionContext.evaluate`, returns a [Promise], then `executionContext.evaluate` would wait for the promise to resolve and return its value. If the function passed to the `executionContext.evaluate` returns a [Promise], then `executionContext.evaluate` would wait for the promise to resolve and return its value.
```js ```js
const executionContext = await page.mainFrame().executionContext(); const executionContext = await page.mainFrame().executionContext();
@ -2021,9 +2018,11 @@ console.log(result); // prints '3'.
#### executionContext.evaluateHandle(pageFunction, ...args) #### executionContext.evaluateHandle(pageFunction, ...args)
- `pageFunction` <[function]|[string]> Function to be evaluated in the `executionContext` - `pageFunction` <[function]|[string]> Function to be evaluated in the `executionContext`
- `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction` - `...args` <...[Serializable]|[JSHandle]> Arguments to pass to `pageFunction`
- returns: <[Promise]<[JSHandle]>> Resolves to the return value of `pageFunction` - returns: <[Promise]<[JSHandle]>> Promise which resolves to the return value of `pageFunction` as in-page object (JSHandle)
If the function, passed to the `executionContext.evaluateHandle`, returns a [Promise], then `executionContext.evaluteHandle` would wait for the promise to resolve and return its value. The only difference between `executionContext.evaluate` and `executionContext.evaluateHandle` is that `executionContext.evaluateHandle` returns in-page object (JSHandle).
If the function passed to the `executionContext.evaluateHandle` returns a [Promise], then `executionContext.evaluteHandle` would wait for the promise to resolve and return its value.
```js ```js
const context = await page.mainFrame().executionContext(); const context = await page.mainFrame().executionContext();

2
lib/Page.js
View File

@ -633,7 +633,7 @@ class Page extends EventEmitter {
} }
/** /**
* @param {function()} pageFunction * @param {function()|string} pageFunction
* @param {!Array<*>} args * @param {!Array<*>} args
* @return {!Promise<*>} * @return {!Promise<*>}
*/ */