HarmonyOS NEXT应用开发之NAPI封装ArkTS接口案例

最新推荐文章于 2024-08-18 16:06:48 发布

OpenHarmony_小贾

最新推荐文章于 2024-08-18 16:06:48 发布

阅读量1.4k

点赞数 8

分类专栏： HarmonyOS OpenHarmony 移动开发文章标签： harmonyos 华为面试鸿蒙开发 NAPI ArkTS

本文链接：https://blog.csdn.net/maniuT/article/details/136879527

版权

移动开发同时被 3 个专栏收录

956 篇文章 8 订阅

订阅专栏

HarmonyOS

871 篇文章 13 订阅

订阅专栏

OpenHarmony

695 篇文章 15 订阅

订阅专栏

介绍

部分应用的主要开发语言为C/C++，但是HarmonyOS的部分接口仅以ArkTS的形式暴露，因此需要将ArkTS的接口封装为Native接口。本例以DocumentViewPicker的Select方法为例，提供了Napi封装ArkTS API的通用方法，本例包含内容如下：

Native侧与ArkTS侧的相互调用
Native对象转换为ArkTS对象（包括如何在ArkTS侧调用一般形式的Native方法）
线程安全函数的使用
等待线程安全函数的执行结果
多实例情况下，如何在正确的窗口内执行方法

效果图预览

测试说明：

点击"JS线程调用"按钮，从native侧js线程拉起picker
点击"PThread线程调用"按钮，从native侧pthread子线程中拉起picker
拉起picker后，单击直接选择单个文件，长按可选择多个文件
本例在拉起picker时设置了maxSelectNumber=3，最多个选择3个文件

集成说明：

源码集成
参考aki方式集成

使用说明：

[建议]在EntryAbility之外调用registryDocumentViewPickerFn方法，避免多实例下的重复注册
[必须]给每个UIAbility生成唯一的ID属性，可使用generateAbilityID方法
[必须]在UIAbility的onWindowStageCreate中的windowStage.loadContent的回调中调用addUIContext方法
[必须]在UIAbility的onWindowStageCreate中的windowStage.loadContent之后调用setTopAbilityID
[建议]在UIAbility的onWindowStageDestroy中调用removeUIContext方法

实现思路

native侧需要主动调用ets侧的代码，需要将ets侧代码注入到native侧，并在注册时创建函数的引用及线程安全函数，并保存当前线程（js线程）的id及env供后续调用时使用

ets侧：

etswrapper.registryDocumentViewPickerFn(documentViewPickerSelect, documentViewPickerSave);

native侧：

NODE_API_CALL(env, napi_create_threadsafe_function(env, args[0], nullptr, selectWork, 0, 1, nullptr, nullptr,
   nullptr, tsfn::callJSSelect, &(uniContext->selectTsfn)));
NODE_API_CALL(env, napi_create_threadsafe_function(env, args[1], nullptr, saveWork, 0, 1, nullptr, nullptr,
   nullptr, tsfn::callJSSave, &(uniContext->saveTsfn)));
NODE_API_CALL(env, napi_create_reference(env, args[0], 1, &(uniContext->selectRef)));
NODE_API_CALL(env, napi_create_reference(env, args[1], 1, &(uniContext->saveRef)));
uniContext->pickerEnv = env;
uniContext->jsThreadID = fns::getCurrentThreadID();

对于某些有返回值的ets函数，为了获取其返回值，需要对调用线程进行区分：如果是js线程，直接通过napi_call_function发起调用并获得返回值；否则需要等异步线程执行完毕并通过全局变量获取结果然后返回

if (uniContext->jsThreadID != fns::getCurrentThreadID()) {
     status = napi_acquire_threadsafe_function(uniContext->selectTsfn);
     status = napi_call_threadsafe_function(uniContext->selectTsfn, selectParam, napi_tsfn_blocking);
     std::unique_lock<std::mutex> unil(uniContext->resultWaitUtil.lock);
     uniContext->resultWaitUtil.cv.wait(unil, [] { return uniContext->resultWaitUtil.isFinished; });
     return;
 } else {
     status = napi_call_function(uniContext->pickerEnv, nullptr, tsSelect, 4, args, &result);
 }

因为napi中的线程安全函数只能通过napi_threadsafe_function_call_js中的data参数进行传参，因此需要将所需参数全部封装到一个对象中

DocumentViewPickerSelectParam *selectParam = new DocumentViewPickerSelectParam(options, thenWrapper, catchWrapper)

因为本例中的filepicker是异步的，回调函数需要调用者传入，而napi中若需要将native方法直接封装为ets方法对于函数类型是有要求的。因此这里通过将回调函数封装到对象中，通过对象包装来实现将一般类型的函数封装为ets侧的函数：

native侧：

// step：类型声明
class DocumentViewPickerSelectThenCbWrapper {
public:
    documentSelectThenFn thenFn;
    DocumentViewPickerSelectThenCbWrapper(documentSelectThenFn fn) : thenFn(fn) {}
    /**
     * 将对象实例包装为js对象
     */
    napi_value convert2NapiValue(napi_env env);
    /**
     * 参数是string[]，这里面会调用thenFn，ets侧调用
     */
    static napi_value call(napi_env env, napi_callback_info info);
};
// step2：convert2NapiValue方法实现
napi_value etswrapper::DocumentViewPickerSelectThenCbWrapper::convert2NapiValue(napi_env env) {
    napi_value object;
    DocumentViewPickerSelectThenCbWrapper *thenWrapper = new DocumentViewPickerSelectThenCbWrapper(this->thenFn);
    NODE_API_CALL(env, napi_create_object(env, &object));
    NODE_API_CALL(env, napi_wrap(
                           env, object, thenWrapper,
                           [](napi_env env, void *finalize_data, void *finalize_hint) -> void {
                               delete reinterpret_cast<DocumentViewPickerSelectThenCbWrapper *>(finalize_data);
                           },
                           nullptr, nullptr));
    napi_property_descriptor desc[] = {
        {"call", nullptr, DocumentViewPickerSelectThenCbWrapper::call, nullptr, nullptr, nullptr, napi_default,
         nullptr},
    };
    NODE_API_CALL(env, napi_define_properties(env, object, sizeof(desc) / sizeof(*desc), desc));
    return object;
}
// step3：call方法实现
napi_value etswrapper::DocumentViewPickerSelectThenCbWrapper::call(napi_env env, napi_callback_info info) {
    // ...
    napi_value thisArg;
    NODE_API_CALL(env, napi_get_cb_info(env, info, &argc, args, &thisArg, nullptr));
    DocumentViewPickerSelectThenCbWrapper *thenWrapper;
    NODE_API_CALL(env, napi_unwrap(env, thisArg, reinterpret_cast<void **>(&thenWrapper)));
    // ...
    thenWrapper->thenFn(data);
    return nullptr;
}

ets侧：

function documentViewPickerSelect(uiContext: UIContext, options: picker.DocumentSelectOptions, thenWrapper:
StringArrayThenCbWrapper, catchWrapper: CatchCbWrapper): void {
  let documentViewPicker: picker.DocumentViewPicker = new picker.DocumentViewPicker();
  documentViewPicker.select(options).then((value: string[]) => {
    thenWrapper.call(value);
  }).catch((error: BusinessError) => {
    // ...
  })
}

多实例情况下，需要在正确的窗口/UIAbility内执行方法。本例通过监听windowStage的状态加上UIContext.runScopedTask方法来实现：

// step1：
windowStage.on("windowStageEvent", (data: window.WindowStageEventType) => {
  if (data === window.WindowStageEventType.ACTIVE) {
    etswrapper.setTopAbilityID(abilityID);
  }
}

// step2：
function documentViewPickerSelect(uiContext: UIContext, options: picker.DocumentSelectOptions, thenWrapper:
StringArrayThenCbWrapper, catchWrapper: CatchCbWrapper): void {
  uiContext.runScopedTask(() => {
    // ...
  })
}

工程结构&模块类型

   dragtoswitchpictures                             // har包
   |---cpp                                          // cpp源码
   |   |---include                                  // 头文件
   |   |---src                                      // 源码
   |---ets/view
   |   |---MockNativeCallPickerView.ets             // 模拟cpp侧发起调用
   |---ets/wrapper
   |   |---wrapper.ets                              // 封装的js方法

模块依赖

routermodule：模块动态导入使用
common/utils：使用功能描述组件

高性能知识点

不涉及

参考资料

其他说明

本例仅实现了DocumentViewPicker的Select方法，对于Save方法，本例搭建了整体框架，因其实现流程基本与Select方法别无二致，因此本例没有具体实现
TODO：当前使用的是windowStage.on(“windowStageEvent”) 来获取当前活跃窗口对应的UIContext，从理论上来讲，因为事件的处理流程有如下两条并行路径，因此在2in1设备的多实例场景下，直接点击失焦窗口的按钮时，可能会在错误的窗口内响应事件:

                 |->焦点切换->on事件分发
多模事件输入->窗口管理
                 |->arkui->button事件触发

为了能让大家更好的学习鸿蒙（HarmonyOS NEXT）开发技术，这边特意整理了《鸿蒙开发学习手册》（共计890页），希望对大家有所帮助：https://qr21.cn/FV7h05

《鸿蒙开发学习手册》：

如何快速入门：`https://qr21.cn/FV7h05`

基本概念
构建第一个ArkTS应用
……

开发基础知识：`https://qr21.cn/FV7h05`

应用基础知识
配置文件
应用数据管理
应用安全管理
应用隐私保护
三方应用调用管控机制
资源分类与访问
学习ArkTS语言
……

基于ArkTS 开发：`https://qr21.cn/FV7h05`

Ability开发
UI开发
公共事件与通知
窗口管理
媒体
安全
网络与链接
电话服务
数据管理
后台任务(Background Task)管理
设备管理
设备使用信息统计
DFX
国际化开发
折叠屏系列
……

鸿蒙开发面试真题（含参考答案）：`https://qr18.cn/F781PH`

鸿蒙开发面试大盘集篇（共计319页）：`https://qr18.cn/F781PH`

1.项目开发必备面试题
2.性能优化方向
3.架构方向
4.鸿蒙开发系统底层方向
5.鸿蒙音视频开发方向
6.鸿蒙车载开发方向
7.鸿蒙南向开发方向

腾讯T10级高工技术，安卓全套VIP课程全网免费送：`https://qr21.cn/D2k9D5`

OpenHarmony_小贾

关注

8
点赞
踩
19

收藏

觉得还不错? 一键收藏
0
评论
HarmonyOS NEXT应用开发之NAPI封装ArkTS接口案例

部分应用的主要开发语言为C/C++，但是HarmonyOS的部分接口仅以ArkTS的形式暴露，因此需要将ArkTS的接口封装为Native接口。Native侧与ArkTS侧的相互调用Native对象转换为ArkTS对象（包括如何在ArkTS侧调用一般形式的Native方法）线程安全函数的使用等待线程安全函数的执行结果多实例情况下，如何在正确的窗口内执行方法。
复制链接

扫一扫