NativeXComponent

介绍

本示例主要介绍开发者如何使用ArkUI NDK API创建XComponent组件进行自定义绘制。主要包括：创建组件，获取ArkUI_NodeHandle和OH_ArkUI_SurfaceHolder实例，注册Surface生命周期和无障碍回调，设置可变帧率，获取NativeWindow后使用OpenGL ES/EGL接口在XComponent组件上进行图形绘制。功能主要包括绘制一个五角星，期望帧率设置，点击按钮开启/关闭软键盘，并可以通过点击XComponent区域改变五角星的颜色。

效果预览

绘制五角星	改变颜色

使用说明

1. 安装编译生成的hap包，并打开应用。
2. 点击XComponent组件区域（页面中蓝色五角星所在区域）改变五角星颜色。
3. 点击“单指点击XComponent软键盘消失”对应区域，软键盘拉起；点击XComponent组件区域，软键盘消失。
4. 点击needSoftKeyboard=false 按钮，点击“单指点击XComponent软键盘消失”对应区域，软键盘拉起；点击XComponent组件区域，软键盘不消失。
5. 拖动期望帧率设置下的滑动条，可以控制期望帧率，具体通过打印日志的速度来衡量，日志检索"OnFrameCallback count"关键字。

工程目录

├──entry/src/main
│  ├──cpp                           // C++代码区
│  │  ├──CMakeLists.txt             // CMake配置文件
│  │  ├──napi_init.cpp              // Napi模块注册
│  │  ├──manager                    // 生命周期管理模块
│  │  │  ├──plugin_manager.cpp
│  │  │  └──plugin_manager.h
│  │  ├──render                     // 渲染模块
│  │  │  ├──EGLConst.h
│  │  │  ├──EGLRender.cpp
│  │  │  └──EGLRender.h
|  |  ├──types
|  |  |  ├──libnativerender
|  |  |  |  ├──Index.d.ts
|  |  |  |  ├──oh-package.json5
│  ├──ets                           // ets代码区
│  │  ├──entryability
│  │  │  ├──EntryAbility.ts         // 程序入口类
|  |  ├──entrybackupability
|  |  |  ├──EntryBackupAbility.ets
│  │  ├──pages                      // 页面文件
│  │     ├──Index.ets               // 主界面
|  ├──resources         			// 资源文件目录

具体实现

通过在IDE中创建Native c++ 工程，在c++代码中定义对外接口为BindNode，在ArkTS侧调用该接口用于注册Surface生命周期、事件和无障碍等回调，在回调逻辑中实现绘制五角星的逻辑。

基于OH_ArkUI_SurfaceHolder实例，在Native侧调用OH_ArkUI_XComponent_GetNativeWindow创建NativeWindow实例并初始化 EGL环境。在Native侧的OnsurfaceChanged回调中，传入OH_ArkUI_SurfaceHolder、宽和高，并以此为输入调用EGL相关的接口改变对应NativeWindow的尺寸和内容。

源码参考：main目录下的文件。涉及到的相关接口：

接口名	描述
OH_ArkUI_QueryModuleInterfaceByName(ArkUI_NativeAPIVariantKind type, const char* structName)	获取指定类型的Native模块接口集合。
OH_ArkUI_XComponent_GetNativeWindow(OH_ArkUI_SurfaceHolder* surfaceHolder)	获取与OH_ArkUI_SurfaceHolder实例关联的nativeWindow。
OH_ArkUI_SurfaceHolder_RemoveSurfaceCallback(OH_ArkUI_SurfaceHolder* surfaceHolder, OH_ArkUI_SurfaceCallback* callback)	从OH_ArkUI_SurfaceHolder实例中移除先前添加的Surface生命周期回调。
OH_ArkUI_SurfaceCallback_Dispose(OH_ArkUI_SurfaceCallback* callback)	释放OH_ArkUI_SurfaceCallback对象。
OH_ArkUI_SurfaceHolder_Dispose(OH_ArkUI_SurfaceHolder* surfaceHolder)	释放OH_ArkUI_SurfaceHolder对象。
OH_ArkUI_NodeEvent_GetEventType(ArkUI_NodeEvent* event)	从组件事件获取事件类型。
OH_ArkUI_NodeEvent_GetNodeHandle(ArkUI_NodeEvent* event)	获取触发组件事件的组件对象。
OH_ArkUI_GetNodeHandleFromNapiValue(napi_env env, napi_value frameNode, ArkUI_NodeHandle* handle)	获取ArkTS侧创建的FrameNode节点对象映射到native侧的ArkUI_NodeHandle。
OH_ArkUI_SurfaceHolder_Create(ArkUI_NodeHandle node)	从XComponent节点创建一个OH_ArkUI_SurfaceHolder对象。
OH_ArkUI_SurfaceCallback_Create()	创建一个OH_ArkUI_SurfaceCallback对象。
OH_ArkUI_SurfaceCallback_SetSurfaceCreatedEvent(OH_ArkUI_SurfaceCallback* callback, void (*onSurfaceCreated)(OH_ArkUI_SurfaceHolder* surfaceHolder))	往OH_ArkUI_SurfaceCallback对象中注册onSurfaceCreated回调。
OH_ArkUI_SurfaceCallback_SetSurfaceChangedEvent(OH_ArkUI_SurfaceCallback* callback, void (*onSurfaceChanged)(OH_ArkUI_SurfaceHolder* surfaceHolder, uint64_t width, uint64_t height))	往OH_ArkUI_SurfaceCallback对象中注册onSurfaceChanged回调。
OH_ArkUI_SurfaceCallback_SetSurfaceDestroyedEvent(OH_ArkUI_SurfaceCallback* callback, void (*onSurfaceDestroyed)(OH_ArkUI_SurfaceHolder* surfaceHolder))	往OH_ArkUI_SurfaceCallback对象中注册onSurfaceDestroyed回调。
OH_ArkUI_SurfaceCallback_SetSurfaceShowEvent(OH_ArkUI_SurfaceCallback* callback, void (*onSurfaceShow)(OH_ArkUI_SurfaceHolder* surfaceHolder))	往OH_ArkUI_SurfaceCallback对象中注册onSurfaceShow回调。
OH_ArkUI_SurfaceCallback_SetSurfaceHideEvent(OH_ArkUI_SurfaceCallback* callback, void (*onSurfaceHide)(OH_ArkUI_SurfaceHolder* surfaceHolder))	往OH_ArkUI_SurfaceCallback对象中注册onSurfaceHide回调。
OH_ArkUI_XComponent_RegisterOnFrameCallback(ArkUI_NodeHandle node, void (*callback)(ArkUI_NodeHandle node, uint64_t timestamp, uint64_t targetTimestamp))	为XComponent节点注册onFrame回调。
OH_ArkUI_SurfaceHolder_AddSurfaceCallback(OH_ArkUI_SurfaceHolder* surfaceHolder, OH_ArkUI_SurfaceCallback* callback)	往OH_ArkUI_SurfaceHolder实例注册OH_ArkUI_SurfaceCallback对象。
OH_ArkUI_AccessibilityProvider_Create(ArkUI_NodeHandle node)	从XComponent节点创建一个ArkUI_AccessibilityProvider对象。
OH_ArkUI_XComponent_UnregisterOnFrameCallback(ArkUI_NodeHandle node)	取消注册XComponent节点的onFrame回调。
OH_ArkUI_AccessibilityProvider_Dispose(ArkUI_AccessibilityProvider* provider)	释放ArkUI_AccessibilityProvider对象。
OH_ArkUI_XComponent_SetExpectedFrameRateRange(ArkUI_NodeHandle node, OH_NativeXComponent_ExpectedRateRange range)	为XComponent节点设置预期的帧率范围。
OH_ArkUI_XComponent_SetNeedSoftKeyboard(ArkUI_NodeHandle node, bool needSoftKeyboard)	设置XComponent节点在获得焦点时是否需要显示软键盘。

相关权限

不涉及。

依赖

不涉及。

约束与限制

1. 本示例仅支持标准系统上运行, 支持设备：华为手机。

2. HarmonyOS系统：HarmonyOS 5.0.5 Release及以上。

3. DevEco Studio版本：6.0.0 Release及以上。

4. HarmonyOS SDK版本：HarmonyOS 6.0.0 Release SDK及以上。

下载

如需单独下载本工程，执行如下命令：

git init
git config core.sparsecheckout true
echo ArkUISample/NativeXComponent/ > .git/info/sparse-checkout
git remote add origin https://gitcode.com/harmonyos_samples/guide-snippets.git
git pull origin master