Création d’un complément natif C++ avec notifications

Ce guide vous montre comment créer un module complémentaire natif C++ qui appelle les API de notification SDK d'application Windows dans votre application Electron. Il s’agit d’un excellent point de départ pour comprendre les compléments natifs avant de vous plonger dans des scénarios plus complexes.

Prerequisites

Avant de commencer ce guide, vérifiez que vous avez :

Étape 1 : Créer un complément natif C++

Nous allons créer un module complémentaire natif à l’aide de C++ et node-addon-api. Cela fournit un accès direct aux API Windows avec des performances maximales.

npx winapp node create-addon

Note

Cette commande peut vous inviter à installer Python ou les outils de Visual Studio requis si vous ne les avez pas déjà installés.

Cela crée un nativeWindowsAddon/ dossier avec :

  • nativeWindowsAddon.cc - Votre code C++ qui appelle les API Windows
  • binding.gyp - Configuration de build pour node-gyp

La commande installe également les dépendances de développement requises (nan, , node-addon-apinode-gyp) et ajoute un build-nativeWindowsAddon script à votre package.json:

{
  "scripts": {
    "build-nativeWindowsAddon": "node-gyp clean configure build --directory=nativeWindowsAddon"
  }
}

Le modèle généré inclut un exemple de fonction ShowNotification qui utilise les API de notification Windows SDK. Vérifions que tout est configuré correctement en créant le module complémentaire :

# Build the C++ addon
npm run build-nativeWindowsAddon

Note

Vous pouvez également créer un module complémentaire C# à l’aide de npx winapp node create-addon --template cs. Les compléments C# utilisent node-api-dotnet. Pour plus d’options, consultez les autres guides de création de compléments ou de la documentation complète des commandes .

Étape 2 : Tester le module complémentaire généré

Vérifions que le module complémentaire généré fonctionne en l’appelant à partir du processus principal. Ouvrir src/index.js:

  1. Ajoutez l'import de l'extension avec vos autres instructions require en haut :
const nativeWindowsAddon = require('../nativeWindowsAddon/build/Release/nativeWindowsAddon.node');
  1. Appelez la fonction de notification à la fin de la createWindow() fonction :
const createWindow = () => {
  // ... existing window creation code ...

  // Test the Windows SDK notification
  nativeWindowsAddon.showNotification(
    'Hello from Electron!',
    'This notification uses the Windows SDK.'
  );
};

Avant que l'API de notification fonctionne, vous devez vous assurer que votre application s'exécute sous une identité reconnue. Run:

npx winapp node add-electron-debug-identity

Note

Cette commande fait déjà partie du postinstall script que nous avons ajouté dans le guide d’installation. Elle s’exécute donc automatiquement après npm install. Toutefois, vous devez l’exécuter manuellement chaque fois que vous modifiez Package.appxmanifest, mettez à jour les ressources d’application ou réinstallez les dépendances.

Exécutez maintenant votre application :

npm start

Vous devriez voir apparaître une notification ! 🎉 Le module complémentaire généré fonctionne hors de la boîte.

⚠️ Problème connu : Blocage de l’application ou fenêtre vide (cliquez pour développer)

Il existe un bogue Windows connu avec le conditionnement sparse d'applications Electron qui provoque un plantage de l'application au démarrage ou empêche le rendu du contenu web. Le problème a été résolu dans Windows mais n’a pas encore été propagé à tous les appareils.

Consultez la configuration de l’environnement de développement pour la solution de contournement.

Étape 3 : Mise à niveau vers SDK d'application Windows notifications

Maintenant que nous avons confirmé que le module complémentaire fonctionne, nous allons le mettre à niveau pour utiliser les API de notification modernes SDK d'application Windows (Microsoft.Windows.AppNotifications), qui offrent une meilleure expérience de développement et plus de fonctionnalités. Nous avons déjà configuré le SDK d'application Windows lors de l’exécution de la commande init à partir des étapes de configuration.

Ouvrez nativeWindowsAddon/nativeWindowsAddon.cc et remplacez tout le contenu par ce code :

#include <napi.h>
#include <windows.h>

#include <winrt/Windows.Foundation.h>
#include <winrt/Microsoft.Windows.AppNotifications.h>
#include <winrt/Microsoft.Windows.AppNotifications.Builder.h>

using namespace winrt;
using namespace Microsoft::Windows::AppNotifications;
using namespace Microsoft::Windows::AppNotifications::Builder;

// Function to display a Windows App SDK notification
void ShowNotification(const Napi::CallbackInfo& info) {
    Napi::Env env = info.Env();

    try {
        // Get arguments from JavaScript (title and message)
        if (info.Length() < 2 || !info[0].IsString() || !info[1].IsString()) {
            Napi::TypeError::New(env, "Expected two string arguments: title and message").ThrowAsJavaScriptException();
            return;
        }

        std::string title = info[0].As<Napi::String>();
        std::string message = info[1].As<Napi::String>();

        // Convert to wide strings
        std::wstring wTitle(title.begin(), title.end());
        std::wstring wMessage(message.begin(), message.end());

        // Use AppNotificationBuilder for a cleaner API
        AppNotificationBuilder builder;
        builder.AddText(wTitle);
        builder.AddText(wMessage);
        
        AppNotification notification = builder.BuildNotification();
        AppNotificationManager::Default().Show(notification);

    } catch (const winrt::hresult_error& ex) {
        Napi::Error::New(env, winrt::to_string(ex.message())).ThrowAsJavaScriptException();
    } catch (const std::exception& ex) {
        // Handle exceptions and throw back to JavaScript
        Napi::Error::New(env, ex.what()).ThrowAsJavaScriptException();
    } catch (...) {
        Napi::Error::New(env, "Unknown error occurred").ThrowAsJavaScriptException();
    }
}

// Initialize the module
Napi::Object Init(Napi::Env env, Napi::Object exports) {
    exports.Set(Napi::String::New(env, "showNotification"), Napi::Function::New(env, ShowNotification));
    return exports;
}

NODE_API_MODULE(addon, Init)

Les principales modifications apportées ici passent de l’ancien espace de noms Windows.UI.Notifications aux API modernes Microsoft.Windows.AppNotifications et à l’utilisation de AppNotificationBuilder pour construire des notifications au lieu de créer manuellement des chaînes XML. Cela offre une API plus propre et plus gérable qui est cohérente avec les modèles SDK d'application Windows.

Étape 4 : Reconstruire et tester

Régénérez maintenant le module complémentaire avec le code mis à jour :

npm run build-nativeWindowsAddon

Mettez à jour le message dans src/index.js pour refléter la modification.

nativeWindowsAddon.showNotification(
  'Hello from Electron!',
  'This notification is powered by the Windows App SDK!'
);

Réexécutez votre application :

npm start

Vous verrez la notification mise à jour à l'aide des API de SDK d'application Windows modernes !

Prochaines étapes

Félicitations! Vous avez créé avec succès un module complémentaire natif C++ qui appelle les API du SDK d'applications Windows ! 🎉

Vous êtes maintenant prêt à :

Ou explorez d’autres guides :

Ressources additionnelles

  • Last updated on