Создание нативного дополнения C++ с уведомлениями

В этом руководстве показано, как создать собственный C++ аддон, который вызывает API уведомлений Windows App SDK в вашем приложении Electron. Это отличная отправная точка для понимания собственных аддонов перед тем как погрузиться в более сложные сценарии.

Необходимые условия

Перед началом работы с этим руководством убедитесь, что вы:

Шаг 1. Создание нативного дополнения C++

Давайте создадим нативный аддон с помощью C++ и node-addon-api. Это обеспечивает прямой доступ к Windows API с максимальной производительностью.

npx winapp node create-addon

Замечание

Эта команда может заставить установить Python или необходимые средства Visual Studio, если они еще не установлены.

При этом создается папка с: nativeWindowsAddon/

  • nativeWindowsAddon.cc — Код C++ с вызовом API Windows
  • binding.gyp — Конфигурация сборки для node-gyp

Команда также устанавливает необходимые зависимости разработки (nan, node-addon-api, node-gyp) и добавляет скрипт build-nativeWindowsAddon в ваш package.json.

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

Созданный шаблон содержит пример функции ShowNotification, использующую API уведомлений пакета SDK Windows. Давайте убедимся, что всё настроено правильно, выполнив сборку дополнения:

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

Замечание

Вы также можете создать надстройку C# с помощью npx winapp node create-addon --template cs. Надстройки C# используют node-api-dotnet. Дополнительные сведения см. в других руководствах по созданию надстроек или полной документации по командам .

Шаг 2. Тестирование созданной надстройки

Давайте убедимся, что созданная надстройка работает, вызывая ее из основного процесса. Открыть src/index.js:

  1. Добавьте импорт дополнения с другими require инструкциями в верхней части:
const nativeWindowsAddon = require('../nativeWindowsAddon/build/Release/nativeWindowsAddon.node');
  1. В конце функции createWindow() вызовите функцию уведомления.
const createWindow = () => {
  // ... existing window creation code ...

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

Прежде чем API уведомлений начнёт работать, необходимо убедиться, что приложение работает с аутентификацией. Запуск:

npx winapp node add-electron-debug-identity

Замечание

Эта команда уже является частью скрипта postinstall , который мы добавили в руководстве по настройке, поэтому он выполняется автоматически после npm install. Однако его необходимо запускать вручную при изменении Package.appxmanifest, обновлении ресурсов приложения или переустановке зависимостей.

Теперь запустите приложение:

npm start

Появится уведомление! 🎉 Созданная надстройка работает сразу после установки.

⚠️ Известная проблема: сбои приложения или пустое окно (щелкните, чтобы развернуть)

Известна ошибка Windows, связанная с разряженной упаковкой приложений Electron, которая приводит к сбою приложения при запуске или не отображает веб-содержимое. Проблема устранена в Windows, но еще не распространилась на все устройства.

См. инструкции по настройке среды разработки для решения обходным путем.

Шаг 3. Обновление до Windows App SDK для уведомлений

Теперь, когда мы подтвердили работу надстройки, давайте обновим надстройку, чтобы использовать современные API уведомлений Windows App SDK (Microsoft.Windows.AppNotifications), которые обеспечивают лучший опыт разработчика и дополнительные функции. Мы уже настроили Windows App SDK при выполнении команды init в ходе шагов установки.

Откройте nativeWindowsAddon/nativeWindowsAddon.cc и замените все содержимое этим кодом:

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

Основные изменения, внесенные здесь, переходят с старого пространства имен Windows.UI.Notifications на современные API-интерфейсы Microsoft.Windows.AppNotifications и используют AppNotificationBuilder для создания уведомлений вместо создания xml-строк вручную. Это обеспечивает более чистый, более доступный для обслуживания API, совместимый с шаблонами Windows App SDK.

Шаг 4. Перестроение и тестирование

Теперь перестройте надстройку с обновленным кодом:

npm run build-nativeWindowsAddon

Обновите сообщение в src/index.js, чтобы отразить изменение.

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

Запустите приложение еще раз:

npm start

Вы увидите обновленное уведомление с помощью современных API Windows App SDK!

Дальнейшие шаги

Поздравляю! Вы успешно создали собственную надстройку C++, которая вызывает Windows App SDK API! 🎉

Теперь вы готовы:

Или ознакомьтесь с другими руководствами:

Дополнительные ресурсы

  • Last updated on