メインコンテンツへ飛ぶ

<webview>タグ

警告

Electron の webview タグは Chromium の webview に基づきつつ、劇的に変更されています。 これはレンダリング、ナビゲーション、イベントルーティングを含む webview の安定性に影響しています。 私たちは webview タグを使用せずに、iframeElectron の BrowserView、または埋め込みコンテンツを完全に避けるアーキテクチャにするといった代替案の検討を推奨しています。

有効にする

既定では webview タグは Electron >= 5 では無効化されています。 タグを有効にするには、BrowserWindow を構築するときに webviewTag webPreferences オプションを設定します。 詳しい情報については、BrowserWindow コンストラクタ を参照してください。

概要

分離したフレームとプロセスに外部ウェブコンテンツを表示します。

プロセス: レンダラー
このクラスは 'electron' モジュールからはエクスポートされません。 Electron API では、他のメソッドの戻り値としてのみ利用できます。

webviewタグを使用して、Electron アプリに 'ゲスト' コンテンツ (ウェブページなど) を埋め込むことができます。 ゲストコンテンツは webview コンテナに含まれています。 アプリ内の埋め込みページは、ゲストコンテンツのレイアウトとレンダリングの方法を制御します。

iframe と異なり、 webview はアプリとは別のプロセスで実行されます。 これはウェブページと同じ権限を持っておらず、アプリと埋め込みコンテンツの間のやりとりは全て非同期になります。 これにより、埋め込みコンテンツからアプリが保護されます。 注釈: ホストページから webview 上で呼び出されるほとんどのメソッドは、メインプロセスへの同期呼び出しを必要とします。

サンプル

アプリにウェブページを埋め込むには、アプリの埋め込みページ (これはゲストコンテンツを表示するアプリページ) へ webview タグを追加します。 最もシンプルな形式では、webview タグには、ウェブページの src と、webview コンテナの見た目を制御する CSS スタイルが含まれます。

<webview id="foo" src="https://www.github.com/" style="display:inline-flex; width:640px; height:480px"></webview>

ゲストコンテンツを制御したい場合は、webview のイベントを傍受し、webview のメソッドを使用してそれらのイベントに応答する JavaScript を記述することでできます。 ここでは、2つのイベントリスナーを持つサンプルコードを示します。1つはウェブページのロード開始を、もう1つはウェブページのロード停止を傍受し、ロード時に "ロード中..." というメッセージを表示します。

<script>
onload = () => {
const webview = document.querySelector('webview')
const indicator = document.querySelector('.indicator')

const loadstart = () => {
indicator.innerText = 'loading...'
}

const loadstop = () => {
indicator.innerText = ''
}

webview.addEventListener('did-start-loading', loadstart)
webview.addEventListener('did-stop-loading', loadstop)
}
</script>

内部実装

内部では webviewOut-of-Process iframe (OOPIF) で実装されています。 webview タグは本質的には、見えない DOM を用いてその内側に iframe 要素をラップしたカスタム要素です。

なので webview の動作はクロスドメイン iframe ととても似ています。例として、

  • webviewをクリックしたとき、ページフォーカスが埋め込みフレームから webview に移動します。
  • webview にキーボード、マウス、スクロールイベントリスナを追加することはできません。
  • 埋め込みフレームと webview 間のすべての反応は非同期です。

CSS スタイルの注意事項

webview タグのスタイルでは、webview コンテナでの子の iframe 要素の高さと幅を完全に埋めるのに内部的に display:flex; を使用しているので、古典的かつフレックスボックスなレイアウトを使用するときは注意して下さい。 display:inline-flex; をインラインレイアウトに指定しない限り、デフォルトのdisplay:flex; CSS プロパティを上書きしないでください。

タグの属性

webview タグには以下の属性があります。

src

<webview src="https://www.github.com/"></webview>

表示される URL を表す string。 この属性に書き込むと、最上位のナビゲーションが始まります。

src に独自の値を代入すると、現在のページがリロードされます。

src 属性は、data:text/plain,Hello, world! などのデータ URL を受け取ることもできます。

nodeintegration

<webview src="http://www.google.com/" nodeintegration></webview>

boolean。 この属性が存在する場合、webview のゲストページは Node Integration を持ち、低レベルのシステムリソースにアクセスするのに、requireprocess のような Node API が使用できます。 デフォルトでは、ゲストページ内の Node Integration は無効化されています。

nodeintegrationinsubframes

<webview src="http://www.google.com/" nodeintegrationinsubframes></webview>

この booleanwebview 内の iframe などのサブフレームで NodeJS サポートを有効にするための実験的オプションです。 すべてのプリロードは iframe 毎にロードされます。メインフレーム内かそうでないか判断するには process.isMainFrame が使用できます。 デフォルトではゲストページ内のこのオプションは無効化されています。

plugins

<webview src="https://www.github.com/" plugins></webview>

boolean。 この属性が存在する場合、webview 内のゲストページはブラウザのプラグインを使用できます。 プラグインはデフォルトで無効です。

preload

<!-- ファイルから -->
<webview src="https://www.github.com/" preload="./test.js"></webview>
<!-- または asar アーカイブから読み込みたい場合 -->
<webview src="https://www.github.com/" preload="./app.asar/test.js"></webview>

この string は、ゲストのページで他のスクリプトを実行する前に読み込まれるスクリプトを指定します。 スクリプトの URL のプロトコルは file: である必要があります (asar: アーカイブを使用している場合でも)。これは、内部で Node の require によって、asar: アーカイブを仮想ディレクトリとして扱い読み込むためです。

ゲストページに Node Integration がない場合、このスクリプトはすべての Node APIにアクセスできますが、Node によって挿入されたグローバルオブジェクトはこのスクリプトの実行が終了した後に削除されます。

httpreferrer

<webview src="https://www.github.com/" httpreferrer="http://cheng.guru"></webview>

ゲストページの参照先 URL を設定する string

useragent

<webview src="https://www.github.com/" useragent="Mozilla/5.0 (Windows NT 6.1; WOW64; Trident/7.0; AS; rv:11.0) like Gecko"></webview>

ページがナビゲーションされる前に設定するゲストページのユーザーエージェントの string。 そのページがロードされると、setUserAgent メソッドでユーザーエージェントを変更します。

disablewebsecurity

<webview src="https://www.github.com/" disablewebsecurity></webview>

boolean。 この属性が存在すると、ゲストページでウェブセキュリティが無効になります。 ウェブセキュリティはデフォルトで有効です。

partition

<webview src="https://github.com" partition="persist:github"></webview>
<webview src="https://electronjs.org" partition="electron"></webview>

ページが使用するセッションを設定する string です。 partitionpersist: 始まりの場合、ページはアプリの全ページで利用可能な永続的なセッションを同じ partition で使用します。 persist: プレフィックスがない場合、ページは、インメモリセッションを使用します。 同じ partition を割り当てることによって、複数のページが同じセッションを共有できます。 partition が設定されていない場合は、アプリのデフォルトのセッションが使用されます。

アクティブなレンダラープロセスのセッションは変更できないため、この値は最初のナビゲーションの前にのみ変更できます。 その後の値の変更は、DOM 例外で失敗します。

allowpopups

<webview src="https://www.github.com/" allowpopups></webview>

boolean。 この属性が存在すると、ゲストページは新しいウィンドウを開くことができます。 ポップアップはデフォルトで無効です。

webpreferences

<webview src="https://github.com" webpreferences="allowRunningInsecureContent, javascript=no"></webview>

webview に設定するウェブ設定を指定する文字列のコンマ区切りリストの string です。 サポートされている設定の文字列の完全なリストは、BrowserWindow にあります。

この文字列は、window.open の features 文字列と同じ形式に従います。 名前自体には true のブール値が与えられます。 設定は、= とそれに続く値を含めることによって別の値に設定できます。 特殊な値として、yes1true として解釈され、no0false として解釈されます。

enableblinkfeatures

<webview src="https://www.github.com/" enableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>

有効にする Blink 機能を指定する , 区切りの文字列リストである string です。 サポートされている機能の文字列の完全なリストは、RuntimeEnabledFeatures.json5 ファイルにあります。

disableblinkfeatures

<webview src="https://www.github.com/" disableblinkfeatures="PreciseMemoryInfo, CSSVariables"></webview>

無効にする Blink 機能を指定する , 区切りの文字列リストである string です。 サポートされている機能の文字列の完全なリストは、RuntimeEnabledFeatures.json5 ファイルにあります。

メソッド

webview タグには以下のメソッドがあります。

注釈: メソッドを使用する前に webview 要素をロードする必要があります。

サンプル

const webview = document.querySelector('webview')
webview.addEventListener('dom-ready', () => {
webview.openDevTools()
})

<webview>.loadURL(url[, options])

  • url URL
  • options Object (任意)
    • httpReferrer (string | Referrer) (任意) - HTTPリファラのURL。
    • userAgent string (任意) - リクエスト元のユーザーエージェント。
    • extraHeaders string (任意) - "\n" で区切られた追加のヘッダー
    • postData (UploadRawData | UploadFile)[] (任意)
    • baseURLForDataURL string (任意) - データURLによってロードされたファイルの (最後のパス区切り文字を含む) ベースURL。 これは指定された url がデータURLで、他のファイルをロードする必要がある場合のみ必要です。

戻り値 Promise<void> - この promise は、ページ読み込みが完了した時 (did-finish-load を参照) に解決され、ページの読み込みに失敗した時 (did-fail-load を参照) に拒否されます。

url を webview にロードします。url には、http:// または file:// のような、プロトコルのプレフィックスを含みます。

<webview>.downloadURL(url)

  • url string

ナビゲーションなしで url のリソースのダウンロードを初期化します。

<webview>.getURL()

戻り値 string - ゲストページの URL。

<webview>.getTitle()

戻り値 string - ゲストページのタイトル。

<webview>.isLoading()

戻り値 boolean - ゲストページがまだリソースを読み込んでいるかどうか。

<webview>.isLoadingMainFrame()

戻り値 boolean - メインフレーム (iframe やフレーム内のフレームだけではない) がまだ読み込んでいるかどうか。

<webview>.isWaitingForResponse()

戻り値 boolean - ゲストページが、ページのメインリソースからの最初の応答を待機しているかどうか。

<webview>.stop()

保留中のナビゲーションを停止します。

<webview>.reload()

ゲストページを再読み込みします。

<webview>.reloadIgnoringCache()

ゲストページを、キャッシュを無視して再読み込みします。

<webview>.canGoBack()

戻り値 boolean - ゲストページが前に戻れるかどうか。

<webview>.canGoForward()

戻り値 boolean - ゲストページが次に進めるかどうか。

<webview>.canGoToOffset(offset)

  • offset Integer

戻り値 boolean - offset 番目のゲストページへ行けるかどうか。

<webview>.clearHistory()

ナビゲーション履歴を消去します。

<webview>.goBack()

ゲストページを前に戻します。

<webview>.goForward()

ゲストページを次に進めます。

<webview>.goToIndex(index)

  • index Integer

指定した絶対インデックスへナビゲーションします。

<webview>.goToOffset(offset)

  • offset Integer

現在のエントリから指定したオフセットへナビゲーションします。

<webview>.isCrashed()

戻り値 boolean - レンダラープロセスがクラッシュしたかどうか。

<webview>.setUserAgent(userAgent)

  • userAgent string

ゲストページページのユーザエージェントをオーバーライドします。

<webview>.getUserAgent()

戻り値 string - ゲストページのユーザエージェント。

<webview>.insertCSS(css)

  • css string

戻り値 Promise<string> - 挿入された CSS のキーで解決される promise。後で <webview>.removeInsertedCSS(key) を使用して CSS を削除するために使用できます。

現在のウェブページに CSS を挿入し、挿入されたスタイルシートの一意なキーを返します。

<webview>.removeInsertedCSS(key)

  • key string

戻り値 Promise<void> - 削除に成功すると解決されます。

現在のウェブページから挿入された CSS を削除します。 スタイルシートは <webview>.insertCSS(css) から返されるキーで識別されます。

<webview>.executeJavaScript(code[, userGesture])

  • code string
  • userGesture boolean (任意) - 省略値は false

戻り値 Promise<any> - 実行されたコードの結果で resolve する Promise。コードの結果が reject な Promise である場合は reject な Promise。

ページ内の code を評価します。 userGesture が設定されている場合、ページのユーザジェスチャコンテキストが作成されます。 requestFullScreen のようなユーザの操作を必要とする HTML API は、このオプションを自動化に利用できます。

<webview>.openDevTools()

ゲストページの開発者向けツールウインドウを開きます。

<webview>.closeDevTools()

ゲストページの開発者向けツールウインドウを閉じます。

<webview>.isDevToolsOpened()

戻り値 boolean - ゲストページに開発者向けツールウインドウが適用されているかどうか。

<webview>.isDevToolsFocused()

戻り値 boolean - ゲストページの開発者向けツールウインドウがフォーカスされているかどうか。

<webview>.inspectElement(x, y)

  • x Integer
  • y Integer

ゲストページの (x, y) の位置の要素の検査を開始します。

<webview>.inspectSharedWorker()

ゲストページに表示されている共有ワーカーコンテキストの開発者向けツールを開きます。

<webview>.inspectServiceWorker()

ゲストページに表示されているサービスワーカコンテキストの開発者向けツールを開きます。

<webview>.setAudioMuted(muted)

  • muted boolean

ゲストページをミュートに設定します。

<webview>.isAudioMuted()

戻り値 boolean - ゲストページがミュートされているかどうか。

<webview>.isCurrentlyAudible()

戻り値 boolean - 音声が現在再生中かどうか。

<webview>.undo()

ページの undo 編集コマンドを実行します。

<webview>.redo()

ページの redo 編集コマンドを実行します。

<webview>.cut()

ページの cut 編集コマンドを実行します。

<webview>.copy()

ページの copy 編集コマンドを実行します。

<webview>.paste()

ページの paste 編集コマンドを実行します。

<webview>.pasteAndMatchStyle()

ページの pasteAndMatchStyle 編集コマンドを実行します。

<webview>.delete()

ページの delete 編集コマンドを実行します。

<webview>.selectAll()

ページの selectAll 編集コマンドを実行します。

<webview>.unselect()

ページの unselect 編集コマンドを実行します。

<webview>.replace(text)

  • text string

ページの replace 編集コマンドを実行します。

<webview>.replaceMisspelling(text)

  • text string

ページの replaceMisspelling 編集コマンドを実行します。

<webview>.insertText(text)

  • text string

戻り値 Promise<void>

フォーカスされた要素に text を挿入します。

<webview>.findInPage(text[, options])

  • text string - 検索するコンテンツ。空にしてはいけません。
  • options Object (任意)
    • forward boolean (任意) - 前方または後方を検索するかどうか。省略値は true
    • findNext boolean (任意) - この要求で新規テキスト検索セッションを開始するかどうか。 最初の要求では true に、二度目以降の要求では false にする必要があります。 省略値は false
    • matchCase boolean (任意) - 大文字と小文字を区別する検索かどうか。省略値は false

戻り値 Integer - リクエストに使われたリクエスト ID。

ウェブページ内の text のすべてのマッチを探すリクエストを開始します。 リクエストの結果は found-in-page イベントを読むことで取得できます。

<webview>.stopFindInPage(action)

  • action string - <webview>.findInPage リクエストを終了する際に行うアクションを指定します。
    • clearSelection - 選択を消去する。
    • keepSelection - その選択を通常の選択に変換する。
    • activateSelection - 選択ノードをフォーカスして、クリックする。

指定された action で、webviewfindInPage リクエストを停止します。

<webview>.print([options])

  • options Object (任意)
    • silent boolean (任意) - プリンタの設定をユーザに尋ねないかどうか。 省略値は false です。
    • printBackground boolean (任意) - ウェブページの背景色と画像を印刷するかどうか。 省略値は false です。
    • deviceName string (任意) - 使用するプリンタデバイスの名前をセットします。 '人間向けの' 名称ではなくシステム定義名である必要があります。例えば、'Brother QL-820NWB' ではなく 'Brother_QL_820NWB' とします。
    • color boolean (任意) - 印刷するウェブページをカラーにするかグレースケールにするかを設定します。 省略値は true です。
    • margins Object (任意)
      • marginType string (任意) - defaultnoneprintableAreacustom にできます。 custom を選択した場合、topbottomleftright も指定する必要があります。
      • top number (任意) - 印刷されたウェブページの上側のマージン。ピクセル単位です。
      • bottom number (任意) - 印刷されたウェブページの下側のマージン。ピクセル単位です。
      • left number (任意) - 印刷されたウェブページの左側のマージン。ピクセル単位です。
      • right number (任意) - 印刷されたウェブページの右側のマージン。ピクセル単位です。
    • landscape boolean (任意) - ウェブページを横向きモードで印刷するかどうか。 省略値は false です。
    • scaleFactor number (任意) - ウェブページのスケール係数。
    • pagesPerSheet number (任意) - ページシートごとに印刷するページ数。
    • collate boolean (任意) - ウェブページを校合するかどうか。
    • copies number (任意) - 印刷するウェブページの版数。
    • pageRanges Object[] (任意) - 印刷するページ範囲。
      • from number - 印刷する最初のページのインデックス (0 始まり)。
      • to number - 印刷する最後のページのインデックス (これを含む) (0 始まり)。
    • duplexMode string (任意) - 印刷されるウェブページの両面モードを設定します。 simplexshortEdgelongEdge のいずれかにできます。
    • dpi Record<string, number> (任意)
      • horizontal number (任意) - 水平 DPI。
      • vertical number (任意) - 垂直 DPI。
    • header string (任意) - ページヘッダーとして印刷される文字列。
    • footer string (任意) - ページフッターとして印刷される文字列。
    • pageSize string | Size (任意) - 印刷するドキュメントのページサイズを指定します。 Can be A3, A4, A5, Legal, Letter, Tabloid or an Object containing height in microns.

戻り値 Promise<void>

webview のウェブページを印刷します。 webContents.print([options]) と同じです。

<webview>.printToPDF(options)

  • options Object
    • headerFooter Record<string, string> (任意) - PDF のヘッダーとフッター。
      • title string - PDF ヘッダーのタイトル。
      • url string - PDF フッターの URL。
    • landscape boolean (任意) - true で横向き、false で縦向き。
    • marginsType Integer (optional) - 使用する余白の種類を指定します。 0 で既定値、1 で余白なし、2 で最小限の余白になります。 width はミクロン単位です。
    • scaleFactor number (任意) - ウェブページのスケール係数。 0 から 100 の範囲にできます。
    • pageRanges Record<string, number> (任意) - 印刷するページ範囲。 macOS では最初の範囲のみが使用されます。
      • from number - 印刷する最初のページのインデックス (0 始まり)。
      • to number - 印刷する最後のページのインデックス (これを含む) (0 始まり)。
    • pageSize string | Size (任意) - 生成する PDF のページサイズを指定します。 A3A4A5LegalLetterTabloid のいずれかにするか、height を含む Object にできます。
    • printBackground boolean (任意) - CSS 背景を印刷するかどうか。
    • printSelectionOnly boolean (任意) - 選択部分だけを印刷するかどうか。

戻り値 Promise<Uint8Array> - 生成された PDF データで実行されます。

webview のウェブページを PDF として印刷します。webContents.printToPDF(options) と同じです。

<webview>.capturePage([rect])

  • rect Rectangle (任意) - キャプチャするページ内の領域。

戻り値 Promise<NativeImage> - NativeImage を解決します

rect 内のページのスナップショットをキャプチャします。 rect を省略すると、表示されているページ全体をキャプチャします。

<webview>.send(channel, ...args)

  • channel string
  • ...args any[]

戻り値 Promise<void>

channel を介してレンダラープロセスに非同期メッセージを送信します。任意の引数を送ることもできます。 レンダラープロセスは ipcRenderer モジュールで channel イベントをリッスンしてメッセージを処理できます。

サンプルについては webContents.send を参照して下さい。

<webview>.sendToFrame(frameId, channel, ...args)

  • frameId [number, number] - [processId, frameId]
  • channel string
  • ...args any[]

戻り値 Promise<void>

channel を介してレンダラープロセスに非同期メッセージを送信します。任意の引数を送ることもできます。 レンダラープロセスは ipcRenderer モジュールで channel イベントをリッスンしてメッセージを処理できます。

サンプルは webContents.sendToFrame をご参照ください。

<webview>.sendInputEvent(event)

戻り値 Promise<void>

入力 event をページに送ります。

event オブジェクトの詳細については、webContents.sendInputEvent を参照してください。

<webview>.setZoomFactor(factor)

  • factor number - 拡大率。

指定の拡大率に変更します。 拡大率は百分率なので、300% = 3.0 です。

<webview>.setZoomLevel(level)

  • level number - 拡大レベル。

指定レベルに拡大レベルを変更します。 原寸は 0 で、各増減分はそれぞれ 20% ずつの拡大または縮小を表し、デフォルトで元のサイズの 300% から 50% までに制限されています。 この式は scale := 1.2 ^ level です。

注意: Chromium でのズームポリシーはドメインごとです。すなわち、特定ドメインのズームレベルは、同じドメインのウィンドウの全インスタンスに伝播します。 ウインドウの URL が別々であれば、ウインドウごとのズームになります。

<webview>.getZoomFactor()

戻り値 number - 現在の拡大率。

<webview>.getZoomLevel()

戻り値 number - 現在の拡大レベル。

<webview>.setVisualZoomLevelLimits(minimumLevel, maximumLevel)

  • minimumLevel number
  • maximumLevel number

戻り値 Promise<void>

ピンチによる拡大レベルの最大値と最小値を設定します。

<webview>.showDefinitionForSelection() macOS

ページ上の選択された単語を検索するポップアップ辞書を表示します。

<webview>.getWebContentsId()

戻り値 number - この webview の WebContents ID。

DOM イベント

webview タグでは、以下の DOM イベントを使用できます。

イベント: 'load-commit'

戻り値:

  • url string
  • isMainFrame boolean

ロードを要求したときに発生します。 これには、現在のドキュメント内のナビゲーションとサブフレームのドキュメントレベルのロードが含まれますが、非同期のリソース読み込みは含まれません。

イベント: 'did-finish-load'

ナビゲーションが終了した時、すなわち、タブのくるくるが止まったときや、onload イベントが送られた後に、発行されます。

イベント: 'did-fail-load'

戻り値:

  • errorCode Integer
  • errorDescription string
  • validatedURL string
  • isMainFrame boolean

このイベントは did-finish-load のようですが、ロードが失敗した、キャンセルされた、window.stop() が呼び出されたなどで発生します。

イベント: 'did-frame-finish-load'

戻り値:

  • isMainFrame boolean

フレームのナビゲーションが終了したときに発行されます。

イベント: 'did-start-loading'

タブのくるくるが始まるタイミングに対応しています。

イベント: 'did-stop-loading'

タブのくるくるが止まるタイミングに対応しています。

イベント: 'did-attach'

埋め込みWebコンテンツに添付したときに発行されます。

イベント: 'dom-ready'

指定のフレームの document が読み込まれたときに発行されます。

イベント: 'page-title-updated'

戻り値:

  • title string
  • explicitSet boolean

ナビゲーション中にページタイトルが設定されると発生します。 explicitSet は、タイトルがファイル URL から合成されている場合に false になります。

イベント: 'page-favicon-updated'

戻り値:

  • favicons string[] - URLの配列。

ページがファビコンの URL を受け取ると発行されます。

イベント: 'enter-html-full-screen'

HTML API にトリガーされてページがフルスクリーンになるときに発生します。

イベント: 'leave-html-full-screen'

HTML API にトリガーされてページがフルスクリーンから抜けるときに発生します。

Event: 'console-message'

戻り値:

  • level Integer - 0 から 3 のログレベル。 順に verboseinfowarningerror に対応します。
  • message string - 実際のコンソールメッセージ
  • line Integer - このコンソールメッセージのトリガーとなったソースの行番号
  • sourceId string

ゲストウィンドウがコンソールメッセージをロギングすると発行されます。

以下のサンプルコードは、ログレベルやその他のプロパティに関係なく、すべてのログメッセージを埋め込みのコンソールに転送します。

const webview = document.querySelector('webview')
webview.addEventListener('console-message', (e) => {
console.log('ゲストページのメッセージログ:', e.message)
})

イベント: 'found-in-page'

戻り値:

  • result Object
    • requestId Integer
    • activeMatchOrdinal Integer - アクティブなマッチの位置。
    • matches Integer - マッチの個数。
    • selectionArea Rectangle - 最初に一致した領域の座標。
    • finalUpdate boolean

webview.findInPage リクエストの結果が有効なときに発行されます。

const webview = document.querySelector('webview')
webview.addEventListener('found-in-page', (e) => {
webview.stopFindInPage('keepSelection')
})

const requestId = webview.findInPage('test')
console.log(requestId)

イベント: 'new-window'

戻り値:

  • url string
  • frameName string
  • disposition string - defaultforeground-tabbackground-tabnew-windowsave-to-diskother にできる。
  • options BrowserWindowConstructorOptions - 新しい BrowserWindow を作成するのに使われるべきオプション。

ゲストページが新しいブラウザウィンドウを開くときに発生します。

以下のサンプルコードは、システムのデフォルトブラウザで新しい URL を開きます。

const { shell } = require('electron')
const webview = document.querySelector('webview')

webview.addEventListener('new-window', async (e) => {
const protocol = (new URL(e.url)).protocol
if (protocol === 'http:' || protocol === 'https:') {
await shell.openExternal(e.url)
}
})

イベント: 'will-navigate'

戻り値:

  • url string

ユーザーまたはページがナビゲーションを開始しようとしたときに発生します。 window.location オブジェクトが変更されるか、ユーザがページ内のリンクをクリックしたときに発生することがあります。

このイベントは、 <webview>.loadURL<webview>.back のような、API によってプログラム上から開始されるナビゲーションのときには発行されません。

アンカーリンクのクリックや window.location.hash の更新のような、ページ内ナビゲーションでも発行されません。 これを意図する場合は did-navigate-in-page を使用して下さい。

event.preventDefault() を呼んでも効果は ありません

イベント: 'did-start-navigation'

戻り値:

  • url string
  • isInPlace boolean
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

フレーム (メインを含む) がナビゲーションを始めているときに発生します。 ページ内ナビゲーションの場合、isInPlacetrue になります。

イベント: 'did-redirect-navigation'

戻り値:

  • url string
  • isInPlace boolean
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

ナビゲーション後にサーバーサイドリダイレクトが発生すると発行されます。 302 リダイレクトなどがその例です。

イベント: 'did-navigate'

戻り値:

  • url string

ナビゲーションが完了したときに発行されます。

このイベントは、アンカーリンクのクリックや window.location.hash の更新のような、ページ内ナビゲーションでは発行されません。 これを意図する場合は did-navigate-in-page を使用して下さい。

イベント: 'did-frame-navigate'

戻り値:

  • url string
  • httpResponseCode Integer - HTTP ナビゲーションが無い場合は-1
  • httpStatusText string - HTTP ナビゲーションが無い場合は空,
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

フレームのナビゲーションが完了したときに発生します。

このイベントは、アンカーリンクのクリックや window.location.hash の更新のような、ページ内ナビゲーションでは発行されません。 これを意図する場合は did-navigate-in-page を使用して下さい。

イベント: 'did-navigate-in-page'

戻り値:

  • isMainFrame boolean
  • url string

ページ内ナビゲーションが発生したときに発行されます。

ページ内ナビゲーションが行われるとき、ページのURLは変更されますがページ外でのナビゲーションは発生しません。 これが発生する例は、アンカーリンクがクリックされたときや、DOM の hashchange イベントがトリガーされたときです。

イベント: 'close'

ゲストのページ自身が閉じようとしたときに発生します。

以下のサンプルコードは、ゲストが自身を閉じるときに webviewabout:blank にナビゲートします。

const webview = document.querySelector('webview')
webview.addEventListener('close', () => {
webview.src = 'about:blank'
})

イベント: 'ipc-message'

戻り値:

  • frameId [number, number] - [processId, frameId] のペア。
  • channel string
  • args any[]

ゲストページが埋め込みページに非同期メッセージを送信したときに発生します。

sendToHost メソッドと ipc-message イベントを使用すると、ゲストページと埋め込みページの間で通信できます。

// 埋め込みページ内
const webview = document.querySelector('webview')
webview.addEventListener('ipc-message', (event) => {
console.log(event.channel)
// "pong" が出力される
})
webview.send('ping')
// ゲストページ内
const { ipcRenderer } = require('electron')
ipcRenderer.on('ping', () => {
ipcRenderer.sendToHost('pong')
})

イベント: 'crashed'

レンダラープロセスがクラッシュしたときに発生します。

イベント: 'plugin-crashed'

戻り値:

  • name string
  • version string

プラグインプロセスがクラッシュしたときに発行されます。

イベント: 'destroyed'

webContents が破棄されたときに発生します。

イベント: 'media-started-playing'

メディアの再生を開始するときに発行されます。

イベント: 'media-paused'

メディアが一時停止、または再生が終了したときに発行されます。

イベント: 'did-change-theme-color'

戻り値:

  • themeColor string

ページのテーマカラーが変わったときに発生します。 これは通常、メタタグを発見すると起こります。

<meta name='theme-color' content='#ff0000'>

イベント: 'update-target-url'

戻り値:

  • url string

マウスをリンクにマウスオーバーしたり、キーボードでリンクにフォーカスしたときに発行されます。

イベント: 'devtools-opened'

開発者向けツールが開かれたときに発行されます。

イベント: 'devtools-closed'

開発者向けツールが閉じられたときに発行されます。

イベント: 'devtools-focused'

開発者向けツールがフォーカスされた / 開かれたときに発行されます。

イベント: 'context-menu'

戻り値:

  • params Object
    • x Integer - x 座標。
    • y Integer - y 座標。
    • linkURL string - コンテキストメニューが呼び出されたノードを囲うリンク URL。
    • linkText string - リンクに関連付けたテキスト。 リンクのコンテンツが画像の場合は、空文字列になります。
    • pageURL string - コンテキストメニューが呼び出された最上位のページの URL。
    • frameURL string - コンテキストメニューが呼び出されたサブフレームの URL。
    • srcURL string - コンテキストメニューが呼び出された要素のソース URL。 ソース URL を持つ要素は、画像、オーディオ、ビデオです。
    • mediaType string - コンテキストメニューが呼び出されたノードの種類。 noneimageaudiovideocanvasfileplugin になれる。
    • hasImageContents boolean - 空でないコンテンツ画像の上でコンテキストメニューが呼び出されたかどうか。
    • isEditable boolean - コンテキストが編集可能かどうか。
    • selectionText string - コンテキストメニューが呼び出されたときの選択テキスト。
    • titleText string - コンテキストメニューが呼び出された選択範囲のタイトルテキスト。
    • altText string - コンテキストメニューが呼び出された選択範囲の代替テキスト。
    • suggestedFilename string - コンテキストメニューの 'リンク先を名前を付けて保存' オプションでファイルを保存する際に使用されるファイル名の候補。
    • selectionRect Rectangle - 選択範囲の document 空間における座標を表す矩形。
    • selectionStartOffset number - 選択テキストの開始位置。
    • referrerPolicy Referrer - メニューが呼び出されるフレームのリファラポリシー。
    • misspelledWord string - カーソルの下のスペルミスした単語 (もしあるならば)。
    • dictionarySuggestions string[] - ユーザに misspelledWord の置き換えを示す推測した単語の配列。 単語のスペルミスがあり、スペルチェッカーが有効な場合にのみ利用できます。
    • frameCharset string - メニューが呼び出されたときのフレームのテキストエンコーディング。
    • inputFieldType string - 入力フィールド内でコンテキストメニューが呼び出されたときの、そのタイプ。 noneplainTextpasswordother になれる。
    • spellcheckEnabled boolean - そのコンテキストが編集可能な場合に、スペルチェックが有効かどうか。
    • menuSourceType string - コンテキストメニューを呼び出した入力ソース。 none, mouse, keyboard, touch, touchMenu, longPress, longTap, touchHandle, stylus, adjustSelection, adjustSelectionReset のいずれかになります。
    • mediaFlags Object - コンテキストメニューが呼び出されたメディア要素のフラグ。
      • inError boolean - メディア要素がクラッシュしたかどうか。
      • isPaused boolean - メディア要素が一時停止されているかどうか。
      • isMuted boolean - メディア要素がミュートされているかどうか。
      • hasAudio boolean - メディア要素に音声があるかどうか。
      • isLooping boolean - メディア要素をループしているかどうか。
      • isControlsVisible boolean - メディア要素のコントロールが見えるかどうか。
      • canToggleControls boolean - メディア要素のコントロールがトグル切り替えできるかどうか。
      • canPrint boolean - そのメディア要素が印刷できるかどうか。
      • canSave boolean - そのメディア要素がダウンロードできるかどうか。
      • canShowPictureInPicture boolean - そのメディア要素がピクチャインピクチャ表示できるかどうか。
      • isShowingPictureInPicture boolean - そのメディア要素をピクチャインピクチャ表示しているかどうか。
      • canRotate boolean - メディア要素を回転できるかどうか。
      • canLoop boolean - そのメディア要素をループ再生できるかどうか。
    • editFlags Object - これらのフラグは、レンダラーが対応するアクションを実行できると信頼しているかどうかを示します。
      • canUndo boolean - レンダラーが、undo できると信頼しているかどうか。
      • canUndo boolean - レンダラーが、redo できると信頼しているかどうか。
      • canCut boolean - レンダラーが、カットできると信頼しているかどうか。
      • canCopy boolean - レンダラーがコピーできると信頼しているかどうか。
      • canPaste boolean - レンダラーが、ペーストできると信頼しているかどうか。
      • canDelete boolean - レンダラーが、削除できると信頼しているかどうか。
      • canSelectAll boolean - レンダラーが、全選択できると信頼しているかどうか。
      • canEditRichly boolean - レンダラーがテキストをリッチ編集できると信頼しているかどうか。

処理が必要な新しいコンテキストメニューがあるときに発行されます。