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.fromFrameToken(processId, frameToken)

• processId Integer - 一个 Integer，表示拥有该框架的进程的内部 ID。
• frameToken string - 一个 string 令牌，用于标识唯一的框架。也可以通过 webFrame.frameToken 在渲染器进程中检索。

返回 WebFrameMain | null - 具有给定进程和框架令牌的框架，或者如果与给定 ID 没有关联的 WebFrameMain，则返回 null。

类: 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 - 重新加载是否已成功启动。只有当框架没有历史记录时，才会返回 false。

frame.isDestroyed()

返回 boolean - 框架是否已销毁。

frame.send(channel, ...args)

• channel string
• ...args any[]

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

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

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

• channel string
• message any
• transfer MessagePortMain[] (可选)

向渲染器进程发送消息，可以选择性地转移零个或多个 MessagePortMain 对象的所有权。

转移的 MessagePortMain 对象将在渲染器进程中通过访问发出的事件的 ports 属性获得。当它们到达渲染器时，它们将是 native 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，表示框架的当前 origin，根据 RFC 6454 序列化。这可能与 URL 不同。例如，如果框架是打开到 about:blank 的子窗口，则 frame.origin 将返回父框架的 origin，而 frame.url 将返回空字符串。没有 scheme/host/port 三元组 origin 的页面将具有序列化的 origin "null"（即包含字母 n、u、l、l 的字符串）。

frame.top 只读

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

frame.parent 只读

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

frame.frames 只读

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

frame.framesInSubtree 只读

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

frame.frameTreeNodeId 只读

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

frame.name 只读

一个 string，表示框架名称。

frame.frameToken 只读

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

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 监听器时访问帧，它可能会被分离，因为新导航的页面已在帧树中替换了它。