Using ArkUI C/C++ API for Native UI Layout in HarmonyOS

ArkUI Provides C/C++ Environment Interfaces

Through the previous ArkUI Engine series we learned that ArkTS components are ultimately mapped to C++ implementations (e.g., a Row component becomes a RowComponent in C++). While most UI code is written on the ArkTS side, some scenarios require direct C++ calls, prompting Huawei to expose a C‑API.

Comparison with ReactNative

ReactNative maps JavaScript components to native controls via an intermediate layout engine (Yoga). In HarmonyOS the mapping is more complex because the native controls are the ArkTS components themselves, leading to performance overhead. The C‑API offers a direct way to create native UI elements without the extra mapping layer.

Using C‑API for UI Layout

1. Create a Native C++ Project

Start with a standard C++ project. NAPI details are omitted here; see the author’s previous article on NAPI for reference.

2. Link Required Libraries

target_link_libraries(entry PUBLIC libace_napi.z.so libace_ndk.z.so)

3. Obtain ArkUI Module Interfaces

Four enums are provided; developers retrieve the needed capability via OH_ArkUI_GetModuleInterface :

typedef enum {
    ARKUI_NATIVE_NODE,
    ARKUI_NATIVE_DIALOG,
    ARKUI_NATIVE_GESTURE,
    ARKUI_NATIVE_ANIMATE,
} ArkUI_NativeAPIVariantKind;

The function takes the enum value, a version string (currently ArkUI_NativeNodeAPI_1 ), and returns a handle:

OH_ArkUI_GetModuleInterface(nativeAPIVariantKind, structType, structPtr);

4. Create a Native Control Object

For example, to create a native Text node:

ArkUI_NativeNodeAPI_1 *arkUINativeNodeApi_ = nullptr;
OH_ArkUI_GetModuleInterface(ARKUI_NATIVE_NODE, ArkUI_NativeNodeAPI_1, arkUINativeNodeApi_);

ArkUI_NodeHandle textHandle = arkUINativeNodeApi_->createNode(ARKUI_NODE_TEXT);

5. Set Control Attributes

Attributes are set via setAttribute . The example sets the font size:

void SetFontSize(float fontSize) {
    ArkUI_NumberValue value[] = {{.f32 = fontSize}};
    ArkUI_AttributeItem item = {value, 1};
    arkUINativeNodeApi_->setAttribute(textHandle, NODE_FONT_SIZE, &item);
}

6. Bind the Native Control to the UI Tree

On the ArkTS side a ContentSlot placeholder is created, which receives a NodeContent object. The native side obtains this object via OH_ArkUI_GetNodeContentFromNapiValue and then attaches the native node:

napi_value CreateNativeRoot(napi_env env, napi_callback_info info) {
    size_t argc = 1;
    napi_value args[1] = {nullptr};
    napi_get_cb_info(env, info, &argc, args, nullptr, nullptr);
    ArkUI_NodeContentHandle contentHandle;
    OH_ArkUI_GetNodeContentFromNapiValue(env, args[0], &contentHandle);
    return nullptr;
}

OH_ArkUI_NodeContent_AddNode(contentHandle, textHandle);

After these steps the native Text component appears in the HarmonyOS UI.

Summary

The tutorial demonstrates how to create a native Text control using ArkUI’s C‑API and bind it to the ArkTS UI tree. While powerful for special scenarios such as cross‑platform frameworks or high‑performance needs, the approach introduces additional learning and maintenance overhead compared to pure ArkTS development, so it should be used judiciously.

Reference

[1] https://juejin.cn/post/7292044286757470260

[2] https://developer.huawei.com/consumer/cn/doc/harmonyos-guides-V5/arkts-use-ndk-V5