2015-08-20 13:17:53 +00:00
# webContents
`webContents` is an
[EventEmitter ](http://nodejs.org/api/events.html#events_class_events_eventemitter ).
2015-08-24 22:41:02 +00:00
It is responsible for rendering and controlling a web page and is a property of
the [`BrowserWindow` ](browser-window.md ) object. An example of accessing the
`webContents` object:
2015-08-20 13:17:53 +00:00
```javascript
2015-11-12 13:20:09 +00:00
const BrowserWindow = require('electron').BrowserWindow;
2015-08-20 13:17:53 +00:00
2015-08-20 17:03:53 +00:00
var win = new BrowserWindow({width: 800, height: 1500});
2015-11-13 08:03:40 +00:00
win.loadURL("http://github.com");
2015-08-20 13:17:53 +00:00
2015-08-26 20:57:42 +00:00
var webContents = win.webContents;
2015-08-20 13:17:53 +00:00
```
## Events
The `webContents` object emits the following events:
### Event: 'did-finish-load'
Emitted when the navigation is done, i.e. the spinner of the tab has stopped
spinning, and the `onload` event was dispatched.
### Event: 'did-fail-load'
Returns:
* `event` Event
* `errorCode` Integer
* `errorDescription` String
2015-11-13 08:03:40 +00:00
* `validatedURL` String
2015-08-20 13:17:53 +00:00
This event is like `did-finish-load` but emitted when the load failed or was
cancelled, e.g. `window.stop()` is invoked.
2015-10-25 15:00:29 +00:00
The full list of error codes and their meaning is available [here ](https://code.google.com/p/chromium/codesearch#chromium/src/net/base/net_error_list.h ).
2015-08-20 13:17:53 +00:00
### Event: 'did-frame-finish-load'
Returns:
* `event` Event
* `isMainFrame` Boolean
Emitted when a frame has done navigation.
### Event: 'did-start-loading'
Corresponds to the points in time when the spinner of the tab started spinning.
### Event: 'did-stop-loading'
Corresponds to the points in time when the spinner of the tab stopped spinning.
### Event: 'did-get-response-details'
Returns:
* `event` Event
* `status` Boolean
2015-11-13 08:03:40 +00:00
* `newURL` String
* `originalURL` String
2015-08-20 13:17:53 +00:00
* `httpResponseCode` Integer
* `requestMethod` String
* `referrer` String
* `headers` Object
2015-08-26 20:57:42 +00:00
Emitted when details regarding a requested resource are available.
2015-08-20 13:17:53 +00:00
`status` indicates the socket connection to download the resource.
### Event: 'did-get-redirect-request'
Returns:
* `event` Event
2015-11-13 08:03:40 +00:00
* `oldURL` String
* `newURL` String
2015-08-20 13:17:53 +00:00
* `isMainFrame` Boolean
2015-09-18 10:01:31 +00:00
* `httpResponseCode` Integer
* `requestMethod` String
* `referrer` String
* `headers` Object
2015-08-20 13:17:53 +00:00
2015-08-26 20:57:42 +00:00
Emitted when a redirect is received while requesting a resource.
2015-08-20 13:17:53 +00:00
### Event: 'dom-ready'
Returns:
* `event` Event
Emitted when the document in the given frame is loaded.
### Event: 'page-favicon-updated'
Returns:
* `event` Event
2015-11-13 08:03:40 +00:00
* `favicons` Array - Array of URLs
2015-08-20 13:17:53 +00:00
Emitted when page receives favicon urls.
### Event: 'new-window'
Returns:
* `event` Event
* `url` String
* `frameName` String
* `disposition` String - Can be `default` , `foreground-tab` , `background-tab` ,
2015-08-26 20:57:42 +00:00
`new-window` and `other` .
2015-09-22 15:41:08 +00:00
* `options` Object - The options which will be used for creating the new
`BrowserWindow` .
2015-08-20 13:17:53 +00:00
Emitted when the page requests to open a new window for a `url` . It could be
requested by `window.open` or an external link like `<a target='_blank'>` .
By default a new `BrowserWindow` will be created for the `url` .
2015-08-26 20:57:42 +00:00
Calling `event.preventDefault()` will prevent creating new windows.
2015-08-20 13:17:53 +00:00
### Event: 'will-navigate'
Returns:
* `event` Event
* `url` String
2016-01-04 04:09:11 +00:00
Emitted when a user or the page wants to start navigation. It can happen when
the `window.location` object is changed or a user clicks a link in the page.
2015-08-20 13:17:53 +00:00
2015-08-24 22:41:02 +00:00
This event will not emit when the navigation is started programmatically with
2015-11-13 08:03:40 +00:00
APIs like `webContents.loadURL` and `webContents.back` .
2015-08-20 13:17:53 +00:00
2016-01-04 04:09:11 +00:00
It is also not emitted for in-page navigations, such as clicking anchor links
or updating the `window.location.hash` . Use `did-navigate-in-page` event for
this purpose.
2016-01-02 00:05:27 +00:00
2015-08-26 20:57:42 +00:00
Calling `event.preventDefault()` will prevent the navigation.
2015-08-20 13:17:53 +00:00
2016-01-04 04:09:11 +00:00
### Event: 'did-navigate'
2016-01-02 00:05:27 +00:00
2016-01-04 04:09:11 +00:00
Returns:
* `event` Event
* `url` String
Emitted when a navigation is done.
This event is not emitted for in-page navigations, such as clicking anchor links
or updating the `window.location.hash` . Use `did-navigate-in-page` event for
this purpose.
2016-01-02 00:05:27 +00:00
### Event: 'did-navigate-in-page'
2016-01-04 04:09:11 +00:00
Returns:
* `event` Event
* `url` String
Emitted when an in-page navigation happened.
When in-page navigation happens, the page URL changes but does not cause
navigation outside of the page. Examples of this occurring are when anchor links
are clicked or when the DOM `hashchange` event is triggered.
2016-01-02 00:05:27 +00:00
2015-08-20 13:17:53 +00:00
### Event: 'crashed'
Emitted when the renderer process has crashed.
### Event: 'plugin-crashed'
Returns:
* `event` Event
* `name` String
* `version` String
Emitted when a plugin process has crashed.
### Event: 'destroyed'
Emitted when `webContents` is destroyed.
2015-10-01 08:30:31 +00:00
### Event: 'devtools-opened'
Emitted when DevTools is opened.
### Event: 'devtools-closed'
Emitted when DevTools is closed.
### Event: 'devtools-focused'
Emitted when DevTools is focused / opened.
2015-11-18 03:35:26 +00:00
### Event: 'certificate-error'
Returns:
* `event` Event
* `url` URL
* `error` String - The error code
* `certificate` Object
* `data` Buffer - PEM encoded data
* `issuerName` String
* `callback` Function
Emitted when failed to verify the `certificate` for `url` .
The usage is the same with [the `certificate-error` event of
`app` ](app.md#event-certificate-error).
### Event: 'select-client-certificate'
Returns:
* `event` Event
* `url` URL
* `certificateList` [Objects]
* `data` Buffer - PEM encoded data
* `issuerName` String - Issuer's Common Name
* `callback` Function
Emitted when a client certificate is requested.
The usage is the same with [the `select-client-certificate` event of
`app` ](app.md#event-select-client-certificate).
2015-10-28 13:14:00 +00:00
### Event: 'login'
Returns:
* `event` Event
* `request` Object
* `method` String
* `url` URL
* `referrer` URL
* `authInfo` Object
* `isProxy` Boolean
* `scheme` String
* `host` String
* `port` Integer
* `realm` String
* `callback` Function
Emitted when `webContents` wants to do basic auth.
The usage is the same with [the `login` event of `app` ](app.md#event-login ).
2015-12-17 23:10:42 +00:00
### Event: 'found-in-page'
2015-12-17 17:27:56 +00:00
Returns:
* `event` Event
* `result` Object
* `requestId` Integer
* `finalUpdate` Boolean - Indicates if more responses are to follow.
2015-12-17 23:10:42 +00:00
* `matches` Integer (Optional) - Number of Matches.
* `selectionArea` Object (Optional) - Coordinates of first match region.
2015-12-17 17:27:56 +00:00
Emitted when a result is available for
[`webContents.findInPage` ](web-contents.md#webcontentsfindinpage ) request.
2015-12-22 22:16:31 +00:00
### Event: 'media-started-playing'
Emitted when media starts playing.
### Event: 'media-paused'
Emitted when media is paused or done playing.
### Event: 'did-change-theme-color'
Emitted when a page's theme color changes. This is usually due to encountering a meta tag:
```html
< meta name = 'theme-color' content = '#ff0000' >
```
2016-01-31 01:27:14 +00:00
### Event: 'cursor-changed'
Returns:
* `event` Event
* `type` String
2016-02-01 06:17:58 +00:00
* `image` NativeImage (optional)
* `scale` Float (optional)
2016-01-31 16:00:14 +00:00
Emitted when the cursor's type changes. The `type` parameter can be `default` ,
`crosshair` , `pointer` , `text` , `wait` , `help` , `e-resize` , `n-resize` ,
`ne-resize` , `nw-resize` , `s-resize` , `se-resize` , `sw-resize` , `w-resize` ,
`ns-resize` , `ew-resize` , `nesw-resize` , `nwse-resize` , `col-resize` ,
`row-resize` , `m-panning` , `e-panning` , `n-panning` , `ne-panning` , `nw-panning` ,
`s-panning` , `se-panning` , `sw-panning` , `w-panning` , `move` , `vertical-text` ,
`cell` , `context-menu` , `alias` , `progress` , `nodrop` , `copy` , `none` ,
`not-allowed` , `zoom-in` , `zoom-out` , `grab` , `grabbing` , `custom` .
If the `type` parameter is `custom` , the `image` parameter will hold the custom
cursor image in a `NativeImage` , and the `scale` will hold scaling information
for the image.
2016-01-31 01:27:14 +00:00
2015-08-20 13:17:53 +00:00
## Instance Methods
The `webContents` object has the following instance methods:
2015-11-13 08:03:40 +00:00
### `webContents.loadURL(url[, options])`
2015-08-20 13:17:53 +00:00
* `url` URL
2015-08-26 20:57:42 +00:00
* `options` Object (optional), properties:
* `httpReferrer` String - A HTTP Referrer url.
* `userAgent` String - A user agent originating the request.
2015-10-26 21:18:16 +00:00
* `extraHeaders` String - Extra headers separated by "\n"
2015-08-20 13:17:53 +00:00
2015-08-20 17:03:53 +00:00
Loads the `url` in the window, the `url` must contain the protocol prefix,
2015-11-14 06:39:18 +00:00
e.g. the `http://` or `file://` . If the load should bypass http cache then
use the `pragma` header to achieve it.
```javascript
const options = {"extraHeaders" : "pragma: no-cache\n"}
webContents.loadURL(url, options)
```
2015-08-20 13:17:53 +00:00
2015-12-02 21:49:42 +00:00
### `webContents.downloadURL(url)`
* `url` URL
Initiates a download of the resource at `url` without navigating. The
`will-download` event of `session` will be triggered.
2015-11-13 08:03:40 +00:00
### `webContents.getURL()`
2015-08-20 13:17:53 +00:00
2015-11-12 13:20:09 +00:00
Returns URL of the current web page.
2015-08-20 13:17:53 +00:00
2015-11-12 13:20:09 +00:00
```javascript
2015-08-20 13:17:53 +00:00
var win = new BrowserWindow({width: 800, height: 600});
2015-11-13 08:03:40 +00:00
win.loadURL("http://github.com");
2015-08-20 13:17:53 +00:00
2015-11-13 08:03:40 +00:00
var currentURL = win.webContents.getURL();
2015-08-20 13:17:53 +00:00
```
### `webContents.getTitle()`
2015-08-20 17:03:53 +00:00
Returns the title of the current web page.
2015-08-20 13:17:53 +00:00
### `webContents.isLoading()`
Returns whether web page is still loading resources.
### `webContents.isWaitingForResponse()`
2015-08-26 20:57:42 +00:00
Returns whether the web page is waiting for a first-response from the main
2015-08-24 22:41:02 +00:00
resource of the page.
2015-08-20 13:17:53 +00:00
### `webContents.stop()`
Stops any pending navigation.
### `webContents.reload()`
2015-08-20 17:03:53 +00:00
Reloads the current web page.
2015-08-20 13:17:53 +00:00
### `webContents.reloadIgnoringCache()`
Reloads current page and ignores cache.
### `webContents.canGoBack()`
2015-08-20 17:03:53 +00:00
Returns whether the browser can go back to previous web page.
2015-08-20 13:17:53 +00:00
### `webContents.canGoForward()`
2015-08-20 17:03:53 +00:00
Returns whether the browser can go forward to next web page.
2015-08-20 13:17:53 +00:00
### `webContents.canGoToOffset(offset)`
* `offset` Integer
Returns whether the web page can go to `offset` .
### `webContents.clearHistory()`
Clears the navigation history.
### `webContents.goBack()`
2015-08-20 17:03:53 +00:00
Makes the browser go back a web page.
2015-08-20 13:17:53 +00:00
### `webContents.goForward()`
2015-08-20 17:03:53 +00:00
Makes the browser go forward a web page.
2015-08-20 13:17:53 +00:00
### `webContents.goToIndex(index)`
* `index` Integer
2015-08-20 17:03:53 +00:00
Navigates browser to the specified absolute web page index.
2015-08-20 13:17:53 +00:00
### `webContents.goToOffset(offset)`
* `offset` Integer
Navigates to the specified offset from the "current entry".
### `webContents.isCrashed()`
Whether the renderer process has crashed.
### `webContents.setUserAgent(userAgent)`
* `userAgent` String
2015-08-26 20:57:42 +00:00
Overrides the user agent for this web page.
2015-08-20 13:17:53 +00:00
### `webContents.getUserAgent()`
2015-08-26 20:57:42 +00:00
Returns a `String` representing the user agent for this web page.
2015-08-20 13:17:53 +00:00
### `webContents.insertCSS(css)`
* `css` String
2015-08-20 17:03:53 +00:00
Injects CSS into the current web page.
2015-08-20 13:17:53 +00:00
### `webContents.executeJavaScript(code[, userGesture])`
* `code` String
2015-08-24 22:55:53 +00:00
* `userGesture` Boolean (optional)
2015-08-20 13:17:53 +00:00
Evaluates `code` in page.
2015-08-24 22:41:02 +00:00
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.
2015-08-20 13:17:53 +00:00
### `webContents.setAudioMuted(muted)`
2015-11-23 08:59:15 +00:00
* `muted` Boolean
2015-08-20 13:17:53 +00:00
2015-08-20 17:03:53 +00:00
Mute the audio on the current web page.
2015-08-20 13:17:53 +00:00
### `webContents.isAudioMuted()`
Returns whether this page has been muted.
### `webContents.undo()`
2015-08-26 20:57:42 +00:00
Executes the editing command `undo` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.redo()`
2015-08-26 20:57:42 +00:00
Executes the editing command `redo` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.cut()`
2015-08-26 20:57:42 +00:00
Executes the editing command `cut` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.copy()`
2015-08-26 20:57:42 +00:00
Executes the editing command `copy` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.paste()`
2015-08-26 20:57:42 +00:00
Executes the editing command `paste` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.pasteAndMatchStyle()`
2015-08-26 20:57:42 +00:00
Executes the editing command `pasteAndMatchStyle` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.delete()`
2015-08-26 20:57:42 +00:00
Executes the editing command `delete` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.selectAll()`
2015-08-26 20:57:42 +00:00
Executes the editing command `selectAll` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.unselect()`
2015-08-26 20:57:42 +00:00
Executes the editing command `unselect` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.replace(text)`
* `text` String
2015-08-26 20:57:42 +00:00
Executes the editing command `replace` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.replaceMisspelling(text)`
* `text` String
2015-08-26 20:57:42 +00:00
Executes the editing command `replaceMisspelling` in web page.
2015-08-20 13:17:53 +00:00
2016-01-13 03:55:49 +00:00
### `webContents.insertText(text)`
* `text` String
Inserts `text` to the focused element.
2015-12-17 23:10:42 +00:00
### `webContents.findInPage(text[, options])`
2015-12-17 17:27:56 +00:00
* `text` String - Content to be searched, must not be empty.
2015-12-17 23:10:42 +00:00
* `options` Object (Optional)
* `forward` Boolean - Whether to search forward or backward, defaults to `true` .
* `findNext` Boolean - Whether the operation is first request or a follow up,
defaults to `false` .
* `matchCase` Boolean - Whether search should be case-sensitive,
defaults to `false` .
2015-12-17 17:27:56 +00:00
* `wordStart` Boolean - Whether to look only at the start of words.
2015-12-17 23:10:42 +00:00
defaults to `false` .
* `medialCapitalAsWordStart` Boolean - When combined with `wordStart` ,
2015-12-17 17:27:56 +00:00
accepts a match in the middle of a word if the match begins with an
uppercase letter followed by a lowercase or non-letter.
2015-12-17 23:10:42 +00:00
Accepts several other intra-word matches, defaults to `false` .
2015-12-17 17:27:56 +00:00
2015-12-17 23:10:42 +00:00
Starts a request to find all matches for the `text` in the web page and returns an `Integer`
representing the request id used for the request. The result of the request can be
obtained by subscribing to [`found-in-page` ](web-contents.md#event-found-in-page ) event.
2015-12-17 17:27:56 +00:00
### `webContents.stopFindInPage(action)`
2015-12-17 23:10:42 +00:00
* `action` String - Specifies the action to take place when ending
2015-12-21 12:54:55 +00:00
[`webContents.findInPage` ](web-contents.md#webcontentfindinpage ) request.
2015-12-17 23:10:42 +00:00
* `clearSelection` - Translate the selection into a normal selection.
* `keepSelection` - Clear the selection.
* `activateSelection` - Focus and click the selection node.
2015-12-17 17:27:56 +00:00
2015-12-17 23:10:42 +00:00
Stops any `findInPage` request for the `webContents` with the provided `action` .
2015-12-17 17:27:56 +00:00
```javascript
2015-12-17 23:10:42 +00:00
webContents.on('found-in-page', function(event, result) {
2015-12-17 17:27:56 +00:00
if (result.finalUpdate)
webContents.stopFindInPage("clearSelection");
});
2015-12-17 23:10:42 +00:00
const requestId = webContents.findInPage("api");
```
2015-12-17 17:27:56 +00:00
2015-08-20 13:17:53 +00:00
### `webContents.hasServiceWorker(callback)`
* `callback` Function
2015-08-20 17:03:53 +00:00
Checks if any ServiceWorker is registered and returns a boolean as
2015-08-20 13:17:53 +00:00
response to `callback` .
### `webContents.unregisterServiceWorker(callback)`
* `callback` Function
2015-08-20 17:03:53 +00:00
Unregisters any ServiceWorker if present and returns a boolean as
response to `callback` when the JS promise is fulfilled or false
2015-08-20 13:17:53 +00:00
when the JS promise is rejected.
### `webContents.print([options])`
2015-08-26 20:57:42 +00:00
`options` Object (optional), properties:
2015-08-20 13:17:53 +00:00
* `silent` Boolean - Don't ask user for print settings, defaults to `false`
* `printBackground` Boolean - Also prints the background color and image of
the web page, defaults to `false` .
Prints window's web page. When `silent` is set to `false` , Electron will pick
up system's default printer and default settings for printing.
2015-08-26 20:57:42 +00:00
Calling `window.print()` in web page is equivalent to calling
2015-08-20 13:17:53 +00:00
`webContents.print({silent: false, printBackground: false})` .
**Note:** On Windows, the print API relies on `pdf.dll` . If your application
2015-08-20 17:03:53 +00:00
doesn't need the print feature, you can safely remove `pdf.dll` to reduce binary
2015-08-20 13:17:53 +00:00
size.
### `webContents.printToPDF(options, callback)`
`options` Object, properties:
* `marginsType` Integer - Specify the type of margins to use
* 0 - default
* 1 - none
* 2 - minimum
2015-08-26 20:57:42 +00:00
* `pageSize` String - Specify page size of the generated PDF.
2015-12-17 17:27:56 +00:00
* `A5`
2015-08-20 13:17:53 +00:00
* `A4`
* `A3`
* `Legal`
* `Letter`
* `Tabloid`
* `printBackground` Boolean - Whether to print CSS backgrounds.
* `printSelectionOnly` Boolean - Whether to print selection only.
* `landscape` Boolean - `true` for landscape, `false` for portrait.
`callback` Function - `function(error, data) {}`
* `error` Error
2015-08-26 20:57:42 +00:00
* `data` Buffer - PDF file content.
2015-08-20 13:17:53 +00:00
Prints window's web page as PDF with Chromium's preview printing custom
settings.
2015-08-20 17:03:53 +00:00
By default, an empty `options` will be regarded as:
```javascript
{
2015-08-26 20:57:42 +00:00
marginsType: 0,
printBackground: false,
printSelectionOnly: false,
landscape: false
2015-08-20 17:03:53 +00:00
}
```
2015-08-20 13:17:53 +00:00
```javascript
2015-11-12 13:20:09 +00:00
const BrowserWindow = require('electron').BrowserWindow;
const fs = require('fs');
2015-08-20 13:17:53 +00:00
var win = new BrowserWindow({width: 800, height: 600});
2015-11-13 08:03:40 +00:00
win.loadURL("http://github.com");
2015-08-20 13:17:53 +00:00
win.webContents.on("did-finish-load", function() {
// Use default printing options
win.webContents.printToPDF({}, function(error, data) {
if (error) throw error;
fs.writeFile("/tmp/print.pdf", data, function(error) {
2015-09-20 22:28:41 +00:00
if (error)
2015-08-20 13:17:53 +00:00
throw error;
console.log("Write PDF successfully.");
})
})
});
```
### `webContents.addWorkSpace(path)`
* `path` String
2015-11-27 06:16:00 +00:00
Adds the specified path to DevTools workspace. Must be used after DevTools
creation:
```javascript
mainWindow.webContents.on('devtools-opened', function() {
mainWindow.webContents.addWorkSpace(__dirname);
});
```
2015-08-20 13:17:53 +00:00
### `webContents.removeWorkSpace(path)`
* `path` String
2015-09-09 21:11:06 +00:00
Removes the specified path from DevTools workspace.
2015-08-20 13:17:53 +00:00
2015-10-01 08:30:31 +00:00
### `webContents.openDevTools([options])`
* `options` Object (optional). Properties:
* `detach` Boolean - opens DevTools in a new window
2016-01-04 02:46:30 +00:00
Opens the devtools.
2015-10-01 08:30:31 +00:00
### `webContents.closeDevTools()`
2016-01-04 02:46:30 +00:00
Closes the devtools.
2015-10-01 08:30:31 +00:00
### `webContents.isDevToolsOpened()`
2016-01-04 02:46:30 +00:00
Returns whether the devtools is opened.
### `webContents.isDevToolsFocused()`
Returns whether the devtools view is focused .
2015-10-01 08:30:31 +00:00
### `webContents.toggleDevTools()`
Toggles the developer tools.
### `webContents.isDevToolsFocused()`
Returns whether the developer tools is focused.
### `webContents.inspectElement(x, y)`
* `x` Integer
* `y` Integer
Starts inspecting element at position (`x`, `y` ).
### `webContents.inspectServiceWorker()`
Opens the developer tools for the service worker context.
2015-11-10 08:48:24 +00:00
### `webContents.send(channel[, arg1][, arg2][, ...])`
2015-08-20 13:17:53 +00:00
* `channel` String
2015-11-10 08:48:24 +00:00
* `arg` (optional)
2015-08-20 13:17:53 +00:00
2015-11-10 08:48:24 +00:00
Send an asynchronous message to renderer process via `channel` , you can also
2016-02-16 03:34:39 +00:00
send arbitrary arguments. Arguments will be serialized in JSON internally and
hence no functions or prototype chain will be included.
The renderer process can handle the message by listening to `channel` with the
`ipcRenderer` module.
2015-08-20 13:17:53 +00:00
An example of sending messages from the main process to the renderer process:
```javascript
2015-09-04 20:44:40 +00:00
// In the main process.
2015-08-20 13:17:53 +00:00
var window = null;
app.on('ready', function() {
window = new BrowserWindow({width: 800, height: 600});
2015-11-13 08:03:40 +00:00
window.loadURL('file://' + __dirname + '/index.html');
2015-08-20 13:17:53 +00:00
window.webContents.on('did-finish-load', function() {
window.webContents.send('ping', 'whoooooooh!');
});
});
```
```html
<!-- index.html -->
< html >
< body >
< script >
2015-11-12 13:20:09 +00:00
require('electron').ipcRenderer.on('ping', function(event, message) {
2015-08-20 13:17:53 +00:00
console.log(message); // Prints "whoooooooh!"
});
< / script >
< / body >
< / html >
```
2015-08-31 09:19:19 +00:00
### `webContents.enableDeviceEmulation(parameters)`
`parameters` Object, properties:
* `screenPosition` String - Specify the screen type to emulate
(default: `desktop` )
* `desktop`
* `mobile`
* `screenSize` Object - Set the emulated screen size (screenPosition == mobile)
* `width` Integer - Set the emulated screen width
* `height` Integer - Set the emulated screen height
* `viewPosition` Object - Position the view on the screen
(screenPosition == mobile) (default: `{x: 0, y: 0}` )
* `x` Integer - Set the x axis offset from top left corner
* `y` Integer - Set the y axis offset from top left corner
* `deviceScaleFactor` Integer - Set the device scale factor (if zero defaults to
original device scale factor) (default: `0` )
* `viewSize` Object - Set the emulated view size (empty means no override)
* `width` Integer - Set the emulated view width
* `height` Integer - Set the emulated view height
* `fitToView` Boolean - Whether emulated view should be scaled down if
necessary to fit into available space (default: `false` )
* `offset` Object - Offset of the emulated view inside available space (not in
fit to view mode) (default: `{x: 0, y: 0}` )
* `x` Float - Set the x axis offset from top left corner
* `y` Float - Set the y axis offset from top left corner
* `scale` Float - Scale of emulated view inside available space (not in fit to
view mode) (default: `1` )
Enable device emulation with the given parameters.
### `webContents.disableDeviceEmulation()`
Disable device emulation enabled by `webContents.enableDeviceEmulation` .
2015-09-18 09:44:11 +00:00
### `webContents.sendInputEvent(event)`
* `event` Object
* `type` String (**required**) - The type of the event, can be `mouseDown` ,
`mouseUp` , `mouseEnter` , `mouseLeave` , `contextMenu` , `mouseWheel` ,
2015-11-16 03:22:37 +00:00
`mouseMove` , `keyDown` , `keyUp` , `char` .
2015-09-18 09:44:11 +00:00
* `modifiers` Array - An array of modifiers of the event, can
include `shift` , `control` , `alt` , `meta` , `isKeypad` , `isAutoRepeat` ,
`leftButtonDown` , `middleButtonDown` , `rightButtonDown` , `capsLock` ,
`numLock` , `left` , `right` .
Sends an input `event` to the page.
For keyboard events, the `event` object also have following properties:
2015-11-16 13:51:26 +00:00
* `keyCode` Char or String (**required**) - The character that will be sent
as the keyboard event. Can be a single UTF-8 character, or the name of the
key that generates the event. Accepted key names are `enter` , `backspace` ,
`delete` , `tab` , `escape` , `control` , `alt` , `shift` , `end` , `home` , `insert` ,
`left` , `up` , `right` , `down` , `pageUp` , `pageDown` , `printScreen`
2015-09-18 09:44:11 +00:00
For mouse events, the `event` object also have following properties:
* `x` Integer (**required**)
* `y` Integer (**required**)
2015-09-28 00:52:16 +00:00
* `button` String - The button pressed, can be `left` , `middle` , `right`
2015-09-18 09:44:11 +00:00
* `globalX` Integer
* `globalY` Integer
* `movementX` Integer
* `movementY` Integer
* `clickCount` Integer
For the `mouseWheel` event, the `event` object also have following properties:
* `deltaX` Integer
* `deltaY` Integer
* `wheelTicksX` Integer
* `wheelTicksY` Integer
* `accelerationRatioX` Integer
* `accelerationRatioY` Integer
* `hasPreciseScrollingDeltas` Boolean
* `canScroll` Boolean
2015-09-18 09:53:19 +00:00
### `webContents.beginFrameSubscription(callback)`
* `callback` Function
Begin subscribing for presentation events and captured frames, the `callback`
will be called with `callback(frameBuffer)` when there is a presentation event.
2015-09-28 20:33:43 +00:00
The `frameBuffer` is a `Buffer` that contains raw pixel data. On most machines,
the pixel data is effectively stored in 32bit BGRA format, but the actual
representation depends on the endianness of the processor (most modern
processors are little-endian, on machines with big-endian processors the data
is in 32bit ARGB format).
2015-09-18 09:53:19 +00:00
### `webContents.endFrameSubscription()`
End subscribing for frame presentation events.
2015-10-01 08:30:31 +00:00
2015-10-14 04:41:31 +00:00
### `webContents.savePage(fullPath, saveType, callback)`
* `fullPath` String - The full file path.
* `saveType` String - Specify the save type.
* `HTMLOnly` - Save only the HTML of the page.
* `HTMLComplete` - Save complete-html page.
* `MHTML` - Save complete-html page as MHTML.
* `callback` Function - `function(error) {}` .
* `error` Error
Returns true if the process of saving page has been initiated successfully.
```javascript
2015-11-13 08:03:40 +00:00
win.loadURL('https://github.com');
2015-10-14 04:41:31 +00:00
win.webContents.on('did-finish-load', function() {
win.webContents.savePage('/tmp/test.html', 'HTMLComplete', function(error) {
if (!error)
console.log("Save page successfully");
});
});
```
2015-11-19 13:10:50 +00:00
## Instance Properties
`WebContents` objects also have the following properties:
2015-11-19 13:48:45 +00:00
### `webContents.session`
Returns the [session ](session.md ) object used by this webContents.
2015-11-19 13:10:50 +00:00
### `webContents.devToolsWebContents`
Get the `WebContents` of DevTools for this `WebContents` .
**Note:** Users should never store this object because it may become `null`
when the DevTools has been closed.
2016-01-21 18:22:23 +00:00
### `webContents.debugger`
2016-01-22 04:57:25 +00:00
Debugger API serves as an alternate transport for [remote debugging protocol][rdp].
2016-01-21 18:22:23 +00:00
```javascript
try {
win.webContents.debugger.attach("1.1");
} catch(err) {
console.log("Debugger attach failed : ", err);
};
2016-01-22 04:57:25 +00:00
win.webContents.debugger.on('detach', function(event, reason) {
2016-01-21 18:22:23 +00:00
console.log("Debugger detached due to : ", reason);
});
2016-01-22 04:57:25 +00:00
win.webContents.debugger.on('message', function(event, method, params) {
2016-01-21 18:22:23 +00:00
if (method == "Network.requestWillBeSent") {
if (params.request.url == "https://www.github.com")
win.webContents.debugger.detach();
}
})
win.webContents.debugger.sendCommand("Network.enable");
```
#### `webContents.debugger.attach([protocolVersion])`
2016-01-22 08:47:23 +00:00
* `protocolVersion` String (optional) - Requested debugging protocol version.
2016-01-21 18:22:23 +00:00
Attaches the debugger to the `webContents` .
2016-01-22 08:47:23 +00:00
#### `webContents.debugger.isAttached()`
Returns a boolean indicating whether a debugger is attached to the `webContents` .
2016-01-21 18:22:23 +00:00
#### `webContents.debugger.detach()`
Detaches the debugger from the `webContents` .
#### `webContents.debugger.sendCommand(method[, commandParams, callback])`
* `method` String - Method name, should be one of the methods defined by the
remote debugging protocol.
2016-01-22 08:47:23 +00:00
* `commandParams` Object (optional) - JSON object with request parameters.
* `callback` Function (optional) - Response
* `error` Object - Error message indicating the failure of the command.
2016-01-21 18:22:23 +00:00
* `result` Object - Response defined by the 'returns' attribute of
the command description in the remote debugging protocol.
Send given command to the debugging target.
2016-01-22 04:57:25 +00:00
#### Event: 'detach'
2016-01-21 18:22:23 +00:00
2016-01-22 04:57:25 +00:00
* `event` Event
* `reason` String - Reason for detaching debugger.
2016-01-21 18:22:23 +00:00
2016-01-22 04:57:25 +00:00
Emitted when debugging session is terminated. This happens either when
2016-01-21 18:22:23 +00:00
`webContents` is closed or devtools is invoked for the attached `webContents` .
2016-01-22 04:57:25 +00:00
#### Event: 'message'
2016-01-21 18:22:23 +00:00
2016-01-22 04:57:25 +00:00
* `event` Event
* `method` String - Method name.
* `params` Object - Event parameters defined by the 'parameters'
attribute in the remote debugging protocol.
Emitted whenever debugging target issues instrumentation event.
2016-01-21 18:22:23 +00:00
2016-01-22 04:57:25 +00:00
[rdp]: https://developer.chrome.com/devtools/docs/debugger-protocol