鸿蒙5.0开辟进阶：利用NAPI封装ArkTS接口实现案例

往期鸿蒙全套实战文章必看：

• 鸿蒙开辟核心知识点，看这篇文章就够了
  
• 最新版！鸿蒙HarmonyOS Next应用开辟实战学习路线
  
• 鸿蒙HarmonyOS NEXT开辟技能最全学习路线指南
  
• 鸿蒙应用开辟实战项目，看这一篇文章就够了（部分项目附源码）
  

---

介绍

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

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

效果图预览

测试阐明：

• 点击"JS线程调用"按钮，从native侧js线程拉起picker
  
• 点击"Thread线程调用"按钮，从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侧：
  
  1. etswrapper.registryDocumentViewPickerFn(documentViewPickerSelect, documentViewPickerSave);

  复制代码
  native侧：
  
  1. NODE_API_CALL(env, napi_create_threadsafe_function(env, args[0], nullptr, selectWork, 0, 1, nullptr, nullptr,
  2.    nullptr, tsfn::callJSSelect, &(uniContext->selectTsfn)));
  3. NODE_API_CALL(env, napi_create_threadsafe_function(env, args[1], nullptr, saveWork, 0, 1, nullptr, nullptr,
  4.    nullptr, tsfn::callJSSave, &(uniContext->saveTsfn)));
  5. NODE_API_CALL(env, napi_create_reference(env, args[0], 1, &(uniContext->selectRef)));
  6. NODE_API_CALL(env, napi_create_reference(env, args[1], 1, &(uniContext->saveRef)));
  7. uniContext->pickerEnv = env;
  8. uniContext->jsThreadID = fns::getCurrentThreadID();

  复制代码
• 对于某些有返回值的ets函数，为了获取其返回值，必要对调用线程进行区分：如果是js线程，直接通过napi_call_function发起调用并得到返回值；否则必要等异步线程执行完毕并通过全局变量获取结果然后返回
  
  1. if (uniContext->jsThreadID != fns::getCurrentThreadID()) {
  2.      status = napi_acquire_threadsafe_function(uniContext->selectTsfn);
  3.      status = napi_call_threadsafe_function(uniContext->selectTsfn, selectParam, napi_tsfn_blocking);
  4.      std::unique_lock<std::mutex> unil(uniContext->resultWaitUtil.lock);
  5.      uniContext->resultWaitUtil.cv.wait(unil, [] { return uniContext->resultWaitUtil.isFinished; });
  6.      return;
  7. } else {
  8.      status = napi_call_function(uniContext->pickerEnv, nullptr, tsSelect, 4, args, &result);
  9. }

  复制代码
• 因为napi中的线程安全函数只能通过napi_threadsafe_function_call_js中的data参数进行传参，因此必要将所需参数全部封装到一个对象中
  
  1. DocumentViewPickerSelectParam *selectParam = new DocumentViewPickerSelectParam(options, thenWrapper, catchWrapper)

  复制代码
• 因为本例中的filepicker是异步的，回调函数必要调用者传入，而napi中若必要将native方法直接封装为ets方法对于函数范例是有要求的。因此这里通过将回调函数封装到对象中，通过对象包装来实现将一般范例的函数封装为ets侧的函数：
  native侧：
  
  1. // step：类型声明
  2. class DocumentViewPickerSelectThenCbWrapper {
  3. public:
  4.     documentSelectThenFn thenFn;
  5.     DocumentViewPickerSelectThenCbWrapper(documentSelectThenFn fn) : thenFn(fn) {}
  6.     /**
  7.      * 将对象实例包装为js对象
  8.      */
  9.     napi_value convert2NapiValue(napi_env env);
  10.     /**
  11.      * 参数是string[]，这里面会调用thenFn，ets侧调用
  12.      */
  13.     static napi_value call(napi_env env, napi_callback_info info);
  14. };
  15. // step2：convert2NapiValue方法实现
  16. napi_value etswrapper::DocumentViewPickerSelectThenCbWrapper::convert2NapiValue(napi_env env) {
  17.     napi_value object;
  18.     DocumentViewPickerSelectThenCbWrapper *thenWrapper = new DocumentViewPickerSelectThenCbWrapper(this->thenFn);
  19.     NODE_API_CALL(env, napi_create_object(env, &object));
  20.     NODE_API_CALL(env, napi_wrap(
  21.                            env, object, thenWrapper,
  22.                            [](napi_env env, void *finalize_data, void *finalize_hint) -> void {
  23.                                delete reinterpret_cast<DocumentViewPickerSelectThenCbWrapper *>(finalize_data);
  24.                            },
  25.                            nullptr, nullptr));
  26.     napi_property_descriptor desc[] = {
  27.         {"call", nullptr, DocumentViewPickerSelectThenCbWrapper::call, nullptr, nullptr, nullptr, napi_default,
  28.          nullptr},
  29.     };
  30.     NODE_API_CALL(env, napi_define_properties(env, object, sizeof(desc) / sizeof(*desc), desc));
  31.     return object;
  32. }
  33. // step3：call方法实现
  34. napi_value etswrapper::DocumentViewPickerSelectThenCbWrapper::call(napi_env env, napi_callback_info info) {
  35.     // ...
  36.     napi_value thisArg;
  37.     NODE_API_CALL(env, napi_get_cb_info(env, info, &argc, args, &thisArg, nullptr));
  38.     DocumentViewPickerSelectThenCbWrapper *thenWrapper;
  39.     NODE_API_CALL(env, napi_unwrap(env, thisArg, reinterpret_cast<void **>(&thenWrapper)));
  40.     // ...
  41.     thenWrapper->thenFn(data);
  42.     return nullptr;
  43. }

  复制代码
  ets侧：
  
  1. function documentViewPickerSelect(uiContext: UIContext, options: picker.DocumentSelectOptions, thenWrapper:
  2. StringArrayThenCbWrapper, catchWrapper: CatchCbWrapper): void {
  3.   let documentViewPicker: picker.DocumentViewPicker = new picker.DocumentViewPicker();
  4.   documentViewPicker.select(options).then((value: string[]) => {
  5.     thenWrapper.call(value);
  6.   }).catch((error: BusinessError) => {
  7.     // ...
  8.   })
  9. }

  复制代码
• 多实例情况下，必要在精确的窗口/UIAbility内执行方法。本例通过监听windowStage的状态加上UIContext.runScopedTask方法来实现：
  
  1. // step1：
  2. windowStage.on("windowStageEvent", (data: window.WindowStageEventType) => {
  3.   if (data === window.WindowStageEventType.ACTIVE) {
  4.     etswrapper.setTopAbilityID(abilityID);
  5.   }
  6. }
  8. // step2：
  9. function documentViewPickerSelect(uiContext: UIContext, options: picker.DocumentSelectOptions, thenWrapper:
  10. StringArrayThenCbWrapper, catchWrapper: CatchCbWrapper): void {
  11.   uiContext.runScopedTask(() => {
  12.     // ...
  13.   })
  14. }

  复制代码

工程结构&模块范例

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

复制代码

免责声明：如果侵犯了您的权益，请联系站长，我们会及时删除侵权内容，谢谢合作！更多信息从访问主页：qidao123.com:ToB企服之家，中国第一个企服评测及商务社交产业平台。