メインコンテンツへ飛ぶ

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)
}
}
)

また、WebContentsmainFrame プロパティを使用することでも既存ページのフレームへアクセスできます。

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 は、ユーザからのジェスチャーでのみ呼び出されます。 userGesturetrue にセットすることでこの制限がなくなります。

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[] (任意)

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

転送された MessagePortMain オブジェクトは、レンダラープロセスで発生したイベントの ports プロパティにアクセスすれば利用できます。 レンダラーに着くと、それらはネイティブの DOM MessagePort オブジェクトになります。

以下がその例です。

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

// レンダラープロセス
ipcRenderer.on('port', (e, msg) => {
const [port] = e.ports
// ...
})

インスタンスプロパティ

frame.ipc Readonly

An IpcMain instance scoped to the frame.

IPC messages sent with ipcRenderer.send, ipcRenderer.sendSync or ipcRenderer.postMessage will be delivered in the following order:

  1. contents.on('ipc-message')
  2. contents.mainFrame.on(channel)
  3. contents.ipc.on(channel)
  4. ipcMain.on(channel)

Handlers registered with invoke will be checked in the following order. The first one that is defined will be called, the rest will be ignored.

  1. contents.mainFrame.handle(channel)
  2. contents.handle(channel)
  3. ipcMain.handle(channel)

In most cases, only the main frame of a WebContents can send or receive IPC messages. However, if the nodeIntegrationInSubFrames option is enabled, it is possible for child frames to send and receive IPC messages also. The WebContents.ipc interface may be more convenient when nodeIntegrationInSubFrames is not enabled.

frame.url 読み出し専用

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

frame.origin Readonly

A string representing the current origin of the frame, serialized according to RFC 6454. This may be different from the URL. For instance, if the frame is a child window opened to about:blank, then frame.origin will return the parent frame's origin, while frame.url will return the empty string. Pages without a scheme/host/port triple origin will have the serialized origin of "null" (that is, the string containing the letters 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 Readonly

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

See also how the Page Visibility API is affected by other Electron APIs.