跳转到主内容

webFrameMain

控制页面和内联框架(iframes)。

Process: Main

The webFrameMain module can be used to lookup frames across existing WebContents instances. 通常在导航事件中使用。

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)
    }
  }
)

You can also access frames of existing pages by using the mainFrame property of WebContents.

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 。 Routing IDs 可以从 WebFrameMain instances (frame.routingId) 获取到，也可以从 frame 指定的 WebContents 的导航事件 (例如 did-frame-navigate) 传入。

返回 WebFrameMain | undefined - 一个带有指定进程和 routing IDs 的 frame，如果指定的 IDs 没有关联的 WebFrameMain 则为 undefined。

Class: WebFrameMain​

Process: Main
This class is not exported from the 'electron' module. 它只能作为 Electron API 中其他方法的返回值。

实例事件​

事件: 'dom-ready'​

当 document 被加载完时触发。

实例方法​

frame.executeJavaScript(code[, userGesture])​

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

返回 Promise<unknown> - 执行代码结果的 promise 的 resolves，如果执行异常或结果为 rejected promise，则为 rejected。

在页面中执行 code。

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

frame.reload()​

返回 boolean - 重新加载是否成功。 仅当 frame 没有历史记录，结果才会为 false。

frame.isDestroyed()​

Returns boolean - Whether the frame is destroyed.

frame.send(channel, ...args)​

  • channel string
  • ...args any[]

由经 channel 向渲染进程发送异步带参消息。 Arguments will be serialized with the Structured Clone Algorithm, just like postMessage, so prototype chains will not be included. Sending Functions, Promises, Symbols, WeakMaps, or WeakSets will throw an exception.

The renderer process can handle the message by listening to channel with the ipcRenderer module.

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

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

Send a message to the renderer process, optionally transferring ownership of zero or more MessagePortMain objects.

被传递 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​

Returns Promise<string> | Promise<void> - A promise that resolves with the currently running JavaScript call stack. If no JavaScript runs in the frame, the promise will never resolve. In cases where the call stack is otherwise unable to be collected, it will return undefined.

This can be useful to determine why the frame is unresponsive in cases where there's long-running JavaScript. For more information, see the proposed 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 Readonly​

An IpcMain instance scoped to the frame.

IPC messages sent with ipcRenderer.send, ipcRenderer.sendSync or ipcRenderer.postMessage will be delivered in the following order:

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

Handlers registered with invoke will be checked in the following order. The first one that is defined will be called, the rest will be ignored.

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

In most cases, only the main frame of a WebContents can send or receive IPC messages. However, if the nodeIntegrationInSubFrames option is enabled, it is possible for child frames to send and receive IPC messages also. The WebContents.ipc interface may be more convenient when nodeIntegrationInSubFrames is not enabled.

frame.url 只读​

一个 string 值，代表 frame 当前的 URL。

frame.origin 只读​

一个 string 值，代表 frame 当前的 origin ，序列化符合 RFC 6454。 这可能来自不同的 URL。 例如，如果 frame 是子窗口打开 about:blank，则frame.origin 将返回父 frame 的 origin，同时 frame.url 将返回空字符号。 页面没有 scheme/host/port 三个 origin 将被序列化成 "null" （即，一个字符串，包括 n，u，l，l 字母）。

frame.top 只读​

一个 WebFrameMain | null 值，代表 frame 所属 frame 层级中的顶部 frame。

frame.parent 只读​

一个 WebFrameMain | null 值， 表示 frame 的父 frame，如果 frame 在层级中是顶级 frame，则属性将为 null。

frame.frames 只读​

一个 WebFrameMain[] 值，包含子 frame 的集合。

frame.framesInSubtree 只读​

一个 WebFrameMain[] 值 ，包含子树上的每一个 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 不同，系统进程需要使用 frame.osProcessId。

frame.routingId 只读​

一个 Integer 值，表示当前渲染进程中的唯一 frame 的 id。 不同的 WebFrameMain 实例，引用相同的相关 frame，具有相同的 routingId。

frame.visibilityState 只读​

一个 string 值，表示 frame 的 visibility state 。

See also how the Page Visibility API is affected by other Electron APIs.

frame.detached 只读​

A Boolean representing whether the frame is detached from the frame tree. If a frame is accessed while the corresponding page is running any unload listeners, it may become detached as the newly navigated page replaced it in the frame tree.