Creación de un complemento nativo de C++ con notificaciones

En esta guía se muestra cómo crear un complemento nativo de C++ que llama a las API de notificación de SDK de Aplicaciones para Windows en la aplicación Electron. Este es un excelente punto de partida para comprender los complementos nativos antes de profundizar en escenarios más complejos.

Prerrequisitos

Antes de iniciar esta guía, asegúrese de que tiene:

Paso 1: Crear un complemento nativo de C++

Vamos a crear un complemento nativo mediante C++ y node-addon-api. Esto proporciona acceso directo a las API de Windows con un rendimiento máximo.

npx winapp node create-addon

Nota:

Este comando puede pedirle que instale Python o las herramientas de Visual Studio necesarias si aún no las tiene instaladas.

Esto crea una nativeWindowsAddon/ carpeta con:

  • nativeWindowsAddon.cc - El código de C++ que llamará a las API de Windows
  • binding.gyp - Configuración de compilación para node-gyp

El comando también instala las dependencias de desarrollo necesarias (nan, node-addon-api, node-gyp) y agrega un build-nativeWindowsAddon script a package.json:

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

La plantilla generada incluye una función de ejemplo ShowNotification que usa las API de notificación del SDK de Windows. Vamos a comprobar que todo está configurado correctamente mediante la compilación del complemento:

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

Nota:

También puede crear un complemento de C# mediante npx winapp node create-addon --template cs. Los complementos de C# usan node-api-dotnet. Consulte las otras guías para crear complementos o la documentación completa del comando para obtener más opciones.

Paso 2: Probar el complemento generado

Vamos a verificar que el complemento creado funcione llamándolo desde el proceso principal. Abra src/index.js:

  1. Agregue la importación del complemento con las demás require instrucciones en la parte superior:
const nativeWindowsAddon = require('../nativeWindowsAddon/build/Release/nativeWindowsAddon.node');
  1. Llame a la función de notificación al final de la createWindow() función:
const createWindow = () => {
  // ... existing window creation code ...

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

Antes de que la API de notificación funcione, debe asegurarse de que la aplicación se ejecuta con identidad. ¡Corre!

npx winapp node add-electron-debug-identity

Nota:

Este comando ya está incluido en el script postinstall que hemos agregado en la guía de configuración, por lo que se ejecuta automáticamente después de npm install. Sin embargo, debe ejecutarlo manualmente siempre que modifique Package.appxmanifest, actualice los recursos de la aplicación o vuelva a instalar las dependencias.

Ahora ejecute la aplicación:

npm start

Debería ver que aparece una notificación. 🎉 El complemento generado funciona directamente.

⚠️ Problema conocido: Bloqueos de la aplicación o ventana en blanco (haga clic para expandir)

Hay un error conocido de Windows con aplicaciones Electron de empaquetado ligero o disperso que hace que la aplicación se bloquee al iniciar o no mostrar contenido web. El problema se ha corregido en Windows pero aún no se ha propagado a todos los dispositivos.

Consulte Configuración del entorno de desarrollo para obtener una solución alternativa.

Paso 3: Actualizar a notificaciones de SDK de Aplicaciones para Windows

Ahora que hemos confirmado que el complemento funciona, vamos a actualizarlo para usar las API de notificación modernas SDK de Aplicaciones para Windows (Microsoft.Windows.AppNotifications), que proporcionan una mejor experiencia de desarrollador y más características. Ya configuramos el SDK de Aplicaciones para Windows cuando ejecutamos el comando init desde los pasos de configuración.

Abra nativeWindowsAddon/nativeWindowsAddon.cc y reemplace todo el contenido por este código:

#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)

Los cambios clave aquí son cambiar del espacio de nombres Windows.UI.Notifications anterior a las API modernas de Microsoft.Windows.AppNotifications, y utilizar AppNotificationBuilder para construir notificaciones en lugar de construir cadenas XML manualmente. Esto proporciona una API más limpia y fácil de mantener que es coherente con los patrones de SDK de Aplicaciones para Windows.

Paso 4: Recompilación y prueba

Ahora vuelva a generar el complemento con el código actualizado:

npm run build-nativeWindowsAddon

Actualice el mensaje en src/index.js para reflejar el cambio:

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

Vuelva a ejecutar la aplicación:

npm start

Verá la notificación actualizada con las API de SDK de Aplicaciones para Windows modernas.

Pasos siguientes

¡Enhorabuena! ¡Ha creado con éxito un complemento nativo de C++ que llama a las API del SDK de Windows App! 🎉

Ahora ya está listo para:

O explore otras guías:

Recursos adicionales

  • Last updated on