webFrameMain

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

プロセス: Main

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'

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.send(channel, ...args)

• channel string
• ...args any[]

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

レンダラープロセスは ipcRenderer モジュールで channel を聞いてメッセージを処理できます。

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

• channel string
• message any
• transfer MessagePortMain[] (任意)

メッセージをレンダラープロセスに送信し、任意でゼロ個以上の MessagePortMain オブジェクトの所有権を転送します。

転送された 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.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 読み出し専用

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 型で、そのフレームの 可視性の状態 を表します。

ページ可視性 API が他の Electron API から受ける影響についてもご覧ください。