electron/docs/api/web-contents.md

554 lines
14 KiB
Markdown
Raw Normal View History

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
var BrowserWindow = require('browser-window');
2015-08-20 17:03:53 +00:00
var win = new BrowserWindow({width: 800, height: 1500});
2015-08-20 13:17:53 +00:00
win.loadUrl("http://github.com");
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
* `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.
### 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
* `newUrl` String
* `originalUrl` String
* `httpResponseCode` Integer
* `requestMethod` String
* `referrer` String
* `headers` Object
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
* `oldUrl` String
* `newUrl` String
* `isMainFrame` Boolean
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
* `favicons` Array - Array of Urls
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`,
`new-window` and `other`.
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`.
Calling `event.preventDefault()` will prevent creating new windows.
2015-08-20 13:17:53 +00:00
### Event: 'will-navigate'
Returns:
* `event` Event
* `url` String
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
APIs like `webContents.loadUrl` and `webContents.back`.
2015-08-20 13:17:53 +00:00
Calling `event.preventDefault()` will prevent the navigation.
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.
## Instance Methods
The `webContents` object has the following instance methods:
### `webContents.session`
Returns the `session` object used by this webContents.
2015-08-20 13:17:53 +00:00
See [session documentation](session.md) for this object's methods.
### `webContents.loadUrl(url[, options])`
* `url` URL
* `options` Object (optional), properties:
* `httpReferrer` String - A HTTP Referrer url.
* `userAgent` String - A user agent originating the request.
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-08-20 13:17:53 +00:00
e.g. the `http://` or `file://`.
### `webContents.getUrl()`
```javascript
var BrowserWindow = require('browser-window');
var win = new BrowserWindow({width: 800, height: 600});
win.loadUrl("http://github.com");
var currentUrl = win.webContents.getUrl();
```
2015-08-20 17:03:53 +00:00
Returns URL of the current web page.
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()`
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
Overrides the user agent for this web page.
2015-08-20 13:17:53 +00:00
### `webContents.getUserAgent()`
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)`
+ `muted` Boolean
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()`
Executes the editing command `undo` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.redo()`
Executes the editing command `redo` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.cut()`
Executes the editing command `cut` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.copy()`
Executes the editing command `copy` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.paste()`
Executes the editing command `paste` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.pasteAndMatchStyle()`
Executes the editing command `pasteAndMatchStyle` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.delete()`
Executes the editing command `delete` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.selectAll()`
Executes the editing command `selectAll` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.unselect()`
Executes the editing command `unselect` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.replace(text)`
* `text` String
Executes the editing command `replace` in web page.
2015-08-20 13:17:53 +00:00
### `webContents.replaceMisspelling(text)`
* `text` String
Executes the editing command `replaceMisspelling` in web page.
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])`
`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.
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
* `pageSize` String - Specify page size of the generated PDF.
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
* `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
{
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
var BrowserWindow = require('browser-window');
var fs = require('fs');
var win = new BrowserWindow({width: 800, height: 600});
win.loadUrl("http://github.com");
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) {
if (err)
throw error;
console.log("Write PDF successfully.");
})
})
});
```
### `webContents.addWorkSpace(path)`
* `path` String
2015-09-09 21:11:06 +00:00
Adds the specified path to DevTools workspace.
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
### `webContents.send(channel[, args...])`
* `channel` String
2015-08-24 22:55:53 +00:00
* `args...` (optional)
2015-08-20 13:17:53 +00:00
2015-08-24 22:55:53 +00:00
Send `args...` to the web page via `channel` in an asynchronous message, the web
2015-08-20 13:17:53 +00:00
page can handle it by listening to the `channel` event of the `ipc` module.
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});
window.loadUrl('file://' + __dirname + '/index.html');
window.webContents.on('did-finish-load', function() {
window.webContents.send('ping', 'whoooooooh!');
});
});
```
```html
<!-- index.html -->
<html>
<body>
<script>
require('ipc').on('ping', function(message) {
console.log(message); // Prints "whoooooooh!"
});
</script>
</body>
</html>
```
**Note:**
1. The IPC message handler in web pages does not have an `event` parameter,
2015-09-04 20:44:40 +00:00
which is different from the handlers in the main process.
2015-08-20 13:17:53 +00:00
2. There is no way to send synchronous messages from the main process to a
renderer process, because it would be very easy to cause dead locks.
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`,
`keyDown`, `keyUp`, `char`.
* `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:
* `keyCode` String (**required**) - A single character that will be sent as
keyboard event. Can be any ASCII character on the keyboard, like `a`, `1`
and `=`.
For mouse events, the `event` object also have following properties:
* `x` Integer (**required**)
* `y` Integer (**required**)
* `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