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 - 代表擁有框架的進程的內部 ID 的 Integer。
• routingId Integer - 代表目前渲染器進程中唯一框架 ID 的 Integer。路由 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 字串
• userGesture boolean (選用) - 預設為 false。

返回 Promise<unknown> - 一個 promise，它會解析為執行程式碼的結果，如果執行拋出或導致 rejected promise，則會被拒絕。

在頁面中評估 code。

在瀏覽器視窗中，某些 HTML API (例如 requestFullScreen) 只能由使用者的手勢調用。將 userGesture 設定為 true 將會移除此限制。

frame.reload()

返回 boolean - 重新載入是否成功啟動。只有當框架沒有歷史記錄時才會導致 false。

frame.isDestroyed()

返回 boolean - 框架是否已銷毀。

frame.send(channel, ...args)

• channel 字串
• ...args any[]

透過 channel 向渲染器進程發送非同步訊息，以及參數。參數將會使用 結構化複製演算法進行序列化，就像 postMessage 一樣，因此不會包含原型鏈。發送 Function、Promise、Symbol、WeakMap 或 WeakSet 將會拋出例外狀況。

渲染器進程可以透過使用 ipcRenderer 模組監聽 channel 來處理訊息。

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

• channel 字串
• 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 訊息。WebContents.ipc 介面在未啟用 nodeIntegrationInSubFrames 時可能更方便。

frame.url 唯讀

代表框架目前 URL 的 string。

frame.origin 唯讀

代表根據 RFC 6454 序列化的框架目前來源的 string。這可能與 URL 不同。例如，如果框架是開啟至 about:blank 的子視窗，則 frame.origin 將會返回父框架的來源，而 frame.url 將會返回空字串。沒有方案/主機/埠三重來源的頁面將會具有序列化來源 "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。這與作業系統的進程 ID 不同；若要讀取作業系統的進程 ID，請使用 frame.osProcessId。

frame.routingId 唯讀

一個 Integer，表示目前渲染進程中唯一的框架 ID。指向同一個底層框架的不同 WebFrameMain 實例將具有相同的 routingId。

frame.visibilityState 唯讀

一個 string，表示框架的可見性狀態。

另請參閱 頁面可見性 API 如何受到其他 Electron API 的影響。

frame.detached 唯讀

一個 Boolean，表示框架是否已從框架樹中分離。如果在對應的頁面正在運行任何 unload 監聽器時訪問框架，則該框架可能會因為新導航的頁面在框架樹中取代它而分離。