Render and control web pages.
Process: Main
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:
const {BrowserWindow} = require('electron')
let win = new BrowserWindow({width: 800, height: 1500})
win.loadURL('http://github.com')
let contents = win.webContents
console.log(contents)
These methods can be accessed from the webContents
module:
const {webContents} = require('electron')
console.log(webContents)
webContents.getAllWebContents()
Returns WebContents[]
- An array of all WebContents
instances. This will contain web contents
for all windows, webviews, opened devtools, and devtools extension background pages.
webContents.getFocusedWebContents()
Returns WebContents
- The web contents that is focused in this application, otherwise
returns null
.
Emitted when the navigation is done, i.e. the spinner of the tab has stopped
spinning, and the onload
event was dispatched.
Returns:
event
EventerrorCode
IntegererrorDescription
StringvalidatedURL
StringisMainFrame
BooleanThis event is like did-finish-load
but emitted when the load failed or was
cancelled, e.g. window.stop()
is invoked.
The full list of error codes and their meaning is available here.
Returns:
event
EventisMainFrame
BooleanEmitted when a frame has done navigation.
Corresponds to the points in time when the spinner of the tab started spinning.
Corresponds to the points in time when the spinner of the tab stopped spinning.
Returns:
event
Eventstatus
BooleannewURL
StringoriginalURL
StringhttpResponseCode
IntegerrequestMethod
Stringreferrer
Stringheaders
ObjectresourceType
StringEmitted when details regarding a requested resource are available.
status
indicates the socket connection to download the resource.
Returns:
event
EventoldURL
StringnewURL
StringisMainFrame
BooleanhttpResponseCode
IntegerrequestMethod
Stringreferrer
Stringheaders
ObjectEmitted when a redirect is received while requesting a resource.
Returns:
event
Eventfavicons
String[] - Array of URLs.Emitted when page receives favicon urls.
Returns:
event
Eventurl
StringframeName
Stringdisposition
String - Can be default
, foreground-tab
, background-tab
,
new-window
, save-to-disk
and other
.options
Object - The options which will be used for creating the new
BrowserWindow
.additionalFeatures
String[] - The non-standard features (features not handled
by Chromium or Electron) given to window.open()
.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 Electron from automatically creating a
new BrowserWindow
. If you call event.preventDefault()
and manually create a new
BrowserWindow
then you must set event.newGuest
to reference the new BrowserWindow
instance, failing to do so may result in unexpected behavior. For example:
myBrowserWindow.webContents.on('new-window', (event, url) => {
event.preventDefault()
const win = new BrowserWindow({show: false})
win.once('ready-to-show', () => win.show())
win.loadURL(url)
event.newGuest = win
})
Returns:
event
Eventurl
StringEmitted 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
.
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.
Calling event.preventDefault()
will prevent the navigation.
Returns:
event
Eventurl
StringEmitted 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.
Returns:
event
Eventurl
StringisMainFrame
BooleanEmitted 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.
Returns:
event
EventEmitted when a beforeunload
event handler is attempting to cancel a page unload.
Calling event.preventDefault()
will ignore the beforeunload
event handler
and allow the page to be unloaded.
const {BrowserWindow, dialog} = require('electron')
const win = new BrowserWindow({width: 800, height: 600})
win.webContents.on('will-prevent-unload', (event) => {
const choice = dialog.showMessageBox(win, {
type: 'question',
buttons: ['Leave', 'Stay'],
title: 'Do you want to leave this site?',
message: 'Changes you made may not be saved.',
defaultId: 0,
cancelId: 1
})
const leave = (choice === 0)
if (leave) {
event.preventDefault()
}
})
Returns:
event
Eventkilled
BooleanEmitted when the renderer process crashes or is killed.
Returns:
event
Eventname
Stringversion
StringEmitted when a plugin process has crashed.
Emitted when webContents
is destroyed.
Returns:
event
Eventinput
Object - Input properties.
type
String - Either keyUp
or keyDown
.key
String - Equivalent to KeyboardEvent.key.code
String - Equivalent to KeyboardEvent.code.isAutoRepeat
Boolean - Equivalent to KeyboardEvent.repeat.shift
Boolean - Equivalent to KeyboardEvent.shiftKey.control
Boolean - Equivalent to KeyboardEvent.controlKey.alt
Boolean - Equivalent to KeyboardEvent.altKey.meta
Boolean - Equivalent to KeyboardEvent.metaKey.Emitted before dispatching the keydown
and keyup
events in the page.
Calling event.preventDefault
will prevent the page keydown
/keyup
events
and the menu shortcuts.
To only prevent the menu shortcuts, use
setIgnoreMenuShortcuts
:
const {BrowserWindow} = require('electron')
let win = new BrowserWindow({width: 800, height: 600})
win.webContents.on('before-input-event', (event, input) => {
// For example, only enable application menu keyboard shortcuts when
// Ctrl/Cmd are down.
win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)
})
Emitted when DevTools is opened.
Emitted when DevTools is closed.
Emitted when DevTools is focused / opened.
Returns:
event
Eventurl
Stringerror
String - The error code.certificate
Certificatecallback
Function
isTrusted
Boolean - Indicates whether the certificate can be considered trusted.Emitted when failed to verify the certificate
for url
.
The usage is the same with the certificate-error
event of
app
.
Returns:
event
Eventurl
URLcertificateList
Certificate[]callback
Function
certificate
Certificate - Must be a certificate from the given list.Emitted when a client certificate is requested.
The usage is the same with the select-client-certificate
event of
app
.
Returns:
event
Eventrequest
Object
method
Stringurl
URLreferrer
URLauthInfo
Object
isProxy
Booleanscheme
Stringhost
Stringport
Integerrealm
Stringcallback
Function
username
Stringpassword
StringEmitted when webContents
wants to do basic auth.
The usage is the same with the login
event of app
.
Returns:
event
Eventresult
Object
requestId
IntegeractiveMatchOrdinal
Integer - Position of the active match.matches
Integer - Number of Matches.selectionArea
Object - Coordinates of first match region.finalUpdate
BooleanEmitted when a result is available for
[webContents.findInPage
] request.
Emitted when media starts playing.
Emitted when media is paused or done playing.
Emitted when a page's theme color changes. This is usually due to encountering a meta tag:
<meta name='theme-color' content='#ff0000'>
Returns:
event
Eventcolor
(String | null) - Theme color is in format of '#rrggbb'. It is null
when no theme color is set.Returns:
event
Eventurl
StringEmitted when mouse moves over a link or the keyboard moves the focus to a link.
Returns:
event
Eventtype
Stringimage
NativeImage (optional)scale
Float (optional) - scaling factor for the custom cursor.size
Size (optional) - the size of the image
.hotspot
Point (optional) - coordinates of the custom cursor's hotspot.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
or custom
.
If the type
parameter is custom
, the image
parameter will hold the custom
cursor image in a NativeImage
, and scale
, size
and hotspot
will hold
additional information about the custom cursor.
Returns:
event
Eventparams
Object
x
Integer - x coordinate.y
Integer - y coordinate.linkURL
String - URL of the link that encloses the node the context menu
was invoked on.linkText
String - Text associated with the link. May be an empty
string if the contents of the link are an image.pageURL
String - URL of the top level page that the context menu was
invoked on.frameURL
String - URL of the subframe that the context menu was invoked
on.srcURL
String - Source URL for the element that the context menu
was invoked on. Elements with source URLs are images, audio and video.mediaType
String - Type of the node the context menu was invoked on. Can
be none
, image
, audio
, video
, canvas
, file
or plugin
.hasImageContents
Boolean - Whether the context menu was invoked on an image
which has non-empty contents.isEditable
Boolean - Whether the context is editable.selectionText
String - Text of the selection that the context menu was
invoked on.titleText
String - Title or alt text of the selection that the context
was invoked on.misspelledWord
String - The misspelled word under the cursor, if any.frameCharset
String - The character encoding of the frame on which the
menu was invoked.inputFieldType
String - If the context menu was invoked on an input
field, the type of that field. Possible values are none
, plainText
,
password
, other
.menuSourceType
String - Input source that invoked the context menu.
Can be none
, mouse
, keyboard
, touch
or touchMenu
.mediaFlags
Object - The flags for the media element the context menu was
invoked on.
inError
Boolean - Whether the media element has crashed.isPaused
Boolean - Whether the media element is paused.isMuted
Boolean - Whether the media element is muted.hasAudio
Boolean - Whether the media element has audio.isLooping
Boolean - Whether the media element is looping.isControlsVisible
Boolean - Whether the media element's controls are
visible.canToggleControls
Boolean - Whether the media element's controls are
toggleable.canRotate
Boolean - Whether the media element can be rotated.editFlags
Object - These flags indicate whether the renderer believes it
is able to perform the corresponding action.
canUndo
Boolean - Whether the renderer believes it can undo.canRedo
Boolean - Whether the renderer believes it can redo.canCut
Boolean - Whether the renderer believes it can cut.canCopy
Boolean - Whether the renderer believes it can copycanPaste
Boolean - Whether the renderer believes it can paste.canDelete
Boolean - Whether the renderer believes it can delete.canSelectAll
Boolean - Whether the renderer believes it can select all.Emitted when there is a new context menu that needs to be handled.
Returns:
event
Eventdevices
BluetoothDevice[]callback
Function
deviceId
StringEmitted when bluetooth device needs to be selected on call to
navigator.bluetooth.requestDevice
. To use navigator.bluetooth
api
webBluetooth
should be enabled. If event.preventDefault
is not called,
first available device will be selected. callback
should be called with
deviceId
to be selected, passing empty string to callback
will
cancel the request.
const {app, webContents} = require('electron')
app.commandLine.appendSwitch('enable-web-bluetooth')
app.on('ready', () => {
webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
event.preventDefault()
let result = deviceList.find((device) => {
return device.deviceName === 'test'
})
if (!result) {
callback('')
} else {
callback(result.deviceId)
}
})
})
Returns:
event
EventdirtyRect
Rectangleimage
NativeImage - The image data of the whole frame.Emitted when a new frame is generated. Only the dirty area is passed in the buffer.
const {BrowserWindow} = require('electron')
let win = new BrowserWindow({webPreferences: {offscreen: true}})
win.webContents.on('paint', (event, dirty, image) => {
// updateBitmap(dirty, image.getBitmap())
})
win.loadURL('http://github.com')
Emitted when the devtools window instructs the webContents to reload
Returns:
event
EventwebPreferences
Object - The web preferences that will be used by the guest
page. This object can be modified to adjust the preferences for the guest
page.params
Object - The other <webview>
parameters such as the src
URL.
This object can be modified to adjust the parameters of the guest page.Emitted when a <webview>
's web contents is being attached to this web
contents. Calling event.preventDefault()
will destroy the guest page.
This event can be used to configure webPreferences
for the webContents
of a <webview>
before it's loaded, and provides the ability to set settings
that can't be set via <webview>
attributes.
Note: The specified preload
script option will be appear as preloadURL
(not preload
) in the webPreferences
object emitted with this event.
Returns:
event
EventwebContents
WebContents - The guest web contents that is used by the
<webview>
.Emitted when a <webview>
has been attached to this web contents.
Returns:
level
Integermessage
Stringline
IntegersourceId
StringEmitted when the associated window logs a console message. Will not be emitted for windows with offscreen rendering enabled.
contents.loadURL(url[, options])
url
Stringoptions
Object (optional)
httpReferrer
String (optional) - A HTTP Referrer url.userAgent
String (optional) - A user agent originating the request.extraHeaders
String (optional) - Extra headers separated by "\n".postData
(UploadRawData[] | UploadFile[] | UploadFileSystem[] | UploadBlob[]) (optional)baseURLForDataURL
String (optional) - Base url (with trailing path separator) for files to be loaded by the data url. This is needed only if the specified url
is a data url and needs to load other files.Loads the url
in the window. The url
must contain the protocol prefix,
e.g. the http://
or file://
. If the load should bypass http cache then
use the pragma
header to achieve it.
const {webContents} = require('electron')
const options = {extraHeaders: 'pragma: no-cache\n'}
webContents.loadURL('https://github.com', options)
contents.loadFile(filePath)
filePath
StringLoads the given file in the window, filePath
should be a path to
an HTML file relative to the root of your application. For instance
an app structure like this:
| root
| - package.json
| - src
| - main.js
| - index.html
Would require code like this
win.loadFile('src/index.html')
contents.downloadURL(url)
url
StringInitiates a download of the resource at url
without navigating. The
will-download
event of session
will be triggered.
contents.getURL()
Returns String
- The URL of the current web page.
const {BrowserWindow} = require('electron')
let win = new BrowserWindow({width: 800, height: 600})
win.loadURL('http://github.com')
let currentURL = win.webContents.getURL()
console.log(currentURL)
contents.getTitle()
Returns String
- The title of the current web page.
contents.isDestroyed()
Returns Boolean
- Whether the web page is destroyed.
contents.focus()
Focuses the web page.
contents.isFocused()
Returns Boolean
- Whether the web page is focused.
contents.isLoading()
Returns Boolean
- Whether web page is still loading resources.
contents.isLoadingMainFrame()
Returns Boolean
- Whether the main frame (and not just iframes or frames within it) is
still loading.
contents.isWaitingForResponse()
Returns Boolean
- Whether the web page is waiting for a first-response from the main
resource of the page.
contents.stop()
Stops any pending navigation.
contents.reload()
Reloads the current web page.
contents.reloadIgnoringCache()
Reloads current page and ignores cache.
contents.canGoBack()
Returns Boolean
- Whether the browser can go back to previous web page.
contents.canGoForward()
Returns Boolean
- Whether the browser can go forward to next web page.
contents.canGoToOffset(offset)
offset
IntegerReturns Boolean
- Whether the web page can go to offset
.
contents.clearHistory()
Clears the navigation history.
contents.goBack()
Makes the browser go back a web page.
contents.goForward()
Makes the browser go forward a web page.
contents.goToOffset(offset)
offset
IntegerNavigates to the specified offset from the "current entry".
contents.isCrashed()
Returns Boolean
- Whether the renderer process has crashed.
contents.getUserAgent()
Returns String
- The user agent for this web page.
contents.executeJavaScript(code[, userGesture, callback])
code
StringuserGesture
Boolean (optional) - Default is false
.callback
Function (optional) - Called after script has been executed.
result
AnyReturns 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.
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.
If the result of the executed code is a promise the callback result will be the resolved value of the promise. We recommend that you use the returned Promise to handle code that results in a Promise.
contents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
.then((result) => {
console.log(result) // Will be the JSON object from the fetch call
})
contents.setIgnoreMenuShortcuts(ignore)
Experimentalignore
BooleanIgnore application menu shortcuts while this web contents is focused.
contents.isAudioMuted()
Returns Boolean
- Whether this page has been muted.
contents.setZoomFactor(factor)
factor
Number - Zoom factor.Changes the zoom factor to the specified factor. Zoom factor is zoom percent divided by 100, so 300% = 3.0.
contents.getZoomFactor(callback)
callback
Function
zoomFactor
NumberSends a request to get current zoom factor, the callback
will be called with
callback(zoomFactor)
.
contents.setZoomLevel(level)
level
Number - Zoom level.Changes the zoom level to the specified level. The original size is 0 and each
increment above or below represents zooming 20% larger or smaller to default
limits of 300% and 50% of original size, respectively. The formula for this is
scale := 1.2 ^ level
.
contents.getZoomLevel(callback)
callback
Function
zoomLevel
NumberSends a request to get current zoom level, the callback
will be called with
callback(zoomLevel)
.
contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)
minimumLevel
NumbermaximumLevel
NumberSets the maximum and minimum pinch-to-zoom level.
contents.setLayoutZoomLevelLimits(minimumLevel, maximumLevel)
minimumLevel
NumbermaximumLevel
NumberSets the maximum and minimum layout-based (i.e. non-visual) zoom level.
contents.undo()
Executes the editing command undo
in web page.
contents.redo()
Executes the editing command redo
in web page.
contents.cut()
Executes the editing command cut
in web page.
contents.copy()
Executes the editing command copy
in web page.
contents.copyImageAt(x, y)
x
Integery
IntegerCopy the image at the given position to the clipboard.
contents.paste()
Executes the editing command paste
in web page.
contents.pasteAndMatchStyle()
Executes the editing command pasteAndMatchStyle
in web page.
contents.delete()
Executes the editing command delete
in web page.
contents.selectAll()
Executes the editing command selectAll
in web page.
contents.unselect()
Executes the editing command unselect
in web page.
contents.replaceMisspelling(text)
text
StringExecutes the editing command replaceMisspelling
in web page.
contents.findInPage(text[, options])
text
String - Content to be searched, must not be empty.options
Object (optional)
forward
Boolean (optional) - Whether to search forward or backward, defaults to true
.findNext
Boolean (optional) - Whether the operation is first request or a follow up,
defaults to false
.matchCase
Boolean (optional) - Whether search should be case-sensitive,
defaults to false
.wordStart
Boolean (optional) - Whether to look only at the start of words.
defaults to false
.medialCapitalAsWordStart
Boolean (optional) - When combined with wordStart
,
accepts a match in the middle of a word if the match begins with an
uppercase letter followed by a lowercase or non-letter.
Accepts several other intra-word matches, defaults to false
.Returns Integer
- The request id used for the request.
Starts a request to find all matches for the text
in the web page. The result of the request
can be obtained by subscribing to found-in-page
event.
contents.stopFindInPage(action)
action
String - Specifies the action to take place when ending
[webContents.findInPage
] request.
clearSelection
- Clear the selection.keepSelection
- Translate the selection into a normal selection.activateSelection
- Focus and click the selection node.Stops any findInPage
request for the webContents
with the provided action
.
const {webContents} = require('electron')
webContents.on('found-in-page', (event, result) => {
if (result.finalUpdate) webContents.stopFindInPage('clearSelection')
})
const requestId = webContents.findInPage('api')
console.log(requestId)
contents.capturePage([rect, ]callback)
rect
Rectangle (optional) - The area of the page to be captured.callback
Function
image
NativeImageCaptures a snapshot of the page within rect
. Upon completion callback
will
be called with callback(image)
. The image
is an instance of
NativeImage that stores data of the snapshot. Omitting
rect
will capture the whole visible page.
contents.hasServiceWorker(callback)
callback
Function
hasWorker
BooleanChecks if any ServiceWorker is registered and returns a boolean as
response to callback
.
contents.unregisterServiceWorker(callback)
callback
Function
success
BooleanUnregisters 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.
contents.print([options], [callback])
options
Object (optional)
silent
Boolean (optional) - Don't ask user for print settings. Default is false
.printBackground
Boolean (optional) - Also prints the background color and image of
the web page. Default is false
.deviceName
String (optional) - Set the printer device name to use. Default is ''
.callback
Function (optional)
success
Boolean - Indicates success of the print call.Prints window's web page. When silent
is set to true
, Electron will pick
the system's default printer if deviceName
is empty and the default settings
for printing.
Calling window.print()
in web page is equivalent to calling
webContents.print({silent: false, printBackground: false, deviceName: ''})
.
Use page-break-before: always;
CSS style to force to print to a new page.
contents.printToPDF(options, callback)
options
Object
marginsType
Integer (optional) - Specifies the type of margins to use. Uses 0 for
default margin, 1 for no margin, and 2 for minimum margin.pageSize
String (optional) - Specify page size of the generated PDF. Can be A3
,
A4
, A5
, Legal
, Letter
, Tabloid
or an Object containing height
and width
in microns.printBackground
Boolean (optional) - Whether to print CSS backgrounds.printSelectionOnly
Boolean (optional) - Whether to print selection only.landscape
Boolean (optional) - true
for landscape, false
for portrait.callback
Function
error
Errordata
BufferPrints window's web page as PDF with Chromium's preview printing custom settings.
The callback
will be called with callback(error, data)
on completion. The
data
is a Buffer
that contains the generated PDF data.
The landscape
will be ignored if @page
CSS at-rule is used in the web page.
By default, an empty options
will be regarded as:
{
marginsType: 0,
printBackground: false,
printSelectionOnly: false,
landscape: false
}
Use page-break-before: always;
CSS style to force to print to a new page.
An example of webContents.printToPDF
:
const {BrowserWindow} = require('electron')
const fs = require('fs')
let win = new BrowserWindow({width: 800, height: 600})
win.loadURL('http://github.com')
win.webContents.on('did-finish-load', () => {
// Use default printing options
win.webContents.printToPDF({}, (error, data) => {
if (error) throw error
fs.writeFile('/tmp/print.pdf', data, (error) => {
if (error) throw error
console.log('Write PDF successfully.')
})
})
})
contents.addWorkSpace(path)
path
StringAdds the specified path to DevTools workspace. Must be used after DevTools creation:
const {BrowserWindow} = require('electron')
let win = new BrowserWindow()
win.webContents.on('devtools-opened', () => {
win.webContents.addWorkSpace(__dirname)
})
contents.setDevToolsWebContents(devToolsWebContents)
devToolsWebContents
WebContentsUses the devToolsWebContents
as the target WebContents
to show devtools.
The devToolsWebContents
must not have done any navigation, and it should not
be used for other purposes after the call.
By default Electron manages the devtools by creating an internal WebContents
with native view, which developers have very limited control of. With the
setDevToolsWebContents
method, developers can use any WebContents
to show
the devtools in it, including BrowserWindow
, BrowserView
and <webview>
tag.
Note that closing the devtools does not destroy the devToolsWebContents
, it
is caller's responsibility to destroy devToolsWebContents
.
An example of showing devtools in a <webview>
tag:
<html>
<head>
<style type="text/css">
* { margin: 0; }
#browser { height: 70%; }
#devtools { height: 30%; }
</style>
</head>
<body>
<webview id="browser" src="https://github.com"></webview>
<webview id="devtools"></webview>
<script>
const browserView = document.getElementById('browser')
const devtoolsView = document.getElementById('devtools')
browserView.addEventListener('dom-ready', () => {
const browser = browserView.getWebContents()
browser.setDevToolsWebContents(devtoolsView.getWebContents())
browser.openDevTools()
})
</script>
</body>
</html>
An example of showing devtools in a BrowserWindow
:
const {app, BrowserWindow} = require('electron')
let win = null
let devtools = null
app.once('ready', () => {
win = new BrowserWindow()
devtools = new BrowserWindow()
win.loadURL('https://github.com')
win.webContents.setDevToolsWebContents(devtools.webContents)
win.webContents.openDevTools({mode: 'detach'})
})
contents.openDevTools([options])
options
Object (optional)
mode
String - Opens the devtools with specified dock state, can be
right
, bottom
, undocked
, detach
. Defaults to last used dock state.
In undocked
mode it's possible to dock back. In detach
mode it's not.Opens the devtools.
When contents
is a <webview>
tag, the mode
would be detach
by default,
explicitly passing an empty mode
can force using last used dock state.
contents.closeDevTools()
Closes the devtools.
contents.isDevToolsOpened()
Returns Boolean
- Whether the devtools is opened.
contents.isDevToolsFocused()
Returns Boolean
- Whether the devtools view is focused .
contents.toggleDevTools()
Toggles the developer tools.
contents.inspectServiceWorker()
Opens the developer tools for the service worker context.
contents.send(channel[, arg1][, arg2][, ...])
channel
String...args
any[]Send an asynchronous message to renderer process via channel
, you can also
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.
An example of sending messages from the main process to the renderer process:
// In the main process.
const {app, BrowserWindow} = require('electron')
let win = null
app.on('ready', () => {
win = new BrowserWindow({width: 800, height: 600})
win.loadURL(`file://${__dirname}/index.html`)
win.webContents.on('did-finish-load', () => {
win.webContents.send('ping', 'whoooooooh!')
})
})
<!-- index.html -->
<html>
<body>
<script>
require('electron').ipcRenderer.on('ping', (event, message) => {
console.log(message) // Prints 'whoooooooh!'
})
</script>
</body>
</html>
contents.enableDeviceEmulation(parameters)
parameters
Object
screenPosition
String - Specify the screen type to emulate
(default: desktop
):
desktop
- Desktop screen type.mobile
- Mobile screen type.screenSize
Size - Set the emulated screen size (screenPosition == mobile).viewPosition
Point - Position the view on the screen
(screenPosition == mobile) (default: {x: 0, y: 0}
).deviceScaleFactor
Integer - Set the device scale factor (if zero defaults to
original device scale factor) (default: 0
).viewSize
Size - Set the emulated view size (empty means no override)scale
Float - Scale of emulated view inside available space (not in fit to
view mode) (default: 1
).Enable device emulation with the given parameters.
contents.disableDeviceEmulation()
Disable device emulation enabled by webContents.enableDeviceEmulation
.
contents.sendInputEvent(event)
event
Object
type
String (required) - The type of the event, can be mouseDown
,
mouseUp
, mouseEnter
, mouseLeave
, contextMenu
, mouseWheel
,
mouseMove
, keyDown
, keyUp
or char
.modifiers
String[] - 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.
Note: The BrowserWindow
containing the contents needs to be focused for
sendInputEvent()
to work.
For keyboard events, the event
object also have following properties:
keyCode
String (required) - The character that will be sent
as the keyboard event. Should only use the valid key codes in
Accelerator.For mouse events, the event
object also have following properties:
x
Integer (required)y
Integer (required)button
String - The button pressed, can be left
, middle
, right
.globalX
IntegerglobalY
IntegermovementX
IntegermovementY
IntegerclickCount
IntegerFor the mouseWheel
event, the event
object also have following properties:
deltaX
IntegerdeltaY
IntegerwheelTicksX
IntegerwheelTicksY
IntegeraccelerationRatioX
IntegeraccelerationRatioY
IntegerhasPreciseScrollingDeltas
BooleancanScroll
Booleancontents.beginFrameSubscription([onlyDirty ,]callback)
onlyDirty
Boolean (optional) - Defaults to false
.callback
Function
frameBuffer
BufferdirtyRect
RectangleBegin subscribing for presentation events and captured frames, the callback
will be called with callback(frameBuffer, dirtyRect)
when there is a
presentation event.
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).
The dirtyRect
is an object with x, y, width, height
properties that
describes which part of the page was repainted. If onlyDirty
is set to
true
, frameBuffer
will only contain the repainted area. onlyDirty
defaults to false
.
contents.endFrameSubscription()
End subscribing for frame presentation events.
contents.startDrag(item)
item
Object
file
String or files
Array - The path(s) to the file(s) being dragged.icon
NativeImage - The image must be non-empty on
macOS.Sets the item
as dragging item for current drag-drop operation, file
is the
absolute path of the file to be dragged, and icon
is the image showing under
the cursor when dragging.
contents.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 - (error) => {}
.
error
ErrorReturns Boolean
- true if the process of saving page has been initiated successfully.
const {BrowserWindow} = require('electron')
let win = new BrowserWindow()
win.loadURL('https://github.com')
win.webContents.on('did-finish-load', () => {
win.webContents.savePage('/tmp/test.html', 'HTMLComplete', (error) => {
if (!error) console.log('Save page successfully')
})
})
contents.showDefinitionForSelection()
macOSShows pop-up dictionary that searches the selected word on the page.
contents.setSize(options)
Set the size of the page. This is only supported for <webview>
guest contents.
options
Object
enableAutoSize
Boolean (optional) - true to make the webview container automatically
resize within the bounds specified by the attributes normal, min and max.normal
Size (optional) - Normal size of the page. This can be used in
combination with the disableguestresize
attribute to manually resize the webview guest contents.min
Size (optional) - Minimum size of the page. This can be used in
combination with the disableguestresize
attribute to manually resize the webview guest contents.max
Size (optional) - Maximium size of the page. This can be used in
combination with the disableguestresize
attribute to manually resize the webview guest contents.contents.isOffscreen()
Returns Boolean
- Indicates whether offscreen rendering is enabled.
contents.startPainting()
If offscreen rendering is enabled and not painting, start painting.
contents.stopPainting()
If offscreen rendering is enabled and painting, stop painting.
contents.isPainting()
Returns Boolean
- If offscreen rendering is enabled returns whether it is currently painting.
contents.setFrameRate(fps)
fps
IntegerIf offscreen rendering is enabled sets the frame rate to the specified number. Only values between 1 and 60 are accepted.
contents.getFrameRate()
Returns Integer
- If offscreen rendering is enabled returns the current frame rate.
contents.invalidate()
Schedules a full repaint of the window this web contents is in.
If offscreen rendering is enabled invalidates the frame and generates a new
one through the 'paint'
event.
contents.getWebRTCIPHandlingPolicy()
Returns String
- Returns the WebRTC IP Handling Policy.
contents.setWebRTCIPHandlingPolicy(policy)
policy
String - Specify the WebRTC IP Handling Policy.
default
- Exposes user's public and local IPs. This is the default
behavior. When this policy is used, WebRTC has the right to enumerate all
interfaces and bind them to discover public interfaces.default_public_interface_only
- Exposes user's public IP, but does not
expose user's local IP. When this policy is used, WebRTC should only use the
default route used by http. This doesn't expose any local addresses.default_public_and_private_interfaces
- Exposes user's public and local
IPs. When this policy is used, WebRTC should only use the default route used
by http. This also exposes the associated default private address. Default
route is the route chosen by the OS on a multi-homed endpoint.disable_non_proxied_udp
- Does not expose public or local IPs. When this
policy is used, WebRTC should only use TCP to contact peers or servers unless
the proxy server supports UDP.Setting the WebRTC IP handling policy allows you to control which IPs are exposed via WebRTC. See BrowserLeaks for more details.
contents.getOSProcessId()
Returns Integer
- The pid
of the associated renderer process.
contents.id
A Integer
representing the unique ID of this WebContents.
contents.session
A Session
used by this webContents.
contents.hostWebContents
A WebContents
instance that might own this WebContents
.
contents.devToolsWebContents
A WebContents
of DevTools for this WebContents
.
Note: Users should never store this object because it may become null
when the DevTools has been closed.
contents.debugger
A Debugger instance for this webContents.