зеркало из https://github.com/electron/electron.git
docs: add custom titlebar example (#43693)
* docs: add custom titlebar example * docs: add links and other small edits * docs: add panel window docs * docs: remove panel example * docs: specify expected emphasis style * docs: responding to feedback * docs: fix section names in links * docs: rework baseWindow note * docs: making window customization its own section * responding to feedback
This commit is contained in:
Anny Yang
GitHub
Родитель
15151c6853
Коммит
2081f771e4
|
|
@ -5,6 +5,9 @@
|
|||
"autolink": false,
|
||||
"shortcut": false
|
||||
},
|
||||
"MD049": {
|
||||
"style": "underscore"
|
||||
},
|
||||
"no-angle-brackets": true,
|
||||
"no-curly-braces": true,
|
||||
"no-inline-html": {
|
||||
|
|
|
|||
|
|
@ -49,7 +49,7 @@
|
|||
* `show` boolean (optional) - Whether window should be shown when created. Default is
|
||||
`true`.
|
||||
* `frame` boolean (optional) - Specify `false` to create a
|
||||
[frameless window](../../tutorial/window-customization.md#create-frameless-windows). Default is `true`.
|
||||
[frameless window](../../tutorial/custom-window-styles.md#frameless-windows). 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`.
|
||||
|
|
@ -70,7 +70,7 @@
|
|||
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](../../tutorial/window-customization.md#create-transparent-windows).
|
||||
* `transparent` boolean (optional) - Makes the window [transparent](../../tutorial/custom-window-styles.md#transparent-windows).
|
||||
Default is `false`. On Windows, does not work unless the window is frameless.
|
||||
* `type` string (optional) - The type of window, default is normal window. See more about
|
||||
this below.
|
||||
|
|
|
|||
|
|
@ -0,0 +1,14 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
|
||||
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'">
|
||||
<link href="./styles.css" rel="stylesheet">
|
||||
<title>Custom Titlebar App</title>
|
||||
</head>
|
||||
<body>
|
||||
<!-- mount your title bar at the top of you application's body tag -->
|
||||
<div class="titlebar">Cool titlebar</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
const { app, BrowserWindow } = require('electron')
|
||||
|
||||
function createWindow () {
|
||||
const win = new BrowserWindow({
|
||||
// remove the default titlebar
|
||||
titleBarStyle: 'hidden',
|
||||
// expose window controlls in Windows/Linux
|
||||
...(process.platform !== 'darwin' ? { titleBarOverlay: true } : {})
|
||||
})
|
||||
|
||||
win.loadFile('index.html')
|
||||
}
|
||||
|
||||
app.whenReady().then(() => {
|
||||
createWindow()
|
||||
})
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
body {
|
||||
margin: 0;
|
||||
}
|
||||
.titlebar {
|
||||
height: 30px;
|
||||
background: blue;
|
||||
color: white;
|
||||
display: flex;
|
||||
justify-content: center;
|
||||
align-items: center;
|
||||
app-region: drag;
|
||||
}
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
|
||||
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'">
|
||||
<link href="./styles.css" rel="stylesheet">
|
||||
<title>Custom Titlebar App</title>
|
||||
</head>
|
||||
<body>
|
||||
<!-- mount your title bar at the top of you application's body tag -->
|
||||
<div class="titlebar">Cool titlebar</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
const { app, BrowserWindow } = require('electron')
|
||||
|
||||
function createWindow () {
|
||||
const win = new BrowserWindow({
|
||||
// remove the default titlebar
|
||||
titleBarStyle: 'hidden',
|
||||
// expose window controlls in Windows/Linux
|
||||
...(process.platform !== 'darwin' ? { titleBarOverlay: true } : {})
|
||||
})
|
||||
|
||||
win.loadFile('index.html')
|
||||
}
|
||||
|
||||
app.whenReady().then(() => {
|
||||
createWindow()
|
||||
})
|
||||
|
|
@ -0,0 +1,12 @@
|
|||
body {
|
||||
margin: 0;
|
||||
}
|
||||
|
||||
.titlebar {
|
||||
height: 30px;
|
||||
background: blue;
|
||||
color: white;
|
||||
display: flex;
|
||||
justify-content: center;
|
||||
align-items: center;
|
||||
}
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
const { app, BrowserWindow } = require('electron')
|
||||
|
||||
function createWindow () {
|
||||
const win = new BrowserWindow({
|
||||
// remove the default titlebar
|
||||
titleBarStyle: 'hidden',
|
||||
// expose window controlls in Windows/Linux
|
||||
...(process.platform !== 'darwin' ? { titleBarOverlay: true } : {})
|
||||
})
|
||||
win.loadURL('https://example.com')
|
||||
}
|
||||
|
||||
app.whenReady().then(() => {
|
||||
createWindow()
|
||||
})
|
||||
|
|
@ -0,0 +1,13 @@
|
|||
const { app, BrowserWindow } = require('electron')
|
||||
|
||||
function createWindow () {
|
||||
const win = new BrowserWindow({
|
||||
// remove the default titlebar
|
||||
titleBarStyle: 'hidden'
|
||||
})
|
||||
win.loadURL('https://example.com')
|
||||
}
|
||||
|
||||
app.whenReady().then(() => {
|
||||
createWindow()
|
||||
})
|
||||
|
|
@ -0,0 +1,10 @@
|
|||
const { app, BrowserWindow } = require('electron')
|
||||
|
||||
function createWindow () {
|
||||
const win = new BrowserWindow({})
|
||||
win.loadURL('https://example.com')
|
||||
}
|
||||
|
||||
app.whenReady().then(() => {
|
||||
createWindow()
|
||||
})
|
||||
|
|
@ -0,0 +1,14 @@
|
|||
const { app, BrowserWindow } = require('electron')
|
||||
|
||||
function createWindow () {
|
||||
const win = new BrowserWindow({
|
||||
width: 300,
|
||||
height: 200,
|
||||
frame: false
|
||||
})
|
||||
win.loadURL('https://example.com')
|
||||
}
|
||||
|
||||
app.whenReady().then(() => {
|
||||
createWindow()
|
||||
})
|
||||
|
|
@ -0,0 +1,15 @@
|
|||
<!DOCTYPE html>
|
||||
<html>
|
||||
<head>
|
||||
<meta charset="UTF-8">
|
||||
<!-- https://developer.mozilla.org/en-US/docs/Web/HTTP/CSP -->
|
||||
<meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self' 'unsafe-inline'">
|
||||
<link href="./styles.css" rel="stylesheet">
|
||||
<title>Transparent Hello World</title>
|
||||
</head>
|
||||
<body>
|
||||
<div class="white-circle">
|
||||
<div>Hello World!</div>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
const { app, BrowserWindow } = require('electron')
|
||||
|
||||
function createWindow () {
|
||||
const win = new BrowserWindow({
|
||||
width: 100,
|
||||
height: 100,
|
||||
resizable: false,
|
||||
frame: false,
|
||||
transparent: true
|
||||
})
|
||||
win.loadFile('index.html')
|
||||
}
|
||||
|
||||
app.whenReady().then(() => {
|
||||
createWindow()
|
||||
})
|
||||
|
|
@ -0,0 +1,16 @@
|
|||
body {
|
||||
margin: 0;
|
||||
padding: 0;
|
||||
background-color: rgba(0, 0, 0, 0); /* Transparent background */
|
||||
}
|
||||
.white-circle {
|
||||
width: 100px;
|
||||
height: 100px;
|
||||
background-color: white;
|
||||
border-radius: 50%;
|
||||
display: flex;
|
||||
align-items: center;
|
||||
justify-content: center;
|
||||
app-region: drag;
|
||||
user-select: none;
|
||||
}
|
||||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 412 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 215 KiB |
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 98 KiB |
|
|
@ -0,0 +1,176 @@
|
|||
# Custom Title Bar
|
||||
|
||||
## Basic tutorial
|
||||
|
||||
Application windows have a default [chrome][] applied by the OS. Not to be confused
|
||||
with the Google Chrome browser, window _chrome_ refers to the parts of the window (e.g.
|
||||
title bar, toolbars, controls) that are not a part of the main web content. While the
|
||||
default title bar provided by the OS chrome is sufficent for simple use cases, many
|
||||
applications opt to remove it. Implementing a custom title bar can help your application
|
||||
feel more modern and consistent across platforms.
|
||||
|
||||
You can follow along with this tutorial by opening Fiddle with the following starter code.
|
||||
|
||||
```fiddle docs/fiddles/features/window-customization/custom-title-bar/starter-code
|
||||
|
||||
```
|
||||
|
||||
### Remove the default title bar
|
||||
|
||||
Let’s start by configuring a window with native window controls and a hidden title bar.
|
||||
To remove the default title bar, set the [`BaseWindowContructorOptions`][] `titleBarStyle`
|
||||
param in the `BrowserWindow` constructor to `'hidden'`.
|
||||
|
||||
```fiddle docs/fiddles/features/window-customization/custom-title-bar/remove-title-bar
|
||||
|
||||
```
|
||||
|
||||
### Add native window controls _Windows_ _Linux_
|
||||
|
||||
On macOS, setting `titleBarStyle: 'hidden'` removes the title bar while keeping the window’s
|
||||
traffic light controls available in the upper left hand corner. However on Windows and Linux,
|
||||
you’ll need to add window controls back into your `BrowserWindow` by setting the
|
||||
[`BaseWindowContructorOptions`][] `titleBarOverlay` param in the `BrowserWindow` constructor.
|
||||
|
||||
```fiddle docs/fiddles/features/window-customization/custom-title-bar/native-window-controls
|
||||
|
||||
```
|
||||
|
||||
Setting `titleBarOverlay: true` is the simplest way to expose window controls back into
|
||||
your `BrowserWindow`. If you’re interested in customizing the window controls further,
|
||||
check out the sections [Custom traffic lights][] and [Custom window controls][] that cover
|
||||
this in more detail.
|
||||
|
||||
### Create a custom title bar
|
||||
|
||||
Now, let’s implement a simple custom title bar in the `webContents` of our `BrowserWindow`.
|
||||
There’s nothing fancy here, just HTML and CSS!
|
||||
|
||||
```fiddle docs/fiddles/features/window-customization/custom-title-bar/custom-title-bar
|
||||
|
||||
```
|
||||
|
||||
Currently our application window can’t be moved. Since we’ve removed the default title bar,
|
||||
the application needs to tell Electron which regions are draggable. We’ll do this by adding
|
||||
the CSS style `app-region: drag` to the custom title bar. Now we can drag the custom title
|
||||
bar to reposition our app window!
|
||||
|
||||
```fiddle docs/fiddles/features/window-customization/custom-title-bar/custom-drag-region
|
||||
|
||||
```
|
||||
|
||||
For more information around how to manage drag regions defined by your electron application,
|
||||
see the [Custom draggable regions][] section below.
|
||||
|
||||
Congratulations, you've just implemented a basic custom title bar!
|
||||
|
||||
## Advanced window customization
|
||||
|
||||
### Custom traffic lights _macOS_
|
||||
|
||||
#### Customize the look of your traffic lights _macOS_
|
||||
|
||||
The `customButtonsOnHover` title bar style will hide the traffic lights until you hover
|
||||
over them. This is useful if you want to create custom traffic lights in your HTML but still
|
||||
use the native UI to control the window.
|
||||
|
||||
```js
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover' })
|
||||
```
|
||||
|
||||
#### Customize the traffic light position _macOS_
|
||||
|
||||
To modify the position of the traffic light window controls, there are two configuration
|
||||
options available.
|
||||
|
||||
Applying `hiddenInset` title bar style will shift the vertical inset of the traffic lights
|
||||
by a fixed amount.
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })
|
||||
```
|
||||
|
||||
If you need more granular control over the positioning of the traffic lights, you can pass
|
||||
a set of coordinates to the `trafficLightPosition` option in the `BrowserWindow`
|
||||
constructor.
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({
|
||||
titleBarStyle: 'hidden',
|
||||
trafficLightPosition: { x: 10, y: 10 }
|
||||
})
|
||||
```
|
||||
|
||||
#### Show and hide the traffic lights programmatically _macOS_
|
||||
|
||||
You can also show and hide the traffic lights programmatically from the main process.
|
||||
The `win.setWindowButtonVisibility` forces traffic lights to be show or hidden depending
|
||||
on the value of its boolean parameter.
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow()
|
||||
// hides the traffic lights
|
||||
win.setWindowButtonVisibility(false)
|
||||
```
|
||||
|
||||
:::note
|
||||
Given the number of APIs available, there are many ways of achieving this. For instance,
|
||||
combining `frame: false` with `win.setWindowButtonVisibility(true)` will yield the same
|
||||
layout outcome as setting `titleBarStyle: 'hidden'`.
|
||||
:::
|
||||
|
||||
#### Custom window controls
|
||||
|
||||
The [Window Controls Overlay API][] is a web standard that gives web apps the ability to
|
||||
customize their title bar region when installed on desktop. Electron exposes this API
|
||||
through the `titleBarOverlay` option in the `BrowserWindow` constructor. When `titleBarOverlay`
|
||||
is enabled, the window controls become exposed in their default position, and DOM elements
|
||||
cannot use the area underneath this region.
|
||||
|
||||
:::note
|
||||
`titleBarOverlay` requires the `titleBarStyle` param in the `BrowserWindow` constructor
|
||||
to have a value other than `default`.
|
||||
:::
|
||||
|
||||
The custom title bar tutorial covers a [basic example][Add native window controls] of exposing
|
||||
window controls by setting `titleBarOverlay: true`. The height, color (_Windows_ _Linux_), and
|
||||
symbol colors (_Windows_) of the window controls can be customized further by setting
|
||||
`titleBarOverlay` to an object.
|
||||
|
||||
The value passed to the `height` property must be an integer. The `color` and `symbolColor`
|
||||
properties accept `rgba()`, `hsla()`, and `#RRGGBBAA` color formats and support transparency.
|
||||
If a color option is not specified, the color will default to its system color for the window
|
||||
control buttons. Similarly, if the height option is not specified, the window controls will
|
||||
default to the standard system height:
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({
|
||||
titleBarStyle: 'hidden',
|
||||
titleBarOverlay: {
|
||||
color: '#2f3241',
|
||||
symbolColor: '#74b1be',
|
||||
height: 60
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
:::note
|
||||
Once your title bar overlay is enabled from the main process, you can access the overlay's
|
||||
color and dimension values from a renderer using a set of readonly
|
||||
[JavaScript APIs][overlay-javascript-apis] and [CSS Environment Variables][overlay-css-env-vars].
|
||||
:::
|
||||
|
||||
[Add native window controls]: #add-native-window-controls-windows-linux
|
||||
[`BaseWindowContructorOptions`]: ../api/structures/base-window-options.md
|
||||
[chrome]: https://developer.mozilla.org/en-US/docs/Glossary/Chrome
|
||||
[Custom draggable regions]: ./custom-window-interactions.md#custom-draggable-regions
|
||||
[Custom traffic lights]: #custom-traffic-lights-macos
|
||||
[Custom window controls]: #custom-window-controls
|
||||
[overlay-css-env-vars]: https://github.com/WICG/window-controls-overlay/blob/main/explainer.md#css-environment-variables
|
||||
[overlay-javascript-apis]: https://github.com/WICG/window-controls-overlay/blob/main/explainer.md#javascript-apis
|
||||
[Window Controls Overlay API]: https://github.com/WICG/window-controls-overlay/blob/main/explainer.md
|
||||
|
|
@ -0,0 +1,107 @@
|
|||
# Custom Window Interactions
|
||||
|
||||
## Custom draggable regions
|
||||
|
||||
By default, windows are dragged using the title bar provided by the OS chrome. Apps
|
||||
that remove the default title bar need to use the `app-region` CSS property to define
|
||||
specific areas that can be used to drag the window. Setting `app-region: drag` marks
|
||||
a rectagular area as draggable.
|
||||
|
||||
It is important to note that draggable areas ignore all pointer events. For example,
|
||||
a button element that overlaps a draggable region will not emit mouse clicks or mouse
|
||||
enter/exit events within that overlapping area. Setting `app-region: no-drag` reenables
|
||||
pointer events by excluding a rectagular area from a draggable region.
|
||||
|
||||
To make the whole window draggable, you can add `app-region: drag` as
|
||||
`body`'s style:
|
||||
|
||||
```css title='styles.css'
|
||||
body {
|
||||
app-region: drag;
|
||||
}
|
||||
```
|
||||
|
||||
And note that if you have made the whole window draggable, you must also mark
|
||||
buttons as non-draggable, otherwise it would be impossible for users to click on
|
||||
them:
|
||||
|
||||
```css title='styles.css'
|
||||
button {
|
||||
app-region: no-drag;
|
||||
}
|
||||
```
|
||||
|
||||
If you're only setting a custom title bar as draggable, you also need to make all
|
||||
buttons in title bar non-draggable.
|
||||
|
||||
### Tip: disable text selection
|
||||
|
||||
When creating a draggable region, the dragging behavior may conflict with text selection.
|
||||
For example, when you drag the title bar, you may accidentally select its text contents.
|
||||
To prevent this, you need to disable text selection within a draggable area like this:
|
||||
|
||||
```css
|
||||
.titlebar {
|
||||
user-select: none;
|
||||
app-region: drag;
|
||||
}
|
||||
```
|
||||
|
||||
### Tip: disable context menus
|
||||
|
||||
On some platforms, the draggable area will be treated as a non-client frame, so
|
||||
when you right click on it, a system menu will pop up. To make the context menu
|
||||
behave correctly on all platforms, you should never use a custom context menu on
|
||||
draggable areas.
|
||||
|
||||
## Click-through windows
|
||||
|
||||
To create a click-through window, i.e. making the window ignore all mouse
|
||||
events, you can call the [win.setIgnoreMouseEvents(ignore)][ignore-mouse-events]
|
||||
API:
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow()
|
||||
win.setIgnoreMouseEvents(true)
|
||||
```
|
||||
|
||||
### Forward mouse events _macOS_ _Windows_
|
||||
|
||||
Ignoring mouse messages makes the web contents oblivious to mouse movement,
|
||||
meaning that mouse movement events will not be emitted. On Windows and macOS, an
|
||||
optional parameter can be used to forward mouse move messages to the web page,
|
||||
allowing events such as `mouseleave` to be emitted:
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow, ipcMain } = require('electron')
|
||||
const path = require('node:path')
|
||||
|
||||
const win = new BrowserWindow({
|
||||
webPreferences: {
|
||||
preload: path.join(__dirname, 'preload.js')
|
||||
}
|
||||
})
|
||||
|
||||
ipcMain.on('set-ignore-mouse-events', (event, ignore, options) => {
|
||||
const win = BrowserWindow.fromWebContents(event.sender)
|
||||
win.setIgnoreMouseEvents(ignore, options)
|
||||
})
|
||||
```
|
||||
|
||||
```js title='preload.js'
|
||||
window.addEventListener('DOMContentLoaded', () => {
|
||||
const el = document.getElementById('clickThroughElement')
|
||||
el.addEventListener('mouseenter', () => {
|
||||
ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })
|
||||
})
|
||||
el.addEventListener('mouseleave', () => {
|
||||
ipcRenderer.send('set-ignore-mouse-events', false)
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
This makes the web page click-through when over the `#clickThroughElement` element,
|
||||
and returns to normal outside it.
|
||||
|
||||
[ignore-mouse-events]: ../api/browser-window.md#winsetignoremouseeventsignore-options
|
||||
|
|
@ -0,0 +1,49 @@
|
|||
# Custom Window Styles
|
||||
|
||||
## Frameless windows
|
||||
|
||||
|
||||
|
||||
A frameless window removes all [chrome][] applied by the OS, including window controls.
|
||||
|
||||
To create a frameless window, set the [`BaseWindowContructorOptions`][] `frame` param in the `BrowserWindow` constructor to `false`.
|
||||
|
||||
```fiddle docs/fiddles/features/window-customization/custom-window-styles/frameless-windows
|
||||
|
||||
```
|
||||
|
||||
## Transparent windows
|
||||
|
||||
|
||||
|
||||
|
||||
To create a fully transparent window, set the [`BaseWindowContructorOptions`][] `transparent` param in the `BrowserWindow` constructor to `true`.
|
||||
|
||||
The following fiddle takes advantage of a tranparent window and CSS styling to create
|
||||
the illusion of a circular window.
|
||||
|
||||
```fiddle docs/fiddles/features/window-customization/custom-window-styles/transparent-windows
|
||||
|
||||
```
|
||||
|
||||
### Limitations
|
||||
|
||||
* You cannot click through the transparent area. See
|
||||
[#1335](https://github.com/electron/electron/issues/1335) for details.
|
||||
* Transparent windows are not resizable. Setting `resizable` to `true` may make
|
||||
a transparent window stop working on some platforms.
|
||||
* The CSS [`blur()`][] filter only applies to the window's web contents, so there is
|
||||
no way to apply blur effect to the content below the window (i.e. other applications
|
||||
open on the user's system).
|
||||
* The window will not be transparent when DevTools is opened.
|
||||
* On _Windows_:
|
||||
* Transparent windows will not work when DWM is disabled.
|
||||
* Transparent windows can not be maximized using the Windows system menu or by double
|
||||
clicking the title bar. The reasoning behind this can be seen on
|
||||
PR [#28207](https://github.com/electron/electron/pull/28207).
|
||||
* On _macOS_:
|
||||
* The native window shadow will not be shown on a transparent window.
|
||||
|
||||
[`BaseWindowContructorOptions`]: ../api/structures/base-window-options.md
|
||||
[`blur()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/blur()
|
||||
[chrome]: https://developer.mozilla.org/en-US/docs/Glossary/Chrome
|
||||
|
|
@ -1,269 +1,17 @@
|
|||
# Window Customization
|
||||
|
||||
The `BrowserWindow` module is the foundation of your Electron application, and it exposes
|
||||
many APIs that can change the look and behavior of your browser windows. In this
|
||||
tutorial, we will be going over the various use-cases for window customization on
|
||||
macOS, Windows, and Linux.
|
||||
The [`BrowserWindow`][] module is the foundation of your Electron application, and
|
||||
it exposes many APIs that let you customize the look and behavior of your app’s windows.
|
||||
This section covers how to implement various use cases for window customization on macOS,
|
||||
Windows, and Linux.
|
||||
|
||||
## Create frameless windows
|
||||
:::info
|
||||
`BrowserWindow` is a subclass of the [`BaseWindow`][] module. Both modules allow
|
||||
you to create and manage application windows in Electron, with the main difference
|
||||
being that `BrowserWindow` supports a single, full size web view while `BaseWindow`
|
||||
supports composing many web views. `BaseWindow` can be used interchangeably with `BrowserWindow`
|
||||
in the examples of the documents in this section.
|
||||
:::
|
||||
|
||||
A frameless window is a window that has no [chrome][]. Not to be confused with the Google
|
||||
Chrome browser, window _chrome_ refers to the parts of the window (e.g. toolbars, controls)
|
||||
that are not a part of the web page.
|
||||
|
||||
To create a frameless window, you need to set `frame` to `false` in the `BrowserWindow`
|
||||
constructor.
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({ frame: false })
|
||||
```
|
||||
|
||||
## Apply custom title bar styles _macOS_ _Windows_
|
||||
|
||||
Title bar styles allow you to hide most of a BrowserWindow's chrome while keeping the
|
||||
system's native window controls intact and can be configured with the `titleBarStyle`
|
||||
option in the `BrowserWindow` constructor.
|
||||
|
||||
Applying the `hidden` title bar style results in a hidden title bar and a full-size
|
||||
content window.
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({ titleBarStyle: 'hidden' })
|
||||
```
|
||||
|
||||
### Control the traffic lights _macOS_
|
||||
|
||||
On macOS, applying the `hidden` title bar style will still expose the standard window
|
||||
controls (“traffic lights”) in the top left.
|
||||
|
||||
#### Customize the look of your traffic lights _macOS_
|
||||
|
||||
The `customButtonsOnHover` title bar style will hide the traffic lights until you hover
|
||||
over them. This is useful if you want to create custom traffic lights in your HTML but still
|
||||
use the native UI to control the window.
|
||||
|
||||
```js
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({ titleBarStyle: 'customButtonsOnHover' })
|
||||
```
|
||||
|
||||
#### Customize the traffic light position _macOS_
|
||||
|
||||
To modify the position of the traffic light window controls, there are two configuration
|
||||
options available.
|
||||
|
||||
Applying `hiddenInset` title bar style will shift the vertical inset of the traffic lights
|
||||
by a fixed amount.
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({ titleBarStyle: 'hiddenInset' })
|
||||
```
|
||||
|
||||
If you need more granular control over the positioning of the traffic lights, you can pass
|
||||
a set of coordinates to the `trafficLightPosition` option in the `BrowserWindow`
|
||||
constructor.
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({
|
||||
titleBarStyle: 'hidden',
|
||||
trafficLightPosition: { x: 10, y: 10 }
|
||||
})
|
||||
```
|
||||
|
||||
#### Show and hide the traffic lights programmatically _macOS_
|
||||
|
||||
You can also show and hide the traffic lights programmatically from the main process.
|
||||
The `win.setWindowButtonVisibility` forces traffic lights to be show or hidden depending
|
||||
on the value of its boolean parameter.
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow()
|
||||
// hides the traffic lights
|
||||
win.setWindowButtonVisibility(false)
|
||||
```
|
||||
|
||||
> Note: Given the number of APIs available, there are many ways of achieving this. For instance,
|
||||
> combining `frame: false` with `win.setWindowButtonVisibility(true)` will yield the same
|
||||
> layout outcome as setting `titleBarStyle: 'hidden'`.
|
||||
|
||||
## Window Controls Overlay
|
||||
|
||||
The [Window Controls Overlay API][] is a web standard that gives web apps the ability to
|
||||
customize their title bar region when installed on desktop. Electron exposes this API
|
||||
through the `BrowserWindow` constructor option `titleBarOverlay`.
|
||||
|
||||
This option only works whenever a custom `titlebarStyle` is applied.
|
||||
When `titleBarOverlay` is enabled, the window controls become exposed in their default
|
||||
position, and DOM elements cannot use the area underneath this region.
|
||||
|
||||
The `titleBarOverlay` option accepts two different value formats.
|
||||
|
||||
Specifying `true` on either platform will result in an overlay region with default
|
||||
system colors:
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({
|
||||
titleBarStyle: 'hidden',
|
||||
titleBarOverlay: true
|
||||
})
|
||||
```
|
||||
|
||||
On either platform `titleBarOverlay` can also be an object. The height of the overlay can be specified with the `height` property. On Windows and Linux, the color of the overlay and can be specified using the `color` property. On Windows and Linux, the color of the overlay and its symbols can be specified using the `color` and `symbolColor` properties respectively. The `rgba()`, `hsla()`, and `#RRGGBBAA` color formats are supported to apply transparency.
|
||||
|
||||
If a color option is not specified, the color will default to its system color for the window control buttons. Similarly, if the height option is not specified it will default to the default height:
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({
|
||||
titleBarStyle: 'hidden',
|
||||
titleBarOverlay: {
|
||||
color: '#2f3241',
|
||||
symbolColor: '#74b1be',
|
||||
height: 60
|
||||
}
|
||||
})
|
||||
```
|
||||
|
||||
> Note: Once your title bar overlay is enabled from the main process, you can access the overlay's
|
||||
> color and dimension values from a renderer using a set of readonly
|
||||
> [JavaScript APIs][overlay-javascript-apis] and [CSS Environment Variables][overlay-css-env-vars].
|
||||
|
||||
## Create transparent windows
|
||||
|
||||
By setting the `transparent` option to `true`, you can make a fully transparent window.
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow({ transparent: true })
|
||||
```
|
||||
|
||||
### Limitations
|
||||
|
||||
* You cannot click through the transparent area. See
|
||||
[#1335](https://github.com/electron/electron/issues/1335) for details.
|
||||
* Transparent windows are not resizable. Setting `resizable` to `true` may make
|
||||
a transparent window stop working on some platforms.
|
||||
* The CSS [`blur()`][] filter only applies to the window's web contents, so there is no way to apply
|
||||
blur effect to the content below the window (i.e. other applications open on
|
||||
the user's system).
|
||||
* The window will not be transparent when DevTools is opened.
|
||||
* On _Windows_:
|
||||
* Transparent windows will not work when DWM is disabled.
|
||||
* Transparent windows can not be maximized using the Windows system menu or by double
|
||||
clicking the title bar. The reasoning behind this can be seen on
|
||||
PR [#28207](https://github.com/electron/electron/pull/28207).
|
||||
* On _macOS_:
|
||||
* The native window shadow will not be shown on a transparent window.
|
||||
|
||||
## Create click-through windows
|
||||
|
||||
To create a click-through window, i.e. making the window ignore all mouse
|
||||
events, you can call the [win.setIgnoreMouseEvents(ignore)][ignore-mouse-events]
|
||||
API:
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow } = require('electron')
|
||||
const win = new BrowserWindow()
|
||||
win.setIgnoreMouseEvents(true)
|
||||
```
|
||||
|
||||
### Forward mouse events _macOS_ _Windows_
|
||||
|
||||
Ignoring mouse messages makes the web contents oblivious to mouse movement,
|
||||
meaning that mouse movement events will not be emitted. On Windows and macOS, an
|
||||
optional parameter can be used to forward mouse move messages to the web page,
|
||||
allowing events such as `mouseleave` to be emitted:
|
||||
|
||||
```js title='main.js'
|
||||
const { BrowserWindow, ipcMain } = require('electron')
|
||||
const path = require('node:path')
|
||||
|
||||
const win = new BrowserWindow({
|
||||
webPreferences: {
|
||||
preload: path.join(__dirname, 'preload.js')
|
||||
}
|
||||
})
|
||||
|
||||
ipcMain.on('set-ignore-mouse-events', (event, ignore, options) => {
|
||||
const win = BrowserWindow.fromWebContents(event.sender)
|
||||
win.setIgnoreMouseEvents(ignore, options)
|
||||
})
|
||||
```
|
||||
|
||||
```js title='preload.js'
|
||||
window.addEventListener('DOMContentLoaded', () => {
|
||||
const el = document.getElementById('clickThroughElement')
|
||||
el.addEventListener('mouseenter', () => {
|
||||
ipcRenderer.send('set-ignore-mouse-events', true, { forward: true })
|
||||
})
|
||||
el.addEventListener('mouseleave', () => {
|
||||
ipcRenderer.send('set-ignore-mouse-events', false)
|
||||
})
|
||||
})
|
||||
```
|
||||
|
||||
This makes the web page click-through when over the `#clickThroughElement` element,
|
||||
and returns to normal outside it.
|
||||
|
||||
## Set custom draggable region
|
||||
|
||||
By default, the frameless window is non-draggable. Apps need to specify
|
||||
`-webkit-app-region: drag` in CSS to tell Electron which regions are draggable
|
||||
(like the OS's standard titlebar), and apps can also use
|
||||
`-webkit-app-region: no-drag` to exclude the non-draggable area from the
|
||||
draggable region. Note that only rectangular shapes are currently supported.
|
||||
|
||||
To make the whole window draggable, you can add `-webkit-app-region: drag` as
|
||||
`body`'s style:
|
||||
|
||||
```css title='styles.css'
|
||||
body {
|
||||
-webkit-app-region: drag;
|
||||
}
|
||||
```
|
||||
|
||||
And note that if you have made the whole window draggable, you must also mark
|
||||
buttons as non-draggable, otherwise it would be impossible for users to click on
|
||||
them:
|
||||
|
||||
```css title='styles.css'
|
||||
button {
|
||||
-webkit-app-region: no-drag;
|
||||
}
|
||||
```
|
||||
|
||||
If you're only setting a custom titlebar as draggable, you also need to make all
|
||||
buttons in titlebar non-draggable.
|
||||
|
||||
### Tip: disable text selection
|
||||
|
||||
When creating a draggable region, the dragging behavior may conflict with text selection.
|
||||
For example, when you drag the titlebar, you may accidentally select its text contents.
|
||||
To prevent this, you need to disable text selection within a draggable area like this:
|
||||
|
||||
```css
|
||||
.titlebar {
|
||||
-webkit-user-select: none;
|
||||
-webkit-app-region: drag;
|
||||
}
|
||||
```
|
||||
|
||||
### Tip: disable context menus
|
||||
|
||||
On some platforms, the draggable area will be treated as a non-client frame, so
|
||||
when you right click on it, a system menu will pop up. To make the context menu
|
||||
behave correctly on all platforms, you should never use a custom context menu on
|
||||
draggable areas.
|
||||
|
||||
[`blur()`]: https://developer.mozilla.org/en-US/docs/Web/CSS/filter-function/blur()
|
||||
[chrome]: https://developer.mozilla.org/en-US/docs/Glossary/Chrome
|
||||
[ignore-mouse-events]: ../api/browser-window.md#winsetignoremouseeventsignore-options
|
||||
[overlay-css-env-vars]: https://github.com/WICG/window-controls-overlay/blob/main/explainer.md#css-environment-variables
|
||||
[overlay-javascript-apis]: https://github.com/WICG/window-controls-overlay/blob/main/explainer.md#javascript-apis
|
||||
[Window Controls Overlay API]: https://github.com/WICG/window-controls-overlay/blob/main/explainer.md
|
||||
[`BaseWindow`]: ../api/base-window.md
|
||||
[`BrowserWindow`]: ../api/browser-window.md
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче