JavaScript'ten Windows API'lerini çağırma (JS bağlamaları)

Bu kılavuz, yerel eklenti kullanmadan ve node-gyp / MSBuild adımı olmadan, hem Windows Uygulama SDK'sı’deki hem de Windows SDK’deki Windows API’lerini doğrudan Electron uygulamanızın JavaScript kodundan nasıl çağıracağınızı gösterir. Yerel bir dosya seçici (Windows Uygulama SDK'sı) açacak, ardından Windows SDK dosyası ve aracılığıyla winapp.jsBindingseklenen görüntüleme API'leri ile seçilen görüntüyü inceleyeceksiniz.

Prerequisites

Bu kılavuza başlamadan önce şunları yaptığınızdan emin olun:

1. Adım: Bağlamalarınızı onaylayın

Kurulum, kaynaklarınızın yanında bir .winapp/bindings/ dizini oluşturdu — üretilen her Windows Uygulama SDK'sı sınıfı için bir .js + .d.ts çifti ve ayrıca bunların tümünü yeniden dışa aktaran bir index.js:

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

2. Adım: Bağlamalarınıza Windows SDK API'leri ekleme

Varsayılan bağlamalar yalnızca Windows Uygulama SDK'sı API'leri kapsar. Seçilen görüntüyü açmak ve kodunu çözmek için iki Windows SDK sınıfına da ihtiyacımız vardır:

  • Windows.Storage.StorageFile — bir dosya yolunu sarmalama.
  • Windows.Graphics.Imaging.BitmapDecoder — boyutlarını okumak için.

package.json öğesini açın ve winapp init tarafından oluşturulan winapp.jsBindings bloğunun içine bir additionalWinmds dizisi ekleyin:

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

Ardından bağlamaları yeniden üretin:

npx winapp node generate-bindings

StorageFile.js, BitmapDecoder.js ve bağımlı oldukları enum dosyaları (FileAccessMode.js, BitmapPixelFormat.js, …) artık .winapp/bindings/ içinde görünür.

Note

dynwinrt-codegen, bu sınıfları çağırmak için ihtiyaç duyduğunuz bağımlı türleri (örneğin, StorageFile.openAsync tarafından döndürülen IRandomAccessStream) otomatik olarak dahil eder; bu nedenle genellikle yalnızca giriş noktası sınıflarını seçmek yeterlidir.

3. Adım: Elektron kodunuzdan Windows API'leri çağırma

Oluşturulan tüm sınıflar aracılığıyla #winapp/bindingsdışarı aktarılır:

@microsoft/dynwinrt-codegen ≥ 0.1.0-preview.8 gereklidir — eski projeler için alternatifler için Electron ile çalışmaya başlama bölümüne bakın.

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

Ardından bunu ön yükleme betiğiniz aracılığıyla renderer sürecine aktarabilirsiniz:

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

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

Son olarak, render bileşeninize bir düğme ekleyin ve tıklandığında window.winapp.pickAndInspectImage() öğesini çağırın:

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

4. Adım: Çalıştırma

Dosya seçici çalışmadan önce uygulamanızın kimlikle çalıştığından emin olmanız gerekir. Koş!

npx winapp node add-electron-debug-identity

Note

Bu komut, kurulum kılavuzuna postinstall eklediğimiz betiğin bir parçasıdır, bu nedenle komutundan sonra npm installotomatik olarak çalışır. Ancak, uygulama varlıklarını her değiştirdiğinizde Package.appxmanifest, güncelleştirdiğinizde veya bağımlılıkları yeniden yüklediğinizde el ile çalıştırmanız gerekir.

Şimdi uygulamayı başlatın:

npm start

Düğmeye tıklayın: yerel Windows dosya seçici görüntülenir ve bir resim seçtiğinizde düğmenin altında yolu ve piksel boyutları gösterilir. 🎉 .winapp/bindings/'den içe aktarma, @microsoft/dynwinrt'i yükler ve her çağrıyı alttaki WinRT API'sine yönlendirir — kodunuz açısından saydamdır.

Sonraki Adımlar

Tebrikler! Şimdi Windows API'lerini (Windows Uygulama SDK'sı ve Windows SDK'sı) doğrudan JavaScript'ten çağırıyorsunuz. Yerel eklenti ve derleme adımı yoknode-gyp. 🎉

Artık şunu yapmaya hazırsınız:

Veya diğer kılavuzları keşfedin:

Ek Kaynaklar

  • Last updated on