メインコンテンツへ飛ぶ

webFrameMain

ウェブページと iframe を制御します。

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 を表します。 ルーティング ID は、WebFrameMain インスタンス (frame.routingId) から取得できるほか、フレーム固有の WebContents ナビゲーションイベント (did-frame-navigate など) によっても渡されます。

戻り値 WebFrameMain | undefined - 指定のプロセスとルーティングの ID のフレームです。指定の ID に関連付けられた WebFrameMain がない場合は undefined になります。

クラス: 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 型で、コードの実行結果で解決され、実行で例外の送出または実行結果が拒否された Promise の場合は拒否されます。

ページ内の code を評価します。

ブラウザウインドウでは、requestFullScreen のような、いくつかの HTML API は、ユーザからのジェスチャーでのみ呼び出されます。 userGesture を true にセットすることでこの制限がなくなります。

frame.reload()​

戻り値 boolean - リロードが正常に開始されたかどうか。 フレームに履歴がない場合のみ false になります。

frame.isDestroyed()​

Returns boolean - Whether the frame is destroyed.

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

  • channel string
  • ...args any[]

引数と共に、channel を介してレンダラープロセスに非同期メッセージを送信します。 引数は postMessage と同じように 構造化複製アルゴリズム によってシリアライズされるため、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。

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 オブジェクトになります。

以下がその例です。

// メインプロセス
const win = new BrowserWindow()
const { port1, port2 } = new MessageChannelMain()
win.webContents.mainFrame.postMessage('port', { message: 'hello' }, [port1])

// レンダラープロセス
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 読み出し専用​

An IpcMain instance scoped to the frame.

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 メッセージを送受信できます。 The WebContents.ipc interface may be more convenient when nodeIntegrationInSubFrames is not enabled.

frame.url 読み出し専用​

string 型で、そのフレームの現在の URL を表します。

frame.origin 読み出し専用​

string 型で、そのフレームの現在のオリジンを表し、RFC 6454 によってシリアライズされています。 これは 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 を表します。 これは OS のプロセス ID と同じではありません。それを読み出すには frame.osProcessId を使用してください。

frame.routingId 読み出し専用​

現在のレンダラープロセスでの一意なフレーム ID を表す Integer。 同じ基底フレームを参照する WebFrameMain インスタンスすべては、それぞれ同じ routingId になります。

frame.visibilityState 読み出し専用​

string 型で、そのフレームの 可視性の状態 を表します。

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.