webContents

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

プロセス: Main

webContents は EventEmitter を継承しています。 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.fromFrame(frame)`

frame WebFrameMain

戻り値 WebContents | undefined - 指定 WebFrameMain の WebContents インスタンス。指定の WebFrameMain に関連付けられた 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'

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

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

戻り値：

event Event
title string
explicitSet boolean

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

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

戻り値：

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

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

イベント: 'content-bounds-updated'

戻り値：

event Event
bounds Rectangle - 要求された新しいコンテンツ領域

ページが window.moveTo、 window.resizeTo 、または関連する API を呼び出すときに発生します。

デフォルトでは、これによりウインドウを動かします。その動作を阻害するには、event.preventDefault() を呼び出してください。

イベント: '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 - default、foreground-tab、background-tab、new-window、save-to-disk、other にできます。

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

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

イベント: 'will-navigate'

戻り値：

event Event
url string

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

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

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

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

戻り値：

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

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

イベント: 'will-redirect'

戻り値：

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

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

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

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

戻り値：

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

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

イベント: '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 - プロセスの終了コードです。reason が launch-failed でなければ、exitCode はプラットフォーム固有の起動失敗のエラーコードになります。

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

イベント: 'unresponsive'

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

イベント: 'responsive'

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

イベント: 'plugin-crashed'

戻り値：

event Event
name string
version string

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

イベント: 'destroyed'

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

イベント: 'input-event'

戻り値：

event Event
inputEvent InputEvent

入力イベントが WebContents へ送信されたときに発生します。詳しくは InputEvent をご参照ください。

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

戻り値：

event Event
input Object - 入力プロパティ。
- type string - keyUp か keyDown。
- key string - KeyboardEvent.key と等価です。
- code string - KeyboardEvent.code と等価です。
- isAutoRepeat boolean - KeyboardEvent.repeat と等価です。
- isComposing boolean - KeyboardEvent.isComposing と等価です。
- shift boolean - KeyboardEvent.shiftKey と同等。
- control boolean - KeyboardEvent.controlKey と同等。
- alt boolean - KeyboardEvent.altKey と等価です。
- meta boolean - KeyboardEvent.metaKey と同等。
- location number - KeyboardEvent.location と同等。
- modifiers string[] - InputEvent.modifiers をご参照ください。

ページ内の keydown と keyup イベントが発生する直前に発行されます。 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 - in か out にできます。

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

イベント: 'blur'

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

イベント: 'focus'

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

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

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

イベント: 'devtools-opened'

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

イベント: 'devtools-closed'

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

イベント: 'devtools-focused'

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

イベント: 'certificate-error'

戻り値：

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

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

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

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

戻り値：

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

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

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

戻り値：

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 認証を要求すると発生します。

使い方は、app の login イベントと同じです。

イベント: '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 (任意) - カスタムカーソルのホットスポットの座標。

カーソルの種類が変更されたときに発行されます。 type は default、crosshair、pointer、text、wait、help、e-resize、n-resize,ne-resize、nw-resize、s-resize、se-resize、sw-resize、w-resize,ns-resize、ew-resize、nesw-resize、nwse-resize、col-resize,row-resize、m-panning、e-panning、n-panning、ne-panning、nw-panning,s-panning、se-panning、sw-panning、w-panning、move、vertical-text,cell、context-menu、alias、progress、nodrop、copy、none,not-allowed、zoom-in、zoom-out、grab、grabbing、custom になれます。

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

戻り値：

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 - コンテキストメニューが呼び出されたノードの種類。 none、image、audio、video、canvas、file、plugin になれる。
- 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 - 入力フィールド内でコンテキストメニューが呼び出されたときの、そのタイプ。 none、plainText、password、other になれる。
- 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'

戻り値：

event Event
devices BluetoothDevice[]
callback Function
- deviceId string

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

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

main.js
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'

戻り値：

event Event
dirtyRect Rectangle
image NativeImage - フレーム全体の画像データ。

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

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 のログレベル。順に verbose、info、warning、error に対応します。
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() を介して非同期メッセージを送信したときに発生します。

webContents.ipc もご参照ください。これはその WebContents からの IPC メッセージに特別に応答するための IpcMain ライクなインターフェイスを提供します。

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

戻り値：

event Event
channel string
...args any[]

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

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

戻り値：

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

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

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

イベント: '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 のリソースのダウンロードを初期化します。 session の will-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.close([opts])`

opts Object (任意)
- waitForBeforeUnload boolean - true であれば、ページを閉じる前に beforeunload イベントを発生させます。ページのアンロードが阻害された場合、WebContents は閉じられません。 will-prevent-unload はページがアンロードを阻害するように要求したときに発生します。

ウェブコンテンツが window.close() を呼ばれたときのように、ページを閉じます。

ページが正常に閉じられた場合 (すなわち、ページによってアンロードが妨げられなかった場合、または waitForBeforeUnload が false や未指定の場合)、WebContents は破棄され、使用できなくなります。また destroyed イベントが発生します。

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

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

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', outlivesOpener?: boolean, 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 - default、foreground-tab、background-tab、new-window、save-to-disk、other のいずれかにできます。
  - referrer Referrer - 新しいウィンドウへ渡される Referrer。 Referrer のポリシーに依存しているので、Referrer ヘッダを送信されるようにしてもしなくてもかまいません。
  - postBody PostBody (任意) - 新しいウインドウに送信する POST データと、それに設定する適切なヘッダ。送信する POST データが無い場合、値は null になります。これは target=_blank を設定したフォームによってウィンドウが作成されている場合にのみセットされます。
戻り値 {action: 'deny'} | {action: 'allow', outlivesOpener?: boolean, overrideBrowserWindowOptions?: BrowserWindowConstructorOptions} - deny を返すと新規ウインドウの作成をキャンセルします。 allow を返すと新規ウインドウが作成されます。 overrideBrowserWindowOptions を指定すると、作成されるウィンドウをカスタマイズできます。デフォルトでは、子ウインドウを開いたウインドウが閉じられるとその子ウインドウも一緒に閉じられます。これは outlivesOpener: true を指定することで変更可能です。こうすると、子ウインドウを開いたウインドウが閉じられても、子ウインドウは閉じなくなります。 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 で、webContents の findInPage リクエストを停止します。

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, opts])`

rect Rectangle (任意) - キャプチャするページ内の領域。
opts Object (任意)
- stayHidden boolean (任意) - ページを表示せずに非表示のままにします。省略値は false です。
- stayAwake boolean (任意) - システムをスリープさせずに、起きたままにします。省略値は false です。

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

rect 内のページのスナップショットをキャプチャします。 rect を省略すると、表示されているページ全体をキャプチャします。ブラウザーウインドウが非表示でもキャプチャ回数がゼロではない場合、ページは表示されていると見なされます。ページを非表示のままにする場合は、stayHidden を true に設定していることを確認してください。

`contents.isBeingCaptured()`

Returns boolean - このページがキャプチャされているかどうか。キャプチャーの数が 0 より大きい場合は 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 (任意) - default、none、printableArea か custom にできます。 custom を選択した場合、top、bottom、left、right も指定する必要があります。
  - 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 (任意) - 印刷されるウェブページの両面モードを設定します。 simplex、shortEdge、longEdge のいずれかにできます。
- dpi Record<string, number> (任意)
  - horizontal number (任意) - 水平 DPI。
  - vertical number (任意) - 垂直 DPI。
- header string (任意) - ページヘッダーとして印刷される文字列。
- footer string (任意) - ページフッターとして印刷される文字列。
- pageSize string | Size (任意) - 印刷するドキュメントのページサイズを指定します。 A0、A1、A2、A3、A4、A5、A6、Legal、Letter、Tabloid、または height と width を含む Object のいずれかにできます。
callback Function (任意)
- success boolean - 印刷呼び出しの成功を示します。
- failureReason string - 印刷に失敗した場合に呼び戻されるエラーの説明です。

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

ウインドウのウェブページを印刷します。 silent が true にセットされたとき、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
- landscape boolean (任意) - 用紙の向き。true で横向き、false で縦向きです。省略値は、false です。
- displayHeaderFooter boolean (任意) - ヘッダーとフッターを表示するかどうか。省略値は、false です。
- printBackground boolean (任意) - 背景グラフィックを印刷するかどうか。省略値は、false です。
- scale number (任意) - ウェブページ描画の拡大率。省略値は 1 です。
- pageSize string | Size (任意) - 生成する PDF のページサイズを指定します。 A0、A1、A2、A3、A4、A5、A6、Legal、Letter、Tabloid、Ledger、またはインチ単位の height と width を含む Object のいずれかにできます。省略値は、Letter です。
- margins Object (任意)
  - top number (任意) - インチ単位の上部余白。省略値は 1cm (約 0.4 インチ) です。
  - bottom number (任意) - インチ単位の下部余白。省略値は 1cm (約 0.4 インチ) です。
  - left number (任意) - インチ単位の左余白。省略値は 1cm (約 0.4 インチ) です。
  - right number (任意) - インチ単位の右余白。省略値は 1cm (約 0.4 インチ) です。
- pageRanges string (任意) - 印刷するページ範囲。例えば '1-5, 8, 11-13' のようにします。省略値は空の文字列で、これは全ページを印刷します。
- headerTemplate string (任意) - 印刷ヘッダーの HTML テンプレート。有効な HTML マークアップで、印刷の値を注入するために次のクラスが使用されている必要があります。date (フォーマットされた印刷日)、title (ドキュメントのタイトル)、url (ドキュメントの場所)、pageNumber (現在のページ番号) および totalPages (ドキュメントの総ページ数)。例えば、<span class=title></span> はタイトルが入った span を生成します。
- footerTemplate string (任意) - 印刷フッターの HTML テンプレート。 headerTemplate と同じ形式を使用すべきです。
- preferCSSPageSize boolean (任意) - CSS で定義されたページサイズに合わせるかどうか。省略値は false で、その場合コンテンツは用紙サイズに合うように拡大縮小されます。

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

そのウインドウのウェブページを PDF として印刷します。

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

これは webContents.printToPDF の例です。

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

const win = new BrowserWindow()
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)
  })
})

詳細は Page.printToPdf をご覧ください。

`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 を使用して、BrowserWindow、BrowserView、<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 内で開発者向けツールを表示する例:

main.js
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 - 指定したドック状態で開発者向けツールを開きます。left、right、bottom、undocked、detach にできます。省略値は最後に使用したときのドック状態。 undocked モードではドックを後ろにやれる。 detach モードではできない。
- activate boolean (任意) - 開かれたデベロッパーツールウインドウを前面に表示するかどうか。省略値は true です。

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

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

Windows では、Windows コントロールオーバーレイが有効になっているとデベロッパーツールは mode: 'detach' で開かれます。

`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 型を送信すると例外が発生します。

さらなる解説は Electron の IPC ガイドをご参照ください。

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

メッセージをレンダラープロセスに送信し、任意でゼロ個以上の 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)。
- viewSize Size - エミュレートされるビューのサイズの設定 (空は上書きしないことを意味します)
- scale Float - 有効なスペース内のエミュレートするビューの拡大率 (表示モードには合わせません) (省略値: 1)。

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

`contents.disableDeviceEmulation()`

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

`contents.sendInputEvent(inputEvent)`

inputEvent MouseInputEvent | MouseWheelInputEvent | KeyboardInputEvent

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

`contents.beginFrameSubscription([onlyDirty ,]callback)`

onlyDirty boolean (任意) - 省略値は false。
callback Function
- image NativeImage
- dirtyRect Rectangle

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

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

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

`contents.endFrameSubscription()`

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

`contents.startDrag(item)`

item Object
- file string - ドラッグされているファイルのパス。
- files string[] (任意) - ドラッグされている複数ファイルのパス。 (files は file フィールドより優先されます)
- 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()`

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

`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 ストリームの識別子。この識別子は tab の chromeMediaSource を使う 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 の型。 backgroundPage、window、browserView、remote、webview か offscreen になります。

`contents.setImageAnimationPolicy(policy)`

policy string - animate、animateOnce か noAnimation にできます。

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

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

インスタンスプロパティ

`contents.ipc` 読み出し専用

この WebContents から送信された 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 メッセージを受信します。ほとんどの場合、メインフレームだけが IPC メッセージを送信できます。しかし、nodeIntegrationInSubFrames オプションが有効の場合、子フレームも IPC メッセージを送信できます。その場合、ハンドラは IPC イベントの senderFrame プロパティをチェックし、メッセージが期待のフレームから送られていることを確認する必要があります。代わりに、適切なフレームで WebFrameMain.ipc インターフェイスを用いて直接ハンドラを登録することもできます。

`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 型のプロパティで、ページの最上位階層のフレームを表します。

`contents.opener` 読み出し専用

WebFrameMain 型のプロパティで、この WebContents を開いたフレームを表します。open() あるいは target 属性を付けたリンクへナビゲートしたときの WebContents です。

メソッド
クラス: WebContents

webContents

メソッド​

webContents.getAllWebContents()​

webContents.getFocusedWebContents()​

webContents.fromId(id)​

webContents.fromFrame(frame)​

webContents.fromDevToolsTargetId(targetId)​

クラス: WebContents​

インスタンスイベント​

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

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

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

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

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

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

イベント: 'dom-ready'​

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

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

イベント: 'content-bounds-updated'​

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

イベント: 'will-navigate'​

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

イベント: 'will-redirect'​

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

イベント: 'did-navigate'​

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

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

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

イベント: 'crashed' 非推奨​

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

イベント: 'unresponsive'​

イベント: 'responsive'​

イベント: 'plugin-crashed'​

イベント: 'destroyed'​

イベント: 'input-event'​

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

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

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

イベント: 'zoom-changed'​

イベント: 'blur'​

イベント: 'focus'​

イベント: 'devtools-opened'​

イベント: 'devtools-closed'​

イベント: 'devtools-focused'​

イベント: 'certificate-error'​

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

イベント: 'login'​

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

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

イベント: 'media-paused'​

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

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

イベント: 'cursor-changed'​

イベント: 'context-menu'​

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

イベント: 'paint'​

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

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

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

Event: 'console-message'​

イベント: 'preload-error'​

イベント: 'ipc-message'​

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

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

イベント: 'frame-created'​

インスタンスメソッド​

contents.loadURL(url[, options])​

contents.loadFile(filePath[, options])​

contents.downloadURL(url)​

contents.getURL()​

contents.getTitle()​

contents.isDestroyed()​

contents.close([opts])​

contents.focus()​

contents.isFocused()​

contents.isLoading()​

contents.isLoadingMainFrame()​

contents.isWaitingForResponse()​

contents.stop()​

contents.reload()​

メソッド

`webContents.getAllWebContents()`

`webContents.getFocusedWebContents()`

`webContents.fromId(id)`

`webContents.fromFrame(frame)`

`webContents.fromDevToolsTargetId(targetId)`

クラス: WebContents

インスタンスイベント

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

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

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

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

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

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

イベント: 'dom-ready'

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

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

イベント: 'content-bounds-updated'

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

イベント: 'will-navigate'

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

イベント: 'will-redirect'

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

イベント: 'did-navigate'

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

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

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

イベント: 'crashed' 非推奨

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

イベント: 'unresponsive'

イベント: 'responsive'

イベント: 'plugin-crashed'

イベント: 'destroyed'

イベント: 'input-event'

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

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

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

イベント: 'zoom-changed'

イベント: 'blur'

イベント: 'focus'

イベント: 'devtools-opened'

イベント: 'devtools-closed'

イベント: 'devtools-focused'

イベント: 'certificate-error'

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

イベント: 'login'

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

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

イベント: 'media-paused'

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

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

イベント: 'cursor-changed'

イベント: 'context-menu'

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

イベント: 'paint'

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

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

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

Event: 'console-message'

イベント: 'preload-error'

イベント: 'ipc-message'

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

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

イベント: 'frame-created'

インスタンスメソッド

`contents.loadURL(url[, options])`

`contents.loadFile(filePath[, options])`

`contents.downloadURL(url)`

`contents.getURL()`

`contents.getTitle()`

`contents.isDestroyed()`

`contents.close([opts])`

`contents.focus()`

`contents.isFocused()`

`contents.isLoading()`

`contents.isLoadingMainFrame()`

`contents.isWaitingForResponse()`

`contents.stop()`

`contents.reload()`

`contents.reloadIgnoringCache()`