Proprietà e Opzioni delle Finestre

Le BrowserWindow di Electron offrono un ampio set di opzioni per personalizzare l’aspetto e il comportamento delle finestre. Questa guida copre tutte le opzioni principali organizzate per categoria.

Dimensioni e Vincoli

const win = new BrowserWindow({
  // Dimensioni iniziali
  width: 1200,
  height: 800,

  // Dimensioni minime
  minWidth: 400,
  minHeight: 300,

  // Dimensioni massime
  maxWidth: 1920,
  maxHeight: 1080,

  // Usa le dimensioni per il contenuto (non per la finestra intera)
  useContentSize: true,
});

useContentSize è particolarmente utile: se impostato a true, width e height si riferiscono alla dimensione del contenuto web, escludendo la barra del titolo e i bordi della finestra.

Posizionamento

const win = new BrowserWindow({
  x: 100,             // Posizione X dallo schermo
  y: 100,             // Posizione Y dallo schermo
  center: true,       // Centra sullo schermo (ignora x/y)
});

Se non specifichi x, y o center, la finestra verrà posizionata secondo le regole del sistema operativo.

Comportamento della Finestra

const win = new BrowserWindow({
  resizable: true,         // L'utente può ridimensionare
  movable: true,           // L'utente può spostare
  minimizable: true,       // Pulsante minimizza attivo
  maximizable: true,       // Pulsante massimizza attivo
  closable: true,          // Pulsante chiudi attivo
  focusable: true,         // La finestra può ricevere focus
  alwaysOnTop: false,      // Sempre sopra le altre finestre
  fullscreen: false,       // Avvia a schermo intero
  fullscreenable: true,    // Permetti schermo intero
  skipTaskbar: false,      // Nascondi dalla barra delle applicazioni
});

Aspetto della Barra del Titolo

titleBarStyle

// Stile predefinito del sistema operativo
new BrowserWindow({ titleBarStyle: 'default' });

// Barra del titolo nascosta (contenuto sotto i controlli della finestra)
new BrowserWindow({ titleBarStyle: 'hidden' });

// macOS: Pulsanti semaforo posizionati più in basso
new BrowserWindow({ titleBarStyle: 'hiddenInset' });

// macOS: Pulsanti visibili solo al hover
new BrowserWindow({ titleBarStyle: 'customButtonsOnHover' });

titleBarOverlay (Windows/Linux)

Per finestre con barra del titolo personalizzata ma controlli nativi:

const win = new BrowserWindow({
  titleBarStyle: 'hidden',
  titleBarOverlay: {
    color: '#1e1e2e',           // Colore di sfondo dei controlli
    symbolColor: '#cdd6f4',     // Colore delle icone (chiudi, minimizza, ecc.)
    height: 40,                  // Altezza dell'overlay
  },
});

Trasparenza e Aspetto

const win = new BrowserWindow({
  backgroundColor: '#1e1e2e',    // Colore di sfondo (evita flash bianco)
  opacity: 1.0,                   // Opacità (0.0 - 1.0)
  transparent: false,             // Finestra trasparente
  hasShadow: true,                // Ombra della finestra
  roundedCorners: true,           // Angoli arrotondati (macOS)

  // Effetto vibrancy (macOS)
  vibrancy: 'under-window',
  // 'appearance-based', 'light', 'dark', 'titlebar', 'selection',
  // 'menu', 'popover', 'sidebar', 'under-window', 'under-page'

  // Effetto sfondo (Windows 11)
  backgroundMaterial: 'auto',
  // 'auto', 'none', 'mica', 'acrylic', 'tabbed'
});

Configurazione Completa per Piattaforma

App Moderna con Title Bar Personalizzata

function createWindow() {
  const options = {
    width: 1200,
    height: 800,
    minWidth: 600,
    minHeight: 400,
    show: false,
    backgroundColor: '#1e1e2e',
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
      contextIsolation: true,
      nodeIntegration: false,
    },
  };

  // Configurazione per piattaforma
  if (process.platform === 'darwin') {
    options.titleBarStyle = 'hiddenInset';
    options.trafficLightPosition = { x: 15, y: 15 };
  } else {
    options.titleBarStyle = 'hidden';
    options.titleBarOverlay = {
      color: '#1e1e2e',
      symbolColor: '#cdd6f4',
      height: 36,
    };
  }

  const win = new BrowserWindow(options);

  win.once('ready-to-show', () => {
    win.show();
  });

  win.loadFile('index.html');
  return win;
}

Finestra Tipo Splash Screen

function createSplashWindow() {
  return new BrowserWindow({
    width: 400,
    height: 300,
    frame: false,              // Nessun bordo
    transparent: true,         // Sfondo trasparente
    alwaysOnTop: true,         // Sopra le altre finestre
    resizable: false,
    movable: false,
    skipTaskbar: true,         // Non mostrare nella taskbar
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
    },
  });
}

Finestra Tipo Widget/Overlay

function createWidgetWindow() {
  return new BrowserWindow({
    width: 300,
    height: 200,
    frame: false,
    alwaysOnTop: true,
    resizable: false,
    skipTaskbar: true,
    focusable: false,          // Non cattura il focus
    transparent: true,
    webPreferences: {
      preload: path.join(__dirname, 'preload.js'),
    },
  });
}

WebPreferences in Dettaglio

const win = new BrowserWindow({
  webPreferences: {
    // Sicurezza
    preload: path.join(__dirname, 'preload.js'),
    nodeIntegration: false,          // Accesso Node.js nel renderer
    contextIsolation: true,          // Isolamento del contesto
    sandbox: true,                    // Sandboxing del processo
    webSecurity: true,               // Politiche same-origin

    // Funzionalità
    devTools: true,                   // Chrome DevTools
    spellcheck: true,                 // Controllo ortografico
    defaultEncoding: 'utf-8',         // Encoding
    autoplayPolicy: 'no-user-gesture-required',

    // Zoom
    zoomFactor: 1.0,                  // Zoom iniziale

    // Immagini e media
    images: true,                     // Caricamento immagini
    webgl: true,                      // Accelerazione WebGL
  },
});

Ottenere Informazioni sulla Finestra

// Dimensioni
const [width, height] = win.getSize();
const [cWidth, cHeight] = win.getContentSize();
const bounds = win.getBounds(); // { x, y, width, height }

// Stato
win.isMaximized();
win.isMinimized();
win.isFullScreen();
win.isVisible();
win.isFocused();
win.isDestroyed();
win.isResizable();
win.isMovable();

// Titolo
win.getTitle();

// ID
win.id;       // Numero identificativo univoco