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 整數 - 代表擁有框架的程序的內部 ID 的 Integer。
• routingId 整數 - 代表當前渲染程序中唯一框架 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 布林值 (可選) - 預設為 false。

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

在頁面中評估 code。

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

frame.reload()

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

frame.isDestroyed()

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

frame.send(channel, ...args)

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

通過 channel 向渲染程序發送異步消息，以及參數。參數將使用 結構化複製演算法 序列化，就像 postMessage 一樣，因此不包括原型鏈。發送函數、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 情況下無響應時很有用。有關更多資訊，請參閱 擬議的崩潰報告 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。這與作業系統進程 ID 不同；要讀取該 ID，請使用 frame.osProcessId。

frame.routingId 唯讀

一個 Integer，表示當前渲染程序中唯一的框架 ID。引用相同底層框架的不同 WebFrameMain 實例將具有相同的 routingId。

frame.visibilityState 唯讀

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

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

frame.detached 唯讀

一個 Boolean，表示框架是否與框架樹分離。如果在相應頁面運行任何 unload 監聽器時訪問框架，則框架可能會分離，因為新導航的頁面在框架樹中替換了它。