Criar um Addon Nativo C++ com Notificações

Este guia mostra-lhe como criar um addon nativo em C++ que chame as APIs de notificação do SDK de Aplicações Windows na sua aplicação Electron. Este é um ótimo ponto de partida para perceber addons nativos antes de entrar em cenários mais complexos.

Pré-requisitos

Antes de começar este guia, certifique-se de que:

Passo 1: Criar um addon nativo em C++

Vamos criar um addon nativo usando C++ e node-addon-api. Isto proporciona acesso direto às APIs do Windows com desempenho máximo.

npx winapp node create-addon

Note

Este comando pode pedir-te para instalar Python ou as ferramentas necessárias do Visual Studio, caso ainda não as tenhas instaladas.

Isto cria uma nativeWindowsAddon/ pasta com:

  • nativeWindowsAddon.cc - O seu código C++ que irá chamar APIs do Windows
  • binding.gyp - Configuração de construção 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 teu package.json:

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

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

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

Note

Também pode criar um addon para C# usando npx winapp node create-addon --template cs. Os addons em C# usam node-api-dotnet. Consulta os outros guias para criar addons ou a documentação completa de comandos para mais opções.

Passo 2: Teste o Addon gerado

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

  1. Adicione a importação do addon com as suas outras require instruções no topo:
const nativeWindowsAddon = require('../nativeWindowsAddon/build/Release/nativeWindowsAddon.node');
  1. Chame a função de notificação no 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 de a API de notificações funcionar, precisa de garantir que a sua aplicação corre com identidade. Corrida:

npx winapp node add-electron-debug-identity

Note

Este comando já faz parte do postinstall script que adicionámos no guia de configuração, por isso corre automaticamente após npm install. No entanto, tens de o executar manualmente sempre que modificas Package.appxmanifest, atualizas assets da aplicação ou reinstalas dependências.

Agora executa a tua aplicação:

npm start

Deverias ver uma notificação a aparecer! 🎉 O add-on gerado funciona imediatamente.

⚠️ Problema Conhecido: A Aplicação Crasha ou Janela Em Branco (clique para expandir)

Existe um bug conhecido no Windows com aplicações Electron em empacotamento esparso que faz com que a aplicação crashe ao iniciar ou não renderize conteúdo web. O problema foi resolvido no Windows, mas ainda não se propagou a todos os dispositivos.

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

Passo 3: Atualizar para Notificações do SDK de Aplicações Windows

Agora que confirmámos que o addon funciona, vamos atualizá-lo para usar as modernas APIs de notificações SDK de Aplicações Windows (Microsoft.Windows.AppNotifications), que oferecem uma melhor experiência de programador e mais funcionalidades. Já configurámos o SDK de Aplicações Windows quando executámos o comando init a partir dos passos de configuraçã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 são a mudança do antigo espaço de nomes Windows.UI.Notifications para as APIs modernas Microsoft.Windows.AppNotifications, e a utilização de AppNotificationBuilder para construir notificações em vez de criar manualmente strings XML. Isto proporciona uma API mais limpa, mais fácil de manter, consistente com os padrões do SDK de Aplicações Windows.

Passo 4: Reconstruir e Testar

Agora reconstrói o addon 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 novamente a sua aplicação:

npm start

Verá a notificação atualizada usando as APIs modernas do SDK de Aplicações Windows!

Próximas Etapas

Parabéns! Criaste com sucesso um addon nativo em C++ que chama APIs do SDK de Aplicações Windows! 🎉

Agora está pronto para:

Ou explore outros guias:

Recursos adicionais

  • Last updated on