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 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、符号、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 运行，则 Promise 永远不会解析。如果调用堆栈无法收集，它将返回 undefined。

这在确定框架为何无响应（在存在长时间运行的 JavaScript 的情况下）时可能很有用。有关更多信息，请参阅 提议的 Crash Reporting 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 只读

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

frame.framesInSubtree 只读

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

frame.frameTreeNodeId 只读

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

frame.name 只读

一个 string，表示框架名称。

frame.osProcessId 只读

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

frame.processId 只读

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

frame.routingId 只读

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

frame.visibilityState 只读

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

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

frame.detached 只读

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