メインコンテンツへ飛ぶ

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 - Integer 型で、そのフレームを所有しているプロセスの内部 ID を表します。
  • routingId Integer - Integer 型で、現在のレンダラープロセスでの一意なフレーム ID を表します。 ルーティング ID は、WebFrameMain インスタンス (frame.routingId) から取得できるほか、フレーム固有の WebContents ナビゲーションイベント (did-frame-navigate など) によっても渡されます。

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

webFrameMain.fromFrameToken(processId, frameToken)​

  • processId Integer - Integer 型で、そのフレームを所有しているプロセスの内部 ID を表します。
  • frameToken string - string 型で、フレームを一意に識別するトークンです。 レンダラープロセスで webFrame.frameToken を介して取得することもできます。

戻り値 WebFrameMain | null - 指定されたプロセスとフレームのトークンを持つフレーム。指定の ID に関連付けられた WebFrameMain がない場合は null になります。

クラス: 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.isDestroyed()​

戻り値 boolean - フレームが破棄されているかどうか。

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.collectJavaScriptCallStack() 実験的​

戻り値 Promise<string> | Promise<void> - 現在実行中の JavaScript 呼び出しのスタックで解決される Promise。 フレーム内で 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 () => {
    // 実行を中断し、応答しないレンダラーからコールスタックを収集します
    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 は空文字列を返します。 スキーム/ホスト/ポートのトリプルオリジンを持たないページは、シリアライズされたオリジンが "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.frameToken 読み出し専用​

string 型で、関連レンダラープロセス内でフレームを一意に識別します。 これは webFrame.frameToken と等価です。

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 から受ける影響についてもご覧ください。

frame.detached 読み出し専用​

Boolean 型で、フレームがフレームツリーから切り離されているかどうかを表します。 対応するページで unload リスナーが実行されているときにフレームにアクセスすると、フレームツリー内で新しくナビゲーションされたページがフレームを置き換えるため、フレームが切り離される可能性があります。