BrowserWindow

ブラウザウィンドウを作成したり、制御したりします。

プロセス: Main

app モジュールの ready イベントが発生するまでは、このモジュールは使用できません。

// メインプロセス
const { BrowserWindow } = require('electron')

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

// 外部 URL を読み込む
win.loadURL('https://github.com')

// またはローカルの HTML ファイルを読み込む
win.loadURL('index.html')

ウインドウのカスタマイズ

BrowserWindow クラスは、アプリのウインドウの見た目や動作を変更するさまざまな方法を提供しています。 詳細は、ウインドウのカスタマイズ のチュートリアルをご覧ください。

ウインドウを違和感なく表示する

ウインドウにページを直接ロードすると、ユーザにはページが徐々にロードされるように見えるかもしれません。これはネイティブアプリとしては良い挙動ではありません。 ちらつかせることなくウインドウを表示するには、さまざまな状況に応じた 2 つの解決策があります。

ready-to-show イベントを使用する

ページのロード中、ウインドウがまだ表示されていない場合、レンダラープロセスが初めてページをレンダリングし終わったとき、ready-to-show イベントが発生します。 このイベントの後にウインドウを表示させれば、チラつくことはありません。

const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ show: false })
win.once('ready-to-show', () => {
  win.show()
})

このイベントは、通常、did-finish-load イベントの後に発生しますが、大量のリモートリソースがあるページでは、did-finish-load イベントの前に発生する可能性があります。

このイベントを使用すると、show が false でもレンダラーが "見えている" と見なされ、描画されることに注意してください。 paintWhenInitiallyHidden: false を使用すると、このイベントは発生しません。

backgroundColor プロパティを設定する

複雑なアプリでは、ready-to-show イベントが発生するのに時間がかかり過ぎて、アプリが遅いと感じさせる可能性があります。 このような場合、ウインドウをすぐに表示し、アプリの背景に近い backgroundColor を使うことを推奨します。

const { BrowserWindow } = require('electron')

const win = new BrowserWindow({ backgroundColor: '#2e2c29' })
win.loadURL('https://github.com')

ready-to-show イベントを使用しているアプリに対しても、アプリがよりネイティブに感じられるように backgroundColor を設定することが推奨されます。

いくつか有効な backgroundColor の例を示します。

const win = new BrowserWindow()
win.setBackgroundColor('hsl(230, 100%, 50%)')
win.setBackgroundColor('rgb(255, 145, 145)')
win.setBackgroundColor('#ff00a3')
win.setBackgroundColor('blueviolet')

これらの色の種類についての詳細は、win.setBackgroundColor の有効なオプションをご参照ください。

親ウィンドウと子ウィンドウ

parent オプションを使用することで、子ウインドウを作成することができます。

const { BrowserWindow } = require('electron')

const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top })
child.show()
top.show()

child ウインドウは、常に top ウインドウの前面に表示されます。

モーダルウィンドウ

モーダルウインドウは、親ウインドウを無効にする子ウインドウです。 モーダルウインドウを作成するには、parent と modal の両方のオプションを設定しなければなりません。

const { BrowserWindow } = require('electron')

const top = new BrowserWindow()
const child = new BrowserWindow({ parent: top, modal: true, show: false })
child.loadURL('https://github.com')
child.once('ready-to-show', () => {
  child.show()
})

ページの表示状態

Page Visibility API は、以下のように動作します。

• すべてのプラットフォームおいて、表示状態はウインドウが非表示/最小化されているかどうかをトラッキングします。
• さらに、macOSでは、表示状態はウインドウが重なり合った状態もトラッキングします。 ウインドウが別のウインドウと重なり合った (例えば、完全に覆い隠された) 場合、表示状態は、hidden になります。 他のプラットフォーム上では、ウインドウが最小化されるか、明示的に win.hide() で非表示にされた場合のみ、表示状態は hidden になります。
• BrowserWindow が show: false で作成された場合、ウインドウが実際には非表示であるにも関わらず、初期の表示状態は visible になります。
• backgroundThrottling が無効の場合、ウインドウを最小化したり、重ねたり、非表示にしたりしても、表示状態は visible のままになります。

消費電力を最小にするために、表示状態が hidden のとき、高負荷な操作を一時停止することを推奨します。

プラットフォームに関する注意事項

• macOSでは、モーダルウインドウは親ウインドウに付随したシートとして表示されます。
• 親ウインドウが移動したとき、macOSでは、子ウインドウは親ウインドウに対する相対的な位置を維持しますが、WindowsとLinuxでは、子ウインドウは移動しません。
• Linuxでは、モーダルウインドウの型は、dialog に変更されます。
• Linuxでは、多くのデスクトップ環境は、モーダルウインドウを非表示にすることをサポートしていません。

クラス: BrowserWindow extends BaseWindow

ブラウザウィンドウを作成したり、制御したりします。

プロセス: Main

BrowserWindow は EventEmitter を継承しています。

options によって設定されたネイティブプロパティで新しい BrowserWindow を生成します。

new BrowserWindow([options])

• options BrowserWindowConstructorOptions (任意)
  • webPreferences WebPreferences (任意) - ウェブページの機能群の設定。
    • devTools boolean (任意) - デベロッパーツールを有効にするかどうか。 false に設定すると、BrowserWindow.webContents.openDevTools() を使ってデベロッパーツールを開くことはできません。 省略値は true です。
    • nodeIntegration boolean (任意) - Node インテグレーションを有効にするかどうか。 省略値は false です。
    • nodeIntegrationInWorker boolean (任意) - WebワーカーでNode統合を有効にするかどうか。 省略値は false です。 これについての詳細は、マルチスレッド を参照してください。
    • nodeIntegrationInSubFrames boolean (任意) - iframe や子ウインドウのようなサブフレーム内で Node.js サポートを有効にする実験的な機能です。 すべてのプリロードは iframe 毎にロードされます。メインフレーム内かそうでないか判断するには process.isMainFrame が使用できます。
    • preload string (任意) - 他のスクリプトがページで実行される前にロードされるスクリプトを指定します。 このスクリプトは、Node統合がオンまたはオフであるかに関係なく常にNode APIにアクセスできます。 値は、スクリプトへの絶対ファイルパスにする必要があります。 Node統合がオフのときでも、プレロードされたスクリプトは、Nodeのグローバルシンボルをグローバルスコープに再導入できます。 ここ の例を参照してください。
    • sandbox boolean (任意) - 設定された場合、ウインドウと関連付けられているレンダラーをサンドボックス化します。これは、ChromiumのOSレベルのサンドボックスと互換性を持ち、Node.jsエンジンを無効化します。 これは nodeIntegration オプションと同じではなく、プレロードスクリプトで利用可能なAPIよりもさらに制限がかかります。 このオプションの詳細については、ここ をお読みください。
    • session Session (任意) - ページで使用されるセッションを設定します。 Session オブジェクトを直接引き渡す代わりに、パーティション文字列を受け付ける partition オプションを使用することを選択することもできます。 session と partition の両方が指定されたときは、session が優先されます。 省略値は、既定のセッションです。
    • partition string (任意) - セッションのパーティション文字列に従って、ページで使用されるセッションを設定します。 partition が persist: 始まりの場合、ページはアプリの全ページで利用可能な永続的なセッションを同じ partition で使用します。 persist: プレフィックスがない場合、ページは、インメモリセッションを使用します。 同じ partition を割り当てることによって、複数のページが同じセッションを共有できます。 省略値は、既定のセッションです。
    • zoomFactor number (任意) - ページの既定のズーム倍率で、3.0 は 300% を表します。 デフォルトは1.0です。
    • javascript boolean (任意) - JavaScript サポートを有効にします。 省略値は true です。
    • webSecurity boolean (任意) - false のとき、同一オリジンポリシー (通常、テスト用Webサイトを使用します) が無効になり、ユーザによって設定されない場合、allowRunningInsecureContent が true に設定されます。 省略値は true です。
    • allowRunningInsecureContent boolean (任意) - https のページで http の URL からの JavaScript、CSS やプラグインを実行することを許可します。 省略値は false です。
    • images boolean (任意) - 画像のサポートを有効にします。 省略値は true です。
    • imageAnimationPolicy string (任意) - 画像アニメーションの実行方法を指定します。(例: GIF)。 animate、animateOnce、noAnimation のいずれかにできます。 デフォルトはanimateです。
    • textAreasAreResizable boolean (任意) - TextArea 要素のサイズを変更可能にします。 省略値は true です。
    • webgl boolean (任意) - WebGL のサポートを有効にします。 省略値は true です。
    • plugins boolean (任意) - プラグインを有効にするかどうか。 省略値は false です。
    • experimentalFeatures boolean (任意) - Chromium の実験的な機能を有効にします。 省略値は false です。
    • scrollBounce boolean (任意) macOS - macOS でスクロールバウンス (ゴムを伸ばすような) 効果を有効にします。 省略値は false です。
    • enableBlinkFeatures string (任意) - CSSVariables,KeyboardEventKey のように , で区切られた有効にする機能の文字列のリスト。 サポートされている機能の文字列の完全なリストは、RuntimeEnabledFeatures.json5 ファイルで確認できます。
    • disableBlinkFeatures string (任意) - CSSVariables,KeyboardEventKey のように , で区切られた無効にする機能の文字列のリスト。 サポートされている機能の文字列の完全なリストは、RuntimeEnabledFeatures.json5 ファイルで確認できます。
    • defaultFontFamily Object (任意) - 各フォントファミリーの既定フォントを設定します。
      • standard string (任意) - 省略値は、Times New Roman です。
      • serif string (任意) - 省略値は、Times New Roman です。
      • sansSerif string (任意) - 省略値は、Arial です。
      • monospace string (任意) - 省略値は、Courier New です。
      • cursive string (任意) - 省略値は、Script です。
      • fantasy string (任意) - 省略値は、Impact です。
      • math string (任意) - 省略値は、Latin Modern Math です。
    • defaultFontSize Integer (任意) - 省略値は、16 です。
    • defaultMonospaceFontSize Integer (任意) - 省略値は、13 です。
    • minimumFontSize Integer (任意) - 省略値は、0 です。
    • defaultEncoding string (任意) - 省略値は、ISO-8859-1 です。
    • backgroundThrottling boolean (任意) - ページがバックグラウンドになったとき、アニメーションやタイマーを抑制するかどうか。 これは Page Visibility API にも影響を与えます。 少なくとも 1 つの webContents が 1 つの browserWindow に表示されていて、そのウインドウの backgroundThrottling が無効になっている場合、ウインドウ全体とウインドウによって表示される他の webContents に対して、フレームが描画されて交換されます。 省略値は true です。
    • offscreen boolean (任意) - ブラウザウィンドウでオフスクリーンレンダリングを有効にするかどうか。 省略値は false です。 詳細については、オフスクリーンレンダリングのチュートリアル を参照してください。
    • contextIsolation boolean (任意) - Electron APIと指定された preload スクリプトを別々のJavaScriptコンテキストで実行するかどうか。 省略値は true です。 preload スクリプトが実行されるコンテキストでは、専用の document および window グローバルと、独自の JavaScript ビルドインのセット (Array, Object, JSON など) にのみアクセスできます。これらすべてはロードされたコンテンツからは見えません。 Electron API は preload スクリプトでのみ利用可能で、読み込まれたページでは利用できません。 このオプションは、信頼できない可能性のあるリモートコンテンツをロードする際に使用します。ロードされたコンテンツが preload スクリプトや使用する Electron API を改ざんできないようにするためです。 このオプションは、Chrome のコンテンツスクリプト のものと同じ手法を使用しています。 Console タブの一番上のコンボボックスの中にある 'Electron Isolated Context' という項目を選択することによって、開発者ツールでこのコンテキストにアクセスできます。
    • webviewTag boolean (任意) - <webview> タグ を有効にするかどうか。 省略値は false です。 注: <webview> に設定された preload スクリプトは、実行時にNode統合が有効になるので、潜在的に悪意のある preload スクリプトを含む <webview> タグをリモート/信頼できないコンテンツに作成させないようにする必要があります。 preload スクリプトを除去したり、検証したり、<webview> の初期設定を変更したりするために、webContents の will-attach-webview イベントを使うことができます。
    • additionalArguments string[] (任意) - このアプリケーションのレンダラープロセスで process.argv に追加される文字列のリスト。 小規模なデータをレンダラープロセスのプリロードスクリプトに渡すのに便利です。
    • safeDialogs boolean (任意) - ブラウザによる連続ダイアログ保護を有効にするかどうか。 省略値は false です。
    • safeDialogsMessage string (任意) - 連続したダイアログからの保護が機能したときに表示されるメッセージ。 定義されていなければデフォルトメッセージが使われますが、現在のデフォルトメッセージは英語であり、ローカライズされていないことに注意してください。
    • disableDialogs boolean (任意) - ダイアログを完全に無効化するかどうか。 safeDialogs を上書きします。 省略値は false です。
    • navigateOnDragDrop boolean (任意) - ファイルやリンクをページにドラッグ & ドロップした際にナビゲーションするかどうか。 省略値は false です。
    • autoplayPolicy string (任意) - ウインドウ内のコンテンツに適用される自動再生ポリシーで、no-user-gesture-required、user-gesture-required、document-user-activation-required にできます。 省略値は no-user-gesture-required です。
    • disableHtmlFullscreenWindowResize boolean (任意) - HTML フルスクリーンになった時にウィンドウのサイズ変更を禁止するかどうか。 省略値は false です。
    • accessibleTitle string (任意) - スクリーンリーダーなどのアクセシビリティツールにのみ提供される代替タイトル文字列。 この文字列はユーザに直接表示されません。
    • spellcheck boolean (任意) - 組み込みスペルチェックを有効にするかどうか。 省略値は true です。
    • enableWebSQL boolean (任意) - WebSQL API を有効にするかどうか。 省略値は true です。
    • v8CacheOptions string (任意) - blink が使用する v8 コードキャッシュポリシーを強制します。 以下は取りうる値です。
      • none - コードキャッシュ無効化
      • code - ヒューリスティックベースのコードキャッシュ
      • bypassHeatCheck - ヒューリスティックのコードキャッシュをバイパスしつつ遅延コンパイル
      • bypassHeatCheckAndEagerCompile - 上と同じにしつつ先行コンパイルします。 既定のポリシーは code です。
    • enablePreferredSizeMode boolean (任意) - 優先サイズモードを有効にするかどうか。 優先サイズとは、document のレイアウトをスクロール無しで格納するにあたって必要な最小サイズのことです。 これを有効にすると、優先サイズが変更されたときに WebContentsでpreferred-size-changedイベントが発生します。 省略値は false です。
    • transparent boolean (任意) - ゲストページの背景の透過を有効にするかどうか。 省略値は true です。 注意: ゲストページのテキストと背景色は、ルート要素の カラースキーム から取得されます。 透過を有効にした場合、テキストの色は指定に応じて変化しますが、背景は透過したままになります。
  • paintWhenInitiallyHidden boolean (任意) - show が false で作成されたばかりのときに、レンダラーをアクティブにするかどうか。 show: false での document.visibilityState が最初のロードで正しく機能するには、これを false に設定する必要があります。 これを false に設定すると、ready-to-show イベントが発生しなくなります。 省略値は true です。

インスタンスイベント

new BrowserWindow で作成されたオブジェクトでは以下のイベントが発生します。

注: いくつかのイベントは特定のオペレーティングシステムでのみ利用可能で、そのように注記がつけられています。

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

戻り値：

• event Event
• title string
• explicitSet boolean

ドキュメントのタイトルが変更されたときに発生します。event.preventDefault() を呼び出すことで、ネイティブウインドウのタイトルが変更されるのをキャンセルできます。 タイトルがファイルの URL から合成された場合、explicitSet は false です。

イベント: 'close'

戻り値：

• event Event

ウインドウがクローズされようとするときに発生します。 これは、DOMの beforeunload と unload イベントの前に発生します。 event.preventDefault() を呼び出すことで、クローズがキャンセルされます。

通常、ウインドウをクローズさせる必要があるかどうかを判断するために、beforeunload ハンドラーを使用したいと思うでしょうが、これは、ウインドウがリロードされるときにも呼び出されます。 Electronでは、undefined 以外の値を返却すれば、クローズをキャンセルします。 以下がその例です。

window.onbeforeunload = (e) => {
  console.log('I do not want to be closed')

  // メッセージボックスがユーザに表示される通常のブラウザーとは違って、
  // 無効でない値を返却すれば、何も表示せずにクローズをキャンセルします。
  // アプリケーションがクローズするのをユーザに確認させるには、
  // ダイアログAPIを使用することを推奨します。
  e.returnValue = false
}

注意: window.onbeforeunload = handler と window.addEventListener('beforeunload', handler) の動作には、微妙な違いがあります。 値のみを返すのではなく、常に明示的に event.returnValue を設定するようにすることを推奨します。後者の方がElectron内でより一貫性のある動作をします。

イベント: 'closed'

ウインドウが閉じられたときに発生します。 このイベントを受け取った後は、ウインドウへの参照を削除し、以降そのウインドウを使用しないようにしてください。

イベント: 'session-end' Windows

強制的なシャットダウン、マシン再起動またはセッションのログオフによってウインドウセッションが終了されようとしたときに発生します。

イベント: 'unresponsive'

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

イベント: 'responsive'

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

イベント: 'blur'

ウインドウがフォーカスを失うときに発生します。

イベント: 'focus'

ウインドウがフォーカスを得るときに発生します。

イベント: 'show'

ウインドウが表示されるときに発生します。

イベント: 'hide'

ウインドウが非表示になるときに発生します。

イベント: 'ready-to-show'

Webページが (まだ表示されていないが) レンダリングされ、チラつくことなくウインドウが表示できるときに発生します。

このイベントを使用すると、show が false でもレンダラーが "見えている" と見なされ、描画されることに注意してください。 paintWhenInitiallyHidden: false を使用すると、このイベントは発生しません。

イベント: 'maximize'

ウィンドウが最大化されるときに発生します。

イベント: 'unmaximize'

ウインドウが最大化状態から抜けるときに発生します。

イベント: 'minimize'

ウィンドウが最小化されるときに発生します。

イベント: 'restore'

ウインドウが最小化状態から復元されたときに発生します。

イベント: 'will-resize' macOS Windows

戻り値：

• event Event
• newBounds Rectangle - ウインドウがリサイズされようとしているサイズ。
• details Object
  • edge (string) - サイズ変更のためにドラッグされているウインドウの縁。 bottom、left、right、top-left、top-right、bottom-left、bottom-right のいずれかになります。

ウィンドウがリサイズされる前に発生します。 event.preventDefault()を呼び出すことで、ウィンドウがリサイズされるのを阻止できます。

このイベントは、ウィンドウが手動でリサイズされようとしているときにしか発生しません。 ウィンドウを、setBoundsやsetSize でリサイズする時には、このイベントは発生しません。

edge オプションに設定できる値と動作は、プラットフォーム依存です。 以下は取りうる値です。

• Windows では、有効な値は bottom、top、left、right、top-left、top-right、bottom-left、bottom-right です。
• macOS では、有効な値は bottom、right です。
  • 値 bottom は垂直方向のサイズ変更の表現に使用されます。
  • 値 right は水平方向のサイズ変更の表現に使用されます。

イベント: 'resize'

ウインドウがリサイズされた後に発生します。

イベント: 'resized' macOS Windows

ウインドウがリサイズされるときに一度発生します。

これは、通常、ウィンドウが手動でリサイズされようとしているときにしか発生しません。 macOS の場合 setBounds/setSize でウィンドウのサイズを変更し、 animate パラメーターを true に設定すると、サイズ変更が完了したときにも、このイベントが発生します。

イベント: 'will-move' macOS Windows

戻り値：

• event Event
• newBounds Rectangle - ウインドウが移動されようとしている位置。

ウィンドウが移動される前に発生します。 Windows では、 event.preventDefault() を呼び出すことで、ウィンドウが移動されるのを阻止できます。

このイベントは、ウィンドウが手動で移動されようとしているときにしか発生しません。 ウインドウを setPosition/setBounds/center で移動する時には、このイベントは発生しません。

イベント: 'move'

ウインドウが新しい位置に移動されているときに発生します。

イベント: 'moved' macOS Windows

ウインドウが新しい位置に移動されるときに一回だけ、発生します。

注: macOSでは、このイベントは move のエイリアスです。

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

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

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

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

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

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

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

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

イベント: 'always-on-top-changed'

戻り値：

• event Event
• isAlwaysOnTop boolean

ウインドウが常に他のウインドウの手前に表示されるように設定またはそれが解除されたときに発生します。

イベント: 'app-command' Windows Linux

戻り値：

• event Event
• command string

アプリコマンド が呼び出されるときに発生します。 これらは、Windowsで幾つかのマウスに組み込まれている "Back" ボタンだけでなく、一般的にキーボードのメディアキーやブラウザコマンドとも関連付けられています。

コマンドは小文字にされ、アンダースコアはハイフンに置き換えられ、APPCOMMAND_プレフィックスは外されます。 例えば、APPCOMMAND_BROWSER_BACKWARD は、browser-backward として送信されます。

const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
win.on('app-command', (e, cmd) => {
  // ユーザーがマウスで戻るボタンを押下したときにナビゲートする
  if (cmd === 'browser-backward' && win.webContents.canGoBack()) {
    win.webContents.goBack()
  }
})

Linux 上では以下のアプリコマンドが明示的にサポートされます。

• browser-backward
• browser-forward

イベント: 'swipe' macOS

戻り値：

• event Event
• direction string

3 本指でのスワイプ時に発生します。 方向は up、right、down、left のいずれかになります。

このイベントは、スワイプで画面の内容が移動しない、古い macOS スタイルのトラックパッドスワイプを元にしています。 ほとんどの macOS トラックパッドはもうこの類のスワイプを許可していないため、正常にイベントを発生させるためには システム環境設定 > トラックパッド > その他のジェスチャ の 'ページ間をスワイプ' 設定を '2本指または3本指でスワイプ' にする必要があります。

イベント: 'rotate-gesture' macOS

戻り値：

• event Event
• rotation Float

トラックパッドの回転ジェスチャで発生します。 回転ジェスチャーが終了するまで継続的に発生します。 各イベントの rotation 値は、最後の発生から回転した角度です。 回転ジェスチャで最後に発行されたイベントは、常に 0 の値になります。 反時計回りの回転値は正であり、時計回りの回転値は負です。

イベント: 'sheet-begin' macOS

ウインドウがシートを開くときに発生します。

イベント: 'sheet-end' macOS

ウインドウがシートを閉じたときに発生します。

イベント: 'new-window-for-tab' macOS

ネイティブの新規タブボタンがクリックされるときに発生します。

イベント: 'system-context-menu' Windows

戻り値：

• event Event
• point Point - コンテキストメニューがトリガーされた画面の座標。

システムコンテキストメニューがウィンドウ上でトリガーされたときに発生します。 通常ユーザーがウィンドウのクライアントエリア以外を右クリックしたときにトリガーされます。 これは、フレームレスウィンドウで-webkit-app-region: dragと宣言したウィンドウタイトルバーまたは任意の領域です。

event.preventDefault() を呼ぶと、そのメニューは表示されなくなります。

静的メソッド

BrowserWindow クラスには、次の静的メソッドがあります。

BrowserWindow.getAllWindows()

戻り値 BrowserWindow[] - 開かれたすべてのブラウザウィンドウの配列。

BrowserWindow.getFocusedWindow()

戻り値 BrowserWindow | null - このアプリケーションでフォーカスされたウインドウ。それ以外は、null を返します。

BrowserWindow.fromWebContents(webContents)

• webContents WebContents

戻り値 BrowserWindow | null - 指定された webContents を保持しているウインドウ。ウインドウが保持していないコンテンツの場合は null です。

BrowserWindow.fromBrowserView(browserView) Deprecated

• browserView BrowserView

注意 BrowserView クラスは非推奨であり、新しい WebContentsView クラスに置き換えられています。

戻り値 BrowserWindow - 指定された browserView を所有するウインドウ。 指定されたビューがどのウィンドウにもアタッチされていない場合は、 nullを返します。

BrowserWindow.fromId(id)

• id Integer

戻り値 BrowserWindow | null - 指定された id のウインドウ。

インスタンスプロパティ

new BrowserWindow で作成されたオブジェクトは、以下のプロパティを持っています。

const { BrowserWindow } = require('electron')
// この例では、 `win` がインスタンス
const win = new BrowserWindow({ width: 800, height: 600 })
win.loadURL('https://github.com')

win.webContents 読み出し専用

このウィンドウが所有する WebContents オブジェクト。 すべての Web ページ関連のイベントおよび操作は、これを介して行われます。

webContents ドキュメント でメソッドやイベントについて参照してください。

win.id 読み出し専用

Integer 型のプロパティです。そのウインドウの一意な ID を表します。 各 ID は、この Electron アプリケーション全体のすべての BrowserWindow インスタンス間で一意です。

win.tabbingIdentifier macOS 読み取り専用

string (任意) 型のプロパティで、BrowserWindow コンストラクタに渡された tabbingIdentifier と等しく、何も設定されていなければ undefined になります。

win.autoHideMenuBar

boolean 型のプロパティです。ウインドウがユーザーによって手動で最小化できるかどうかを決定します。 一度設定されると、メニューバーはユーザが単独で Alt キーを押したときのみに表示されます。

メニューバーが既に表示されている場合、このプロパティを true にセットしてもすぐに非表示にはなりません。

win.simpleFullScreen

boolean 型のプロパティです。ウインドウがシンプルな (Lion 以前の) フルスクリーンモードかどうかを決定します。

win.fullScreen

boolean 型のプロパティです。ウインドウがフルスクリーンモードかどうかを決定します。

win.focusable Windows macOS

boolean 型のプロパティです。ウインドウにフォーカスできるどうかを決定します。

win.visibleOnAllWorkspaces macOS Linux

boolean 型のプロパティです。ウインドウがすべてのワークスペースで表示されるどうかを決定します。

注: Windows の場合、常に false を返します。

win.shadow

boolean 型のプロパティです。ウインドウに影があるかどうかを決定します。

win.menuBarVisible Windows Linux

boolean 型のプロパティです。メニューバーが表示されるかどうかを決定します。

注: メニューバーが自動的に非表示にされている場合でも、ユーザが単に Alt キーを押下すれば、依然としてメニューバーを表示させることができます。

win.kiosk

boolean 型のプロパティです。ウインドウがキオスクモードかどうかを決定します。

win.documentEdited macOS

boolean 型のプロパティです。ウインドウのドキュメントが編集されたかどうかを決定します。

true にすると、タイトルバーのアイコンが灰色になります。

win.representedFilename macOS

string 型のプロパティです。ウインドウが表すファイルのパス名を決定し、そのファイルのアイコンをウインドウのタイトルバーに表示します。

win.title

string 型のプロパティです。ネイティブウインドウのタイトルを決定します。

注: ウェブページのタイトルとネイティブウインドウのタイトルは異なる可能性があります。

win.minimizable macOS Windows

boolean 型のプロパティです。ウインドウがユーザーによって手動で最小化できるかどうかを決定します。

Linux ではセッターは何もしませんが、ゲッターは true を返します。

win.maximizable macOS Windows

boolean 型のプロパティです。ウインドウがユーザーによって手動で最大化できるかどうかを決定します。

Linux ではセッターは何もしませんが、ゲッターは true を返します。

win.fullScreenable

boolean 型のプロパティです。ウインドウを最大化/ズームするウインドウボタンでフルスクリーンモードや最大化をトグル切り替えできるかどうかを決定します。

win.resizable

boolean 型のプロパティです。ウインドウがユーザーによって手動でサイズ変更できるかどうかを決定します。

win.closable macOS Windows

boolean 型のプロパティです。ウインドウがユーザーによって手動で閉じることができるかどうかを決定します。

Linux ではセッターは何もしませんが、ゲッターは true を返します。

win.movable macOS Windows

boolean 型のプロパティです。ウインドウがユーザーによって移動できるかどうかを決定します。

Linux ではセッターは何もしませんが、ゲッターは true を返します。

win.excludedFromShownWindowsMenu macOS

boolean 型のプロパティです。ウインドウをアプリケーションの Windows メニューから除外するかどうかを決定します。 省略値は false です。

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

const template = [
  {
    role: 'windowmenu'
  }
]

win.excludedFromShownWindowsMenu = true

const menu = Menu.buildFromTemplate(template)
Menu.setApplicationMenu(menu)

win.accessibleTitle

string 型のプロパティです。スクリーンリーダーなどのアクセシビリティツールにのみ提供される代替タイトルを定義します。 この文字列はユーザに直接表示されません。

インスタンスメソッド

new BrowserWindow で作成されたオブジェクトは、次のインスタンスメソッドを持っています。

注意: いくつかのメソッドは特定のオペレーティングシステムでのみ利用可能ですので、そのようなラベルを付けてあります。

win.destroy()

強制的にウインドウを閉じます。unload と beforeunload イベントはWebページで発生しません。また、close イベントもこのウインドウで発生しません。しかし、closed イベントが発生することは保証されます。

win.close()

ウインドウを閉じようとします。 これは、ユーザーが手動でウィンドウの閉じるボタンをクリックした場合と同じ効果があります。 ただし、 Web ページはウィンドウが閉じようとするのををキャンセルすることができます。 close イベント を参照してください。

win.focus()

ウインドウにフォーカスを当てます。

win.blur()

ウインドウからフォーカスを外します。

win.isFocused()

戻り値 boolean - ウインドウがフォーカスされているかどうか。

win.isDestroyed()

戻り値 boolean - ウインドウが破棄されているかどうか。

win.show()

表示し、ウインドウにフォーカスを当てます。

win.showInactive()

ウインドウを表示しますが、フォーカスを当てません。

win.hide()

ウインドウを非表示にします。

win.isVisible()

戻り値 boolean - アプリのフォアグラウンドでそのウインドウがユーザーに見えるかどうか。

win.isModal()

戻り値 boolean - 現在のウインドウがモーダルウインドウかどうか。

win.maximize()

ウィンドウを最大化します。 ウインドウがまだ表示されていない場合、併せてウインドウを表示 (ただし、フォーカスは当たりません) します。

win.unmaximize()

ウインドウの最大化を解除します。

win.isMaximized()

戻り値 boolean - ウインドウが最大化されているかどうか。

win.minimize()

ウィンドウを最小化します。 一部のプラットフォームでは、最小化されたウィンドウが Dock に表示されます。

win.restore()

ウインドウを最小化された状態からその前の状態に戻します。

win.isMinimized()

戻り値 boolean - ウインドウが最小化されているかどうか。

win.setFullScreen(flag)

• flag boolean

ウインドウをフルスクリーンモードにするかどうかを設定します。

注意: macOS では、フルスクリーンへの遷移は非同期で行われます。 さらなるアクションがフルスクリーン状態に依存する場合は、'enter-full-screen' や 'leave-full-screen' イベントをご使用ください。

win.isFullScreen()

戻り値 boolean - ウインドウがフルスクリーンモードであるかどうか。

注意: macOS では、フルスクリーンへの遷移は非同期で行われます。 BrowserWindow のフルスクリーン状態を確認するには、'enter-full-screen' または 'leave-full-screen' イベントのいずれかの発生を確かめる必要があります。

win.setSimpleFullScreen(flag) macOS

• flag boolean

簡易フルスクリーンモードに設定したり、解除したりします。

macOS Lion (10.7) より前のバージョンで見られる簡易フルスクリーンモードはネイティブのフルスクリーン動作をエミュレートします。

win.isSimpleFullScreen() macOS

戻り値 boolean - ウインドウが簡易 (Lion 以前の) フルスクリーンモードであるかどうか。

win.isNormal()

戻り値 boolean - ウインドウが通常の状態 (最大化されていない、最小化されていない、フルスクリーンモードでない) かどうか。

win.setAspectRatio(aspectRatio[, extraSize])

• aspectRatio Float - コンテンツビューの一部を維持するためのアスペクト比。
• extraSize Size (任意) macOS - アスペクト比を維持している間は含まれない余分のサイズ。

これはウインドウのアスペクト比を維持します。 ピクセルで指定した追加のサイズによって、開発者は、アスペクト比の計算に含まれないスペースを確保することができます。 このAPIはウインドウのサイズとそのコンテンツのサイズの差異も考慮しています。

HDビデオプレーヤーと関連したコントロールを持つ通常のウインドウを考えてみましょう。 ひょっとすると、左端に15ピクセルのコントロール、右端に25ピクセルのコントロール、プレーヤーの下部に50ピクセルのコントロールがあるかもしれません。 プレーヤー内で 16:9 アスペクト比 (HD @1920x1280 の標準的なアスペクト比) を維持するためには、この関数を 16/9 と { width: 40, height: 50 } の引数で呼び出します。 2番目の引数は、追加の幅と高さがコンテンツビューの中に収まるかを気にしません。それらはただ存在しているだけです。 全体のコンテンツビュー内にある余分な幅と高さの領域を単純に足し合わせます。

win.setSize などの API でプログラム上からウインドウをサイズ変更した場合、アスペクト比は維持されません。

アスペクト比をリセットするには、aspectRatio の値として 0 を渡します。つまり、win.setAspectRatio(0) です。

win.setBackgroundColor(backgroundColor)

• backgroundColor string - 16進数、RGB、RGBA、HSL、HSLA、または名前付き CSS カラーフォーマットの色。 16 進数タイプの場合のアルファチャンネルは任意です。

有効な backgroundColor の値の例を示します。

• Hex
  • #fff (略記 RGB)
  • #ffff (略記 ARGB)
  • #ffffff (RGB)
  • #ffffffff (ARGB)
• RGB
  • rgb\(([\d]+),\s*([\d]+),\s*([\d]+)\)
    • 例: rgb(255, 255, 255)
• RGBA
  • rgba\(([\d]+),\s*([\d]+),\s*([\d]+),\s*([\d.]+)\)
    • 例: rgba(255, 255, 255, 1.0)
• HSL
  • hsl\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%\)
    • 例: hsl(200, 20%, 50%)
• HSLA
  • hsla\((-?[\d.]+),\s*([\d.]+)%,\s*([\d.]+)%,\s*([\d.]+)\)
    • 例: hsla(200, 20%, 50%, 0.5)
• 色の名前
  • 選択肢は SkParseColor.cpp に列挙してあります。
  • CSS カラーモジュールレベル 3 のキーワードと似ていますが、大文字と小文字を区別します。
    • 例: blueviolet や red

ウィンドウの背景色を設定します。 backgroundColor の設定 もご覧ください。

win.previewFile(path[, displayName]) macOS

• path string - クイックルックでプレビューするファイルへの絶対パス。 ここで、Quick Lookはパスのファイル名とファイル拡張子をファイルを開くためのコンテンツタイプを決定するのに使用する点が重要です。
• displayName string (任意) - クイックルックのモーダルビューに表示するファイルの名前。 これは純粋に見た目だけのもので、ファイルのコンテンツタイプには影響しません。 省略値は、path です。

クイックルック を使用して、指定パスのファイルをプレビューします。

win.closeFilePreview() macOS

現在開いている クイックルック パネルを閉じます。

win.setBounds(bounds[, animate])

• bounds Partial<Rectangle>
• animate boolean (任意) macOS

指定した境界までウインドウのサイズを変更して移動します。 指定されていないプロパティは、既定で現在の値になります。

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

// bounds のプロパティをすべて設定
win.setBounds({ x: 440, y: 225, width: 800, height: 600 })

// bounds のプロパティをひとつ設定
win.setBounds({ width: 100 })

// { x: 440, y: 225, width: 100, height: 600 }
console.log(win.getBounds())

注意: macOS では、Y 座標の値が Tray の高さより小さくなることはありません。 Tray の高さは時期やオペレーティングシステムによって異なりますが、20 から 40px の間です。 Tray の高さより低い値を渡すと、Tray と同じ高さのウインドウになります。

win.getBounds()

戻り値 Rectangle - ウインドウの bounds が Object になったもの。

注意: macOS では、返される Y 座標の値は最小で Tray の高さになります。 例えば、トレイの高さを 38 にして win.setBounds({ x: 25, y: 20, width: 800, height: 600 }) を呼び出すと、win.getBounds() は { x: 25, y: 38, width: 800, height: 600 } を返します。

win.getBackgroundColor()

戻り値 string - ウインドウの背景色を 16 進数 (#RRGGBB) 形式で取得します。

backgroundColor の設定 もご覧ください。

注意: アルファの値は、赤、緑、青の値と共に返され ません。

win.setContentBounds(bounds[, animate])

• bounds Rectangle
• animate boolean (任意) macOS

指定した境界までウインドウのクライアント領域 (例えば、Webページ) のサイズを変更して移動します。

win.getContentBounds()

戻り値 Rectangle - ウインドウの内部領域の bounds が Object になったもの。

win.getNormalBounds()

戻り地 Rectangle - 通常状態のウインドウ境界を含んだ領域

注意: ウインドウの現在の状態、すなわち最大化、最小化、または全画面表示に関係なく、この関数は常に通常状態のウインドウの位置とサイズを返します。 通常状態においては、getBounds と getNormalBounds は同じ Rectangle を返します。

win.setEnabled(enable)

• enable boolean

ウインドウを無効にするか有効にします。

win.isEnabled()

戻り値 boolean - そのウインドウが有効かどうか。

win.setSize(width, height[, animate])

• width Integer
• height Integer
• animate boolean (任意) macOS

ウインドウのサイズを width と height に変更します。 width または height が最小サイズ制約の設定値より低い場合、ウィンドウはその最小サイズにスナップします。

win.getSize()

戻り値 Integer[] - ウインドウの幅と高さを含みます。

win.setContentSize(width, height[, animate])

• width Integer
• height Integer
• animate boolean (任意) macOS

ウインドウのクライアント領域 (例えば、Webページ) のサイズを width と height に変更します。

win.getContentSize()

戻り値 Integer[] - ウインドウのクライアント領域の幅と高さを含みます。

win.setMinimumSize(width, height)

• width Integer
• height Integer

ウインドウの最小サイズを width と height に設定します。

win.getMinimumSize()

戻り値 Integer[] - ウインドウの最小の幅と高さを含みます。

win.setMaximumSize(width, height)

• width Integer
• height Integer

ウインドウの最大サイズを width と height に設定します。

win.getMaximumSize()

戻り値 Integer[] - ウインドウの最大の幅と高さを含みます。

win.setResizable(resizable)

• resizable boolean

ウインドウがユーザによって手動でサイズ変更できるかどうかを設定します。

win.isResizable()

戻り値 boolean - ウインドウがユーザによって手動でサイズ変更できるかどうか。

win.setMovable(movable) macOS Windows

• movable boolean

ウインドウがユーザーによって手動で移動できるかどうかを設定します。 Linux では何もしません。

win.isMovable() macOS Windows

戻り値 boolean - ウインドウがユーザーによって移動できるかどうか。

Linuxでは常に true を返します。

win.setMinimizable(minimizable) macOS Windows

• minimizable boolean

ウインドウがユーザーによって手動で最小化できるかどうかを設定します。 Linux では何もしません。

win.isMinimizable() macOS Windows

戻り値 boolean - ウインドウがユーザによって手動で最小化できるかどうか。

Linuxでは常に true を返します。

win.setMaximizable(maximizable) macOS Windows

• maximizable boolean

ウインドウがユーザーによって手動で最大化できるかどうかを設定します。 Linux では何もしません。

win.isMaximizable() macOS Windows

戻り値 boolean - ウインドウがユーザーによって手動で最大化できるかどうか。

Linuxでは常に true を返します。

win.setFullScreenable(fullscreenable)

• fullscreenable boolean

ウインドウの最大化/ズームボタンでフルスクリーンモードに切り替えるか、ウインドウを最大化するかを設定します。

win.isFullScreenable()

戻り値 boolean - ウインドウの最大化/ズームボタンでフルスクリーンモードに切り替えるのか、それともウインドウを最大化するのか。

win.setClosable(closable) macOS Windows

• closable boolean

ウインドウがユーザーによって手動で閉じられるかどうかを設定します。 Linux では何もしません。

win.isClosable() macOS Windows

戻り値 boolean - ウインドウをユーザーが手動で閉じられるかどうか。

Linuxでは常に true を返します。

win.setHiddenInMissionControl(hidden) macOS

• hidden boolean

ユーザーが Mission Control に切り替えたときに、このウインドウを隠すかどうかを設定します。

win.isHiddenInMissionControl() macOS

戻り値 boolean - ユーザーが Mission Control に切り替えたときに、このウインドウを非表示にするかどうかです。

win.setAlwaysOnTop(flag[, level][, relativeLevel])

• flag boolean
• level string (任意) macOS Windows - 値は、normal、floating、torn-off-menu、modal-panel、main-menu、status、pop-up-menu、screen-saver と dock (非推奨) です。 flag が true の場合、省略値は floating です。 flag が false の場合、level は normal にリセットされます。 floating から status までに含まれているものにおいて、ウィンドウは macOS では Dock の下に、Windows ではタスクバーの下に配置されることをことに注意してください。 pop-up-menu 以降は、macOS では Dock の上に、Windows ではタスクバーの上に表示されます。 詳細については、macOS のドキュメント をご参照ください。
• relativeLevel Integer (任意) macOS - このウインドウを指定した level から相対的により高いレイヤーへ設定するための数です。 省略値は、0 です。 Apple社は、screen-saver より上に1以上のレベルを設定することを推奨していないことに注意してください。

ウィンドウを常に他のウィンドウの上に表示するかどうかを設定します。 この設定を行った後でも、ウィンドウはまだ通常のものであり、フォーカスが当てられないツールボックスウィンドウではありません。

win.isAlwaysOnTop()

戻り値 boolean - ウインドウが常に他のウインドウの上に表示されるかどうか。

win.moveAbove(mediaSourceId)

• mediaSourceId string - DesktopCapturerSource の ID の形式のウィンドウ ID。 例えば "window:1869:0" 。

Z オーダーの意味で、ウィンドウをソースウィンドウの上に移動します。 mediaSourceId がウィンドウの ID でないか、ウィンドウが存在しない場合、このメソッドはエラーをスローします。

win.moveTop()

フォーカスに関係なく上 (Z順序) にウィンドウを移動します。

win.center()

ウインドウを画面の中央に移動します。

win.setPosition(x, y[, animate])

• x Integer
• y Integer
• animate boolean (任意) macOS

ウインドウを x と y に移動します。

win.getPosition()

戻り値 Integer[] - ウインドウの現在の位置を含みます。

win.setTitle(title)

• title string

ネイティブのウインドウのタイトルを title に変更します。

win.getTitle()

戻り値 string - ネイティブウインドウのタイトル。

注: Web ページのタイトルはネイティブのウインドウのタイトルとは異なる可能性があります。

win.setSheetOffset(offsetY[, offsetX]) macOS

• offsetY Float
• offsetX Float (optional)

macOS においてシートを設置する位置を変更します。 既定では、シートはウィンドウフレームのすぐ下に設置されますが、 HTML で表示されたツールバーの下に表示することもできます。 以下がその例です。

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

const toolbarRect = document.getElementById('toolbar').getBoundingClientRect()
win.setSheetOffset(toolbarRect.height)

win.flashFrame(flag)

History

Version(s)	Changes
None	macOS で window.flashFrame(bool) が Dock のアイコンを持続的に点滅させるようになりました

• flag boolean

ユーザの注意を引きつけるためにウインドウの点滅を開始または停止します。

win.setSkipTaskbar(skip) macOS Windows

• skip boolean

ウインドウがタスクバーに表示されなくなります。

win.setKiosk(flag)

• flag boolean

キオスクモードに入ったり出たりします。

win.isKiosk()

戻り値 boolean - ウインドウがキオスクモードであるかどうか。

win.isTabletMode() Windows

戻り値 boolean - ウインドウが Windows 10 タブレットモードであるかどうか。

Windows 10 ユーザーは PC をタブレットとして使用できる ので、アプリはこのモードの際にタイトルバーを大きくしたり、タイトルバーのボタンを非表示にしたりと、タブレット用に UI を最適化できます。

この API は、ウインドウがタブレットモードかどうかを返します。resize イベントでタブレットモードへの変更をリッスンすることもできます。

win.getMediaSourceId()

戻り値 string - DesktopCapturerSource の ID の形式のウィンドウ ID。 例えば "window:1324:0" 。

より正確には、フォーマットは window:id:other_id です。ここでの id は、Windows では HWND、macOS では CGWindowID (uint64_t)、Linux では Window (unsigned long) です。 other_id は、同じトップレベルウィンドウ内のウェブコンテンツ (タブ) を識別するために使用されます。

win.getNativeWindowHandle()

戻り値 Buffer - ウインドウのプラットフォーム固有のハンドル。

ハンドルのネイティブな型は、Windowsでは HWND、macOSでは NSView*、Linuxでは Window (unsigned long) です。

win.hookWindowMessage(message, callback) Windows

• message Integer
• callback Function
  • wParam Buffer - WndProc に指定された wParam
  • lParam Buffer - WndProc に指定された lParam

ウィンドウメッセージをフックします。 メッセージが WndProc で受信されると、 callback が呼び出されます。

win.isWindowMessageHooked(message) Windows

• message Integer

戻り値 boolean - メッセージがフックされているかどうかによって、true または false 。

win.unhookWindowMessage(message) Windows

• message Integer

ウインドウメッセージのフックを解除します。

win.unhookAllWindowMessages() Windows

すべてのウインドウメッセージのフックを解除します。

win.setRepresentedFilename(filename) macOS

• filename string

ウインドウが表すファイルのパス名を設定します。ファイルのアイコンがウインドウのタイトルバーに表示されます。

win.getRepresentedFilename() macOS

戻り値 string - ウインドウが表すファイルのパス名。

win.setDocumentEdited(edited) macOS

• edited boolean

ウインドウのドキュメントが編集されたかどうかを指定します。true に設定すると、タイトルバーのアイコンがグレーになります。

win.isDocumentEdited() macOS

戻り値 boolean - ウインドウのドキュメントが編集されたかどうか。

win.focusOnWebView()

win.blurWebView()

win.capturePage([rect, opts])

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

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

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

win.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。

webContents.loadURL(url[, options]) と同じです。

url は、リモートアドレス (例えば、http://) または file:// プロトコルを使ってローカルのHTMLファイルのパスにすることができます。

ファイルのURLが正しく構成されているようにするため、Nodeの url.format メソッドを使用することを推奨します。

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

const url = require('url').format({
  protocol: 'file',
  slashes: true,
  pathname: require('node:path').join(__dirname, 'index.html')
})

win.loadURL(url)

次のようにすることによって、URLエンコードされたデータで POST リクエストを使用してURLをロードすることができます。

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

win.loadURL('http://localhost:8000/post', {
  postData: [{
    type: 'rawData',
    bytes: Buffer.from('hello=world')
  }],
  extraHeaders: 'Content-Type: application/x-www-form-urlencoded'
})

win.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。

webContents.loadFile と同じく、 filePath はアプリケーションのルートからの HTML ファイルへの相対パスである必要があります。 詳しくは、 webContents ドキュメントを参照してください。

win.reload()

webContents.reload と同じです。

win.setMenu(menu) Linux Windows

• menu Menu | null

menu をウインドウのメニューバーとして設定します。

win.removeMenu() Linux Windows

ウインドウのメニューバーを消去します。

win.setProgressBar(progress[, options])

• progress Double
• options Object (任意)
  • mode string Windows - プログレスバーのモード。 none 、 normal 、 indeterminate 、 error 、 paused のいずれかが使用できます。

プログレスバーの進捗を設定します。 有効な範囲は [0, 1.0] です。

進捗 < 0 の場合、プログレスバーは削除されます。進捗 > 1 の場合、不確定モードに変更します。

Linuxプラットフォームでは、Unityデスクトップ環境のみがサポートされ、package.json の desktopName フィールドに *.desktop ファイル名を指定する必要があります。 既定では、{app.name}.desktop であるとみなされます。

Windowsでは、モードを渡すことができます。 有効な値は、none、normal、indeterminate、error と paused です。 モードを設定せずに (ただし、有効範囲内の値で) setProgressBar を呼び出した場合、normal とみなされます。

win.setOverlayIcon(overlay, description) Windows

• overlay NativeImage | null - タスクバーアイコンの右下隅に表示されるアイコン。 この引数が null の場合、オーバーレイは消去されます。
• description string - アクセシビリティスクリーンリーダーに提供される説明

現在のタスクバーアイコンの上に、通常、何らかのアプリケーションステータスを伝えたり、ユーザーに控えめに通知したりするのに使われる16 x 16ピクセルのオーバレイを設定します。

win.invalidateShadow() macOS

ウインドウの影を現在のウインドウの形状に基づいて再計算するように更新します。

透明な BrowserWindows では、macOS で視覚的な残留物を残すことがあります。 このメソッドは、例えばアニメーションを実行するときにこれらの残留物を消去するときに利用できます。

win.setHasShadow(hasShadow)

• hasShadow boolean

ウインドウに影を付けるべきかどうかを設定します。

win.hasShadow()

戻り値 boolean - ウインドウに影を表示させているかどうか。

win.setOpacity(opacity) Windows macOS

• opacity number - 0.0 (完全に透明) と 1.0 (完全に不透明) の間

ウィンドウの不透明度を設定します。 Linux では何もしません。 範囲外の値は [0, 1] に収められます。

win.getOpacity()

戻り値 number - 0.0 (完全に透明) と 1.0 (完全に不透明) の間です。 Linuxでは常に 1 を返します。

win.setShape(rects) Windows Linux 実験的

• rects Rectangle[] - ウィンドウの形を設定します。 空のリストを渡すと、ウィンドウが四角形に戻ります。

ウィンドウの形を設定すると、システム内で描画とユーザ操作が許可されているウィンドウ内の領域が決まります。 与えられた領域の外側のピクセルでは描画されず、マウスイベントも登録されません。 領域外のマウスイベントはそのウィンドウでは受信されませんが、ウィンドウの後ろにあるものにそのイベントがフォールスルーします。

win.setThumbarButtons(buttons) Windows

• buttons ThumbarButton[]

戻り値 boolean - ボタンの追加に成功したかどうか

タスクバーボタンレイアウトのウインドウのサムネイルイメージに指定されたボタンのセットと一緒にサムネイルツールバーを追加します。 戻り値の boolean オブジェクトは、サムネイルの追加に成功したかどうかを示します。

限られた空間のため、サムネイルツールバーのボタン数は、7以下にしてください。 一度、サムネイルツールバーをセットアップすると、プラットフォームの制約のため、ツールバーを削除することはできません。 しかしながら、ボタンを取り除くためにAPIを空の配列で呼び出すことはできます。

buttons は、Button オブジェクトの配列です。

• Button Object
  • icon NativeImage - サムネイルツールバーで表示されるアイコン。
  • click Function
  • tooltip string (任意) - ボタンのツールチップのテキスト。
  • flags string[] (任意) - ボタンの特定の状態や動作を制御します。 省略値は、['enabled'] です。

flags は、以下の string を含めることができる配列です。

• enabled - ボタンはアクティブで、ユーザーが使用できます。
• disabled - そのボタンは無効化されます。 存在しますが、ユーザ操作に応答しないことを示す視覚的な状態です。
• dismissonclick - そのボタンをクリックすると、サムネイルウインドウがすぐに閉じます。
• nobackground - そのボタンの縁を描画しません。画像にのみ使用してください。
• hidden - そのボタンはユーザに表示されません。
• noninteractive - そのボタンは有効ですが、反応せず、押されたボタンの状態も描画されません。 この値は、例えば通知内で使用するボタンに使用されます。

win.setThumbnailClip(region) Windows

• region Rectangle - ウインドウの領域

タスクバーのウインドウの上でホバリングするときに表示されるサムネイルイメージとして表示するウインドウの領域を設定します。 空の領域: { x: 0, y: 0, width: 0, height: 0 } を指定することで、サムネイルをウインドウ全体にリセットすることができます。

win.setThumbnailToolTip(toolTip) Windows

• toolTip string

タスクバーのウインドウサムネイルでホバリングするときに表示されるツールチップを設定します。

win.setAppDetails(options) Windows

• options Object
  • appId string (任意) - ウインドウのアプリユーザーモデルID。 設定されないと、他のオプションは無効です。
  • appIconPath string (任意) - ウインドウの 再起動アイコン。
  • appIconIndex Integer (任意) - appIconPath でのアイコンのインデックス。 appIconPath が設定されていない場合は無視されます。 省略値は 0 です。
  • relaunchCommand string (任意) - ウインドウの 再起動コマンド。
  • relaunchDisplayName string (任意) - ウインドウの 再起動表示名。

ウインドウのタスクバーボタンのプロパティを設定します。

注: relaunchCommand と relaunchDisplayName は一緒に設定する必要があります。 いずれかが設定されていない場合、どちらも使用されません。

win.showDefinitionForSelection() macOS

webContents.showDefinitionForSelection() と同じです。

win.setIcon(icon) Windows Linux

• icon NativeImage | string

ウインドウのアイコンを変更します。

win.setWindowButtonVisibility(visible) macOS

• visible boolean

ウインドウの信号ボタンを表示するかどうかを設定します。

win.setAutoHideMenuBar(hide) Windows Linux

• hide boolean

ウィンドウのメニューバーを自動的に非表示にするかどうかを設定します。 一度設定されると、メニューバーはユーザが単独で Alt キーを押したときのみに表示されます。

メニューバーが既に表示されている場合、setAutoHideMenuBar(true) を呼び出してもすぐに非表示にはなりません。

win.isMenuBarAutoHide() Windows Linux

戻り値 boolean - メニューバーを自動的に非表示にするかどうか。

win.setMenuBarVisibility(visible) Windows Linux

• visible boolean

メニューバーを表示するかどうかを設定します。 メニューバーが自動的に非表示にされている場合でも、ユーザが単に Alt キーを押下すれば、依然としてメニューバーを表示させることができます。

win.isMenuBarVisible() Windows Linux

戻り値 boolean - メニューバーを表示しているかどうか。

win.setVisibleOnAllWorkspaces(visible[, options]) macOS Linux

• visible boolean
• options Object (任意)
  • visibleOnFullScreen boolean (任意) macOS - ウインドウをフルスクリーンウィンドウの上で表示するかどうかを設定します。
  • skipTransformProcessType boolean (任意) macOS - setVisibleOnAllWorkspaces を呼ぶと、デフォルトでは UIElementApplication と ForegroundApplication の間でプロセスタイプが変換され、正しい動作を保証します。 しかし、これでは呼び出されるたびに短時間だけウインドウが非表示になり、Dock も非表示になってしまいます。 ウインドウが既に UIElementApplication 型である場合、skipTransformProcessType に true を渡すことでこの変換をバイパスできます。

ウインドウをすべてのワークスペースで表示させるかどうかを設定します。

注: このAPIはWindowsでは何もしません。

win.isVisibleOnAllWorkspaces() macOS Linux

戻り値 boolean - ウインドウがすべてのワークスペースで表示されているかどうか。

注: このAPIはWindowsの場合、常にfalseを返します。

win.setIgnoreMouseEvents(ignore[, options])

• ignore boolean
• options Object (任意)
  • forward boolean (任意) macOS Windows - true の場合、マウスの移動メッセージが Chromium に転送され、mouseleave のようなマウス関連のイベントが有効になります。 ignore がtrueのときだけ使用されます。 ignore がfalseの場合、この値に関わらず、転送は常に無効です。

ウインドウがすべてのマウスイベントを無視するようにします。

このウインドウで発生するすべてのマウスイベントは、このウインドウの下にあるウインドウに渡されますが、このウインドウにフォーカスがある場合、依然としてキーボードイベントは受信されます。

win.setContentProtection(enable) macOS Windows

• enable boolean

他のアプリによってウインドウのコンテンツがキャプチャされるのを防止します。

macOS では、NSWindow の共有タイプを NSWindowSharingNone に設定します。 Windows では、 SetWindowDisplayAffinity を WDA_EXCLUDEFROMCAPTURE で呼び出します。 Windows 10 バージョン 2004 以降からウインドウのキャプチャが完全に削除されましたが、古い Windows バージョンで WDA_MONITOR が適用された場合は黒いウィンドウをキャプチャするように動作します。

win.setFocusable(focusable) macOS Windows

• focusable boolean

ウインドウにフォーカスできるかどうかを変更します。

macOS ではウィンドウからフォーカスは除去されません。

win.isFocusable() macOS Windows

戻り値 boolean - ウインドウにフォーカスできるかどうか。

win.setParentWindow(parent)

• parent BrowserWindow | null

現在のウインドウの親ウインドウとして parent を設定します。null を渡すと、現在のウインドウをトップレベルウインドウにします。

win.getParentWindow()

戻り値 BrowserWindow | null - 親ウインドウ、もしくは親が無ければ null です。

win.getChildWindows()

戻り値 BrowserWindow[] - すべての子ウインドウ。

win.setAutoHideCursor(autoHide) macOS

• autoHide boolean

タイプしているときにカーソルを非表示にするかどうかを制御します。

win.selectPreviousTab() macOS

ネイティブのタブが有効で、ウインドウに他のタブがあるとき、一つ前のタブを選択します。

win.selectNextTab() macOS

ネイティブのタブが有効で、ウインドウに他のタブがあるとき、次のタブを選択します。

win.showAllTabs() macOS

ネイティブのタブが有効な場合に、タブの概要を表示または非表示にします。

win.mergeAllWindows() macOS

ネイティブのタブが有効で複数の開いているウインドウがあるとき、すべてのウインドウを複数のタブで1つのウインドウにマージします。

win.moveTabToNewWindow() macOS

ネイティブのタブが有効で現在のウインドウに複数のタブがあるとき、現在のタブを新しいウインドウに移動します。

win.toggleTabBar() macOS

ネイティブのタブが有効で現在のウインドウにタブが1つだけしかないとき、タブバーを表示するかどうかを切り替えます。

win.addTabbedWindow(browserWindow) macOS

• browserWindow BrowserWindow

ウインドウインスタンスのタブの後ろに、このウインドウのタブとしてウインドウを追加します。

win.setVibrancy(type) macOS

• type string | null - titlebar, selection, menu, popover, sidebar, header, sheet, window, hud, fullscreen-ui, tooltip, content, under-window, under-page のいずれかにできます。 詳細は macOSのドキュメント をご参照ください。

ブラウザウィンドウにバイブレンシーエフェクトを追加します。 null または空の文字列を渡すと、ウィンドウのバイブレンシーエフェクトを削除します。

win.setBackgroundMaterial(material) Windows

• material string
  • auto - デスクトップウインドウマネージャ (DWM) に、このウインドウのシステム描画の背景マテリアルを自動決定させます。 これが既定値です。
  • none - システムの背景を描画しません。
  • mica - 長い間表示されるウインドウに対応する背景マテリアルの効果を描画します。
  • acrylic - 一時的なウインドウに対応する背景マテリアルの効果を描画します。
  • tabbed - タブ化したタイトルバー付きのウインドウに対応する背景マテリアルの効果を描画します。

このメソッドは、非クライアント領域の背後を含む、ブラウザウインドウのシステム描画の背景マテリアルを設定します。

詳細は Windows のドキュメント をご参照ください。

注意: このメソッドは Windows 11 22H2 以降でのみサポートされています。

win.setWindowButtonPosition(position) macOS

• position Point | null

フレームレスウインドウにおける信号機ボタンのカスタム位置を設定します。 null を渡すと既定の位置へリセットします。

win.getWindowButtonPosition() macOS

戻り値 Point | null - フレームレスウインドウの信号機ボタンのカスタム位置。カスタム位置がない場合は null が返されます。

win.setTouchBar(touchBar) macOS

• touchBar TouchBar | null

現在のウインドウのTouchBarレイアウトを設定します。 null または undefined を指定すると、TouchBarがクリアされます。 このメソッドは TouchBar 搭載マシンでのみ作用します。

Note: TouchBar API は現在実験的な機能です。そのため、将来的には変更されたり削除されたりする可能性があります。

win.setBrowserView(browserView) 実験的 非推奨

• browserView BrowserView | null - browserView を win へアタッチします。 他の BrowserView がアタッチされている場合、それはこのウィンドウから削除されます。

注意 BrowserView クラスは非推奨であり、新しい WebContentsView クラスに置き換えられています。

win.getBrowserView() 実験的 非推奨

戻り値 BrowserView | null - win にアタッチされた BrowserView。 アタッチされていない場合は null を返します。 複数の BrowserView がアタッチされている場合、エラーを送出します。

注意 BrowserView クラスは非推奨であり、新しい WebContentsView クラスに置き換えられています。

win.addBrowserView(browserView) 実験的 非推奨

• browserView BrowserView

複数の BrowserView をサポートする setBrowserView の置換 API。

注意 BrowserView クラスは非推奨であり、新しい WebContentsView クラスに置き換えられています。

win.removeBrowserView(browserView) 実験的 非推奨

• browserView BrowserView

注意 BrowserView クラスは非推奨であり、新しい WebContentsView クラスに置き換えられています。

win.setTopBrowserView(browserView) 実験的 非推奨

• browserView BrowserView

browserView を win にアタッチされた他の BrowserView の上へと持ち上げます。 browserView が win にアタッチされていない場合, エラーを送出します。

注意 BrowserView クラスは非推奨であり、新しい WebContentsView クラスに置き換えられています。

win.getBrowserViews() 実験的 非推奨

戻り値 BrowserView[] - addBrowserView または setBrowserView でアタッチされ、z-index でソートされたたすべての BrowserView の配列。 最も上にある BrowserView は配列の最後の要素です。

注意 BrowserView クラスは非推奨であり、新しい WebContentsView クラスに置き換えられています。

win.setTitleBarOverlay(options) Windows Linux

• options Object
  • color String (任意) - 有効化されたウインドウコントロールオーバーレイの CSS カラー。
  • symbolColor String (任意) - 有効化されたウインドウコントロールオーバーレイ内の記号の CSS カラー。
  • height Integer (任意) - ピクセル単位のタイトルバーとウインドウコントロールオーバーレイの高さ。

ウインドウコントロールオーバーレイがすでに有効になっているウインドウに対して、このメソッドはそのタイトルバーオーバーレイのスタイルを更新します。

Linux で color を明示的に設定していない場合、symbolColor は color に対して最小限のアクセシビリティがあるコントラストになるように自動計算されます。