webFrameMain

控制网页和 iframe。

进程：主进程

webFrameMain 模块可用于查找现有 WebContents 实例中的 frame。导航事件是最常见的用例。

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 属性来访问现有页面的 frame。

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 - 代表拥有该 frame 的进程的内部 ID 的 Integer。
• routingId Integer - 代表当前渲染器进程中唯一 frame ID 的 Integer。路由 ID 可以从 WebFrameMain 实例（frame.routingId）中检索，也可以通过特定 frame 的 WebContents 导航事件（例如 did-frame-navigate）传递。

返回 WebFrameMain | undefined - 具有给定进程 ID 和路由 ID 的 frame，如果不存在与给定 ID 关联的 WebFrameMain，则返回 undefined。

webFrameMain.fromFrameToken(processId, frameToken)

• processId Integer - 代表拥有该 frame 的进程的内部 ID 的 Integer。
• frameToken string - 标识唯一 frame 的 string token。也可以在渲染器进程中通过 webFrame.frameToken 检索。

返回 WebFrameMain | null - 具有给定进程 ID 和 frame token 的 frame，如果不存在与给定 ID 关联的 WebFrameMain，则返回 null。

Class: WebFrameMain

进程：主进程
此类未从 'electron' 模块导出。它仅作为 Electron API 中其他方法的返回值可用。

实例事件

事件: 'dom-ready'

当文档加载完成时触发。

实例方法

frame.executeJavaScript(code[, userGesture])

• code string
• userGesture boolean (可选) - 默认为 false。

返回 Promise<unknown> - 一个 Promise，它会以执行代码的结果解析，如果执行抛出异常或导致 Promise 被拒绝，则会拒绝。

在页面中执行 code。

在浏览器窗口中，某些 HTML API（如 requestFullScreen）只能由用户的手势调用。将 userGesture 设置为 true 将消除此限制。

frame.reload()

返回 boolean - 重新加载是否成功启动。仅在 frame 没有历史记录时返回 false。

frame.isDestroyed()

返回 boolean - frame 是否已被销毁。

frame.send(channel, ...args)

• channel string
• ...args any[]

通过 channel 将异步消息发送到渲染器进程，并附带参数。参数将使用 结构化克隆算法 进行序列化，就像 postMessage 一样，因此原型链不会被包含。发送 Functions、Promises、Symbols、WeakMaps 或 WeakSets 将会抛出异常。

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

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

• channel string
• 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() Experimental

返回 Promise<string> | Promise<void> - 一个 Promise，它将以当前运行的 JavaScript 调用堆栈解析。如果没有 JavaScript 在 frame 中运行，则 Promise 永远不会解析。在无法收集调用堆栈的情况下，它将返回 undefined。

这对于确定 frame 无响应的原因非常有用，尤其是在存在长时间运行的 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 Readonly

一个作用域限定在 frame 的 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 的主 frame 才能发送或接收 IPC 消息。但是，如果启用了 nodeIntegrationInSubFrames 选项，则子 frame 也可以发送和接收 IPC 消息。当 nodeIntegrationInSubFrames 未启用时，WebContents.ipc 接口可能会更方便。

frame.url Readonly

一个 string，表示 frame 的当前 URL。

frame.origin Readonly

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

frame.top Readonly

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

frame.parent Readonly

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

frame.frames Readonly

一个 WebFrameMain[] 集合，包含 frame 的直接子级。

frame.framesInSubtree Readonly

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

frame.frameTreeNodeId Readonly

一个 Integer，表示 frame 内部 FrameTreeNode 实例的 ID。此 ID 是全局唯一的，并唯一标识托管内容的 frame。该标识符在 frame 创建时固定，并在 frame 的生命周期内保持不变。当 frame 被移除时，该 ID 不会再次使用。

frame.name Readonly

一个 string，表示 frame 的名称。

frame.frameToken Readonly

一个 string，唯一标识其关联渲染器进程中的 frame。这与 webFrame.frameToken 相同。

frame.osProcessId Readonly

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

frame.processId Readonly

一个 Integer，表示拥有此 frame 的进程的 Chromium 内部 pid。这与 OS 进程 ID 不同；要获取 OS 进程 ID，请使用 frame.osProcessId。

frame.routingId Readonly

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

frame.visibilityState Readonly

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

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

frame.detached Readonly

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