11 KiB
webContents
webContents
is an
EventEmitter.
It is responsible for rendering and controlling a web page and is a property of
the BrowserWindow
object. An example of accessing the
webContents
object:
var BrowserWindow = require('browser-window');
var win = new BrowserWindow({width: 800, height: 1500});
win.loadUrl("http://github.com");
var webContents = win.webContents;
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
EventerrorCode
IntegererrorDescription
String
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
EventisMainFrame
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
Eventstatus
BooleannewUrl
StringoriginalUrl
StringhttpResponseCode
IntegerrequestMethod
Stringreferrer
Stringheaders
Object
Emitted when details regarding a requested resource are available.
status
indicates the socket connection to download the resource.
Event: 'did-get-redirect-request'
Returns:
event
EventoldUrl
StringnewUrl
StringisMainFrame
Boolean
Emitted when a redirect is received while requesting a resource.
Event: 'dom-ready'
Returns:
event
Event
Emitted when the document in the given frame is loaded.
Event: 'page-favicon-updated'
Returns:
event
Eventfavicons
Array - Array of Urls
Emitted when page receives favicon urls.
Event: 'new-window'
Returns:
event
Eventurl
StringframeName
Stringdisposition
String - Can bedefault
,foreground-tab
,background-tab
,new-window
andother
.
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.
Event: 'will-navigate'
Returns:
event
Eventurl
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.
This event will not emit when the navigation is started programmatically with
APIs like webContents.loadUrl
and webContents.back
.
Calling event.preventDefault()
will prevent the navigation.
Event: 'crashed'
Emitted when the renderer process has crashed.
Event: 'plugin-crashed'
Returns:
event
Eventname
Stringversion
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.
See session documentation for this object's methods.
webContents.loadUrl(url[, options])
url
URLoptions
Object (optional), properties:httpReferrer
String - A HTTP Referrer url.userAgent
String - A user agent originating the request.
Loads the url
in the window, the url
must contain the protocol prefix,
e.g. the http://
or file://
.
webContents.getUrl()
var BrowserWindow = require('browser-window');
var win = new BrowserWindow({width: 800, height: 600});
win.loadUrl("http://github.com");
var currentUrl = win.webContents.getUrl();
Returns URL of the current web page.
webContents.getTitle()
Returns the title of the current web page.
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 resource of the page.
webContents.stop()
Stops any pending navigation.
webContents.reload()
Reloads the current web page.
webContents.reloadIgnoringCache()
Reloads current page and ignores cache.
webContents.canGoBack()
Returns whether the browser can go back to previous web page.
webContents.canGoForward()
Returns whether the browser can go forward to next web page.
webContents.canGoToOffset(offset)
offset
Integer
Returns whether the web page can go to offset
.
webContents.clearHistory()
Clears the navigation history.
webContents.goBack()
Makes the browser go back a web page.
webContents.goForward()
Makes the browser go forward a web page.
webContents.goToIndex(index)
index
Integer
Navigates browser to the specified absolute web page index.
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.
webContents.getUserAgent()
Returns a String
representing the user agent for this web page.
webContents.insertCSS(css)
css
String
Injects CSS into the current web page.
webContents.executeJavaScript(code[, userGesture])
code
StringuserGesture
Boolean (optional)
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.
webContents.setAudioMuted(muted)
muted
Boolean
Mute the audio on the current web page.
webContents.isAudioMuted()
Returns whether this page has been muted.
webContents.undo()
Executes the editing command undo
in web page.
webContents.redo()
Executes the editing command redo
in web page.
webContents.cut()
Executes the editing command cut
in web page.
webContents.copy()
Executes the editing command copy
in web page.
webContents.paste()
Executes the editing command paste
in web page.
webContents.pasteAndMatchStyle()
Executes the editing command pasteAndMatchStyle
in web page.
webContents.delete()
Executes the editing command delete
in web page.
webContents.selectAll()
Executes the editing command selectAll
in web page.
webContents.unselect()
Executes the editing command unselect
in web page.
webContents.replace(text)
text
String
Executes the editing command replace
in web page.
webContents.replaceMisspelling(text)
text
String
Executes the editing command replaceMisspelling
in web page.
webContents.hasServiceWorker(callback)
callback
Function
Checks if any ServiceWorker is registered and returns a boolean as
response to callback
.
webContents.unregisterServiceWorker(callback)
callback
Function
Unregisters any ServiceWorker if present and returns a boolean as
response to callback
when the JS promise is fulfilled or false
when the JS promise is rejected.
webContents.print([options])
options
Object (optional), properties:
silent
Boolean - Don't ask user for print settings, defaults tofalse
printBackground
Boolean - Also prints the background color and image of the web page, defaults tofalse
.
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
webContents.print({silent: false, printBackground: false})
.
Note: On Windows, the print API relies on pdf.dll
. If your application
doesn't need the print feature, you can safely remove pdf.dll
to reduce binary
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.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
Errordata
Buffer - PDF file content.
Prints window's web page as PDF with Chromium's preview printing custom settings.
By default, an empty options
will be regarded as:
{
marginsType: 0,
printBackground: false,
printSelectionOnly: false,
landscape: false
}
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
Adds the specified path to devtools workspace.
webContents.removeWorkSpace(path)
path
String
Removes the specified path from devtools workspace.
webContents.send(channel[, args...])
channel
Stringargs...
(optional)
Send args...
to the web page via channel
in an asynchronous message, the web
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:
// In the main process.
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!');
});
});
<!-- index.html -->
<html>
<body>
<script>
require('ipc').on('ping', function(message) {
console.log(message); // Prints "whoooooooh!"
});
</script>
</body>
</html>
Note:
- The IPC message handler in web pages does not have an
event
parameter, which is different from the handlers in the main process. - 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.