Udostępnij za pośrednictwem

Konfigurowanie narzędzia Electron na potrzeby tworzenia interfejsu API systemu Windows

Ten przewodnik przeprowadzi Cię przez proces konfigurowania środowiska programistycznego Electron na potrzeby tworzenia interfejsu API systemu Windows. Zainstalujesz niezbędne narzędzia, zainicjujesz project i skonfigurujesz zestawy SDK systemu Windows.

Na końcu tego przewodnika będziesz mieć aplikację Electron, która:

  • Wywołuje nowoczesne interfejsy API systemu Windows (Windows SDK i Windows App SDK)
  • Może używać natywnych dodatków z funkcjami sztucznej inteligencji (Silica Phi lub WinML)
  • Działa z tożsamością aplikacji na potrzeby testowania chronionych interfejsów API
  • Można spakować jako podpisany plik MSIX do dystrybucji

Wymagania wstępne

  • Windows 11 (Copilot+ PC w przypadku korzystania z Phi Silica)
  • Node.js - winget install OpenJS.NodeJS --source winget
  • .NET SDK w wersji 10 - winget install Microsoft.DotNet.SDK.10 --source winget
  • Visual Studio z obciążeniem pulpitu natywnego - winget install --id Microsoft.VisualStudio.Community --source winget --override "--add Microsoft.VisualStudio.Workload.NativeDesktop --includeRecommended --passive --wait"

Krok 1. Tworzenie nowej aplikacji Electron

Zacznij od nowej aplikacji Elektron przy użyciu narzędzia Electron Forge. Jeśli masz istniejącą aplikację, pomiń ten krok.

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

Sprawdź, czy aplikacja działa:

npm start

Krok 2: Instalowanie CLI winapp

npm install --save-dev @microsoft/winappcli

Krok 3. Inicjowanie projektu na potrzeby tworzenia w systemie Windows

npx winapp init

Po wyświetleniu monitu:

  • Nazwa pakietu: naciśnij klawisz Enter, aby zaakceptować wartość domyślną (my-windows-app)
  • Nazwa wydawcy: Naciśnij klawisz Enter, aby zaakceptować wartość domyślną lub wprowadź swoją nazwę
  • Wersja: Naciśnij klawisz Enter, aby zaakceptować 1.0.0.0
  • Punkt wejścia: Naciśnij klawisz Enter, aby zaakceptować wartość domyślną (my-windows-app.exe)
  • Konfiguracja zestawów SDK: wybierz pozycję "Stabilne zestawy SDK"

winapp init Co robi?

To polecenie konfiguruje wszystko, czego potrzebujesz do programowania w systemie Windows:

  1. Utwórz folder .winapp/ zawierający nagłówki i biblioteki z zestawu Windows SDK i Windows App SDK
  2. Generuje appxmanifest.xml — Manifest aplikacji wymagany do obsługi tożsamości aplikacji i tworzenia pakietów MSIX
  3. Tworzy Assets/ folder — zawiera ikony aplikacji i zasoby wizualne
  4. Tworzy winapp.yaml — śledzi wersje zestawu SDK i konfigurację projektu
  5. Installs Windows App SDK runtime — wymagane składniki środowiska uruchomieniowego dla nowoczesnych interfejsów API
  6. Włącza tryb dewelopera w systemie Windows — wymagane do debugowania

Uwaga / Notatka

Folder .winapp/ jest automatycznie dodawany do .gitignore i nie powinien być zamieszczany w systemie kontroli wersji.

Krok 4: Dodaj przywracanie do potoku kompilacji

Dodaj skrypt postinstall do package.json, aby upewnić się, że zestawy SDK systemu Windows są dostępne, gdy inni deweloperzy sklonują projekt.

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

Ten skrypt jest uruchamiany po npm install i:

  1. winapp restore — Pobiera i przywraca wszystkie pakiety zestawu Windows SDK
  2. winapp node add-electron-debug-identity — Rejestruje aplikację Electron z tożsamością do debugowania

W przypadku projektów międzyplatformowych utwórz polecenie 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.');
}

Następnie zaktualizuj package.json:

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

Krok 5: Zrozumienie tożsamości debugowania

Polecenie winapp node add-electron-debug-identity:

  1. Odczytuje appxmanifest.xml, aby uzyskać szczegóły i możliwości aplikacji.
  2. Rejestruje electron.exe w node_modules przy użyciu tożsamości tymczasowej
  3. Umożliwia testowanie interfejsów API wymagających tożsamości bez tworzenia kompletnego pakietu MSIX

Uruchamiaj to polecenie ręcznie za każdym razem, gdy modyfikujesz appxmanifest.xml lub powiązane zasoby.

npx winapp node add-electron-debug-identity

Przetestuj konfigurację:

npm start

Uwaga / Notatka

Istnieje znana usterka systemu Windows z rozrzednymi pakietami aplikacji Electron, które mogą powodować awarie lub puste okna. Dodaj --no-sandbox do skryptu uruchamiania jako obejście: "start": "electron-forge start -- --no-sandbox". Ten problem nie ma wpływu na pełne pakowanie MSIX. Aby cofnąć debugowanie tożsamości, uruchom polecenie npx winapp node clear-electron-debug-identity.

Następne kroki

Teraz, po skonfigurowaniu środowiska projektowego, utwórz natywne dodatki i wywołaj interfejsy API systemu Windows:

  • Last updated on