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

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

类: 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 一样，因此原型链不会被包含。发送函数、Promise、Symbol、WeakMap 或 WeakSet 将引发异常。

渲染器进程可以通过使用 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() 实验性

返回 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 只读

一个作用于该 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 只读

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

frame.origin 只读

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

frame.top 只读

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

frame.parent 只读

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

frame.frames 只读

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

frame.framesInSubtree 只读

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

frame.frameTreeNodeId 只读

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

frame.name 只读

一个 string，表示 frame 名称。

frame.osProcessId 只读

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

frame.processId 只读

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

frame.routingId 只读

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

frame.visibilityState 只读

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

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

frame.detached 只读

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