electron/docs/api/web-frame.md

267 lines
7.6 KiB
Markdown
Raw Normal View History

2015-08-29 06:20:49 +00:00
# webFrame
2014-06-16 06:56:24 +00:00
2016-04-21 22:39:12 +00:00
> Customize the rendering of the current web page.
2014-06-16 06:56:24 +00:00
2016-11-23 19:20:56 +00:00
Process: [Renderer](../glossary.md#renderer-process)
2016-11-03 17:26:00 +00:00
2018-01-09 19:41:40 +00:00
`webFrame` export of the electron module is an instance of the `WebFrame`
class representing the top frame of the current `BrowserWindow`. Sub-frames can
be retrieved by certain properties and methods (e.g. `webFrame.firstChild`)
2014-06-16 06:56:24 +00:00
An example of zooming current page to 200%.
```javascript
const {webFrame} = require('electron')
2015-08-29 06:20:49 +00:00
webFrame.setZoomFactor(2)
2014-06-16 06:56:24 +00:00
```
2015-08-29 06:20:49 +00:00
## Methods
2018-01-09 19:41:40 +00:00
The `WebFrame` class has the following instance methods:
2015-08-29 06:20:49 +00:00
### `webFrame.setZoomFactor(factor)`
2014-06-16 06:56:24 +00:00
2015-08-29 06:20:49 +00:00
* `factor` Number - Zoom factor.
2014-06-16 06:56:24 +00:00
2015-09-02 16:57:29 +00:00
Changes the zoom factor to the specified factor. Zoom factor is
zoom percent divided by 100, so 300% = 3.0.
2014-06-16 06:56:24 +00:00
2015-08-29 06:20:49 +00:00
### `webFrame.getZoomFactor()`
2014-06-16 06:56:24 +00:00
Returns `Number` - The current zoom factor.
2014-06-16 06:56:24 +00:00
2015-08-29 06:20:49 +00:00
### `webFrame.setZoomLevel(level)`
2014-06-16 06:56:24 +00:00
* `level` Number - Zoom level.
2014-06-16 06:56:24 +00:00
2015-09-01 03:05:57 +00:00
Changes the zoom level to the specified level. The original size is 0 and each
2014-06-16 06:56:24 +00:00
increment above or below represents zooming 20% larger or smaller to default
limits of 300% and 50% of original size, respectively.
2015-08-29 06:20:49 +00:00
### `webFrame.getZoomLevel()`
2014-06-16 06:56:24 +00:00
Returns `Number` - The current zoom level.
2014-12-20 06:34:34 +00:00
### `webFrame.setVisualZoomLevelLimits(minimumLevel, maximumLevel)`
2016-11-21 20:16:13 +00:00
* `minimumLevel` Number
* `maximumLevel` Number
Sets the maximum and minimum pinch-to-zoom level.
### `webFrame.setLayoutZoomLevelLimits(minimumLevel, maximumLevel)`
* `minimumLevel` Number
* `maximumLevel` Number
2016-11-21 20:16:13 +00:00
Sets the maximum and minimum layout-based (i.e. non-visual) zoom level.
2015-08-27 14:08:25 +00:00
2015-08-29 06:20:49 +00:00
### `webFrame.setSpellCheckProvider(language, autoCorrectWord, provider)`
2014-12-20 06:34:34 +00:00
* `language` String
* `autoCorrectWord` Boolean
* `provider` Object
* `spellCheck` Function - Returns `Boolean`.
2016-11-25 12:33:31 +00:00
* `text` String
2014-12-20 06:34:34 +00:00
Sets a provider for spell checking in input fields and text areas.
The `provider` must be an object that has a `spellCheck` method that returns
whether the word passed is correctly spelled.
An example of using [node-spellchecker][spellchecker] as provider:
```javascript
const {webFrame} = require('electron')
webFrame.setSpellCheckProvider('en-US', true, {
spellCheck (text) {
return !(require('spellchecker').isMisspelled(text))
2014-12-20 06:34:34 +00:00
}
})
2014-12-20 06:34:34 +00:00
```
2015-11-13 08:03:40 +00:00
### `webFrame.registerURLSchemeAsSecure(scheme)`
* `scheme` String
Registers the `scheme` as secure scheme.
Secure schemes do not trigger mixed content warnings. For example, `https` and
`data` are secure schemes because they cannot be corrupted by active network
attackers.
2015-11-13 08:03:40 +00:00
### `webFrame.registerURLSchemeAsBypassingCSP(scheme)`
* `scheme` String
2015-08-29 06:20:49 +00:00
Resources will be loaded from this `scheme` regardless of the current page's
Content Security Policy.
### `webFrame.registerURLSchemeAsPrivileged(scheme[, options])`
* `scheme` String
* `options` Object (optional)
2017-11-28 17:15:15 +00:00
* `secure` Boolean (optional) - Default true.
* `bypassCSP` Boolean (optional) - Default true.
* `allowServiceWorkers` Boolean (optional) - Default true.
* `supportFetchAPI` Boolean (optional) - Default true.
* `corsEnabled` Boolean (optional) - Default true.
Registers the `scheme` as secure, bypasses content security policy for resources,
allows registering ServiceWorker and supports fetch API.
Specify an option with the value of `false` to omit it from the registration.
An example of registering a privileged scheme, without bypassing Content Security Policy:
```javascript
const {webFrame} = require('electron')
webFrame.registerURLSchemeAsPrivileged('foo', { bypassCSP: false })
```
2016-01-13 03:21:16 +00:00
### `webFrame.insertText(text)`
* `text` String
2016-01-13 03:55:49 +00:00
Inserts `text` to the focused element.
2016-01-13 03:21:16 +00:00
2016-11-25 12:33:31 +00:00
### `webFrame.executeJavaScript(code[, userGesture, callback])`
2016-01-13 04:20:49 +00:00
* `code` String
* `userGesture` Boolean (optional) - Default is `false`.
2016-11-25 12:33:31 +00:00
* `callback` Function (optional) - Called after script has been executed.
* `result` Any
2016-01-13 04:20:49 +00:00
Returns `Promise` - A promise that resolves with the result of the executed code
or is rejected if the result of the code is a rejected promise.
2016-01-13 04:20:49 +00:00
Evaluates `code` in page.
In the browser window some HTML APIs like `requestFullScreen` can only be
invoked by a gesture from the user. Setting `userGesture` to `true` will remove
this limitation.
### `webFrame.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture, callback])`
* `worldId` Integer
* `scripts` [WebSource[]](structures/web-source.md)
* `userGesture` Boolean (optional) - Default is `false`.
* `callback` Function (optional) - Called after script has been executed.
* `result` Any
Work like `executeJavaScript` but evaluates `scripts` in isolated context.
### `webFrame.setIsolatedWorldContentSecurityPolicy(worldId, csp)`
* `worldId` Integer
* `csp` String
Set the content security policy of the isolated world.
### `webFrame.setIsolatedWorldHumanReadableName(worldId, name)`
* `worldId` Integer
* `name` String
Set the name of the isolated world. Useful in devtools.
### `webFrame.setIsolatedWorldSecurityOrigin(worldId, securityOrigin)`
* `worldId` Integer
* `securityOrigin` String
Set the security origin of the isolated world.
2016-05-12 22:03:47 +00:00
### `webFrame.getResourceUsage()`
Returns `Object`:
2016-10-25 03:35:18 +00:00
* `images` [MemoryUsageDetails](structures/memory-usage-details.md)
* `cssStyleSheets` [MemoryUsageDetails](structures/memory-usage-details.md)
* `xslStyleSheets` [MemoryUsageDetails](structures/memory-usage-details.md)
* `fonts` [MemoryUsageDetails](structures/memory-usage-details.md)
* `other` [MemoryUsageDetails](structures/memory-usage-details.md)
Returns an object describing usage information of Blink's internal memory
caches.
2016-05-12 22:03:47 +00:00
```javascript
const {webFrame} = require('electron')
console.log(webFrame.getResourceUsage())
```
This will generate:
2016-08-16 21:50:21 +00:00
```javascript
2016-05-12 22:03:47 +00:00
{
images: {
count: 22,
size: 2549,
liveSize: 2542
2016-05-12 22:03:47 +00:00
},
cssStyleSheets: { /* same with "images" */ },
xslStyleSheets: { /* same with "images" */ },
fonts: { /* same with "images" */ },
other: { /* same with "images" */ }
2016-08-16 21:49:42 +00:00
}
2016-05-12 22:03:47 +00:00
```
### `webFrame.clearCache()`
2016-05-12 22:03:47 +00:00
Attempts to free memory that is no longer being used (like images from a
previous navigation).
2016-05-12 22:03:47 +00:00
Note that blindly calling this method probably makes Electron slower since it
will have to refill these emptied caches, you should only call it if an event
2016-06-16 22:19:38 +00:00
in your app has occurred that makes you think your page is actually using less
2016-05-12 22:03:47 +00:00
memory (i.e. you have navigated from a super heavy page to a mostly empty one,
and intend to stay there).
2016-05-12 22:03:47 +00:00
2014-12-20 06:34:34 +00:00
[spellchecker]: https://github.com/atom/node-spellchecker
2018-01-09 19:41:40 +00:00
### `webFrame.getFrameForSelector(selector)`
* Returns `WebFrame` for the frame element in `webFrame's` document selected by
`selector`
* Returns `null` if `selector` does not select a frame or if the frame is not in
the current renderer process.
* `selector` String - CSS selector for a frame element
### `webFrame.findFrameByName(name)`
* Returns `WebFrame` - a child of `webFrame` with the supplied `name`
* Returns `null` if there's no such frame or if the frame is not in the current
renderer process.
## Properties
### `webFrame.top`
* Returns `WebFrame` - top frame in frame hierarchy to which `webFrame` belongs
* Returns `null` if top frame is not in the current renderer process.
### `webFrame.opener`
* Returns `WebFrame` - frame which opened `webFrame`
* Returns `null` if there's no opener or opener is not in the current renderer
process.
### `webFrame.parent`
* Returns `WebFrame` - parent frame of `webFrame`
* Returns `null` if `webFrame` is top or parent is not in the current renderer
process.
### `webFrame.firstChild`
* Returns `WebFrame` - first child frame of `webFrame`
* Returns `null` if `webFrame` has no children or if first child is not in the
current renderer process.
### `webFrame.nextSibling`
* Returns `WebFrame` - next sibling frame
* Returns `null` if `webFrame` is the last frame its parent or if the next
sibling is not in the current renderer process.