Condividi tramite

Configurazione di Electron per lo sviluppo di API Windows

Questa guida illustra come configurare l'ambiente di sviluppo Electron per lo sviluppo di API Windows. Si installeranno gli strumenti necessari, si inizializzeranno i project e si configureranno gli SDK di Windows.

Al termine di questa guida, si avrà un'app Electron che:

  • Chiama le API di Windows moderne (Windows SDK e Windows App SDK)
  • Può usare componenti aggiuntivi nativi con funzionalità di intelligenza artificiale (Phi Silica o WinML)
  • Viene eseguito con l'identità dell'app per testare le API protette
  • Può essere inserita in un pacchetto come MSIX firmato per la distribuzione

Prerequisiti

  • Windows 11 (Copilot+ PC se si utilizza Phi Silica)
  • Node.js - winget install OpenJS.NodeJS --source winget
  • .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
  • Visual Studio con il workload desktop nativo - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Passaggio 1: Creare una nuova app Electron

Iniziare con una nuova app Electron usando Electron Forge. Se si dispone di un'app esistente, ignorare questo passaggio.

npm create electron-app@latest my-windows-app
cd my-windows-app

Verificare che l'app funzioni correttamente:

npm start

Passaggio 2: Installare il CLI di winapp

npm install --save-dev @microsoft/winappcli

Passaggio 3: Inizializzare il project per lo sviluppo di Windows

npx winapp init

Quando richiesto:

  • Nome pacchetto: premere INVIO per accettare il valore predefinito (my-windows-app)
  • Publisher nome: premere INVIO per accettare il valore predefinito o immettere il nome
  • Versione: premere INVIO per accettare 1.0.0.0
  • Punto di ingresso: premere INVIO per accettare il valore predefinito (my-windows-app.exe)
  • SDK di installazione: selezionare "SDK stabili"

Che cosa fa winapp init?

Questo comando configura tutto ciò che serve per lo sviluppo di Windows:

  1. Crea la cartella .winapp/ contenente intestazioni e librerie da Windows SDK e Windows App SDK
  2. Genera appxmanifest.xml - Manifesto dell'app necessario per l'identità dell'app e la creazione di pacchetti MSIX
  3. Crea Assets/ una cartella : contiene icone dell'app e asset visivi
  4. Crea winapp.yaml - Tiene traccia delle versioni dell'SDK e della configurazione del progetto
  5. Installa Windows App SDK runtime - Componenti di runtime necessari per le API moderne
  6. Abilita la modalità sviluppatore in Windows - Obbligatorio per il debug

Annotazioni

La cartella .winapp/ viene aggiunta automaticamente a .gitignore e non deve essere inserita nel controllo del codice sorgente.

Passaggio 4: Aggiungere il ripristino alla pipeline di compilazione

Aggiungere uno script postinstall al package.json per assicurarsi che gli SDK di Windows siano disponibili quando altri sviluppatori clonano il project:

{
  "scripts": {
    "postinstall": "winapp restore && winapp node add-electron-debug-identity"
  }
}

Questo script viene eseguito dopo npm install e:

  1. winapp restore - Scarica e ripristina tutti i pacchetti di Windows SDK
  2. winapp node add-electron-debug-identity - Registra la tua app Electron con l'identità di debug

Per i progetti multipiattaforma, creare scripts/postinstall.js:

if (process.platform === 'win32') {
  const { execSync } = require('child_process');
  try {
    execSync('npx winapp restore && npx winapp cert generate --if-exists skip && npx winapp node add-electron-debug-identity', {
      stdio: 'inherit'
    });
  } catch (error) {
    console.warn('Warning: Windows-specific setup failed.');
  }
} else {
  console.log('Skipping Windows-specific setup on non-Windows platform.');
}

Quindi aggiorna :

{
  "scripts": {
    "postinstall": "node scripts/postinstall.js"
  }
}

Passaggio 5: Comprensione dell'identità di debug

Il comando winapp node add-electron-debug-identity:

  1. Legge il tuo appxmanifest.xml per ottenere i dettagli e le funzionalità dell'app
  2. Registra electron.exe nel node_modules con un'identità temporanea.
  3. Consente di testare le API necessarie per l'identità senza creare un pacchetto MSIX completo

Esegui questo comando manualmente ogni volta che modifichi appxmanifest.xml o le risorse collegate.

npx winapp node add-electron-debug-identity

Testare la configurazione:

npm start

Annotazioni

Esiste un bug noto di Windows con pacchetti sparse di applicazioni Electron che possono causare arresti anomali o finestre vuote. Aggiungere --no-sandbox allo script iniziale come soluzione alternativa: "start": "electron-forge start -- --no-sandbox". Questo problema non influisce sulla creazione di pacchetti MSIX completi. Per annullare l'identità di debug, eseguire npx winapp node clear-electron-debug-identity.

Passaggi successivi

Ora che l'ambiente di sviluppo è configurato, creare componenti aggiuntivi nativi e chiamare le API di Windows:

  • Last updated on