webFrameMain
控制网页和 iframe。
进程:主进程
webFrameMain
模块可用于在现有 WebContents
实例中查找帧。导航事件是常见的用例。
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)
}
}
)
你也可以通过使用 WebContents
的 mainFrame
属性来访问现有页面的帧。
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()
方法
这些方法可以从 webFrameMain
模块访问
webFrameMain.fromId(processId, routingId)
processId
Integer - 表示拥有该帧的进程的内部 ID 的Integer
类型。routingId
Integer - 表示当前渲染进程中唯一帧 ID 的Integer
类型。路由 ID 可以从WebFrameMain
实例 (frame.routingId
) 中检索,并且也由帧特定的WebContents
导航事件 (例如did-frame-navigate
) 传递。
返回 WebFrameMain | undefined
- 具有给定进程和路由 ID 的帧,如果与给定 ID 没有关联的 WebFrameMain,则返回 undefined
。
类:WebFrameMain
进程:主进程
这个类没有从 'electron'
模块导出。它只作为 Electron API 中其他方法的返回值可用。
实例事件
事件:'dom-ready'
当文档加载时发出。
实例方法
frame.executeJavaScript(code[, userGesture])
code
字符串userGesture
布尔值 (可选) - 默认为false
。
返回 Promise<unknown>
- 一个 Promise,它会解析为执行代码的结果,或者在执行抛出异常或导致 Promise 被拒绝时被拒绝。
在页面中评估 code
。
在浏览器窗口中,一些 HTML API (如 requestFullScreen
) 只能由用户手势触发。将 userGesture
设置为 true
将解除此限制。
frame.reload()
返回 boolean
- 重新加载是否成功启动。只有当帧没有历史记录时才返回 false
。
frame.isDestroyed()
返回 boolean
- 帧是否已销毁。
frame.send(channel, ...args)
channel
字符串...args
任意类型数组
通过 channel
向渲染进程发送异步消息,并附带参数。参数将使用 结构化克隆算法 进行序列化,就像 postMessage
一样,因此不会包含原型链。发送函数、Promise、Symbol、WeakMap 或 WeakSet 将抛出异常。
渲染进程可以通过使用 ipcRenderer
模块监听 channel
来处理消息。
frame.postMessage(channel, message, [transfer])
channel
字符串message
任意类型transfer
MessagePortMain[] (可选)
向渲染进程发送消息,可选择性地转移零个或多个 MessagePortMain
对象的拥有权。
被转移的 MessagePortMain
对象将通过访问触发事件的 ports
属性在渲染进程中可用。当它们到达渲染器时,它们将是原生的 DOM MessagePort
对象。
例如
// 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()
实验性
返回 Promise<string> | Promise<void>
- 一个 Promise,它会解析为当前正在运行的 JavaScript 调用栈。如果帧中没有运行 JavaScript,该 Promise 将永远不会解析。在调用栈无法被收集的情况下,它将返回 undefined
。
这在存在长时间运行的 JavaScript 导致帧无响应的情况下可能很有用。有关更多信息,请参阅 提议的崩溃报告 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)
})
})
实例属性
frame.ipc
只读
一个作用域限定于帧的 IpcMain
实例。
通过 ipcRenderer.send
、ipcRenderer.sendSync
或 ipcRenderer.postMessage
发送的 IPC 消息将按以下顺序传递
contents.on('ipc-message')
contents.mainFrame.on(channel)
contents.ipc.on(channel)
ipcMain.on(channel)
使用 invoke
注册的处理程序将按以下顺序检查。第一个被定义的回调将被调用,其余的将被忽略。
contents.mainFrame.handle(channel)
contents.handle(channel)
ipcMain.handle(channel)
在大多数情况下,只有 WebContents 的主帧才能发送或接收 IPC 消息。但是,如果启用了 nodeIntegrationInSubFrames
选项,子帧也可以发送和接收 IPC 消息。WebContents.ipc
接口在未启用 nodeIntegrationInSubFrames
时可能更方便。
frame.url
只读
表示帧当前 URL 的 string
类型。
frame.origin
只读
表示帧当前来源的 string
类型,根据 RFC 6454 序列化。这可能与 URL 不同。例如,如果帧是一个打开到 about:blank
的子窗口,那么 frame.origin
将返回父帧的来源,而 frame.url
将返回空字符串。没有方案/主机/端口三重来源的页面将具有序列化来源 "null"
(即包含字母 n、u、l、l 的字符串)。
frame.top
只读
表示 frame
所属帧层级结构中的顶层帧的 WebFrameMain | null
类型。
frame.parent
只读
表示 frame
父帧的 WebFrameMain | null
类型,如果 frame
是帧层级结构中的顶层帧,则此属性将为 null
。
frame.frames
只读
包含 frame
的直接后代的 WebFrameMain[]
集合。
frame.framesInSubtree
只读
包含 frame
子树中所有帧的 WebFrameMain[]
集合,包括其自身。这在遍历所有帧时可能很有用。
frame.frameTreeNodeId
只读
表示帧内部 FrameTreeNode 实例 ID 的 Integer
类型。此 ID 是浏览器全局的,并唯一标识一个承载内容的帧。该标识符在帧创建时固定,并在帧的生命周期内保持不变。当帧被移除时,该 ID 不会再次使用。
frame.name
只读
表示帧名称的 string
类型。
frame.osProcessId
只读
表示拥有此帧的进程的操作系统 pid
的 Integer
类型。
frame.processId
只读
表示拥有此帧的 Chromium 内部 pid
的 Integer
类型。这与操作系统进程 ID 不同;要读取操作系统进程 ID,请使用 frame.osProcessId
。
frame.routingId
只读
表示当前渲染进程中唯一帧 ID 的 Integer
类型。引用相同底层帧的不同 WebFrameMain
实例将具有相同的 routingId
。
frame.visibilityState
只读
表示帧的 可见性状态 的 string
类型。
另请参阅 页面可见性 API 如何受其他 Electron API 的影响。
frame.detached
只读
一个 Boolean
类型,表示帧是否从帧树中分离。如果在相应页面运行任何 卸载 侦听器时访问帧,则该帧可能会因新导航的页面在帧树中替换它而分离。