Qt for HarmonyOS Platform API
Note: Qt's HarmonyOS platform API is in Technology Preview and may change in future releases.
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
UIAbilityinstance, and registers delegates forUIAbilitymethods. - 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.
- QNativeInterface::QHarmonyWindow provides the ability that shows a QWindow, and the
window.Windowthat the QWindow is shown in. - QNativeInterface::QHarmonyScreen provides the ID of the display that a QScreen represents.
- 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().
Window-Bound Platform APIs
QHarmonyAppJsContext::defaultAbility() is meant for calls that concern the application as a whole. Some platform APIs are bound to a particular window, for example a picker that opens over the window, or an ability started from it. These APIs need the UIAbility instance that shows the window, or the window's window.Window.
To get them, use QNativeInterface::QHarmonyWindow, which is available through QWindow::nativeInterface<QNativeInterface::QHarmonyWindow>(). It returns both as QHarmonyJsObjectRef handles. You get the handles on the Qt thread and use the objects they refer to on the JS thread.
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.
UIAbility Delegates
Some platform callbacks reach only the application's HarmonyOS UIAbility class, which the ArkTS application template bundled with Qt implements. onNewWant() delivers a Want to a running ability, and onContinue() asks whether the ability may be migrated to another device. To receive such calls, register a delegate with QHarmonyAppJsContext::addUiAbilityDelegate(). A delegate is a JS object whose methods Qt calls from the matching UIAbility methods, with the UIAbility instance as the first argument, followed by the arguments of the UIAbility method. The function's documentation lists the forwarded methods and the rules for each.
Delegate methods run on the JS thread and follow the same rules as tasks passed to QNativeInterface::QHarmonyApplication::runOnJsThread(). The handle that addUiAbilityDelegate() returns can be released on any thread. Releasing it on another thread blocks that thread until the JS thread has unregistered the delegate.
The following class receives new Wants as QJsonObject on the Qt thread. It registers the delegate in its constructor, and the handle is released when the receiver is destroyed:
class WantReceiver : public QObject
{
public:
WantReceiver()
{
m_delegateHandle = QNativeInterface::QHarmonyApplication::runOnJsThreadAndWait(
[self = QPointer<WantReceiver>(this)](QHarmonyJsContext &jsContext) {
Napi::Env env(jsContext.env());
Napi::Object delegate = Napi::Object::New(env);
delegate.Set(
"onNewWant",
Napi::Function::New(
env,
[self](const Napi::CallbackInfo &info) {
const QJsonObject want = QtHarmony::mapJsObjectToQJsonObject(info.Env(), info[1]);
QNativeInterface::QHarmonyApplication::runOnQtThread(
[self, want]() {
if (self)
self->handleNewWant(want);
});
}));
return QHarmonyAppJsContext::fromJsContext(jsContext).addUiAbilityDelegate(delegate);
});
}
private:
void handleNewWant(const QJsonObject &want);
std::shared_ptr<void> m_delegateHandle;
};Platform API Examples
© 2026 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.