# class:frame
### class: Frame v0.9.0
在每一个时间点，页面通过 [page.mainFrame()](#?product=Puppeteer&version=v1.11.0&show=api-pagemainframe) 和 [frame.childFrames()](#?product=Puppeteer&version=v1.11.0&show=api-framechildframes) 方法暴露当前框架的细节。
[Frame](#?product=Puppeteer&version=v1.11.0&show=api-class-frame "Frame") 对象的生命周期由 3 个事件控制，它们通过 [page](https://github.com/zhaoqize/puppeteer-api-zh_CN/blob/master/class-Page.md#event-frameattached) 对象监听：
- ['frameattached'](#?product=Puppeteer&version=v1.11.0&show=api-event-frameattached) - 当框架被页面加载时触发。一个框架只会被加载一次。
- ['framenavigated'](#?product=Puppeteer&version=v1.11.0&show=api-event-framenavigated) - 当框架改变URL时触发。
- ['framedetached'](#?product=Puppeteer&version=v1.11.0&show=api-event-framedetached) - 当框架被页面分离时触发。一个框架只会被分离一次。
一个获得框架树的例子：
```
const puppeteer = require('puppeteer');puppeteer.launch().then(async browser => { const page = await browser.newPage(); await page.goto('https://www.google.com/chrome/browser/canary.html'); dumpFrameTree(page.mainFrame(), ''); await browser.close(); function dumpFrameTree(frame, indent) { console.log(indent + frame.url()); for (let child of frame.childFrames()) dumpFrameTree(child, indent + ' '); }});
```
一个从 iframe 元素中获取文本的例子：
```
const frame = page.frames().find(frame => frame.name() === 'myframe'); const text = await frame.$eval('.selector', element => element.textContent); console.log(text);
```
#### Methods
- [frame.$(selector)](#?product=Puppeteer&version=v1.11.0&show=api-frameselector)v0.9.0
- [frame.$$(selector)](#?product=Puppeteer&version=v1.11.0&show=api-frameselector-1)v0.9.0
- [frame.$$eval(selector, pageFunction\[, ...args\])](#?product=Puppeteer&version=v1.11.0&show=api-frameevalselector-pagefunction-args)v0.9.0
- [frame.$eval(selector, pageFunction\[, ...args\])](#?product=Puppeteer&version=v1.11.0&show=api-frameevalselector-pagefunction-args-1)v0.9.0
- [frame.$x(expression)](#?product=Puppeteer&version=v1.11.0&show=api-framexexpression)v0.9.0
- [frame.addScriptTag(options)](#?product=Puppeteer&version=v1.11.0&show=api-frameaddscripttagoptions)v0.9.0
- [frame.addStyleTag(options)](#?product=Puppeteer&version=v1.11.0&show=api-frameaddstyletagoptions)v0.9.0
- [frame.childFrames()](#?product=Puppeteer&version=v1.11.0&show=api-framechildframes)v0.9.0
- [frame.click(selector\[, options\])](#?product=Puppeteer&version=v1.11.0&show=api-frameclickselector-options)v0.9.0
- [frame.content()](#?product=Puppeteer&version=v1.11.0&show=api-framecontent)v0.9.0
- [frame.evaluate(pageFunction, ...args)](#?product=Puppeteer&version=v1.11.0&show=api-frameevaluatepagefunction-args)v0.9.0
- [frame.evaluateHandle(pageFunction, ...args)](#?product=Puppeteer&version=v1.11.0&show=api-frameevaluatehandlepagefunction-args)v0.9.0
- [frame.executionContext()](#?product=Puppeteer&version=v1.11.0&show=api-frameexecutioncontext)v0.9.0
- [frame.focus(selector)](#?product=Puppeteer&version=v1.11.0&show=api-framefocusselector)v0.9.0
- [frame.goto(url, options)](#?product=Puppeteer&version=v1.11.0&show=api-framegotourl-options)v0.9.0
- [frame.hover(selector)](#?product=Puppeteer&version=v1.11.0&show=api-framehoverselector)v0.9.0
- [frame.isDetached()](#?product=Puppeteer&version=v1.11.0&show=api-frameisdetached)v0.9.0
- [frame.name()](#?product=Puppeteer&version=v1.11.0&show=api-framename)v0.9.0
- [frame.parentFrame()](#?product=Puppeteer&version=v1.11.0&show=api-frameparentframe)v0.9.0
- [frame.select(selector, ...values)](#?product=Puppeteer&version=v1.11.0&show=api-frameselectselector-values)v0.9.0
- [frame.setContent(html)](#?product=Puppeteer&version=v1.11.0&show=api-framesetcontenthtml)v0.9.0
- [frame.tap(selector)](#?product=Puppeteer&version=v1.11.0&show=api-frametapselector)v0.9.0
- [frame.title()](#?product=Puppeteer&version=v1.11.0&show=api-frametitle)v0.9.0
- [frame.type(selector, text\[, options\])](#?product=Puppeteer&version=v1.11.0&show=api-frametypeselector-text-options)v0.9.0
- [frame.url()](#?product=Puppeteer&version=v1.11.0&show=api-frameurl)v0.9.0
- [frame.waitFor(selectorOrFunctionOrTimeout\[, options\[, ...args\]\])](#?product=Puppeteer&version=v1.11.0&show=api-framewaitforselectororfunctionortimeout-options-args)v0.9.0
- [frame.waitForFunction(pageFunction\[, options\[, ...args\]\])](#?product=Puppeteer&version=v1.11.0&show=api-framewaitforfunctionpagefunction-options-args)v0.9.0
- [frame.waitForNavigation(options)](#?product=Puppeteer&version=v1.11.0&show=api-framewaitfornavigationoptions)v0.9.0
- [frame.waitForSelector(selector\[, options\])](#?product=Puppeteer&version=v1.11.0&show=api-framewaitforselectorselector-options)v0.9.0
- [frame.waitForXPath(xpath\[, options\])](#?product=Puppeteer&version=v1.11.0&show=api-framewaitforxpathxpath-options)v0.9.0
### Methods
#### frame.$(selector)v0.9.0
- `selector` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Selector to query frame for
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<?[ElementHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-elementhandle "ElementHandle")>> Promise which resolves to ElementHandle pointing to the frame element.
这个方法在框架中查询指定的选择器。如果在框架中没有匹配的元素会返回 `null`
#### frame.$$(selector)v0.9.0
- `selector` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Selector to query frame for
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array")<[ElementHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-elementhandle "ElementHandle")>>> Promise which resolves to ElementHandles pointing to the frame elements.
这个方法会在框架中执行 `document.querySelectorAll` 方法。如果没有元素匹配会返回 `[]`
#### frame.$$eval(selector, pageFunction\[, ...args\])v0.9.0
- `selector` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector") to query frame for
- `pageFunction` <[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function")> Function to be evaluated in browser context
- `...args` <...[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable")|[JSHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-jshandle "JSHandle")> Arguments to pass to `pageFunction`
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable")>> Promise which resolves to the return value of `pageFunction`
这个方法会在框架中执行 `Array.from(document.querySelectorAll(selector))` 方法，然后将返回值传给 `pageFunction` 函数的第一个参数。
如果 `pageFunction` 返回了一个[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"),那么 `frame.$$eval` 将会等待Promise resolve之后返回它的值。
例子：
```
const divsCounts = await frame.$$eval('div', divs => divs.length);
```
#### frame.$eval(selector, pageFunction\[, ...args\])v0.9.0
- `selector` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector") to query frame for
- `pageFunction` <[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function")> Function to be evaluated in browser context
- `...args` <...[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable")|[JSHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-jshandle "JSHandle")> Arguments to pass to `pageFunction`
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable")>> Promise which resolves to the return value of `pageFunction`
这个方法会在框架中执行 `document.querySelector` 方法，然后将返回值传给 `pageFunction` 函数的第一个参数。如果没有匹配到任何元素，则会抛出一个错误。
如果 `pageFunction` 返回了一个 [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise"),那么 `frame.$eval` 将会等待 Promise 并解析后返回它的值。
例如:
```
const searchValue = await frame.$eval('#search', el => el.value);const preloadHref = await frame.$eval('link[rel=preload]', el => el.href);const html = await frame.$eval('.main-container', e => e.outerHTML);
```
#### frame.$x(expression)v0.9.0
- `expression` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Expression to [evaluate](https://developer.mozilla.org/en-US/docs/Web/API/Document/evaluate).
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array")<[ElementHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-elementhandle "ElementHandle")>>>
这个方法用来执行 XPath 表达式。
#### frame.addScriptTag(options)v0.9.0
- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object")>
- `url` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> URL of a script to be added.
- `path` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Path to the JavaScript file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Raw JavaScript content to be injected into frame.
- `type` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Script type. Use 'module' in order to load a Javascript ES6 module. See [script](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/script) for more details.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[ElementHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-elementhandle "ElementHandle")>> which resolves to the added tag when the script's onload fires or when the script content was injected into frame.
将 url 或脚本内容添加到 `<script>` 标签中。
#### frame.addStyleTag(options)v0.9.0
- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object")>
- `url` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> URL of the `<link>` tag.
- `path` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Path to the CSS file to be injected into frame. If `path` is a relative path, then it is resolved relative to [current working directory](https://nodejs.org/api/process.html#process_process_cwd).
- `content` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Raw CSS content to be injected into frame.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[ElementHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-elementhandle "ElementHandle")>> which resolves to the added tag when the stylesheet's onload fires or when the CSS content was injected into frame.
根据样式路径或内容往页面中添加 `<link rel="stylesheet">` 或 `<style type="text/css">` 样式标签。
#### frame.childFrames()v0.9.0
- returns: <[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array")<[Frame](#?product=Puppeteer&version=v1.11.0&show=api-class-frame "Frame")>>
#### frame.click(selector\[, options\])v0.9.0
- `selector` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector") to search for element to click. If there are multiple elements satisfying the selector, the first will be clicked.
- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object")>
- `button` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> `left`, `right`, or `middle`, defaults to `left`.
- `clickCount` <[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number")> defaults to 1. See [UIEvent.detail](https://developer.mozilla.org/en-US/docs/Web/API/UIEvent/detail "UIEvent.detail").
- `delay` <[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number")> Time to wait between `mousedown` and `mouseup` in milliseconds. Defaults to 0.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")> Promise which resolves when the element matching `selector` is successfully clicked. The Promise will be rejected if there is no element matching `selector`.
这个方法选择传入的元素，如果必要的话会将元素滚动到可视区域，之后使用 [page.mouse](#?product=Puppeteer&version=v1.11.0&show=api-pagemouse) 点击元素的内容。如果没有匹配到元素，会抛出异常。
注意：如果 `click()` 触发了导航事件，那么就会有一个由 `page.waitForNavigation()` 产生的 promise 要被解析，你可能会得到一个 promise 的竞争状态。正确的处理 click 和 wait for navigation 的方式如下：
```
const [response] = await Promise.all([ page.waitForNavigation(waitOptions), frame.click(selector, clickOptions),]);
```
#### frame.content()v0.9.0
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[String](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")>>
获取框架完整的HTML内容，包括 doctype。
#### frame.evaluate(pageFunction, ...args)v0.9.0
- `pageFunction` <[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function")|[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Function to be evaluated in browser context
- `...args` <...[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable")|[JSHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-jshandle "JSHandle")> Arguments to pass to `pageFunction`
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable")>> Promise which resolves to the return value of `pageFunction`
如果传给 `frame.evaluate` 的函数返回了一个 promise，那么 `frame.evaluate` 将会等到 promise resolve 时返回它的值。
如果传给 `frame.evaluate` 的函数返回了一个非序列化的值，那么 `frame.evaluate` 将返回 `undefined`
```
const result = await frame.evaluate(() => { return Promise.resolve(8 * 7);});console.log(result); // 输出 "56"
```
也可以给函数传递字符串。
```
console.log(await frame.evaluate('1 + 2')); // 输出 "3"
```
[ElementHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-elementhandle "ElementHandle") 实例也可以作为 `frame.evaluate` 的参数：
```
const bodyHandle = await frame.$('body');const html = await frame.evaluate(body => body.innerHTML, bodyHandle);await bodyHandle.dispose();
```
#### frame.evaluateHandle(pageFunction, ...args)v0.9.0
- `pageFunction` <[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function")|[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Function to be evaluated in the page context
- `...args` <...[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable")|[JSHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-jshandle "JSHandle")> Arguments to pass to `pageFunction`
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[JSHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-jshandle "JSHandle")>> Promise which resolves to the return value of `pageFunction` as in-page object (JSHandle)
`frame.evaluate` 和 `frame.evaluateHandle` 唯一的不同是 `frame.evaluateHandle` 返回页面对象（JSHandle）。
如果传给 `frame.evaluateHandle`的函数返回了一个 [Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")，那么 `frame.evaluateHandle` 将会等到 promise resolve 时返回它的值。
```
const aWindowHandle = await frame.evaluateHandle(() => Promise.resolve(window));aWindowHandle; // Handle for the window object.
```
也可以向函数传递字符串。
```
const aHandle = await frame.evaluateHandle('document'); // Handle for the 'document'.
```
[JSHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-jshandle "JSHandle") 实例也可以作为 `frame.evaluateHandle` 的参数:
```
const aHandle = await frame.evaluateHandle(() => document.body);const resultHandle = await frame.evaluateHandle(body => body.innerHTML, aHandle);console.log(await resultHandle.jsonValue());await resultHandle.dispose();
```
#### frame.executionContext()v0.9.0
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[ExecutionContext](#?product=Puppeteer&version=v1.11.0&show=api-class-executioncontext "ExecutionContext")>>
返回解析为框架的默认执行上下文的 promise。
#### frame.focus(selector)v0.9.0
- `selector` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> 一个选择器元素。A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector") of an element to focus. If there are multiple elements satisfying the selector, the first will be focused.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")> Promise which resolves when the element matching `selector` is successfully focused. The promise will be rejected if there is no element matching `selector`.
这个方法选择传入的元素并且使之获得焦点。如果没有匹配到元素，会抛出异常。
#### frame.goto(url, options)v0.9.0
- `url` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> URL to navigate frame to. The url should include scheme, e.g. `https://`.
- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object")> Navigation parameters which might have the following properties:
- `timeout` <[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number")> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#?product=Puppeteer&version=v1.11.0&show=api-pagesetdefaultnavigationtimeouttimeout) method.
- `waitUntil` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")|[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array")<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
- `load` - consider navigation to be finished when the `load` event is fired.
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
- `referer` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Referer header value. If provided it will take preference over the referer header value set by [page.setExtraHTTPHeaders()](#?product=Puppeteer&version=v1.11.0&show=api-pagesetextrahttpheadersheaders).
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<?[Response](#?product=Puppeteer&version=v1.11.0&show=api-class-response "Response")>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect.
如果存在下面的情况 `frame.goto` 将会抛出错误：
- SSL 错误 (e.g. in case of self-signed certificates).
- 目标 URL 不可用。
- 导航过程中 `timeout` 被触发。
- 主资源加载失败。
> **注意**`frame.goto`抛出或返回一个主资源响应。 唯一的例外是导航到`about：blank`或导航到具有不同 hash 的相同URL，这将成功并返回`null`。
>
> **注意** 无头模式将不支持导航到一个 PDF 文档。具体见 [upstream issue](https://bugs.chromium.org/p/chromium/issues/detail?id=761295).
#### frame.hover(selector)v0.9.0
- `selector` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector") to search for element to hover. If there are multiple elements satisfying the selector, the first will be hovered.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")> Promise which resolves when the element matching `selector` is successfully hovered. Promise gets rejected if there's no element matching `selector`.
这个方法选择传入的元素，如果必要的话会滚动到视野区域中，然后使用 [page.mouse](#?product=Puppeteer&version=v1.11.0&show=api-pagemouse) 方法将鼠标悬浮在元素的中心。
如果没有匹配到元素，会抛出异常。
#### frame.isDetached()v0.9.0
- returns: <[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean")>
如果框架不被加载了返回 `true`，否则返回 `false`。
#### frame.name()v0.9.0
- returns: <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")>
返回框架在标签中指定的 name 属性。
如果 name 为空，返回 id。
> **注意** 这个值在框架创建的时侯就就计算好了，如果之后修改属性的话不会更新。
#### frame.parentFrame()v0.9.0
- returns: <?[Frame](#?product=Puppeteer&version=v1.11.0&show=api-class-frame "Frame")> Returns parent frame, if any. Detached frames and main frames return `null`.
#### frame.select(selector, ...values)v0.9.0
- `selector` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector") to query frame for
- `...values` <...[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> 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.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array")<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")>>> Returns an array of option values that have been successfully selected.
下拉框一旦选择了所提供的选项，`change` 和 `input` 事件将会被触发。
如果没有匹配到下拉框，会抛出异常。
```
frame.select('select#colors', 'blue'); // 单选frame.select('select#colors', 'red', 'green', 'blue'); // 多选
```
#### frame.setContent(html)v0.9.0
- `html` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> HTML markup to assign to the page.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")>
#### frame.tap(selector)v0.9.0
- `selector` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector") to search for element to tap. If there are multiple elements satisfying the selector, the first will be tapped.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")>
这个方法选择传入的元素，如果必要的话会滚动到视野区域中，然后使用 [page.touchscreen](#?product=Puppeteer&version=v1.11.0&show=api-pagemouse) 方法单击元素中心。
如果没有匹配到元素，会抛出异常。
#### frame.title()v0.9.0
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")>> Returns page's title.
#### frame.type(selector, text\[, options\])v0.9.0
- `selector` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector") of an element to type into. If there are multiple elements satisfying the selector, the first will be used.
- `text` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> A text to type into a focused element.
- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object")>
- `delay` <[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number")> Time to wait between key presses in milliseconds. Defaults to 0.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")>
对于每一个文本中的字符执行 `keydown`、`keypress` / `input`, 和 `keyup` 事件
如果要输入特殊按键，比如 `Control` 或者 `ArrowDown`,使用 [`keyboard.press`](#?product=Puppeteer&version=v1.11.0&show=api-keyboardpresskey-options)。
```
frame.type('#mytextarea', 'Hello'); // 立即输入frame.type('#mytextarea', 'World', {delay: 100}); // 延迟输入, 操作更像用户
```
#### frame.url()v0.9.0
- returns: <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")>
返回框架的 url。
#### frame.waitFor(selectorOrFunctionOrTimeout\[, options\[, ...args\]\])v0.9.0
- `selectorOrFunctionOrTimeout` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")|[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number")|[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function")> A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector"), predicate or timeout to wait for
- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object")> Optional waiting parameters
- `...args` <...[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable")|[JSHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-jshandle "JSHandle")> Arguments to pass to `pageFunction`
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[JSHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-jshandle "JSHandle")>> Promise which resolves to a JSHandle of the success value
这个方法根据第一个参数类型的不同起到不同的作用：
- 如果 `selectorOrFunctionOrTimeout` 是 `string`，那么第一个参数会被当作 [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector") 或者 [xpath](https://developer.mozilla.org/en-US/docs/Web/XPath "xpath")，取决于是不是以`//`开头的，这是 [frame.waitForSelector](#?product=Puppeteer&version=v1.11.0&show=api-framewaitforselectorselector-options) 或 [frame.waitForXPath](#?product=Puppeteer&version=v1.11.0&show=api-framewaitforxpathxpath-options) 的快捷方式。
- 如果 `selectorOrFunctionOrTimeout` 是 `function`，那么第一个参数会当作条件等待触发，这是 [frame.waitForFunction()](#?product=Puppeteer&version=v1.11.0&show=api-framewaitforfunctionpagefunction-options-args) 的快捷方式。
- 如果 `selectorOrFunctionOrTimeout` 是 `number`，那么第一个参数会被当作毫秒为单位的时间，方法会在超时之后返回 promise。
- 其他类型，将会抛出错误。
// wait for selectorawait page.waitFor('.foo');// wait for 1 secondawait page.waitFor(1000);// wait for predicateawait page.waitFor(() => !!document.querySelector('.foo'));
将 node.js 中的参数传递给 `page.waitFor` 函数：
```
const selector = '.foo';await page.waitFor(selector => !!document.querySelector(selector), {}, selector);
```
#### frame.waitForFunction(pageFunction\[, options\[, ...args\]\])v0.9.0
- `pageFunction` <[function](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Function "Function")|[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> Function to be evaluated in browser context
- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object")> Optional waiting parameters
- `polling` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")|[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number")> An interval at which the `pageFunction` is executed, defaults to `raf`. If `polling` is a number, then it is treated as an interval in milliseconds at which the function would be executed. If `polling` is a string, then it can be one of the following values:
- `raf` - to constantly execute `pageFunction` in `requestAnimationFrame` callback. This is the tightest polling mode which is suitable to observe styling changes.
- `mutation` - to execute `pageFunction` on every DOM mutation.
- `timeout` <[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number")> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
- `...args` <...[Serializable](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#Description "Serializable")|[JSHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-jshandle "JSHandle")> Arguments to pass to `pageFunction`
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[JSHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-jshandle "JSHandle")>> Promise which resolves when the `pageFunction` returns a truthy value. It resolves to a JSHandle of the truthy value.
`waitForFunction` 可以用来观察可视区域大小是否改变。
```
const puppeteer = require('puppeteer');puppeteer.launch().then(async browser => { const page = await browser.newPage(); const watchDog = page.mainFrame().waitForFunction('window.innerWidth < 100'); page.setViewport({width: 50, height: 50}); await watchDog; await browser.close();});
```
将 node.js 中的参数传递给 `page.waitForFunction` 函数：
```
const selector = '.foo';await page.waitForFunction(selector => !!document.querySelector(selector), {}, selector);
```
#### frame.waitForNavigation(options)v0.9.0
- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object")> Navigation parameters which might have the following properties:
- `timeout` <[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number")> Maximum navigation time in milliseconds, defaults to 30 seconds, pass `0` to disable timeout. The default value can be changed by using the [page.setDefaultNavigationTimeout(timeout)](#?product=Puppeteer&version=v1.11.0&show=api-pagesetdefaultnavigationtimeouttimeout) method.
- `waitUntil` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")|[Array](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array "Array")<[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")>> When to consider navigation succeeded, defaults to `load`. Given an array of event strings, navigation is considered to be successful after all events have been fired. Events can be either:
- `load` - consider navigation to be finished when the `load` event is fired.
- `domcontentloaded` - consider navigation to be finished when the `DOMContentLoaded` event is fired.
- `networkidle0` - consider navigation to be finished when there are no more than 0 network connections for at least `500` ms.
- `networkidle2` - consider navigation to be finished when there are no more than 2 network connections for at least `500` ms.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<\[?Response\]>> Promise which resolves to the main resource response. In case of multiple redirects, the navigation will resolve with the response of the last redirect. In case of navigation to a different anchor or navigation due to History API usage, the navigation will resolve with `null`.
当框架导航到新 URL 时将被解析。它在运行代码时很有用。这将间接导致框架进行导航。看下这个例子：
```
const [response] = await Promise.all([ frame.waitForNavigation(), // The navigation promise resolves after navigation has finished frame.click('a.my-link'), // Clicking the link will indirectly cause a navigation]);
```
**注意** 使用 [History API](https://developer.mozilla.org/en-US/docs/Web/API/History_API) 去改变 URL 将会被认为是导航。
#### frame.waitForSelector(selector\[, options\])v0.9.0
- `selector` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> A [selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors "selector") of an element to wait for
- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object")> Optional waiting parameters
- `visible` <[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean")> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `hidden` <[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean")> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `timeout` <[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number")> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[ElementHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-elementhandle "ElementHandle")>> Promise which resolves when element specified by selector string is added to DOM.
等待被选择等待元素出现在页面中。如果调用时选择的元素已存在，则立即返回。如果在设定的毫秒时间之后还没有出现，则抛出异常。
这个方法可以在切换导航时使用:
```
const puppeteer = require('puppeteer');puppeteer.launch().then(async browser => { const page = await browser.newPage(); let currentURL; page.mainFrame() .waitForSelector('img') .then(() => console.log('First URL with image: ' + currentURL)); for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) await page.goto(currentURL); await browser.close();});
```
#### frame.waitForXPath(xpath\[, options\])v0.9.0
- `xpath` <[string](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#String_type "String")> A [xpath](https://developer.mozilla.org/en-US/docs/Web/XPath "xpath") of an element to wait for
- `options` <[Object](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object "Object")> Optional waiting parameters
- `visible` <[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean")> wait for element to be present in DOM and to be visible, i.e. to not have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `hidden` <[boolean](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Boolean_type "Boolean")> wait for element to not be found in the DOM or to be hidden, i.e. have `display: none` or `visibility: hidden` CSS properties. Defaults to `false`.
- `timeout` <[number](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Data_structures#Number_type "Number")> maximum time to wait for in milliseconds. Defaults to `30000` (30 seconds). Pass `0` to disable timeout.
- returns: <[Promise](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise "Promise")<[ElementHandle](#?product=Puppeteer&version=v1.11.0&show=api-class-elementhandle "ElementHandle")>> Promise which resolves when element specified by xpath string is added to DOM.
等待 `xpath` 出现在页面中。如果在调用函数的时候 `xpath` 已经存在，会立即返回。如果在设定的毫秒时间之后还没有出现，则抛出异常。
这个方法可以在切换导航时使用:
```
const puppeteer = require('puppeteer');puppeteer.launch().then(async browser => { const page = await browser.newPage(); let currentURL; page.mainFrame() .waitForXPath('//img') .then(() => console.log('First URL with image: ' + currentURL)); for (currentURL of ['https://example.com', 'https://google.com', 'https://bbc.com']) await page.goto(currentURL); await browser.close();});
```
puppeteer.js中文网|class:frame
puppeteer.js中文文档, puppeteer chrome, puppeteer firefox, puppeteer api 中文文档
puppeteer.js中文网包含了Puppeteer中文文档，最新资讯，应用案例等。Puppeteer 是一个 Node 库，它提供了一个高级 API 来通过 DevTools 协议控制 Chromium 或 Chrome。
- Introduction
- 版本记录
- 概要
- puppeteer-vs-puppeteer-core
- 环境变量
- error-handling
- working-with-chrome-extensions
- class:puppeteer
- class:browserfetcher
- class:browser
- class:page
- class:worker
- class:accessibility
- class:keyboard
- class:mouse
- class:touchscreen
- class:tracing
- class:dialog
- class:consolemessage
- class:frame
- class:executioncontext
- class:jshandle
- class:elementhandle
- class:request
- class:response
- class:securitydetails
- class:target
- class:cdpsession
- class:coverage
- class:timeouterror