Aller au contenu principal

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.

Créer une fenêtre sans bordure

Une fenêtre sans bords est une fenêtre qui n'a pas de chrome. A ne pas confondre avec le navigateur Google Chrome, le chrome d'une fenêtre fait référence aux parties de la fenêtre (par ex. barre d'outils et de contrôles) qui ne font pas partie de la page web.

Pour créer une fenêtre sans bordure, vous devez définir frame comme false dans le constructeur BrowserWindow.

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ frame: false })

Appliquer des styles de barre de titre personnalisés 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.

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.

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.

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.

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.

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 macOS Windows

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 on macOS or Windows. 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:

main.js
// on macOS or Windows
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
titleBarStyle: 'hidden',
titleBarOverlay: true
})

On Windows, you can also specify additional parameters. The color of the overlay and its symbols can be specified by setting titleBarOverlay to an object and using the color and symbolColor properties respectively. The height of the overlay can also be specified with the height property.

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:

main.js
// on Windows
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 and CSS Environment Variables.

Limitations

  • Transparent colors are currently not supported. Progress updates for this feature can be found in PR #33567.

Create transparent windows

By setting the transparent option to true, you can make a fully transparent window.

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({ transparent: true })

Limitations

  • You cannot click through the transparent area. Voir #1335 pour plus de détails.
  • 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.
  • Sous Windows :
    • Les fenêtres transparentes ne fonctionneront pas lorsque DWM est désactivé.
    • Transparent windows can not be maximized using the Windows system menu or by double clicking the title bar. Le raisonnement derrière cela peut être vu sur PR #28207.
  • Sur macOS :
    • L'ombre native de la fenêtre ne sera pas affichée sur une fenêtre transparente.

Create click-through windows

Pour créer une fenêtre non cliquable, c'est-à-dire faire en sorte que la fenêtre ignore tous les événements de la souris, vous pouvez appeler l'API win.setIgnoreMouseEvents(ignore) :

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:

main.js
const { BrowserWindow, ipcMain } = require('electron')
const path = require('path')

const win = new BrowserWindow({
webPreferences: {
preload: path.join(__dirname, 'preload.js')
}
})

ipcMain.on('set-ignore-mouse-events', (event, ...args) => {
const win = BrowserWindow.fromWebContents(event.sender)
win.setIgnoreMouseEvents(...args)
})
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

Par défaut, la fenêtre sans cadre ne peut pas être déplacée. Les applications doivent spécifier -webkit-app-region: glisser dans CSS pour dire à Electron quelles régions sont glissables (comme la barre de titre standard de l'OS), et les applications peuvent également utiliser -webkit-app-region : no-drag pour exclure la zone non glissable de la région glissable. Notez que seules les formes rectangulaires sont actuellement prises en charge.

Pour que toute la fenêtre puisse être déplacée, vous pouvez ajouter -webkit-app-region : glisser comme body's style :

styles.css
body {
-webkit-app-region: drag;
}

Et notez que si vous avez rendu toute la fenêtre déplaçable, vous devez également marquer les boutons comme non glissables, sinon il serait impossible pour les utilisateurs de cliquer sur eux :

styles.css
button {
-webkit-app-region: no-drag;
}

Si vous définissez seulement une barre de titre personnalisée comme glissable, vous devez également rendre tous les boutons de la barre de titre non glissables.

Astuce : désactiver la sélection de texte

Lors de la création d'une région déplaçable, le comportement de déplacement peut entrer en conflit avec la sélection de texte. 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:

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