メインコンテンツへ飛ぶ

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, 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][] と同様に [構造化複製アルゴリズム][SCA] でシリアライズされるので、プロトタイプチェーンは含まれません。 関数、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.url 読み出し専用

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

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

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