Partilhar via

Configuração do Electron para desenvolvimento de API Windows

Este guia guia-o na configuração do seu ambiente de desenvolvimento Electron para desenvolvimento de APIs Windows. Vais instalar as ferramentas necessárias, inicializar o teu project e configurar SDKs do Windows.

Ao final deste guia, terá uma aplicação Electron que:

  • Chama APIs modernas do Windows (Windows SDK e Windows App SDK)
  • Pode usar addons nativos com capacidades de IA (Phi Silica ou WinML)
  • Executa com identidade de aplicação para testar APIs protegidas
  • Pode ser empacotado como um MSIX assinado para distribuição

Pré-requisitos

  • Windows 11 (Copilot+ PC se estiver a usar Phi Silica)
  • Node.js - winget install OpenJS.NodeJS --source winget
  • .NET SDK v10 - winget install Microsoft.DotNet.SDK.10 --source winget
  • Visual Studio com a Carga de Trabalho Nativa para Desktop - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Passo 1: Criar uma nova aplicação Electron

Comece com uma aplicação Electron nova usando o Electron Forge. Se já tens uma aplicação, salta este passo.

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

Verifique se a aplicação está a funcionar:

npm start

Passo 2: Instalar a CLI do winapp

npm install --save-dev @microsoft/winappcli

Passo 3: Iniciar o projeto para desenvolvimento no Windows

npx winapp init

Quando solicitado:

  • Nome do pacote: Pressione Enter para aceitar o predefinido (my-windows-app)
  • Nome do Publicador: Pressione Enter para aceitar o padrão ou inserir o seu nome
  • Versão: Pressione Enter para aceitar 1.0.0.0
  • Ponto de entrada: Pressione Enter para aceitar o padrão (my-windows-app.exe)
  • Configurar SDKs: Selecione "SDKs Estáveis"

O que winapp init faz?

Este comando define tudo o que precisas para o desenvolvimento do Windows:

  1. Cria .winapp/ pasta contendo cabeçalhos e bibliotecas do SDK do Windows e Windows App SDK
  2. Gera appxmanifest.xml - O manifesto da aplicação necessário para a identidade da aplicação e o empacotamento MSIX
  3. Cria Assets/ pasta - Contém ícones da aplicação e recursos visuais
  4. Creates winapp.yaml - Monitoriza versões do SDK e configuração de projetos
  5. Instala Windows App SDK runtime - Componentes de runtime necessários para APIs modernas
  6. Ativa o Modo Desenvolvedor no Windows - Necessário para depuração

Observação

A pasta .winapp/ é adicionada automaticamente a .gitignore e não deve ser registada no controlo de origem.

Passo 4: Adicionar a restauração ao seu pipeline de construção

Adicione um script postinstall ao seu package.json para garantir que os SDKs do Windows estão disponíveis quando outros programadores clonarem o seu project:

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

Este guião executa-se após o npm install e:

  1. winapp restore - Descarrega e restaura todos os pacotes de SDK do Windows
  2. winapp node add-electron-debug-identity - Regista a sua aplicação Electron com identidade de depuração

Para projetos multiplataforma, crie 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.');
}

Depois atualiza package.json:

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

Passo 5: Entender a identidade de depuração

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

  1. Lê o seu appxmanifest.xml para obter detalhes e funcionalidades da aplicação.
  2. Regista electron.exe no seu node_modules com uma identidade temporária
  3. Permite testar APIs que exigem identidade sem criar um pacote MSIX completo

Executa este comando manualmente sempre que modificares appxmanifest.xml ou ligares assets:

npx winapp node add-electron-debug-identity

Testa a tua configuração:

npm start

Observação

Existe um bug conhecido no Windows com aplicações Electron com empacotamento esparso que pode causar falhas ou janelas em branco. Adicione --no-sandbox ao seu script de início como solução alternativa: "start": "electron-forge start -- --no-sandbox". Este problema não afeta a embalagem completa do MSIX. Para desfazer a identidade de depuração, execute npx winapp node clear-electron-debug-identity.

Passos seguintes

Agora que o seu ambiente de desenvolvimento está configurado, crie addons nativos e chame APIs do Windows:

  • Last updated on