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 - 一个 Integer，表示拥有该帧的进程的内部 ID。
• routingId Integer - 一个 Integer，表示当前渲染器进程中的唯一帧 ID。路由 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 any[]

通过 channel 向渲染器进程发送异步消息，以及参数。参数将使用结构化克隆算法进行序列化，就像postMessage一样，因此不会包含原型链。发送函数、Promise、符号、WeakMap 或 WeakSet 将抛出异常。

渲染器进程可以通过使用ipcRenderer模块监听channel来处理消息。

frame.postMessage(channel, message, [transfer])

• channel 字符串
• message any
• 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 消息将按以下顺序传递

1. contents.on('ipc-message')
2. contents.mainFrame.on(channel)
3. contents.ipc.on(channel)
4. ipcMain.on(channel)

使用 invoke 注册的处理程序将按以下顺序进行检查。将调用第一个定义的处理程序，其余的将被忽略。

1. contents.mainFrame.handle(channel)
2. contents.handle(channel)
3. ipcMain.handle(channel)

在大多数情况下，只有 WebContents 的主帧才能发送或接收 IPC 消息。但是，如果启用了 nodeIntegrationInSubFrames 选项，则子帧也可以发送和接收 IPC 消息。当未启用 nodeIntegrationInSubFrames 时，WebContents.ipc 接口可能更方便。

frame.url 只读

一个 string，表示该帧的当前 URL。

frame.origin 只读

一个 string，表示帧的当前源，根据RFC 6454进行序列化。这可能与 URL 不同。例如，如果该帧是打开到 about:blank 的子窗口，则 frame.origin 将返回父帧的源，而 frame.url 将返回空字符串。没有 scheme/host/port 三元组源的页面将具有序列化后的源 "null"（即包含字母 n、u、l、l 的字符串）。

frame.top 只读

一个 WebFrameMain | null，表示 frame 所属的帧层次结构中的顶层帧。

frame.parent 只读

一个 WebFrameMain | null，表示 frame 的父帧，如果 frame 是帧层次结构中的顶层帧，则该属性将为 null。

frame.frames 只读

一个包含 frame 的直接后代的 WebFrameMain[] 集合。

frame.framesInSubtree 只读

一个 WebFrameMain[] 集合，其中包含 frame 子树中的每个帧，包括它自身。这在遍历所有帧时很有用。

frame.frameTreeNodeId 只读

一个 Integer，表示帧的内部 FrameTreeNode 实例的 ID。此 ID 是浏览器全局的，并且唯一标识托管内容的帧。该标识符在创建帧时固定，并在帧的生命周期内保持不变。当删除该帧时，该 ID 将不再使用。

frame.name 只读

一个 string，表示帧名称。

frame.osProcessId 只读

一个 Integer，表示拥有此帧的进程的操作系统 pid。

frame.processId 只读

一个 Integer，表示拥有此帧的进程的 Chromium 内部 pid。这与操作系统进程 ID 不同；要读取操作系统进程 ID，请使用 frame.osProcessId。

frame.routingId 只读

一个 Integer，表示当前渲染器进程中唯一的帧 ID。引用同一个底层帧的不同 WebFrameMain 实例将具有相同的 routingId。

frame.visibilityState 只读

一个 string，表示帧的可见性状态。

另请参阅页面可见性 API 如何受到其他 Electron API 的影响。

frame.detached 只读

一个 Boolean，表示帧是否已从帧树中分离。如果在相应的页面运行任何 unload 侦听器时访问某个帧，则该帧可能会分离，因为新导航的页面已在帧树中替换了它。