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
stringuserGesture
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
stringmessage
anytransfer
MessagePortMain[] (任意)
メッセージをレンダラープロセスに送信し、任意でゼロ個以上の 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
読み出し専用
そのフレームに範囲が限定された IpcMain
インスタンス。
ipcRenderer.send
、ipcRenderer.sendSync
や ipcRenderer.postMessage
で送信した IPC メッセージは以下の順番で伝達されます。
contents.on('ipc-message')
contents.mainFrame.on(channel)
contents.ipc.on(channel)
ipcMain.on(channel)
invoke
で登録されたハンドラは以下の順番で確認されます。 最初に定義されているものが呼び出され, 以降は無視されます。
contents.mainFrame.handle(channel)
contents.handle(channel)
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 から受ける影響についてもご覧ください。