Criando um complemento nativo do C++ com notificações

Este guia mostra como criar um complemento nativo do C++ que chama as APIs de notificação SDK do Aplicativo Windows em seu aplicativo Electron. Este é um ótimo ponto de partida para entender os complementos nativos antes de se aprofundar em cenários mais complexos.

Pré-requisitos

Antes de iniciar este guia, verifique se você:

Etapa 1: Criar um complemento nativo do C++

Vamos criar um complemento nativo usando C++ e node-addon-api. Isso fornece acesso direto às APIs de Windows com desempenho máximo.

npx winapp node create-addon

Note

Esse comando pode solicitar que você instale Python ou as ferramentas de Visual Studio necessárias se você ainda não as tiver instalado.

Isso cria uma nativeWindowsAddon/ pasta com:

  • nativeWindowsAddon.cc - Seu código C++ que chamará APIs do Windows
  • binding.gyp – Configuração de build para node-gyp

O comando também instala as dependências de desenvolvimento necessárias (nan, node-addon-api, node-gyp) e adiciona um build-nativeWindowsAddon script ao seu package.json:

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

O modelo gerado inclui uma função de ShowNotification de exemplo que usa as APIs de notificação do SDK Windows. Vamos verificar se tudo está configurado corretamente criando o complemento:

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

Note

Você também pode criar um complemento C# usando npx winapp node create-addon --template cs. Os complementos C# usam node-api-dotnet. Consulte os outros guias para criar complementos ou a documentação de comando completa para obter mais opções.

Etapa 2: Testar o complemento gerado

Vamos verificar se o complemento gerado funciona chamando-o do processo principal. Abrir src/index.js:

  1. Adicione a importação do add-on com suas outras require declarações na parte superior:
const nativeWindowsAddon = require('../nativeWindowsAddon/build/Release/nativeWindowsAddon.node');
  1. Chame a função de notificação ao final da função createWindow().
const createWindow = () => {
  // ... existing window creation code ...

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

Antes que a API de notificação funcione, você precisa garantir que seu aplicativo seja executado com identidade. Execute:

npx winapp node add-electron-debug-identity

Note

Esse comando já faz parte do postinstall script que adicionamos no guia de instalação, portanto, ele é executado automaticamente após npm install. No entanto, você precisa executá-lo manualmente sempre que modificar Package.appxmanifest, atualizar ativos de aplicativo ou reinstalar dependências.

Agora, execute seu aplicativo:

npm start

Você deve ver uma notificação aparecer! 🎉 O complemento gerado funciona prontamente.

⚠️ Problema Conhecido: Falhas de aplicativo ou janela em branco (clique para expandir)

Há um bug de Windows conhecido com aplicativos Electron de empacotamento esparso que faz com que o aplicativo falhe no início ou não renderize o conteúdo da Web. O problema foi corrigido em Windows mas ainda não foi propagado para todos os dispositivos.

Consulte a configuração do ambiente de desenvolvimento para solução alternativa.

Etapa 3: Atualizar as Notificações do SDK do Aplicativo Windows

Agora que confirmamos que o complemento funciona, vamos atualizá-lo para usar as APIs de notificação SDK do Aplicativo Windows modernas (Microsoft.Windows.AppNotifications), que fornecem uma melhor experiência de desenvolvedor e mais recursos. Já configuramos o SDK do Aplicativo Windows quando executamos o comando init nas etapas de instalação.

Abra nativeWindowsAddon/nativeWindowsAddon.cc e substitua todo o conteúdo 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)

As principais alterações aqui estão mudando do namespace Windows.UI.Notifications mais antigo para as APIs Microsoft.Windows.AppNotifications modernas e usando AppNotificationBuilder para construir notificações em vez de criar manualmente cadeias de caracteres XML. Isso fornece uma API mais limpa e mais mantenedível que é consistente com os padrões de SDK do Aplicativo Windows.

Etapa 4: Recompilar e testar

Agora recompile o complemento com o código atualizado:

npm run build-nativeWindowsAddon

Atualize a mensagem src/index.js para refletir a alteração:

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

Execute seu aplicativo novamente:

npm start

Você verá a notificação atualizada usando as APIs de SDK do Aplicativo Windows modernas!

Próximas etapas

Parabéns! Você criou com êxito um complemento C++ nativo que chama APIs de SDK do Aplicativo Windows! 🎉

Agora você está pronto para:

Ou explore outros guias:

Recursos adicionais

  • Last updated on