BaseWindow
Create and control windows.
Process: Main
Note
BaseWindow
provides a flexible way to compose multiple web views in a
single window. For windows with only a single, full-size web view, the
BrowserWindow
class may be a simpler option.
This module cannot be used until the ready
event of the app
module is emitted.
const { BaseWindow, WebContentsView } = require('electron')
const win = new BaseWindow({ width: 800, height: 600 })
const leftView = new WebContentsView()
leftView.webContents.loadURL('https://electronjs.org')
win.contentView.addChildView(leftView)
const rightView = new WebContentsView()
rightView.webContents.loadURL('https://github.com/electron/electron')
win.contentView.addChildView(rightView)
leftView.setBounds({ x: 0, y: 0, width: 400, height: 600 })
rightView.setBounds({ x: 400, y: 0, width: 400, height: 600 })
親ウィンドウと子ウィンドウ
By using parent
option, you can create child windows:
const { BaseWindow } = require('electron')
const parent = new BaseWindow()
const child = new BaseWindow({ parent })
The child
window will always show on top of the parent
window.
モーダルウィンドウ
A modal window is a child window that disables parent window. To create a modal
window, you have to set both the parent
and modal
options:
const { BaseWindow } = require('electron')
const parent = new BaseWindow()
const child = new BaseWindow({ parent, modal: true })
プラットフォームに関する注意事項
- macOSでは、モーダルウインドウは親ウインドウに付随したシートとして表示されます。
- On macOS the child windows will keep the relative position to parent window
when parent window moves, while on Windows and Linux child windows will not
move.
- On Linux the type of modal windows will be changed to
dialog
.
- Linuxでは、多くのデスクトップ環境は、モーダルウインドウを非表示にすることをサポートしていません。
Class: BaseWindow
Create and control windows.
Process: Main
BaseWindow
is an EventEmitter.
It creates a new BaseWindow
with native properties as set by the options
.
new BaseWindow([options])
options
BaseWindowConstructorOptions (optional)
width
Integer (optional) - Window's width in pixels. Default is 800
.
height
Integer (optional) - Window's height in pixels. Default is 600
.
x
Integer (optional) - (required if y is used) Window's left offset from screen.
省略すると、ウインドウは中央に配置されます。
y
Integer (optional) - (required if x is used) Window's top offset from screen.
省略すると、ウインドウは中央に配置されます。
useContentSize
boolean (optional) - The width
and height
would be used as web
page's size, which means the actual window's size will include window
frame's size and be slightly larger. Default is false
.
center
boolean (optional) - Show window in the center of the screen. Default is false
.
minWidth
Integer (optional) - Window's minimum width. Default is 0
.
minHeight
Integer (optional) - Window's minimum height. Default is 0
.
maxWidth
Integer (optional) - Window's maximum width. 省略すると無制限です。
maxHeight
Integer (optional) - Window's maximum height. 省略すると無制限です。
resizable
boolean (optional) - Whether window is resizable. Default is true
.
movable
boolean (optional) macOS Windows - Whether window is
movable. これは Linux では実装されていません。 Default is true
.
minimizable
boolean (optional) macOS Windows - Whether window is
minimizable. これは Linux では実装されていません。 Default is true
.
maximizable
boolean (optional) macOS Windows - Whether window is
maximizable. これは Linux では実装されていません。 Default is true
.
closable
boolean (optional) macOS Windows - Whether window is
closable. これは Linux では実装されていません。 Default is true
.
focusable
boolean (optional) - Whether the window can be focused. Default is
true
. On Windows setting focusable: false
also implies setting
skipTaskbar: true
. On Linux setting focusable: false
makes the window
stop interacting with wm, so the window will always stay on top in all
workspaces.
alwaysOnTop
boolean (optional) - Whether the window should always stay on top of
other windows. Default is false
.
fullscreen
boolean (optional) - Whether the window should show in fullscreen. When
explicitly set to false
the fullscreen button will be hidden or disabled
on macOS. Default is false
.
fullscreenable
boolean (optional) - Whether the window can be put into fullscreen
mode. On macOS, also whether the maximize/zoom button should toggle full
screen mode or maximize window. Default is true
.
simpleFullscreen
boolean (optional) macOS - Use pre-Lion fullscreen on
macOS. Default is false
.
skipTaskbar
boolean (optional) macOS Windows - Whether to show the window in taskbar.
Default is false
.
hiddenInMissionControl
boolean (optional) macOS - Whether window should be hidden when the user toggles into mission control.
kiosk
boolean (optional) - Whether the window is in kiosk mode. Default is false
.
title
string (optional) - Default window title. Default is "Electron"
. If the HTML tag <title>
is defined in the HTML file loaded by loadURL()
, this property will be ignored.
icon
(NativeImage | string) (optional) - The window icon. On Windows it is
recommended to use ICO
icons to get best visual effects, you can also
leave it undefined so the executable's icon will be used.
show
boolean (optional) - Whether window should be shown when created. Default is
true
.
frame
boolean (optional) - Specify false
to create a
frameless window. Default is true
.
parent
BaseWindow (optional) - Specify parent window. Default is null
.
modal
boolean (optional) - Whether this is a modal window. This only works when the
window is a child window. Default is false
.
acceptFirstMouse
boolean (optional) macOS - Whether clicking an
inactive window will also click through to the web contents. Default is
false
on macOS. このオプションは他プラットフォームでは設定できません。
disableAutoHideCursor
boolean (optional) - Whether to hide cursor when typing.
Default is false
.
autoHideMenuBar
boolean (optional) - Auto hide the menu bar unless the Alt
key is pressed. Default is false
.
enableLargerThanScreen
boolean (optional) macOS - Enable the window to
be resized larger than screen. Only relevant for macOS, as other OSes
allow larger-than-screen windows by default. Default is false
.
backgroundColor
string (optional) - The window's background color in Hex, RGB, RGBA, HSL, HSLA or named CSS color format. Alpha in #AARRGGBB format is supported if transparent
is set to true
. Default is #FFF
(white). See win.setBackgroundColor for more information.
hasShadow
boolean (optional) - Whether window should have a shadow. Default is true
.
opacity
number (optional) macOS Windows - Set the initial opacity of
the window, between 0.0 (fully transparent) and 1.0 (fully opaque). This
is only implemented on Windows and macOS.
darkTheme
boolean (optional) - Forces using dark theme for the window, only works on
some GTK+3 desktop environments. Default is false
.
transparent
boolean (optional) - Makes the window transparent.
Default is false
. Windows では、ウィンドウがフレームレスでない限り機能しません。
type
string (optional) - The type of window, default is normal window. See more about
this below.
visualEffectState
string (optional) macOS - Specify how the material
appearance should reflect window activity state on macOS. Must be used
with the vibrancy
property. 以下は取りうる値です。
followWindow
- The backdrop should automatically appear active when the window is active, and inactive when it is not. これが既定値です。
active
- The backdrop should always appear active.
inactive
- The backdrop should always appear inactive.
titleBarStyle
string (optional) - The style of window title bar.
Default is default
. 以下は取りうる値です。
default
- Results in the standard title bar for macOS or Windows respectively.
hidden
- Results in a hidden title bar and a full size content window. macOS では、ウインドウの左上に標準ウインドウコントロール ("信号機ボタン") が付きます。 On Windows and Linux, when combined with titleBarOverlay: true
it will activate the Window Controls Overlay (see titleBarOverlay
for more information), otherwise no window controls will be shown.
hiddenInset
macOS - Results in a hidden title bar
with an alternative look where the traffic light buttons are slightly
more inset from the window edge.
customButtonsOnHover
macOS - Results in a hidden
title bar and a full size content window, the traffic light buttons will
display when being hovered over in the top left of the window.
Note: This option is currently experimental.
trafficLightPosition
Point (optional) macOS -
Set a custom position for the traffic light buttons in frameless windows.
roundedCorners
boolean (optional) macOS - Whether frameless window
should have rounded corners on macOS. Default is true
. Setting this property
to false
will prevent the window from being fullscreenable.
thickFrame
boolean (optional) - Use WS_THICKFRAME
style for frameless windows on
Windows, which adds standard window frame. Setting it to false
will remove
window shadow and window animations. Default is true
.
vibrancy
string (optional) macOS - Add a type of vibrancy effect to
the window, only on macOS. Can be appearance-based
, titlebar
, selection
,
menu
, popover
, sidebar
, header
, sheet
, window
, hud
, fullscreen-ui
,
tooltip
, content
, under-window
, or under-page
.
backgroundMaterial
string (optional) Windows - Set the window's
system-drawn background material, including behind the non-client area.
Can be auto
, none
, mica
, acrylic
or tabbed
. See win.setBackgroundMaterial for more information.
zoomToPageWidth
boolean (optional) macOS - Controls the behavior on
macOS when option-clicking the green stoplight button on the toolbar or by
clicking the Window > Zoom menu item. If true
, the window will grow to
the preferred width of the web page when zoomed, false
will cause it to
zoom to the width of the screen. This will also affect the behavior when
calling maximize()
directly. Default is false
.
tabbingIdentifier
string (optional) macOS - Tab group name, allows
opening the window as a native tab. Windows with the same
tabbing identifier will be grouped together. This also adds a native new
tab button to your window's tab bar and allows your app
and window to
receive the new-window-for-tab
event.
When setting minimum or maximum window size with minWidth
/maxWidth
/
minHeight
/maxHeight
, it only constrains the users. It won't prevent you from
passing a size that does not follow size constraints to setBounds
/setSize
or
to the constructor of BrowserWindow
.
The possible values and behaviors of the type
option are platform dependent.
以下は取りうる値です。
- On Linux, possible types are
desktop
, dock
, toolbar
, splash
,
notification
.
- The
desktop
type places the window at the desktop background window level
(kCGDesktopWindowLevel - 1). However, note that a desktop window will not
receive focus, keyboard, or mouse events. You can still use globalShortcut to
receive input sparingly.
- The
dock
type creates a dock-like window behavior.
- The
toolbar
type creates a window with a toolbar appearance.
- The
splash
type behaves in a specific way. It is not
draggable, even if the CSS styling of the window's body contains
-webkit-app-region: drag. このタイプは主にスプラッシュスクリーンで使用されます。
- The
notification
type creates a window that behaves like a system notification.
- On macOS, possible types are
desktop
, textured
, panel
.
- The
textured
type adds metal gradient appearance
(NSWindowStyleMaskTexturedBackground
).
- The
desktop
type places the window at the desktop background window level
(kCGDesktopWindowLevel - 1
). Note that desktop window will not receive
focus, keyboard or mouse events, but you can use globalShortcut
to receive
input sparingly.
- The
panel
type enables the window to float on top of full-screened apps
by adding the NSWindowStyleMaskNonactivatingPanel
style mask,normally
reserved for NSPanel, at runtime. Also, the window will appear on all
spaces (desktops).
- On Windows, possible type is
toolbar
.
インスタンスイベント
Objects created with new BaseWindow
emit the following events:
Note: Some events are only available on specific operating systems and are
labeled as such.
イベント: 'close'
戻り値:
ウインドウがクローズされようとすると きに発生します。 It's emitted before the
beforeunload
and unload
event of the DOM. Calling event.preventDefault()
will cancel the close.
Usually you would want to use the beforeunload
handler to decide whether the
window should be closed, which will also be called when the window is
reloaded. In Electron, returning any value other than undefined
would cancel the
close. 以下がその例です。
window.onbeforeunload = (e) => {
console.log('I do not want to be closed')
e.returnValue = false
}
Note: There is a subtle difference between the behaviors of window.onbeforeunload = handler
and window.addEventListener('beforeunload', handler)
. It is recommended to always set the event.returnValue
explicitly, instead of only returning a value, as the former works more consistently within Electron.
イベント: 'closed'
ウインドウが閉じられたときに発生します。 このイベントを受け取った後は、ウインドウへの参照を削除し、以降そのウインドウを使用しないようにしてください。
Event: 'session-end' Windows
強制的なシャットダウン、マシン再起動またはセッションのログオフによってウインドウセッションが終了されようとしたときに発生します。
イベント: 'blur'
ウインドウがフォーカスを失うときに発生します。
イベント: 'focus'
ウインドウがフォーカスを得るときに発生します。
イベント: 'show'
ウインドウが表示されるときに発生します。
イベント: 'hide'
ウインドウが非表示になるときに発生します。
イベント: 'maximize'
ウィンドウが最大化されるときに発生します。
イベント: 'unmaximize'
ウインドウが最大化状態から抜けるときに発生します。
イベント: 'minimize'
ウィンドウが最小化されるときに発生します。
イベント: 'restore'
ウインドウが最小化状態から復元されたときに発生します。
Event: 'will-resize' macOS Windows
戻り値:
event
Event
newBounds
Rectangle - Size the window is being resized to.
details
Object
edge
(string) - The edge of the window being dragged for resizing. Can be bottom
, left
, right
, top-left
, top-right
, bottom-left
or bottom-right
.
ウィンドウがリサイズされる前に発生します。 Calling event.preventDefault()
will prevent the window from being resized.
このイベントは、ウィンドウが手動でリサイズされようとしているときにしか発生しません。 Resizing the window with setBounds
/setSize
will not emit this event.
The possible values and behaviors of the edge
option are platform dependent. 以下は取りうる値です。
- On Windows, possible values are
bottom
, top
, left
, right
, top-left
, top-right
, bottom-left
, bottom-right
.
- On macOS, possible values are
bottom
and right
.
- The value
bottom
is used to denote vertical resizing.
- The value
right
is used to denote horizontal resizing.
イベント: 'resize'
ウインドウがリサイズされた後に発生します。
Event: 'resized' macOS Windows
ウインドウがリサイズされるときに一度発生します。
これは、通常、ウィンドウが手動でリサ イズされようとしているときにしか発生しません。 On macOS, resizing the window with setBounds
/setSize
and setting the animate
parameter to true
will also emit this event once resizing has finished.
Event: 'will-move' macOS Windows
戻り値:
event
Event
newBounds
Rectangle - Location the window is being moved to.
ウィンドウが移動される前に発生します。 On Windows, calling event.preventDefault()
will prevent the window from being moved.
このイベントは、ウィンドウが手動で移動されようとしているときにしか発生しません。 Moving the window with setPosition
/setBounds
/center
will not emit this event.
イベント: 'move'
ウインドウが新しい位置に移動されているときに発生します。
Event: 'moved' macOS Windows