webFrameMain
Control web pages and iframes.
Process: Main
The webFrameMain
module can be used to lookup frames across existing
WebContents
instances. Navigation events are the common
use case.
const { BrowserWindow, webFrameMain } = require('electron')
const win = new BrowserWindow({ width: 800, height: 1500 })
win.loadURL('https://twitter.com')
win.webContents.on(
'did-frame-navigate',
(event, url, httpResponseCode, httpStatusText, isMainFrame, frameProcessId, frameRoutingId) => {
const frame = webFrameMain.fromId(frameProcessId, frameRoutingId)
if (frame) {
const code = 'document.body.innerHTML = document.body.innerHTML.replaceAll("heck", "h*ck")'
frame.executeJavaScript(code)
}
}
)
You can also access frames of existing pages by using the mainFrame
property
of WebContents
.
const { BrowserWindow } = require('electron')
async function main () {
const win = new BrowserWindow({ width: 800, height: 600 })
await win.loadURL('https://reddit.com')
const youtubeEmbeds = win.webContents.mainFrame.frames.filter((frame) => {
try {
const url = new URL(frame.url)
return url.host === 'www.youtube.com'
} catch {
return false
}
})
console.log(youtubeEmbeds)
}
main()
Methods
These methods can be accessed from the webFrameMain
module:
webFrameMain.fromId(processId, routingId)
processId
Integer - AnInteger
representing the internal ID of the process which owns the frame.routingId
Integer - AnInteger
representing the unique frame ID in the current renderer process. Routing IDs can be retrieved fromWebFrameMain
instances (frame.routingId
) and are also passed by frame specificWebContents
navigation events (e.g.did-frame-navigate
).
Returns WebFrameMain | undefined
- A frame with the given process and routing IDs,
or undefined
if there is no WebFrameMain associated with the given IDs.
Class: WebFrameMain
Process: Main
This class is not exported from the 'electron'
module. It is only available as a return value of other methods in the Electron API.
Instance Events
Event: 'dom-ready'
Emitted when the document is loaded.
Instance Methods
frame.executeJavaScript(code[, userGesture])
code
stringuserGesture
boolean (optional) - Default isfalse
.
Returns Promise<unknown>
- A promise that resolves with the result of the executed
code or is rejected if execution throws or results in 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.
frame.reload()
Returns boolean
- Whether the reload was initiated successfully. Only results in false
when the frame has no history.
frame.isDestroyed()
Returns boolean
- Whether the frame is destroyed.
frame.send(channel, ...args)
channel
string...args
any[]
Send an asynchronous message to the renderer process via channel
, along with
arguments. Arguments will be serialized with the Structured Clone Algorithm,
just like postMessage
, so prototype chains will not be included.
Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.
The renderer process can handle the message by listening to channel
with the
ipcRenderer
module.
frame.postMessage(channel, message, [transfer])
channel
stringmessage
anytransfer
MessagePortMain[] (optional)
Send a message to the renderer process, optionally transferring ownership of
zero or more MessagePortMain
objects.
The transferred MessagePortMain
objects will be available in the renderer
process by accessing the ports
property of the emitted event. When they
arrive in the renderer, they will be native DOM MessagePort
objects.
For example:
// Main process
const win = new BrowserWindow()
const { port1, port2 } = new MessageChannelMain()
win.webContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])
// Renderer process
ipcRenderer.on('port', (e, msg) => {
const [port] = e.ports
// ...
})
frame.collectJavaScriptCallStack()
Experimental
Returns Promise<string> | Promise<void>
- A promise that resolves with the currently running JavaScript call
stack. If no JavaScript runs in the frame, the promise will never resolve. In cases where the call stack is
otherwise unable to be collected, it will return undefined
.
This can be useful to determine why the frame is unresponsive in cases where there's long-running JavaScript. For more information, see the proposed Crash Reporting API.
const { app } = require('electron')
app.commandLine.appendSwitch('enable-features', 'DocumentPolicyIncludeJSCallStacksInCrashReports')
app.on('web-contents-created', (_, webContents) => {
webContents.on('unresponsive', async () => {
// Interrupt execution and collect call stack from unresponsive renderer
const callStack = await webContents.mainFrame.collectJavaScriptCallStack()
console.log('Renderer unresponsive\n', callStack)
})
})