Volání rozhraní API Windows z JavaScriptu (vazby JS)

V této příručce se dozvíte, jak volat rozhraní API Windows – Windows App SDK i Windows SDK – přímo z JavaScriptu vaší aplikace Electron bez nativního doplňku a bez node-gyp kroku MSBuild. Otevřete nativní dialog pro výběr souboru (Windows App SDK) a pak prozkoumáte vybraný obrázek pomocí rozhraní API pro soubory a zpracování obrazu z Windows SDK přidaných prostřednictvím winapp.jsBindings.

Předpoklady

Než začnete s touto příručkou, ujistěte se, že máte:

Krok 1: Potvrzení vazeb

Instalační proces vygeneroval adresář .winapp/bindings/ vedle vašich zdrojových souborů – jeden pár .js + .d.ts pro každou vygenerovanou třídu Windows App SDK a také index.js, který je všechny znovu exportuje:

.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
└── …

Krok 2: Přidání rozhraní API sady Windows SDK do vazeb

Výchozí vazby pokrývají pouze Windows App SDK rozhraní API. K otevření a dekódování vybraného obrázku potřebujeme také dvě třídy sady WINDOWS SDK:

  • Windows.Storage.StorageFile — zalomení cesty k souboru.
  • Windows.Graphics.Imaging.BitmapDecoder — pro zjištění jeho rozměrů.

Otevřete package.json a přidejte additionalWinmds pole uvnitř vytvořeného winapp.jsBindings bloku winapp init :

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

Potom znovu vygenerujte vazby:

npx winapp node generate-bindings

StorageFile.js, BitmapDecoder.jsa soubory výčtu, na které jsou závislé (FileAccessMode.js, BitmapPixelFormat.js, ...), se nyní zobrazují v .winapp/bindings/.

Note

dynwinrt-codegen automaticky zahrnuje závislé typy, které potřebujete k volání těchto tříd (například IRandomAccessStream, vrácené funkcí StorageFile.openAsync), takže výběr pouze tříd vstupních bodů obvykle stačí.

Krok 3: Volání rozhraní API Windows z vašeho elektronového kódu

Všechny vygenerované třídy se exportují prostřednictvím #winapp/bindings:

Vyžaduje @microsoft/dynwinrt-codegen ≥ 0.1.0-preview.8 – viz Začínáme s Elektronem , kde najdete náhradní řešení starších projektů.

// 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);
});

Pak jej propojte s rendererem pomocí preload skriptu:

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

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

Nakonec přidejte do svého rendereru tlačítko a při kliknutí na něj zavolejte window.winapp.pickAndInspectImage():

<!-- 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>

Krok 4: Spusťte ho

Než bude výběr souboru fungovat, musíte zajistit, aby vaše aplikace běžela s identitou. Běh:

npx winapp node add-electron-debug-identity

Note

Tento příkaz je již součástí postinstall skriptu, který jsme přidali v průvodci nastavením, takže se spustí automaticky po npm install. Musíte ho ale spustit ručně pokaždé, když upravíte Package.appxmanifest, aktualizujete prostředky aplikace nebo přeinstalujete závislosti.

Teď spusťte aplikaci:

npm start

Klikněte na tlačítko: Zobrazí se nativní výběr souboru Windows a jakmile vyberete obrázek, jeho cesta a rozměry pixelů se zobrazí pod tlačítkem. 🎉 Import z .winapp/bindings/ načte @microsoft/dynwinrt, které přesměruje každé volání do podkladového rozhraní WinRT API — zcela transparentně pro váš kód.

Další kroky

Gratulujeme! Teď voláte rozhraní API Windows – Windows App SDK a Windows SDK – přímo z JavaScriptu, bez nativního doplňku a kroku node-gyp sestavení. 🎉

Teď jste připraveni:

  • Zabalte aplikaci pro distribuci — vytvořte balíček MSIX, který můžete distribuovat (modul @microsoft/dynwinrt runtime už je součástí vaší sady dependencies).

Nebo prozkoumejte další příručky:

Další zdroje

  • Last updated on