メインコンテンツへ飛ぶ

webContents

ウェブページを描画、制御します。

プロセス: Main

webContentsEventEmitter を継承しています。 BrowserWindow オブジェクトのプロパティには、ウェブページを描画し、制御する責任があります。 以下は、webContents オブジェクトにアクセスする例です。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 1500 })
win.loadURL('http://github.com')

const contents = win.webContents
console.log(contents)

メソッド

これらのメソッドは、webContents モジュールからアクセスできます。

const { webContents } = require('electron')
console.log(webContents)

webContents.getAllWebContents()

戻り値 WebContents[] - すべての WebContents インスタンスの配列。 これには、すべてのウインドウ、開かれた開発者向けツール、開発者向けツールのバックグラウンド拡張のページが含まれます。

webContents.getFocusedWebContents()

戻り値 WebContents | null - このアプリケーション内でフォーカス中の WebContents。無ければ null です。

webContents.fromId(id)

  • id Integer

戻り値 WebContents | undefined - 指定 ID の WebContents インスタンス。指定 ID に関連付けられた WebContents が存在しない場合は undefined です。

webContents.fromDevToolsTargetId(targetId)

  • targetId string - WebContents インスタンスに関連付けられた Chrome デベロッパー ツールプロトコルの TargetID

戻り値 WebContents | undefined - 指定 TargetID の WebContents インスタンス。指定 TargetID に関連付けられた WebContents が存在しない場合は undefined です。

Chrome デベロッパー ツールプロトコル と通信する際に、割り当てられた TargetID で WebContents インスタンスを検索すると便利な場合があります。

async function lookupTargetId (browserWindow) {
const wc = browserWindow.webContents
await wc.debugger.attach('1.3')
const { targetInfo } = await wc.debugger.sendCommand('Target.getTargetInfo')
const { targetId } = targetInfo
const targetWebContents = await webContents.fromDevToolsTargetId(targetId)
}

クラス: WebContents

BrowserWindow インスタンスのコンテンツを、描画し、制御します。

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

インスタンスイベント

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

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

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

戻り値:

  • event Event
  • errorCode Integer
  • errorDescription string
  • validatedURL string
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

このイベントは did-finish-load に似ていますが、ロードが失敗したときも発行されます。 エラーコードとその意味のすべてのリストは こちら です。

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

戻り値:

  • event Event
  • errorCode Integer
  • errorDescription string
  • validatedURL string
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

このイベントは did-fail-load に似ていますが、ロードがキャンセルされたときに発行されます (例えば window.stop() が呼び出されたときなど)。

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

戻り値:

  • event Event
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

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

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

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

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

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

イベント: 'dom-ready'

戻り値:

  • event Event

最上位フレームの document が読み込まれたときに発生します。

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

戻り値:

  • event Event
  • title string
  • explicitSet boolean

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

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

戻り値:

  • event Event
  • favicons string[] - URLの配列。

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

イベント: 'new-window' 非推奨

戻り値:

  • event NewWindowWebContentsEvent
  • url string
  • frameName string
  • disposition string - defaultforeground-tabbackground-tabnew-windowsave-to-diskother にできる。
  • options BrowserWindowConstructorOptions - 新しい BrowserWindow を作成するのに使われるオプション。
  • additionalFeatures string[] - window.open() に与えられている、標準でない機能 (Chromium や Electron によって処理されない機能)。 非推奨であり、現在は必ず空の配列 [] になります。
  • referrer Referrer - 新しいウィンドウへ渡される Referrer。 Referrer のポリシーに依存しているので、Referrer ヘッダを送信されるようにしてもしなくてもかまいません。
  • postBody PostBody (任意) - 新しいウィンドウに送信する POST データと、それにセットする適切なヘッダ。 送信する POST データが無い場合、値は null になります。 これは target=_blank を設定したフォームによってウィンドウが作成されている場合にのみセットされます。

これは webContents.setWindowOpenHandler に代わって非推奨となりました。

ページが url のための新しいウィンドウを開く要求をすると発生します。 window.open<a target='_blank'> のような外部リンクによるリクエストである可能性があります。

デフォルトでは、url の新しい BrowserWindow が作成されます。

event.preventDefault() を呼ぶと、Electron が自動的に新しい BrowserWindow を作成するのを防ぎます。 もし event.preventDefault() を呼び、新しい BrowserWindow を手動で作る場合、新しい BrowserWindow インスタンスの参照を event.newGuest にセットしなければ、予期しない動作になる可能性があります。 以下がその例です。

myBrowserWindow.webContents.on('new-window', (event, url, frameName, disposition, options, additionalFeatures, referrer, postBody) => {
event.preventDefault()
const win = new BrowserWindow({
webContents: options.webContents, // あれば既存の webContents を使用する
show: false
})
win.once('ready-to-show', () => win.show())
if (!options.webContents) {
const loadOptions = {
httpReferrer: referrer
}
if (postBody != null) {
const { data, contentType, boundary } = postBody
loadOptions.postData = postBody.data
loadOptions.extraHeaders = `content-type: ${contentType}; boundary=${boundary}`
}

win.loadURL(url, loadOptions) // 自動で既存の webContents をナビゲーションする
}
event.newGuest = win
})

イベント: 'did-create-window'

戻り値:

  • window BrowserWindow
  • details Object
    • url string - 作成したウインドウの URL。
    • frameName string - window.open() の呼び出しで作成したウインドウに指定した名前。
    • options BrowserWindowConstructorOptions - その BrowserWindow の作成に使用したオプション。 これらは、window.open()features 文字列から解析されたオプション、親ウインドウから継承されたセキュリティ関連の webPreferences、webContents.setWindowOpenHandler で与えられたオプションなどが優先度の高い順に結合されたものです。 認識できないオプションが取り除かれることはありません。
    • referrer Referrer - 新しいウィンドウへ渡される Referrer。 リファラのポリシーに応じた Referer ヘッダーが送信されるとは限りません。
    • postBody PostBody (任意) - 新しいウィンドウに送信される POST データと、設定される適切なヘッダです。 送信する POST データが無い場合、値は null になります。 これは target=_blank を設定したフォームによってウィンドウが作成されている場合にのみセットされます。
    • disposition string - defaultforeground-tabbackground-tabnew-windowsave-to-diskother にできます。

レンダラーで window.open を使用したウィンドウの作成に成功した に発生します。 webContents.setWindowOpenHandler からウインドウの作成がキャンセルされた場合には発生しません。

詳細や webContents.setWindowOpenHandler と併せた使用方法については window.open() をご参照ください。

イベント: 'will-navigate'

戻り値:

  • event Event
  • url string

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

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

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

event.preventDefault() を呼ぶとナビゲーションが阻害されます。

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

戻り値:

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

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

イベント: 'will-redirect'

戻り値:

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

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

このイベントは常に、同一ナビゲーションで did-start-navigation の後かつ did-redirect-navigation イベントの前に発行されます。

event.preventDefault() を呼ぶとナビゲーション (リダイレクトではない) が阻害されます。

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

戻り値:

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

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

このイベントを阻害することはできません。リダイレクトを防ぎたい場合は、上記の will-redirect イベントを確認してください。

イベント: 'did-navigate'

戻り値:

  • event Event
  • url string
  • httpResponseCode Integer - HTTP ナビゲーションが無い場合は-1
  • httpStatusText string - HTTP ナビゲーションが無い場合は空

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

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

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

戻り値:

  • event Event
  • 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'

戻り値:

  • event Event
  • url string
  • isMainFrame boolean
  • frameProcessId Integer
  • frameRoutingId Integer

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

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

イベント: 'will-prevent-unload'

戻り値:

  • event Event

beforeunload イベントハンドラがページのアンロードをキャンセルしようとしたときに発行されます。

event.preventDefault() を呼ぶと、beforeunload イベントハンドラが無視され、 ページをアンロードできます。

const { BrowserWindow, dialog } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('will-prevent-unload', (event) => {
const choice = dialog.showMessageBoxSync(win, {
type: 'question',
buttons: ['Leave', 'Stay'],
title: 'Do you want to leave this site?',
message: 'Changes you made may not be saved.',
defaultId: 0,
cancelId: 1
})
const leave = (choice === 0)
if (leave) {
event.preventDefault()
}
})

注意: これは BrowserView に対して発生しますが、尊重 されません。これは、仕様 にあるように、BrowserView のライフサイクルはそれを所有する BrowserWindow に結び付けないとしたためです。

イベント: 'crashed' 非推奨

戻り値:

  • event Event
  • killed boolean

レンダラープロセスがクラッシュしたり、強制終了されたりしたときに発行されます。

非推奨: このイベントは render-process-gone イベント によって引き継がれます。このイベントには、子プロセスが失われた理由についての詳細情報が含まれています。 これはクラッシュした場合に限りません。 移植する場合は、Boolean 型の killed だと reason === 'killed' をチェックするように置き換えればできます。

イベント: 'render-process-gone'

戻り値:

  • event Event
  • details Object
    • reason string - レンダープロセスがなくなった理由。 取りうる値:
      • clean-exit - 終了コードが0でプロセスが終了した
      • abnormal-exit - ゼロでない終了コードでプロセスを終了しました。
      • killed - プロセスへSIGTERMシグナルが送信されたか、その他の方法で殺されました。
      • crashed - プロセスがクラッシュした
      • oom - プロセスがメモリ不足になった
      • launch-failed - プロセスが正常に起動されなかった
      • integrity-failure - Windows コードの整合性チェックに失敗しました
    • exitCode Integer - プロセスの終了コードです。reasonlaunch-failed でなければ、exitCode はプラットフォーム固有の起動失敗のエラーコードになります。

renderer processが予期せず消えたときに発生します。 プロセスがクラッシュした場合やまたは殺された場合、これは正常です。

イベント: 'unresponsive'

Webページが応答しなくなるときに発生します。

イベント: 'responsive'

応答しないWebページが再び応答するようになるときに発生します。

イベント: 'plugin-crashed'

戻り値:

  • event Event
  • name string
  • version string

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

イベント: 'destroyed'

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

イベント: 'before-input-event'

戻り値:

ページ内の keydownkeyup イベントが発生する直前に発行されます。 event.preventDefault を呼ぶと、ページの keydown/keyup イベントとメニューショートカットを阻害します。

メニューショートカットだけを阻害するには、以下のように setIgnoreMenuShortcuts を使用します。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ width: 800, height: 600 })

win.webContents.on('before-input-event', (event, input) => {
// 例として、Ctrl/Cmd が押下されているときだけアプリケーションメニューの
// キーボードショートカットを有効にしてみます。
win.webContents.setIgnoreMenuShortcuts(!input.control && !input.meta)
})

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

ウインドウがHTML APIによってフルスクリーン状態に入るときに発生します。

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

ウインドウがHTML APIによってフルスクリーン状態を抜けるときに発生します。

イベント: 'zoom-changed'

戻り値:

  • event Event
  • zoomDirection string - inout にできます。

ユーザーがマウスホイールを使用してズームレベルの変更を要求しているときに生成されます。

イベント: 'blur'

WebContents がフォーカスを失ったときに発生します。

イベント: 'focus'

WebContents がフォーカスを得たときに発生します。

注意として macOS でフォーカスを得るというのは WebContents がウインドウのファーストレスポンダ となることを意味するため、ウインドウ間でフォーカスを切り替えても各ウインドウのファーストレスポンダが変更されず WebContentsblurfocus の イベントはトリガされません。

WebContentsfocusblur イベントは、同じウインドウ内の異なる WebContentsBrowserView の間のフォーカス変化の検出に使用するとよいでしょう。

イベント: 'devtools-opened'

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

イベント: 'devtools-closed'

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

イベント: 'devtools-focused'

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

イベント: 'certificate-error'

戻り値:

  • event Event
  • url string
  • error string - エラーコード。
  • certificate Certificate
  • callback Function
    • isTrusted boolean - 証明書が信頼できるとみなされるかどうかを示す。
  • isMainFrame boolean

urlcertificate の認証に失敗したときに発行されます。

使い方は、appcertificate-error イベント と同じです。

イベント: 'select-client-certificate'

戻り値:

  • event Event
  • url URL
  • certificateList Certificate[]
  • callback Function
    • certificate Certificate - 指定されたリストの証明書でなければならない。

クライアント証明書が要求されたときに発生します。

使い方は、appselect-client-certificate イベント と同じです。

イベント: 'login'

戻り値:

  • event Event
  • authenticationResponseDetails Object
    • url URL
  • authInfo Object
    • isProxy boolean
    • scheme string
    • host string
    • port Integer
    • realm string
  • callback Function
    • username string (任意)
    • password string (optional)

webContents がBasic認証を要求すると発生します。

使い方は、applogin イベント と同じです。

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

戻り値:

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

[webContents.findINPage] リクエストの結果が有効なときに発行されます。

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

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

イベント: 'media-paused'

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

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

戻り値:

  • event Event
  • color (string | null) - '#rrggbb' 形式のテーマカラー。 テーマカラーが設定されていないと null です。

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

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

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

戻り値:

  • event Event
  • url string

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

イベント: 'cursor-changed'

戻り値:

  • event Event
  • type string
  • image NativeImage (任意)
  • scale Float (任意) - カスタムカーソルの拡大率。
  • size Size (任意) - image のサイズ。
  • hotspot Point (任意) - カスタムカーソルのホットスポットの座標。

カーソルの種類が変更されたときに発行されます。 typedefaultcrosshairpointertextwaithelpe-resizen-resize,ne-resizenw-resizes-resizese-resizesw-resizew-resize,ns-resizeew-resizenesw-resizenwse-resizecol-resize,row-resizem-panninge-panningn-panningne-panningnw-panning,s-panningse-panningsw-panningw-panningmovevertical-text,cellcontext-menualiasprogressnodropcopynone,not-allowedzoom-inzoom-outgrabgrabbingcustom になれます。

もし type パラメータが custom の場合、image パラメータはカスタムカーソルの NativeImage を、scalesizehotspot はカスタムカーソルについての追加の情報を持ちます。

イベント: 'context-menu'

戻り値:

  • event Event
  • params Object
    • x Integer - x 座標。
    • y Integer - y 座標。
    • frame WebFrameMain - コンテキストメニューが呼び出されたフレーム。
    • 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 - レンダラーがテキストをリッチ編集できると信頼しているかどうか。

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

イベント: 'select-bluetooth-device'

戻り値:

navigator.bluetooth.requestDevice を呼ぶうえで、Bluetooth デバイスを選択する必要があるときに発行されます。 navigator.bluetooth を使用するには、webBluetooth API を有効にする必要があります。 もし event.preventDefault が呼ばれなければ、最初に有効なデバイスが選択されます。 callback は選択された deviceId で呼ばれます。リクエストがキャンセルされると、callbback に空文字列が渡されます。

このイベントに対してイベントリスナーが追加されていない場合、すべての Bluetooth リクエストはキャンセルされます。

const { app, BrowserWindow } = require('electron')

let win = null
app.commandLine.appendSwitch('enable-experimental-web-platform-features')

app.whenReady().then(() => {
win = new BrowserWindow({ width: 800, height: 600 })
win.webContents.on('select-bluetooth-device', (event, deviceList, callback) => {
event.preventDefault()
const result = deviceList.find((device) => {
return device.deviceName === 'test'
})
if (!result) {
callback('')
} else {
callback(result.deviceId)
}
})
})

イベント: 'paint'

戻り値:

新しいフレームが生成されたときに発生します。 バッファには変更された部分だけが渡されます。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ webPreferences: { offscreen: true } })
win.webContents.on('paint', (event, dirty, image) => {
// updateBitmap(dirty, image.getBitmap())
})
win.loadURL('http://github.com')

イベント: 'devtools-reload-page'

開発者向けツールウインドウが webContents にリロードを指示したときに発行されます。

イベント: 'will-attach-webview'

戻り値:

  • event Event
  • webPreferences WebPreferences - ゲストページで使用されるウェブ設定。 このオブジェクトを変更して、ゲストページの設定を調整できます。
  • params Record<string, string> - 他の <webview> パラメーター。src URL などがこれにあたります。 このオブジェクトを変更して、ゲストページのパラメーターを調整できます。

<webview> の webContents がこの webContents に適用されようとしているときに発行されます。 event.preventDefault() を呼ぶとゲストページを破棄します。

このイベントは、 webContents<webview> が読み込まれる前に webPreferences を設定するのに使用でき、<webview> の属性を通して設定できない設定を、設定する機能を提供します。

イベント: 'did-attach-webview'

戻り値:

  • event Event
  • webContents WebContents - <webview> で使われるゲスト WebContents。

<webview> がこの webContents に適用されたときに発行されます。

Event: 'console-message'

戻り値:

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

関連付けられたウインドウがコンソールメッセージを出力すると発生します。

イベント: 'preload-error'

戻り値:

  • event Event
  • preloadPath string
  • error Error

プリロードスクリプト preloadPath がハンドルされていない例外 error を投げたときに発行されます。

イベント: 'ipc-message'

戻り値:

  • event Event
  • channel string
  • ...args any[]

レンダラープロセスが ipcRenderer.send() を介して非同期メッセージを送信したときに発生します。

イベント: 'ipc-message-sync'

戻り値:

  • event Event
  • channel string
  • ...args any[]

レンダラープロセスが ipcRenderer.sendSync() を介して同期メッセージを送信したときに発生します。

イベント: 'preferred-size-changed'

戻り値:

  • event Event
  • preferredSize Size - スクロールなしでドキュメントのレイアウトを格納するのに必要な最小サイズ。

WebContents の優先サイズが変更された場合に発生します。

このイベントは、webPreferencesenablePreferredSizeModetrue に設定されている場合にのみ発生します。

イベント: 'frame-created'

戻り値:

  • event Event
  • details Object
    • frame WebFrameMain

mainFrame<iframe>、またはネストされた <iframe> がページ内にロードされたときに発生します。

インスタンスメソッド

contents.loadURL(url[, options])

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

戻り値 Promise<void> - ページの読み込みが完了した時 (did-finish-load を参照) に解決され、ページの読み込みに失敗した時 (did-fail-load を参照) に拒否される Promise。 無操作拒否ハンドラーが既にアタッチされているため、未処理の拒否エラーは回避されます。

ウインドウ内に url を読み込みます。 url は、http://file:// のようなプロトコルの接頭子を含まなければなりません。 HTTP キャッシュをバイパスする必要があるロードの場合は、pragma ヘッダを使用してそれを実現します。

const { webContents } = require('electron')
const options = { extraHeaders: 'pragma: no-cache\n' }
webContents.loadURL('https://github.com', options)

contents.loadFile(filePath[, options])

  • filePath string
  • options Object (任意)
    • query Record<string, string> (任意) - url.format() に渡されます。
    • search string (任意) - url.format() に渡されます。
    • hash string (任意) - url.format() に渡されます。

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

指定されたファイルをウインドウにロードします。filePath は、アプリケーションのルートを基準にした HTML ファイルへのパスにする必要があります。 たとえば以下のようなアプリの構造において、

| root
| - package.json
| - src
| - main.js
| - index.html

このようなコードが必要です。

win.loadFile('src/index.html')

contents.downloadURL(url)

  • url string

ナビゲーションなしで url のリソースのダウンロードを初期化します。 sessionwill-download イベントが発生します。

contents.getURL()

戻り値 string - 現在のウェブページの URL。

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://github.com').then(() => {
const currentURL = win.webContents.getURL()
console.log(currentURL)
})

contents.getTitle()

戻り値 string - 現在のウェブページのタイトル。

contents.isDestroyed()

戻り値 boolean - ウェブページが破棄されているかどうか。

contents.focus()

ウェブページにフォーカスします。

contents.isFocused()

戻り値 boolean - ウェブページがフォーカスされているかどうか。

contents.isLoading()

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

contents.isLoadingMainFrame()

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

contents.isWaitingForResponse()

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

contents.stop()

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

contents.reload()

現在のページを再読み込みします。

contents.reloadIgnoringCache()

現在のページを、キャッシュを無視して再読み込みします。

contents.canGoBack()

戻り値 boolean - ブラウザが前のウェブページへ戻れるかどうか。

contents.canGoForward()

戻り値 boolean - ブラウザが次のウェブページへ進めるかどうか。

contents.canGoToOffset(offset)

  • offset Integer

戻り値 boolean - offset 番目のウェブページへ行けるかどうか。

contents.clearHistory()

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

contents.goBack()

ブラウザを前のページへ戻させます。

contents.goForward()

ブラウザを次のページへ進めさせます。

contents.goToIndex(index)

  • index Integer

ブラウザを指定した絶対ウェブページインデックスへナビゲーションします。

contents.goToOffset(offset)

  • offset Integer

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

contents.isCrashed()

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

contents.forcefullyCrashRenderer()

このwebContents を現在ホスティングしているレンダラープロセスを強制終了します。 これにより、 reason=kill || reason=crashed である、render-process-gone イベントが発生します。 レンダラープロセスを共有しているWebContents の中には、このメソッドを呼び出すと、他のウェブコンテンツのホストプロセスがクラッシュする場合がありますのでご注意ください。

メソッドを呼び出した直後にこの reload() を呼び出すと、新しいプロセスでリロードが発生します。 これは、このプロセスが不安定または使用不可の場合、例えば unresponsive イベントから回復する際に使用されるべきです。

contents.on('unresponsive', async () => {
const { response } = await dialog.showMessageBox({
message: 'App X has become unresponsive',
title: 'Do you want to try forcefully reloading the app?',
buttons: ['OK', 'Cancel'],
cancelId: 1
})
if (response === 0) {
contents.forcefullyCrashRenderer()
contents.reload()
}
})

contents.setUserAgent(userAgent)

  • userAgent string

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

contents.getUserAgent()

戻り値 string - このウェブページのユーザエージェント。

contents.insertCSS(css[, options])

  • css string
  • options Object (任意)
    • cssOrigin string (任意) - 'user' か 'author' のいずれかにできます。 挿入されるスタイルシートの カスケードのオリジン を設定します。 既定値は 'author' です。

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

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

contents.on('did-finish-load', () => {
contents.insertCSS('html, body { background-color: #f00; }')
})

contents.removeInsertedCSS(key)

  • key string

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

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

contents.on('did-finish-load', async () => {
const key = await contents.insertCSS('html, body { background-color: #f00; }')
contents.removeInsertedCSS(key)
})

contents.executeJavaScript(code[, userGesture])

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

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

ページ内の code を評価します。

ブラウザウインドウでは、requestFullScreen のような、いくつかの HTML API は、ユーザからのジェスチャーでのみ呼び出されます。 userGesturetrue にセットすることでこの制限がなくなります。

コードの実行は、ウェブページの読み込みが停止するまで中断されます。

contents.executeJavaScript('fetch("https://jsonplaceholder.typicode.com/users/1").then(resp => resp.json())', true)
.then((result) => {
console.log(result) // フェッチ呼び出しの JSON オブジェクトになります
})

contents.executeJavaScriptInIsolatedWorld(worldId, scripts[, userGesture])

  • worldId Integer - JavaScript を実行するワールドの ID。0 はデフォルトのワールドで、999 は Electron の contextIsolation 機能で使用されるワールドです。 任意の整数を指定できます。
  • scripts WebSource[]
  • userGesture boolean (任意) - 省略値は false

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

executeJavaScript のように動きますが、 scripts はイソレートコンテキスト内で評価します。

contents.setIgnoreMenuShortcuts(ignore)

  • ignore boolean

この WebContents がフォーカスされている間、アプリケーションのメニューショートカットを無視します。

contents.setWindowOpenHandler(handler)

  • handler Function<{action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions}>

    • details Object
      • url string - window.open() に渡されて 解決された URL。 例えば window.open('foo') でウインドウを開くと、これは https://the-origin/the/current/path/foo のようになります。
      • frameName string - window.open() で指定されたウインドウ名
      • features string - window.open() で指定されたウインドウ機能のカンマ区切りリスト。
      • disposition string - defaultforeground-tabbackground-tabnew-windowsave-to-diskother のいずれかにできます。
      • referrer Referrer - 新しいウィンドウへ渡される Referrer。 Referrer のポリシーに依存しているので、Referrer ヘッダを送信されるようにしてもしなくてもかまいません。
      • postBody PostBody (任意) - 新しいウィンドウに送信する POST データと、それにセットする適切なヘッダ。 送信する POST データが無い場合、値は null になります。 これは target=_blank を設定したフォームによってウィンドウが作成されている場合にのみセットされます。

    戻り値 {action: 'deny'} | {action: 'allow', overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} - deny を返すと新規ウインドウの作成をキャンセルします。 allow を返すと新規ウインドウが作成されます。 overrideBrowserWindowOptions を指定すると、作成されるウィンドウをカスタマイズできます。 null、undefined、規定の 'action' の値を持たないオブジェクトといった認識されない値を返すと、コンソールエラーになり、{action: 'deny'} を返すのと同じ効果となります。

window.open()target="_blank" のリンク、リンクのシフトクリック、<form target="_blank"> のフォーム送信などによりレンダラーが新しいウインドウを要求すると、ウインドウ作成前に呼び出されます。 詳細や did-create-window と併せた使用方法については window.open() をご参照ください。

contents.setAudioMuted(muted)

  • muted boolean

現在のウェブページのオーディオをミュートします。

contents.isAudioMuted()

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

contents.isCurrentlyAudible()

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

contents.setZoomFactor(factor)

  • factor Double - 拡大率。省略値は 1.0 です。

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

拡大率は 0.0 より大きい必要があります。

contents.getZoomFactor()

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

contents.setZoomLevel(level)

  • level number - 拡大レベル。

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

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

contents.getZoomLevel()

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

contents.setVisualZoomLevelLimits(minimumLevel, maximumLevel)

  • minimumLevel number
  • maximumLevel number

戻り値 Promise<void>

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

注意: Electron ではデフォルトで視覚ズームは無効化されています。 再び有効にする場合は以下を呼び出します。

contents.setVisualZoomLevelLimits(1, 3)

contents.undo()

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

contents.redo()

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

contents.cut()

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

contents.copy()

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

contents.copyImageAt(x, y)

  • x Integer
  • y Integer

指定した位置の画像をクリップボードにコピーします。

contents.paste()

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

contents.pasteAndMatchStyle()

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

contents.delete()

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

contents.selectAll()

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

contents.unselect()

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

contents.replace(text)

  • text string

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

contents.replaceMisspelling(text)

  • text string

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

contents.insertText(text)

  • text string

戻り値 Promise<void>

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

contents.findInPage(text[, options])

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

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

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

contents.stopFindInPage(action)

  • action string - [webContents.findInPage] リクエストを終了する際に行う動作を指定します。
    • clearSelection - 選択を消去する。
    • keepSelection - その選択を通常の選択に変換する。
    • activateSelection - 選択ノードをフォーカスして、クリックする。

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

const { webContents } = require('electron')
webContents.on('found-in-page', (event, result) => {
if (result.finalUpdate) webContents.stopFindInPage('clearSelection')
})

const requestId = webContents.findInPage('api')
console.log(requestId)

contents.capturePage([rect])

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

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

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

contents.isBeingCaptured()

Returns boolean - このページがキャプチャされているかどうか。 キャプチャーの数が 0 より大きい場合は true を返します。

contents.incrementCapturerCount([size, stayHidden, stayAwake])

  • size Size (任意) - キャプチャの優先サイズ。
  • stayHidden boolean (任意) - ページを表示せずに非表示のままにします。
  • stayAwake boolean (任意) - システムをスリープさせずに、起きたままにします。

キャプチャ回数は 1 ずつ増加します。 ブラウザーウインドウが非表示でもキャプチャ回数がゼロではない場合、ページは表示されていると見なされます。 ページを非表示のままにする場合は、stayHidden を true に設定していることを確認してください。

これは Page Visibility API にも影響を与えます。

contents.decrementCapturerCount([stayHidden, stayAwake])

  • stayHidden boolean (任意) - ページを表示状態にせず非表示のままにします。
  • stayAwake boolean (任意) - システムをスリープさせずに、起きたままにします。

キャプチャ回数は 1 ずつ減少します。 ブラウザウィンドウが隠されるまたはオクルージョンされるか、キャプチャーカウントが 0 になると、ページは非表示状態やオクルージョン状態にセットされます。 代わりに非表示のキャプチャ回数を減らしたい場合は、stayHidden を true に設定してください。

contents.getPrinters() 非推奨

システムプリンタのリストを取得します。

戻り値 PrinterInfo[]

非推奨: 新しい contents.getPrintersAsync API を使用するようにしてください。

contents.getPrintersAsync()

システムプリンタのリストを取得します。

戻り値 Promise<PrinterInfo[]> - PrinterInfo[] で解決されます。

contents.print([options], [callback])

  • 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[] (任意) - 印刷するページ範囲。 macOS では 1 つの範囲のみが許可されています。
      • 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 (任意) - 印刷するドキュメントのページサイズを指定します。 A3A4A5LegalLetterTabloid のいずれかにするか、height を含む Object にできます。
  • callback Function (任意)
    • success boolean - 印刷呼び出しの成功を示す。
    • failureReason string - 印刷に失敗した場合に呼び戻されるエラーの説明。

カスタムの pageSize を渡すと、Chromium は width_micronsheight_microns それぞれのプラットフォーム固有の最小値を検証しようとします。 幅、高さともに最低 353 ミクロンでなければなりませんが、オペレーティングシステムによってはそれ以上になることがあります。

ウインドウのウェブページを印刷します。 silenttrue にセットされたとき、deviceName が空で印刷のデフォルト設定があれば、Electron はシステムのデフォルトプリンタを選択します。

page-break-before: always; CSS スタイルを使用して、強制的に改ページして印刷できます。

使用例:

const options = {
silent: true,
deviceName: 'My-Printer',
pageRanges: [{
from: 0,
to: 1
}]
}
win.webContents.print(options, (success, errorType) => {
if (!success) console.log(errorType)
})

contents.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 で最小限の余白になります。
    • scaleFactor number (任意) - ウェブページのスケール係数。 0 から 100 の範囲にできます。
    • pageRanges Record<string, number> (任意) - 印刷するページ範囲。
      • from number - 印刷する最初のページのインデックス (0 始まり)。
      • to number - 印刷する最後のページのインデックス (これを含む) (0 始まり)。
    • pageSize string | Size (任意) - 生成する PDF のページサイズを指定します。 A3A4A5LegalLetterTabloid、またはミクロン単位の heightwidth を含む Object にできます。
    • printBackground boolean (任意) - CSS 背景を印刷するかどうか。
    • printSelectionOnly boolean (任意) - 選択部分だけを印刷するかどうか。

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

Chromium の印刷のカスタム設定のプレビューで、PDF としてウインドウのウェブページを出力します。

@page CSS ルールがウェブページ内で使われている場合、landscape は無視されます。

デフォルトでは、空の options は以下のようにみなされます。

{
marginsType: 0,
printBackground: false,
printSelectionOnly: false,
landscape: false,
pageSize: 'A4',
scaleFactor: 100
}

page-break-before: always; CSS スタイルを使用して、強制的に改ページして印刷できます。

これは webContents.printToPDF の例です。

const { BrowserWindow } = require('electron')
const fs = require('fs')
const path = require('path')
const os = require('os')

const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('http://github.com')

win.webContents.on('did-finish-load', () => {
// 既定の印刷オプションを使用します
const pdfPath = path.join(os.homedir(), 'Desktop', 'temp.pdf')
win.webContents.printToPDF({}).then(data => {
fs.writeFile(pdfPath, data, (error) => {
if (error) throw error
console.log(`Wrote PDF successfully to ${pdfPath}`)
})
}).catch(error => {
console.log(`Failed to write PDF to ${pdfPath}: `, error)
})
})

contents.addWorkSpace(path)

  • path string

指定したパスをデベロッパー ツールのワークスペースに追加します。 デベロッパー ツールが生成された後で使用しなければいけません。

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.webContents.on('devtools-opened', () => {
win.webContents.addWorkSpace(__dirname)
})

contents.removeWorkSpace(path)

  • path string

開発者向けツールのワークスペースから指定したパスを削除します。

contents.setDevToolsWebContents(devToolsWebContents)

  • devToolsWebContents WebContents

devToolsWebContents を開発者向けツールを表示するターゲット WebContents として使用します。

devToolsWebContents はナビゲーションを行ってはいけません。また、コール後に他の目的に使用することはできません。

デフォルトでは、Electron は開発者が制御を非常に制限したネイティブビューを持つ内部 WebContents を作成することによって開発者向けツールを管理します。 setDevToolsWebContents メソッドでは、開発者は任意の WebContents を使用して、BrowserWindowBrowserView<webview> タグなどの開発者向けツールを表示できます。

開発者向けツールを閉じても devToolsWebContents は破棄されないことに注意してください。 devToolsWebContents を破棄するのは呼び出し元の責任です。

<webview> タグ内で開発者向けツールを表示する例:

<html>
<head>
<style type="text/css">
* { margin: 0; }
#browser { height: 70%; }
#devtools { height: 30%; }
</style>
</head>
<body>
<webview id="browser" src="https://github.com"></webview>
<webview id="devtools" src="about:blank"></webview>
<script>
const { ipcRenderer } = require('electron')
const emittedOnce = (element, eventName) => new Promise(resolve => {
element.addEventListener(eventName, event => resolve(event), { once: true })
})
const browserView = document.getElementById('browser')
const devtoolsView = document.getElementById('devtools')
const browserReady = emittedOnce(browserView, 'dom-ready')
const devtoolsReady = emittedOnce(devtoolsView, 'dom-ready')
Promise.all([browserReady, devtoolsReady]).then(() => {
const targetId = browserView.getWebContentsId()
const devtoolsId = devtoolsView.getWebContentsId()
ipcRenderer.send('open-devtools', targetId, devtoolsId)
})
</script>
</body>
</html>
// メインプロセス
const { ipcMain, webContents } = require('electron')
ipcMain.on('open-devtools', (event, targetContentsId, devtoolsContentsId) => {
const target = webContents.fromId(targetContentsId)
const devtools = webContents.fromId(devtoolsContentsId)
target.setDevToolsWebContents(devtools)
target.openDevTools()
})

BrowserWindow 内で開発者向けツールを表示する例:

const { app, BrowserWindow } = require('electron')

let win = null
let devtools = null

app.whenReady().then(() => {
win = new BrowserWindow()
devtools = new BrowserWindow()
win.loadURL('https://github.com')
win.webContents.setDevToolsWebContents(devtools.webContents)
win.webContents.openDevTools({ mode: 'detach' })
})

contents.openDevTools([options])

  • options Object (任意)
    • mode string - 指定したドック状態で開発者向けツールを開きます。leftrightbottomundockeddetach にできます。 省略値は最後に使用したときのドック状態。 undocked モードではドックを後ろにやれる。 detach モードではできない。
    • activate boolean (任意) - 開かれたデベロッパー ツールウインドウを前面に表示するかどうか。 省略値は true です。

開発者向けツールを開く。

contents<webview> タグである場合、デフォルトでは modedetach になり、空の mode を明示的に渡すと最後に使用されたドックステートを使用して強制的に実行されます。

contents.closeDevTools()

開発者向けツールを閉じる。

contents.isDevToolsOpened()

戻り値 boolean - 開発者向けツールが開かれているかどうか。

contents.isDevToolsFocused()

戻り値 boolean - 開発者向けツールがフォーカスされているかどうか。

contents.toggleDevTools()

開発者向けツールをトグル切り替えします。

contents.inspectElement(x, y)

  • x Integer
  • y Integer

(x, y) の位置の要素の検査を開始します。

contents.inspectSharedWorker()

共有ワーカーコンテキストの開発者向けツールを開きます。

contents.inspectSharedWorkerById(workerId)

  • workerId string

ID に基づいて共有ワーカーのインスペクターを起動します。

contents.getAllSharedWorkers()

戻り値 SharedWorkerInfo[] - すべての共有ワーカーに関する情報。

contents.inspectServiceWorker()

サービスワーカコンテキストの開発者向けツールを開きます。

contents.send(channel, ...args)

  • channel string
  • ...args any[]

引数と共に、channel を介してレンダラープロセスに非同期メッセージを送信します。 引数は postMessage と同じように 構造化複製アルゴリズム によってシリアライズされるため、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。

注意: DOM オブジェクトや特殊な Electron オブジェクトなど、非標準の JavaScript 型を送信すると例外が発生します。

レンダラープロセスは ipcRenderer モジュールで channel を聞いてメッセージを処理できます。

以下はメインプロセスからレンダラープロセスにメッセージを送る例です。

// メインプロセス
const { app, BrowserWindow } = require('electron')
let win = null

app.whenReady().then(() => {
win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL(`file://${__dirname}/index.html`)
win.webContents.on('did-finish-load', () => {
win.webContents.send('ping', 'whoooooooh!')
})
})
<!-- index.html -->
<html>
<body>
<script>
require('electron').ipcRenderer.on('ping', (event, message) => {
console.log(message) // Prints 'whoooooooh!'
})
</script>
</body>
</html>

contents.sendToFrame(frameId, channel, ...args)

  • frameId Integer | [number, number] - 送信先のフレームの ID、またはフレームがメインフレームと異なるプロセスにある場合に [processId, frameId] の組み合わせを指定します。
  • channel string
  • ...args any[]

引数と共に、channel を介してレンダラープロセス内の指定のフレームに非同期メッセージを送信します。 引数は postMessage と同じように 構造化複製アルゴリズム によってシリアライズされるため、プロトタイプチェーンは含まれません。 関数、Promise、Symbol、WeakMap、WeakSet の送信は、例外が送出されます。

注意: DOM オブジェクトや特殊な Electron オブジェクトなど、非標準の JavaScript 型を送信すると例外が発生します。

レンダラープロセスは ipcRenderer モジュールで channel を聞いてメッセージを処理できます。

与えられたレンダラーコンテキストの frameId を取得したい場合は、webFrame.routingId の値を使用します。 以下は例です。

// レンダラープロセス内
console.log('My frameId is:', require('electron').webFrame.routingId)

メインプロセス内の受信した IPC メッセージすべてから frameId を読み取ることもできます。

// メインプロセス内
ipcMain.on('ping', (event) => {
console.info('Message came from frameId:', event.frameId)
})

contents.postMessage(channel, message, [transfer])

  • channel string
  • message any
  • transfer MessagePortMain[] (任意)

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

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

以下がその例です。

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

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

contents.enableDeviceEmulation(parameters)

  • parameters Object
    • screenPosition string - エミュレートする画面の種類を以下から指定します (省略値: desktop)。
      • desktop - デスクトップ画面タイプ.
      • mobile - モバイル画面タイプ.
    • screenSize Size - エミュレートされる画面サイズの設定 (screenPosition == mobile).
    • viewPosition Point - スクリーン上のビューの位置 (screenPosition == mobile) (省略値: { x: 0, y: 0 }).
    • deviceScaleFactor Integer - デバイスの拡大率の設定 (ゼロなら元々のデバイスの拡大率) (省略値: 0).
    • screenSize Size - エミュレートされるビューのサイズの設定 (空は上書きしないことを意味する)
    • scale Float - 有効なスペース内のエミュレートするビューの拡大率。 (表示モードにフィットしない) (省略値: 1).

与えられた引数でデバイスのエミュレートを有効にします

contents.disableDeviceEmulation()

webContents.enableDeviceEmulation で有効にしたデバイスのエミュレートを向こうにします。

contents.sendInputEvent(inputEvent)

入力 event をページに送ります。 注釈: sendInputEvent() が動くには、そのコンテツを含む BrowserWindow がフォーカスされている必要があります。

contents.beginFrameSubscription([onlyDirty ,]callback)

  • onlyDirty boolean (任意) - 省略値は false
  • callback Function

プレゼンテーションイベントとキャプチャされたフレームの監視を開始し、プレゼンテーションイベントがあれば、callbabckcallback(image, dirtyRect) で呼ばれます。

image はキャプチャされたフレームを格納する NativeImage のインスタンスです。

dirtyRect は 再描画されたページの部分を示す x, y, width, height プロパティのオブジェクトです。 もし onlyDirtytrue にセットされている場合、image は再描画された領域だけを含みます。 onlyDirty の省略値は false です。

contents.endFrameSubscription()

フレームプレゼンテーションイベントの監視を終了します。

contents.startDrag(item)

  • item Object
    • file string - ドラッグされているファイルのパス。
    • files string[] (任意) - ドラッグされている複数ファイルのパス。 (filesfile フィールドより優先されます)
    • icon NativeImage | string - この画像は macOS では空にできません。

現在の D&D 操作のドラッグアイテムに item をセットします。file はドラッグされるファイルへの絶対パスで、icon はドラッグするときにカーソルの下に表示される画像です。

contents.savePage(fullPath, saveType)

  • fullPath string - ファイルの絶対パス。
  • saveType string - 保存のタイプを指定します。
    • HTMLOnly - ページの HTML だけを保存する。
    • HTMLComplete - 完全な HTML ページを保存する。
    • MHTML - MHTML として完全な HTML ページを保存する。

戻り値 Promise<void> - ページが保存された場合に実行されます。

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()

win.loadURL('https://github.com')

win.webContents.on('did-finish-load', async () => {
win.webContents.savePage('/tmp/test.html', 'HTMLComplete').then(() => {
console.log('Page was saved successfully.')
}).catch(err => {
console.log(err)
})
})

contents.showDefinitionForSelection() macOS

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

contents.isOffscreen()

戻り値 boolean - オフスクリーンレンダリング が有効にされているかどうかを示す。

contents.startPainting()

もし オフスクリーンレンダリング が有効かつ描画中でなければ、描画を開始します。

contents.stopPainting()

もし オフスクリーンレンダリング が有効かつ描画中であれば、描画を終了します。

contents.isPainting()

戻り値 boolean - もし オフスクリーンレンダリング が有効であれば、現在描画中かどうかを返します。

contents.setFrameRate(fps)

  • fps Integer

もし オフスクリーンレンダリング が有効であれば指定された数字にフレームレートをセットします。 1 から 240 の値のみを受け取ります。

contents.getFrameRate()

戻り値 Boolean - もし オフスクリーンレンダリング が有効であれば、現在のフレームレートを返します。

contents.invalidate()

このウェブコンテンツが入っているウインドウの完全な再描画をスケジュールします。

もし オフスクリーンレンダリング が有効であれば、フレームを無効にし、'paint' を通して新しいフレームを生成します。

contents.getWebRTCIPHandlingPolicy()

戻り値 string - WebRTC IP ハンドリングポリシーを返します。

contents.setWebRTCIPHandlingPolicy(policy)

  • policy string - WebRTC IP ハンドリングポリシーを指定します。
    • default - ユーザの公開IPとローカルIPを公開します。 これはデフォルトの動作です。 このポリシーが使用されるとき、WebRTC には、すべてのインターフェースを列挙し、それらを結合して公開インターフェースを検出する権利があります。
    • default_public_interface_only - ユーザの公開IPを公開しますが、ユーザのローカルIPは公開しません。 このポリシーが使用されるとき、WebRTC は HTTP が使用するデフォルトのルートのみを使用する必要があります。 これはどのローカルアドレスも公開しません。
    • default_public_and_private_interfaces - ユーザの公開IPとローカルIPを公開します。 このポリシーが使用されるとき、WebRTC は HTTP が使用するデフォルトのルートのみを使用する必要があります。 これは関連するデフォルトのプライベートアドレスも公開します。 デフォルトルートは、マルチホームのエンドポイント上で OS によって選択されたルートです。
    • disable_non_proxied_udp - パブリック IP やローカル IP を非公開にします。 このポリシーが使用される WebRTC は、プロキシサーバーが UDP をサポートしていない限り、TCP を使用してピアまたはサーバーに接続する必要があります。

WebRTC IP ハンドリングポリシーを設定すると、WebRTC を介して公開される IP を制御できます。 より詳しくは BrowserLeaks を参照して下さい。

contents.getMediaSourceId(requestWebContents)

  • requestWebContents WebContents - id が登録されるウェブコンテンツ。

Returns string - WebContents ストリームの識別子。 この識別子は tabchromeMediaSource を使う navigator.mediaDevices.getUserMedia で利用できます。 この識別子は登録されたウェブコンテンツのみにおいて、10 秒間だけ有効です。

contents.getOSProcessId()

戻り値 Integer - 関連するレンダラープロセスのオペレーティングシステムの pid

contents.getProcessId()

戻り値 Integer - 関連するレンダラーの Chromium 内部の pid。 フレーム特有のナビゲーションイベント (did-frame-navigate など) で渡される frameProcessId と比較できます。

contents.takeHeapSnapshot(filePath)

  • filePath string - 出力ファイルのパス

戻り値 Promise<void> - スナップショットの作成が成功したかどうかを示します。

V8 ヒープのスナップショットを撮り、それを filePath に保存します。

contents.getBackgroundThrottling()

戻り値 boolean - ページがバックグラウンドになったときに、この WebContents がアニメーションやタイマーを抑制するかどうか。 これは Page Visibility API にも影響を与えます。

contents.setBackgroundThrottling(allowed)

  • allowed boolean

ページがバックグラウンドになったときにこの WebContents がアニメーションとタイマーを抑制するかどうかを制御します。 これは Page Visibility API にも影響を与えます。

contents.getType()

Returns string - webContents の型。 backgroundPagewindowbrowserViewremotewebviewoffscreen になります。

contents.setImageAnimationPolicy(policy)

  • policy string - animateanimateOncenoAnimation にできます。

この webContents の画像アニメーションポリシーを設定します。 このポリシーは 新しく読み込まれた 画像にのみ適用され、現在アニメーションを行っている既存の画像は影響を受けません。 これは Chromium の既知の制限で、img.src = img.src とすることで画像のアニメーションを強制的に再計算させられます。この場合、ネットワークトラフィックは発生しませんが、アニメーションポリシーが更新されます。

これは、Chromium のアクセシビリティ機能である animationPolicy に対応します。

インスタンスプロパティ

contents.audioMuted

このページをミュートするかどうかを決定する boolean プロパティ。

contents.userAgent

このウェブページのユーザーエージェントを決定する string プロパティ。

contents.zoomLevel

このウェブコンテンツのズームレベルを決定する number プロパティ。

原寸は 0 で、各増減分はそれぞれ 20% ずつの拡大または縮小を表し、デフォルトで元のサイズの 300% から 50% までに制限されています。 The formula for this is scale := 1.2 ^ level.

contents.zoomFactor

number 型のプロパティです。このウェブコンテンツのズーム率を決定します。

ズーム率は百分率のズームなので、300% = 3.0 になります。

contents.frameRate

Integer 型のプロパティです。ウェブコンテンツのフレームレートを指定された数値に設定します。 1 から 240 の値のみを受け取ります。

オフスクリーンレンダリング が有効な場合にのみ適用されます。

contents.id 読み出し専用

この WebContents の一意のIDを表す Integer。 各 ID は、この Electron アプリケーション全体のすべての WebContents インスタンス間で一意です。

contents.session 読み出し専用

この webContents で使われる Session

contents.hostWebContents 読み出し専用

この WebContents を所有するかもしれない WebContents インスタンス。

contents.devToolsWebContents 読み出し専用

WebContents | null 型のプロパティ。その WebContents に関連付けられたデベロッパー ツール の WebContents を表します。

注釈: 開発者向けツールが閉じられたときに null になる可能性があるので、このオブジェクトは決して格納しないで下さい。

contents.debugger 読み出し専用

この webContents の Debugger インスタンス。

contents.backgroundThrottling

boolean 型のプロパティです。ページがバックグラウンドになったときに、この WebContents がアニメーションやタイマーを抑制するかどうかを決定します。 これは Page Visibility API にも影響を与えます。

contents.mainFrame 読み出し専用

WebFrameMain 型のプロパティで、ページの最上位階層のフレームを表します。