Aufrufen Windows APIs aus JavaScript (JS-Bindungen)

In diesem Handbuch wird gezeigt, wie Sie Windows APIs – sowohl Windows App SDK als auch Windows SDK – direkt aus dem JavaScript Ihrer Electron-App aufrufen, ohne systemeigenes Addon und kein node-gyp /MSBuild-Schritt. Sie öffnen einen nativen Dateiauswahldialog (Windows App SDK) und untersuchen dann das ausgewählte Bild mit Datei- und Bildverarbeitungs-APIs des Windows SDK, die über winapp.jsBindings hinzugefügt wurden.

Voraussetzungen

Bevor Sie diesen Leitfaden starten, stellen Sie sicher, dass Sie folgendes haben:

Schritt 1: Bestätigen Ihrer Bindungen

Setup hat ein .winapp/bindings/-Verzeichnis neben Ihren Quelltexten generiert – ein .js + .d.ts-Paar pro generierter Windows App SDK-Klasse sowie eine index.js, die sie alle re-exportiert:

.winapp/bindings/
├── index.js                  # entry — re-exports every emitted class
├── index.d.ts                # TS bundle
├── FileOpenPicker.js         # one pair of files per emitted class
├── FileOpenPicker.d.ts
├── PickerLocationId.js
├── PickerLocationId.d.ts
└── …

Schritt 2: Hinzufügen Windows SDK-APIs zu Ihren Bindungen

Die Standardbindungen decken nur Windows App SDK APIs ab. Um das ausgewählte Bild zu öffnen und zu decodieren, benötigen wir auch zwei Windows SDK-Klassen:

  • Windows.Storage.StorageFile — um einen Dateipfad umzuschließen.
  • Windows.Graphics.Imaging.BitmapDecoder — um seine Abmessungen zu lesen.

Öffnen Sie package.json und fügen Sie ein additionalWinmds-Array innerhalb des winapp.jsBindings-Blocks hinzu, den winapp init erstellt hat:

// package.json
{
  "winapp": {
    "jsBindings": {
      "additionalWinmds": [
        { "namespace": "Windows.Storage", "classes": ["StorageFile"] },
        { "namespace": "Windows.Graphics.Imaging", "classes": ["BitmapDecoder"] }
      ]
    }
  }
}

Generieren Sie dann die Bindungen neu:

npx winapp node generate-bindings

StorageFile.js, BitmapDecoder.jsund die Enumerationsdateien, von der sie abhängen (FileAccessMode.js, BitmapPixelFormat.js, ...) werden jetzt in .winapp/bindings/angezeigt.

Hinweis

dynwinrt-codegen bindet die abhängigen Typen, die Sie benötigen, um diese Klassen aufzurufen (zum Beispiel IRandomAccessStream, zurückgegeben von StorageFile.openAsync), automatisch mit ein, sodass die gezielte Auswahl nur der Einstiegspunktklassen in der Regel ausreicht.

Schritt 3: Aufrufen Windows APIs aus Ihrem Elektronencode

Alle generierten Klassen werden durch #winapp/bindingsexportiert:

Erfordert @microsoft/dynwinrt-codegen ≥ 0.1.0-preview.8 — siehe Erste Schritte mit Electron für Ausweichlösungen bei älteren Projekten.

// src/index.js (Electron main, CommonJS)
const { app, BrowserWindow, ipcMain } = require('electron');
const {
  // Windows App SDK (default bindings)
  FileOpenPicker,
  PickerLocationId,
  PickerViewMode,
  // Windows SDK (added via additionalWinmds in Step 2)
  StorageFile,
  FileAccessMode,
  BitmapDecoder,
} = require('#winapp/bindings');

async function pickAndInspectImage(mainWindow) {
  // FileOpenPicker needs the parent window's HWND wrapped in a WindowId struct.
  // Electron's getNativeWindowHandle() returns an 8-byte buffer on 64-bit Windows.
  const hwnd = mainWindow.getNativeWindowHandle().readBigUInt64LE(0);

  const picker = FileOpenPicker.createInstance({ value: hwnd });
  picker.viewMode = PickerViewMode.Thumbnail;
  picker.suggestedStartLocation = PickerLocationId.PicturesLibrary;
  picker.fileTypeFilter.replaceAll(['.png', '.jpg', '.jpeg', '.gif']);

  const result = await picker.pickSingleFileAsync();
  if (!result?.path) return null; // User cancelled.

  // Use Windows SDK APIs to inspect the picked image.
  const file = await StorageFile.getFileFromPathAsync(result.path);
  const stream = await file.openAsync(FileAccessMode.Read);
  const decoder = await BitmapDecoder.createAsync(stream);

  return {
    path: result.path,
    width: decoder.pixelWidth,
    height: decoder.pixelHeight,
  };
}

// Expose it to the renderer via IPC so a button click can trigger the flow.
ipcMain.handle('pick-and-inspect-image', (event) => {
  const win = BrowserWindow.fromWebContents(event.sender);
  return pickAndInspectImage(win);
});

Binden Sie es dann durch Ihr Preload-Skript in den Renderer ein:

// src/preload.js
const { contextBridge, ipcRenderer } = require('electron');

contextBridge.exposeInMainWorld('winapp', {
  pickAndInspectImage: () => ipcRenderer.invoke('pick-and-inspect-image'),
});

Fügen Sie dem Renderer schließlich eine Schaltfläche hinzu, und rufen Sie auf window.winapp.pickAndInspectImage() , wenn darauf geklickt wird:

<!-- src/index.html -->
<button id="pick">Pick an image</button>
<p id="result"></p>

<script>
  document.getElementById('pick').addEventListener('click', async () => {
    const info = await window.winapp.pickAndInspectImage();
    document.getElementById('result').textContent = info
      ? `${info.path} (${info.width}×${info.height})`
      : 'Cancelled';
  });
</script>

Schritt 4: Ausführen

Bevor die Dateiauswahl funktioniert, müssen Sie sicherstellen, dass Ihre App mit Identität ausgeführt wird. Run:

npx winapp node add-electron-debug-identity

Hinweis

Dieser Befehl ist bereits Teil des Skripts, das wir im postinstall Einrichtungsanleitung hinzugefügt haben, sodass es automatisch nach npm install ausgeführt wird. Sie müssen den Vorgang jedoch manuell ausführen, wann immer Sie Package.appxmanifest ändern, App-Ressourcen aktualisieren oder Abhängigkeiten erneut installieren.

Starten Sie nun die App:

npm start

Klicken Sie auf die Schaltfläche: Die systemeigene Windows Dateiauswahl wird angezeigt, und sobald Sie ein Bild ausgewählt haben, werden der Pfad und die Pixelabmessungen unterhalb der Schaltfläche angezeigt. 🎉 Der Import aus .winapp/bindings/ lädt @microsoft/dynwinrt, wodurch jeder Aufruf an die zugrunde liegende WinRT-API weitergeleitet wird – für Ihren Code transparent.

Nächste Schritte

Herzlichen Glückwunsch! Sie rufen jetzt Windows-APIs – Windows App SDK und Windows SDK – direkt aus JavaScript auf, ohne natives Add-On und ohne node-gyp Build-Schritt. 🎉

Jetzt sind Sie bereit für:

Oder erkunden Sie andere Guides:

Zusätzliche Ressourcen

  • Last updated on