Launching EmbeddedUIExtensionAbility with EmbeddedComponent
ArkUI offers a subset of ArkTS capabilities on the native side, excluding features such as declarative UI syntax, custom struct components, and the preset UI component library.
Since API version 20, the ArkUI framework provides the capability to embed EmbeddedComponent components on the native side. This capability relies on the EmbeddedComponent mechanism. EmbeddedComponent is used to embed UI content provided by another EmbeddedUIExtensionAbility component (within the same application) into the current page. EmbeddedUIExtensionAbility runs in an independent process, handling page layout and rendering. This functionality is primarily designed for modular development scenarios that require process isolation.
NOTE
After creating ArkUI_EmbeddedComponentOption with OH_ArkUI_EmbeddedComponentOption_Create, use OH_ArkUI_EmbeddedComponentOption_SetOnError to set the onError callback and OH_ArkUI_EmbeddedComponentOption_SetOnTerminated to set the onTerminated callback. Use OH_ArkUI_NodeUtils_MoveTo for node migration.
When the onTerminated callback is set using OH_ArkUI_EmbeddedComponentOption_SetOnTerminated, the returned want parameter contains only the key-value pairs returned by the provider. Nested parsing is not supported.
Call OH_ArkUI_EmbeddedComponentOption_Dispose to release memory when the EmbeddedComponent component is destroyed.
The width and height attributes must be explicitly set for EmbeddedComponent using setAttribute.
This example demonstrates the basic usage of EmbeddedComponent. For details about ability usage, see EmbeddedComponent. The sample application's bundle name is "com.example.embeddeddemo", and the EmbeddedUIExtensionAbility to be launched within the same application is named "ExampleEmbeddedAbility". This sample requires multi-process permission and can only run on supported devices such as PCs and 2-in-1 devices.
#include <arkui/native_node.h>
#include <arkui/native_type.h>
#include <AbilityKit/ability_base/want.h> // Include the ability want header file.
// Register events.
void onError(int32_t code, const char *name, const char *message) {}
void onTerminated(int32_t code, AbilityBase_Want *want) {}
const unsigned int LOG_PRINT_DOMAIN = 0xFF00;
#define SIZE_300 300
#define SIZE_401 401
#define SIZE_480 480
// ···
// Create a node.
ArkUI_NodeHandle embeddedNode = nodeAPI->createNode(ARKUI_NODE_EMBEDDED_COMPONENT);
// Set properties.
AbilityBase_Element Element = {.bundleName = "com.example.uiextensionandaccessibility",
.abilityName = "ExampleEmbeddedAbility",
.moduleName = "entry"}; // This API is provided by the ability subsystem.
AbilityBase_Want *want = OH_AbilityBase_CreateWant(Element); // The API is provided by the ability subsystem.
if (want == nullptr) {
OH_LOG_Print(LOG_APP, LOG_ERROR, LOG_PRINT_DOMAIN, "AbilityBase_Want", "~PluginManager");
}
ArkUI_AttributeItem itemobjwant = {.object = want};
nodeAPI->setAttribute(embeddedNode, NODE_EMBEDDED_COMPONENT_WANT, &itemobjwant);
auto embeddedNode_option = OH_ArkUI_EmbeddedComponentOption_Create();
auto onErrorCallback = onError;
auto onTerminatedCallback = onTerminated;
OH_ArkUI_EmbeddedComponentOption_SetOnError(embeddedNode_option, onErrorCallback);
OH_ArkUI_EmbeddedComponentOption_SetOnTerminated(embeddedNode_option, onTerminatedCallback);
ArkUI_AttributeItem itemobjembeddedNode = {.object = embeddedNode_option};
nodeAPI->setAttribute(embeddedNode, NODE_EMBEDDED_COMPONENT_OPTION, &itemobjembeddedNode);
// Set basic attributes, such as width and height.
ArkUI_NumberValue value[] = {SIZE_480};
ArkUI_AttributeItem item = {value, sizeof(value) / sizeof(ArkUI_NumberValue)};
value[0].f32 = SIZE_300;
nodeAPI->setAttribute(embeddedNode, NODE_WIDTH, &item);
nodeAPI->setAttribute(embeddedNode, NODE_HEIGHT, &item);
// Create a Column node.
ArkUI_NodeHandle column = nodeAPI->createNode(ARKUI_NODE_COLUMN);
nodeAPI->setAttribute(column, NODE_WIDTH, &item);
ArkUI_NumberValue column_bc[] = {{.u32 = 0xFFF00BB}};
ArkUI_AttributeItem column_item = {column_bc, 1};
nodeAPI->setAttribute(column, NODE_BACKGROUND_COLOR, &column_item);
ArkUI_AttributeItem column_id = {.string = "Column_CAPI"};
nodeAPI->setAttribute(column, NODE_ID, &column_id);
// Mount the component node to the parent node.
nodeAPI->addChild(column, embeddedNode);