Aller au contenu principal

Personnalisation des fenêtres

Le module BrowserWindow est la base de votre application Electron, et expose de nombreuses API utilisables pour modifier l’apparence et le comportement des fenêtres de votre navigateur. Dans ce tutoriel, nous allons passer en revue les différents cas d’utilisation de personnalisation de fenêtres sur macOS, Windows et Linux.

Créer une fenêtre sans bordure​

Une fenêtre sans bordure 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 de BrowserWindow.

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

Appliquer des styles de barre de titre personnalisés macOS Windows​

Les styles de barre de titre vous permettent de masquer la majeure partie du chrome d’une BrowserWindow tout en conservant intacts les contrôles de fenêtre natifs du système et en permettant la configuration avec l’option titleBarStyle dans le constructeur de la BrowserWindow .

L’application du style de barre de titre hidden entraîne une barre de titre masquée et une fenêtre de contenu affichée en plein format.

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

Contrôlez les feux de signalisation de macOS​

Sous macOS, l’application du style de barre de titre hidden exposera toujours les contrôles standards(« feux de signalisation ») de fenêtre en haut à gauche.

Personnalisation de l'apparence des feux de signalisation macOS​

Le style de barre de titre customButtonsOnHover masquera les feux de circulation sauf lorsque le curseur les survole. C'est très utile si vous souhaitez créer des feux de signalisation personnalisés dans votre code HTML, mais toujours utiliser l’interface utilisateur native pour contrôler la fenêtre.

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

Personnalisation de la position des feux de signalisation macOS​

Pour modifier la position des feux de signalisation, deux options de configuration sont disponibles.

L’application du style hiddenInset à la barer de titre déplacera l’insertion verticale des feux de circulation d’un montant fixe.

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

Si vous avez besoin d’un contrôle plus fin sur le positionnement des feux, vous pouvez passer un ensemble de coordonnées à l’option trafficLightPosition dans le constructeur de BrowserWindow .

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  trafficLightPosition: { x: 10, y: 10 }
})

Afficher et masquer les feux de signalisation par programme macOS​

Vous pouvez également afficher ou masquer les feux de signalisation par programme à partir du processus principal. win.setWindowButtonVisibility force ou masque les feux en fonction de la valeur de son paramètre booléen.

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow()
// hides the traffic lights
win.setWindowButtonVisibility(false)

Remarque : Compte tenu du nombre d’API disponibles, il existe de nombreuses façons d’y parvenir. Par exemple, la combinaison de frame: false et de win.setWindowButtonVisibility(true) donnera le même résultat de mise en page que la définition de titleBarStyle: 'hidden'.

Window Controls Overlay​

L’API Window Controls Overlay est une norme Web qui donne aux applications Web la possibilité de personnaliser leur région de barre de titre lorsqu’elles sont installées sur le bureau. Electron expose cette API via l'option titleBarOverlay du constructeur de BrowserWindow.

This option only works whenever a custom titlebarStyle is applied. Lorsque titleBarOverlay est activé, les contrôles de fenêtre sont exposés dans leur position par défaut et les éléments DOM ne peuvent pas utiliser la zone située sous cette région.

L’option titleBarOverlay accepte deux formats de valeur différents.

La valeur true entraînera la création pour les plateformes supportées d'une zone de superposition avec les couleurs par défaut du système :

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

Sur l'une ou l'autre des plateformes titleBarOverlay peut également être un objet. 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.

Si une option de couleur n'est pas spécifiée, la couleur par défaut sera celle du système pour les boutons de contrôle de fenêtre. De même, si l'option de hauteur n'est pas spécifiée, la hauteur par défaut sera la valeur par défaut :

main.js
const { BrowserWindow } = require('electron')
const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  titleBarOverlay: {
    color: '#2f3241',
    symbolColor: '#74b1be',
    height: 60
  }
})

Remarque : Une fois que vous avez activé la superposition de la barre de titre dans votre processus principal, vous pouvez accéder à partir d’un moteur de rendu aux valeurs de couleur et de dimension de la superposition à l’aide d’un ensemble en lecture seule d’API JavaScript et de variables d’environnement CSS.

Création de fenêtres transparentes​

Vous pouvez créer une fenêtre entièrement transparente en définissant l'option transparent à true, .

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

Limitations​

  • Vous ne pouvez pas cliquer dans la zone transparente. Voir #1335 pour plus de détails.
  • Les fenêtres transparentes ne sont pas redimensionnables. Définir resizable à true peut empêcher une fenêtre transparente de fonctionner sur certaines plates-formes.
  • Le filtre CSS blur() ne s’applique qu’au contenu Web de la fenêtre, il n’y a donc aucun moyen d’appliquer un effet de flou au contenu sous la fenêtre (c’est-à-dire sur d’autres applications ouvertes sur le système de l’utilisateur).
  • La fenêtre ne sera pas transparente lorsque les DevTools sont ouverts.
  • Sous Windows :
    • Les fenêtres transparentes ne fonctionneront pas lorsque DWM est désactivé.
    • Les fenêtres transparentes ne peuvent pas être maximalisées à l’aide du menu système Windows ou par un double click sur la barre de titre. 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.

Fenêtre non cliquable​

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)

Transfert des événements de la souris macOS Windows​

Le fait d'ignorer les messages de la souris rend la page Web insensible au mouvement de la souris, signifiant que les événements de déplacement de la souris ne seront pas émis. Sous Windows et macOS, un paramètre optionnel peut être utilisé pour transferrer les messages de la souris à la page web, permettant d'émettre des événements tels que mouseleave:

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)
})
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)
  })
})

Cela rend la page Web cliquable pour l’élément #clickThroughElement , et normale en dehors de celui-ci.

Définir une région glissable personnalisée​

Par défaut, la fenêtre sans cadre ne peut pas être déplacée. Les applications doivent spécifier -webkit-app-region: drag dans CSS pour dire à Electron quelles régions sont déplaçables (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 déplaçable de la région déplaçable. 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 : drag comme style au body:

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 déplaçables car sinon il sera impossible pour les utilisateurs de cliquer sur ceux-ci :

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

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

Astuce : désactiver la sélection de texte​

Lors de la création d'une région déplaçable, le déplacement peut entrer en conflit avec la sélection de texte. Par exemple, lorsque vous faites glisser la barre de titre, vous pouvez accidentellement sélectionner son contenu. Vous éviterez de tels désagréments en désactivant la sélection de texte dans une zone pouvant être glissée comme celle-ci :

.titlebar {
  -webkit-user-select: none;
  -webkit-app-region: drag;
}

Astuce : désactiver les menus contextuels​

Sur certaines plateformes, la zone déplaçable sera traitée comme une frame hors-client, donc lun clic droit sur celle-ci fera apparaître un menu système. Pour que le menu contextuel se comporte correctement sur toutes les plates-formes, vous ne devez jamais utiliser un menu contextuel personnalisé sur des zones déplaçables.