Qt for HarmonyOS Platform API

A Qt application can call HarmonyOS ArkTS APIs directly. This documentation calls them platform APIs. Use them for features that Qt does not cover, such as showing the system share sheet, making an in-app purchase, or refreshing the application's home-screen widgets. Qt does not wrap these APIs.

On HarmonyOS, the ArkTS runtime and the platform UI run on the main thread of the process. This documentation refers to this thread as the JS thread, and to the objects of the ArkTS runtime as JS objects. Qt runs the application on a separate thread, called the Qt thread.

Qt provides the following classes and functions for calling platform APIs:

• QNativeInterface::QHarmonyApplication runs code on the JS thread, where the platform APIs are available, and brings results back to the Qt thread. The code receives a QHarmonyJsContext.
• QHarmonyJsContext provides the Node-API environment and loads JS modules by name.
• QHarmonyAppJsContext gives access to application-level JS objects, such as the default UIAbility instance.
• QHarmonyJsObjectRef keeps a JS object alive. You can store, copy, and compare the reference on any thread, but you can access the object only on the JS thread.
• The QtHarmony namespace contains free functions for code that runs on the JS thread, such as conversions between QJsonObject and JS objects.

Qt's HarmonyOS platform API uses the C Node-API types napi_env and napi_value. They are part of the HarmonyOS SDK and have a stable ABI. Node-API is a low-level, weakly typed C API that requires manual error handling and resource management. It is strongly recommended that applications use node-addon-api, the header-only C++ wrapper for Node-API that the Node.js project publishes. Its types convert to and from the C types at no cost. The snippet in the next section uses it.

The Two Threads

The Qt thread is the thread of the QCoreApplication object, which runs the Qt event loop. Platform APIs are available only on the JS thread. To run code there, pass it as a task to QNativeInterface::QHarmonyApplication::runOnJsThread():

const QJsonObject vibrationEffect{
    {"type", "time"},
    {"duration", 200},
};
const QJsonObject vibrationAttribute{
    {"usage", "touch"},
};

// ...

QNativeInterface::QHarmonyApplication::runOnJsThread(
    [vibrationEffect, vibrationAttribute](QHarmonyJsContext &jsContext) {
        Napi::Env env(jsContext.env());
        Napi::Object vibratorModule(env, jsContext.tryImportModule("@ohos.vibrator"));
        if (vibratorModule.IsEmpty())
            return;

        Napi::Object jsVibrationEffect(env, QtHarmony::mapQJsonObjectToJsObject(env, vibrationEffect));
        Napi::Object jsVibrationAttribute(env, QtHarmony::mapQJsonObjectToJsObject(env, vibrationAttribute));

        auto startVibrationFunc = vibratorModule.Get("startVibration").As<Napi::Function>();
        auto startVibrationPromise = startVibrationFunc.Call(vibratorModule, {jsVibrationEffect, jsVibrationAttribute}).As<Napi::Object>();
        startVibrationPromise.Get("then").As<Napi::Function>().Call(
            startVibrationPromise,
            {
                Napi::Function::New(
                    env,
                    [](const Napi::CallbackInfo &) {
                        qDebug() << "startVibration() succeeded";
                    }),
                Napi::Function::New(
                    env,
                    [](const Napi::CallbackInfo &info) {
                        qWarning() << "startVibration() failed:" << QString::fromStdString(info[0].ToString());
                    }),
            });
    });

Code that runs on the JS thread must follow the rules listed in the QNativeInterface::QHarmonyApplication documentation. To send results back to the Qt thread, use QNativeInterface::QHarmonyApplication::runOnQtThread(). To pass JS data to the Qt thread, convert it to a QJsonObject with QtHarmony::mapJsObjectToQJsonObject(), or keep it in a QHarmonyJsObjectRef.

JS Callbacks

Asynchronous platform APIs return promises or take callbacks. To handle a promise or to pass a callback, create a function with napi_create_function(). Such a function receives the napi_env, but not a QHarmonyJsContext. To get the context, call QHarmonyJsContext::fromEnv(). These functions run on the JS thread and follow the same rules as tasks passed to QNativeInterface::QHarmonyApplication::runOnJsThread().

JS Modules

QHarmonyJsContext::tryImportModule() returns a JS module by name, for example @ohos.app.ability.AbilityConstant. It loads the module on first use. Enumerations are properties of the module object or of a namespace in it. For example, LaunchReason is a property of the @ohos.app.ability.AbilityConstant module object. Enumeration values are properties of their enumeration.

Native code cannot load kits, the @kit.* modules. The ArkTS application template bundled with Qt makes the kit modules that Qt needs available to native code. QHarmonyJsContext::tryImportModule() accepts their names, such as @kit.ShareKit.systemShare.

Platform API Examples

• Qt for HarmonyOS Restart Application Example
• Qt for HarmonyOS Notification Example