社区编辑申请
注册/登录
OpenHarmony 源码解析之JavaScript API框架(NAPI)
开发 前端
JavaScript Application Programming Interface, JavaScript应用程序编程接口。OpenHarmony上JS API实现方式有三种,分别是:JSI机制、Channel机制、NAPI机制。

想了解更多内容,请访问:

51CTO和华为官方合作共建的鸿蒙技术社区

https://harmonyos.51cto.com

1.NAPI概念

1.1 JS API概念

JS API: JavaScript Application Programming Interface, JavaScript应用程序编程接口。

1.2 JS API实现方式

OpenHarmony上JS API实现方式有三种,分别是:JSI机制、Channel机制、NAPI机制。

JSI机制:L0~L1设备支持。

Channel机制:L3设备支持。

NAPI机制:目前仅L2设备支持,后续须推广到L3~L5设备。

OpenHarmony 源码解析之JavaScript API框架(NAPI)-鸿蒙HarmonyOS技术社区

1.3 NAPI概念

一句话概括NAPI,就是L2设备上的 JS API实现方式。

2.NAPI机制介绍

2.1 实现原则

优先封装异步方法!同步方法可待社区反馈需要时再行添加。

若引擎开启Promise特性支持,则异步方法必须同时支持Callback方式和Promise方式。使用哪种方式由应用开发者决定,以是否传递Callback进行区分。不传递Callback即为Promise方式,方法执行结果为Promise实例对象。

  • L0到L1设备上受限于硬件水平,只实现Callback方式的异步方法;
  • L2到L5设备上,必须实现同时支持Callback方式和Promise方式的异步方法。

2.2 异步编程模型

2.2.1Promise 异步模型

Promise 异步模型是 OHOS 标准异步模型之一。

Promise对象: ES6原生提供了Promise对象,Promise是异步编程的一种解决方案,可以替代传统的解决方案–回调函数和事件。promise对象是一个异步操作的结果,提供了一些API使得异步执行可以按照同步的流表示出来,避免了层层嵌套的回调函数,保证了回调是以异步的方式进行调用的。用户在调用这些接口的时候,接口实现将异步执行任务,同时返回一个 Promise 对象,其代表异步操作的结果。在返回的结果的个数超过一个时,其以对象属性的形式返回。

Promise特点 作为对象,Promise有两个特点:(1)对象的状态不受外界影响;(2)一旦状态改变了就不会再变,也就是说任何时候Promise都只有一种状态。

2.2.2Callback 异步模型

Callback 异步模型是 OHOS 标准异步模型之一。用户在调用这些接口的时候,接口实现将异步执行任务。任务执行结果以参数的形式提供给用户注册的回调函数。这些参数的第一个是 Error 或 undefined 类型,分别表示执行出错与正常。

2.2 实现步骤

2.2.1 模块注册

API集合按业务功能进行模块划分。开发者使用前须import对应的模块。

命名:@ohos.模块名

注意:

  • 模块名须唯一,由ACE团队统一维护,子系统新增模块时须向ACE团队申请。
  • 模块名最好是单个名词。实在不行,也可以由多个名词组成,但必须遵循小驼峰命名规则。
  • 一个模块,一个声明文件(*.d.ts)。声明文件命名遵循@ohos.模块名.d.ts,文件名全小写,单词间无分割。

N-API通过注册函数进行模块的注册,其接受一个全局变量参数,全局变量结构体中定义了模块名及模块初始化函数。在模块的初始化中,我们可以定义模块需要暴露的方法及属性。

示例:

  1. static napi_value StorageExport(napi_env env, napi_value exports) 
  2.  
  3. const char* storageClassName = "Storage"
  4. napi_value storageClass = nullptr; 
  5.  
  6. /* 定义模块需要对外暴露的方法 */ 
  7. static napi_property_descriptor storageDesc[] = { 
  8.     DECLARE_NAPI_FUNCTION("get", JSStorageGet), 
  9.     DECLARE_NAPI_FUNCTION("getSync", JSStorageGetSync), 
  10. }; 
  11.  
  12. /* 定义C++类对应的JavaScript类,包括JS类名、JS构造函数 */ 
  13. napi_define_class(env, storageClassName, strlen(storageClassName), JSStorageConstructor, nullptr, 
  14.                   sizeof(storageDesc) / sizeof(storageDesc[0]), storageDesc, &storageClass); 
  15.  
  16. /* 定义模块需要对外暴露的属性 */ 
  17. static napi_property_descriptor desc[] = { 
  18.     DECLARE_NAPI_PROPERTY("Storage", storageClass), 
  19. }; 
  20.  
  21. /* 设置exports对象属性 */ 
  22. napi_define_properties(env, exports, sizeof(desc) / sizeof(desc[0]), desc); 
  23. return exports; 

模块定义

  1. static napi_module storageModule = { 
  2.     .nm_version = 1, 
  3.     .nm_flags = 0, 
  4.     .nm_filename = nullptr, 
  5.     .nm_register_func = StorageExport, 
  6.     .nm_modname = "storage"
  7.     .nm_priv = ((void*)0), 
  8.     .reserved = { 0 }, 
  9.     }; 

 模块注册

  1. extern "C" __attribute__((constructor)) void StorageRegister() 
  2.     napi_module_register(&storageModule); 

2.2.2 NAPI声明

声明文件模板

@ohos.模块名.d.ts文件:

  1. /** 
  2. * 模块描述 
  3. * @since API版本号,IT Release3 对应 4,以此类推 
  4. * @sysCap 系统能力 
  5. * @devices 支持设备 
  6. * @import 导入模块 
  7. * @permission 权限列表 
  8. */ 
  9. declare namespace 模块名 { 
  10. // 在此处定义功能方法 
  11.  
  12. export default 模块名; 

示例:

声明文件@ohos.storage.d.ts

  1. /** 
  2.  * 存储 
  3.  * @since 3 
  4.  * @sysCap ACE Engine 
  5.  * @devices phone, tablet, tv, wearable, liteWearable, smartVision 
  6.  * @import import storage from '@ohos.storage'
  7.  * @permission N/A 
  8.  */ 
  9. declare namespace storage { 
  10.   // 在此处定义功能方法 
  11.    
  12. export default storage; 

2.2.2 NAPI实现

JS API 调用流程如下图所示:

OpenHarmony 源码解析之JavaScript API框架(NAPI)-鸿蒙HarmonyOS技术社区

接口定义

  1.  /**入参**     
  2.   napi_env:表示一个上下文的变量;   
  3.   napi_callback_info:传递给回调函数的一个封装的数据类型,可以用于获取有关调用时的上下文信息,也可以用于设置回调函数的返回值; 
  4.  
  5.  **返回值**     
  6.  napi_value:对所有js的基本值的一个密闭封装,就是表示一个基本值; 
  7.  */ 
  8.  
  9. static napi_value Get(napi_env env, napi_callback_info info); 
  10. static napi_value GetSync(napi_env env, napi_callback_info info); 

2.2.2.1 同步回调

同步方法调用之后,将阻塞住JS线程直至获取到返回值。

命名:动词+Sync或动词+名词+Sync

格式:

  • 无参:方法名()
  • 有参:方法名Sync(必填参数[, 可选参数])

返回值

声明文件模板

  1. declare namespace 模块名  
  2.    /** 
  3.    * 方法描述 
  4.    * @note 特殊说明 
  5.    * @since (可选,方法支持版本与模块不一致时需标明) 
  6.    * @sysCap 系统能力 
  7.    * @devices 支持设备 (可选,支持设备类型与模块不一致时需标明) 
  8.     * @param 参数 参数说明(可选,没有参数或参数用interface包含时不需要标明) 
  9.    * @return 返回值说明(可选,没有返回值或返回值用interface包含时不需要标明) 
  10.     */ 
  11.  
  12.    // 无参 
  13.    function 方法名Sync(): 返回值类型; 
  14.  
  15.     // 有参 
  16.     function 方法名Sync(必填参数: 参数类型, options?: 可选参数类型): 返回值类型; 
  17.  
  18.     interface 可选参数类型 { 
  19.    参数名: 参数类型; 
  20.     } 
  21.  
  22. export default 模块名; 

示例

声明

  1. declare namespace storage { 
  2.   /** 
  3.    * getSync方法描述 
  4.    * @since 6 
  5.    * @sysCap ACE Enginge 
  6.    * @param key key值说明 
  7.    * @return 返回值说明 
  8.    */ 
  9.   function getSync(key: string,  options?: GetStorageOptions): string; 
  10.    
  11.   interface GetStorageOptions { 
  12.     /** 
  13.      * default参数描述 
  14.      * @since 6 
  15.      * @sysCap ACE Enginge 
  16.      */ 
  17.     default: string; 
  18.   } 
  19.    
  20. export default storage; 

实现

  1. static napi_value GetSync(napi_env env, napi_callback_info info)         
  2.         {        
  3.             size_t requireArgc = 1; 
  4.             size_t argc = 2; //参数个数 
  5.             napi_value argv[2] = { 0 }; //参数定义 
  6.             napi_value thisVar = nullptr; //JS对象的this参数 
  7.             void* data = nullptr; //回调数据指针 
  8.  
  9.             /* 根据环境变量获取参数 */ 
  10.             napi_get_cb_info(env, info, &argc, argv, &thisVar, &data); 
  11.              
  12.             NAPI_ASSERT(env, argc >= requireArgc, "requires 1 parameter"); 
  13.              
  14.             char key[KEY_BUFFER_SIZE] = { 0 }; 
  15.             size_t keyLen = 0; 
  16.             char value[VALUE_BUFFER_SIZE] = { 0 }; 
  17.             size_t valueLen = 0; 
  18.             for (size_t i = 0; i < argc; i++) { 
  19.                 napi_valuetype valueType = napi_undefined; 
  20.                 napi_typeof(env, argv[i], &valueType);   
  21.                 if (i == 0 && valueType == napi_string) { 
  22.  
  23.                     /* 根据JS字符串获取对应的UTF8编码格式的C/C++字符串 */ 
  24.                     napi_get_value_string_utf8(env, argv[i], key, KEY_BUFFER_SIZE, &keyLen); 
  25.                 } else if (i == 1 && valueType == napi_string) { 
  26.                     napi_get_value_string_utf8(env, argv[i], value, VALUE_BUFFER_SIZE, &valueLen); 
  27.                     break; 
  28.                 } else { 
  29.                     NAPI_ASSERT(env, false"type mismatch"); 
  30.                 } 
  31.             } 
  32.             StorageObjectInfo* objectInfo = nullptr; 
  33.  
  34.             /* 根据JS对象获取与之绑定的原生对象实例 */ 
  35.             napi_unwrap(env, thisVar, (void**)&objectInfo); 
  36.             auto itr = g_keyValueStorage.find(key); 
  37.             napi_value result = nullptr; // JS字符串对象 
  38.             if (itr != g_keyValueStorage.end()) { 
  39.                  
  40.                 /* 根据UTF8编码格式的 C/C++字符串 创建一个 JS字符串对象 */ 
  41.                 napi_create_string_utf8(env, itr->second.c_str(), itr->second.length(), &result); 
  42.             } else if (valueLen > 0) { 
  43.                 napi_create_string_utf8(env, value, valueLen, &result); 
  44.             } else { 
  45.                 objectInfo->Emit(nullptr, "error"); 
  46.                 NAPI_ASSERT(env, false"key does not exist"); 
  47.             } 
  48.             return result; //返回JS对象 
  49.         } 

2.2.2.2 异步回调

异步方法调用整个过程不会阻碍调用者的工作。

命名:动词或动词+名词

格式:

  • 无参:方法名([回调函数])
  • 有参:方法名(必填参数[, 可选参数][, 回调函数])

返回值

  • 若回调函数非空,则返回void
  • 若回调函数为空,则返回Promise实例对象

声明文件模板

  1. declare namespace 模块名 { 
  2.  
  3. /** 
  4. * 方法描述 
  5. * @note 特殊说明 
  6. * @since (可选,方法支持版本与模块不一致时需标明) 
  7. * @sysCap 系统能力 
  8. * @devices 支持设备 (可选,支持设备类型与模块不一致时需标明) 
  9. * @param 参数 参数说明(可选,没有参数或参数用interface包含时不需要标明) 
  10. */ 
  11.  
  12. // 无参 
  13. function 方法名(callback: AsyncCallback<结果数据类型>): void; 
  14. function 方法名(): Promise<结果数据类型>; 
  15.  
  16. // 有参 
  17. function 方法名(必填参数: 参数类型, callback: AsyncCallback<结果数据类型>): void; 
  18. function 方法名(必填参数: 参数类型, options: 可选参数类型, callback: AsyncCallback<结果数据类型>): void; 
  19. function 方法名(必填参数: 参数类型, options?: 可选参数类型): Promise<结果数据类型>; 
  20.  
  21. interface 可选参数类型 { 
  22.  参数名: 参数类型; 
  23.  
  24. export default 模块名; 

示例:

声明

  1. import { AsyncCallback } from './basic'
  2.  
  3. declare namespace storage { 
  4. /** 
  5. * get方法描述 
  6. * @note N/A 
  7. * @since 5 
  8. * @sysCap ACE Engine 
  9. * @devices phone, tablet, tv, wearable 
  10. * @param key key值说明 
  11. */ 
  12. function get(key: string, callback: AsyncCallback<string>): void; 
  13. function get(key: string, options: GetStorageOptions, callback: AsyncCallback<string>): void; 
  14. function get(key: string, options?: GetStorageOptions): Promise<string>; 
  15.  
  16. interface GetStorageOptions { 
  17. default: string; 
  18.  
  19. export default storage; 

实现

异步回调流程如下图所示:

OpenHarmony 源码解析之JavaScript API框架(NAPI)-鸿蒙HarmonyOS技术社区
  1. static napi_value Get(napi_env env, napi_callback_info info) 
  2.     size_t requireArgc = 1; 
  3.     size_t argc = 3; //参数个数 
  4.     napi_value argv[3] = { 0 }; //参数定义 
  5.     napi_value thisVar = nullptr; //JS对象的this参数 
  6.     void* data = nullptr; //回调数据指针 
  7.  
  8.     /* 根据环境变量获取参数 */ 
  9.     napi_get_cb_info(env, info, &argc, argv, &thisVar, &data); 
  10.  
  11.     NAPI_ASSERT(env, argc >= requireArgc, "requires 1 parameter"); 
  12.  
  13.     /* 异步接口上下文,用于接收JS接口传进来的环境变量、参数、回调函数、接口返回值等*/ 
  14.     auto asyncContext = new StorageAsyncContext(); 
  15.  
  16.     asyncContext->env = env; 
  17.  
  18.     for (size_t i = 0; i < argc; i++) { 
  19.         napi_valuetype valueType = napi_undefined; 
  20.         napi_typeof(env, argv[i], &valueType); 
  21.  
  22.         if ((i == 0) && (valueType == napi_string)) { 
  23.  
  24.             /* 根据JS字符串获取对应的UTF8编码格式的C/C++字符串 */ 
  25.             napi_get_value_string_utf8(env, argv[i], asyncContext->key, KEY_BUFFER_SIZE, &asyncContext->keyLen); 
  26.         } else if (valueType == napi_string) { 
  27.             napi_get_value_string_utf8(env, argv[i], asyncContext->value, VALUE_BUFFER_SIZE, &asyncContext->valueLen); 
  28.         } else if (valueType == napi_function) { 
  29.  
  30.             /* 根据JS对象参数argv[i]新建引用 */ 
  31.             napi_create_reference(env, argv[i], 1, &asyncContext->callbackRef); 
  32.             break; 
  33.         } else { 
  34.             NAPI_ASSERT(env, false"type mismatch"); 
  35.         } 
  36.     } 
  37.  
  38.     napi_value result = nullptr; 
  39.  
  40.     if (asyncContext->callbackRef == nullptr) { 
  41.  
  42.         /* Promise方式异步调用,创建延迟对象、JS Promise对象,使二者进行关联 */ 
  43.         napi_create_promise(env, &asyncContext->deferred, &result); 
  44.     } else { 
  45.  
  46.         /* Callback方式异步调用,不需要返回Promise对象,返回一个JS未定义值 */ 
  47.         napi_get_undefined(env, &result); 
  48.     } 
  49.  
  50.     /* 根据JS对象获取与之绑定的原生对象实例 */ 
  51.     napi_unwrap(env, thisVar, (void**)&asyncContext->objectInfo); 
  52.  
  53.     napi_value resource = nullptr; 
  54.     napi_create_string_utf8(env, "JSStorageGet", NAPI_AUTO_LENGTH, &resource); //获取JS异步资源名称 
  55.  
  56.     /* 创建异步工作 */ 
  57.     napi_create_async_work( 
  58.         env, nullptr, resource, 
  59.          
  60.         /* 执行异步逻辑的原生函数 */ 
  61.         [](napi_env env, void* data) { 
  62.             StorageAsyncContext* asyncContext = (StorageAsyncContext*)data; 
  63.             auto itr = g_keyValueStorage.find(asyncContext->key); 
  64.             if (itr != g_keyValueStorage.end()) { 
  65.                 if (strncpy_s(asyncContext->value, VALUE_BUFFER_SIZE, itr->second.c_str(), itr->second.length()) == 
  66.                     -1) { 
  67.                     asyncContext->status = 1; //失败 
  68.                 } else { 
  69.                     asyncContext->status = 0; //成功 
  70.                 } 
  71.             } else { 
  72.                 asyncContext->status = 1; //失败 
  73.             } 
  74.         }, 
  75.  
  76.         /* 异步函数执行完成或者取消后,需要执行的后处理函数 */ 
  77.         [](napi_env env, napi_status status, void* data) { 
  78.             StorageAsyncContext* asyncContext = (StorageAsyncContext*)data; 
  79.             napi_value result[2] = { 0 }; 
  80.             if (!asyncContext->status) { 
  81.                 napi_get_undefined(env, &result[0]); 
  82.                 napi_create_string_utf8(env, asyncContext->value, strlen(asyncContext->value), &result[1]); 
  83.             } else { 
  84.                 napi_value message = nullptr; 
  85.                 napi_create_string_utf8(env, "key does not exist", NAPI_AUTO_LENGTH, &message); 
  86.                 napi_create_error(env, nullptr, message, &result[0]); 
  87.                 napi_get_undefined(env, &result[1]); 
  88.                 asyncContext->objectInfo->Emit(nullptr, "error"); 
  89.             } 
  90.             if (asyncContext->deferred) { 
  91.                 if (!asyncContext->status) { 
  92.  
  93.                     /* 异步函数执行成功后,执行成功后处理函数 */ 
  94.                     napi_resolve_deferred(env, asyncContext->deferred, result[1]);  
  95.                 } else { 
  96.  
  97.                     /* 异步函数执行失败后,执行失败后处理函数 */ 
  98.                     napi_reject_deferred(env, asyncContext->deferred, result[0]); 
  99.                 } 
  100.             } else { 
  101.                 napi_value callback = nullptr; 
  102.                 napi_get_reference_value(env, asyncContext->callbackRef, &callback); 
  103.                 napi_call_function(env, nullptr, callback, sizeof(result) / sizeof(result[0]), result, nullptr); 
  104.                 napi_delete_reference(env, asyncContext->callbackRef); 
  105.             } 
  106.  
  107.             /* 异步回调完成后进行资源释放 */ 
  108.             napi_delete_async_work(env, asyncContext->work); 
  109.             delete asyncContext; 
  110.         }, 
  111.  
  112.         /* 用户数据上下文,此数据传递给异步执行函数与后处理函数 */ 
  113.         (void*)asyncContext, 
  114.  
  115.         /* 生成的异步工作*/ 
  116.          &asyncContext->work); 
  117.     napi_queue_async_work(env, asyncContext->work); //异步工作入队列,排队执行 
  118.  
  119.     return result; 

3. 应用代码示例

JS应用引用NAPI接口时,须先引用接口定义的对应模块,才能进行接口的调用。

  1. import storage from '@ohos.storage' 
  2. export default {  
  3.  
  4.     testGetSync() { 
  5.         //同步接口   
  6.         var name = storage.getSync('name');          
  7.         console.log('name is ' + name);  
  8.     },  
  9.     testGet() {  
  10.         //异步接口 
  11.         storage.get('name') .then(date => console.log('name is ' + data) ) .catch(error => console.log('error: ' + error) );  
  12.     }  
  13. }  

想了解更多内容,请访问:

51CTO和华为官方合作共建的鸿蒙技术社区

https://harmonyos.51cto.com

 

责任编辑:jianghua 来源: 鸿蒙社区
相关推荐

2021-12-08 15:07:51

2021-12-06 06:19:03

2022-06-13 14:18:39

电源管理子系统耗电量服务

2022-05-11 15:08:52

驱动开发系统移植

2021-12-17 16:42:09

2022-04-06 11:27:05

harmonyeTS 开发NAPI开发

2021-11-08 15:04:47

2022-04-02 20:45:04

Hi3516开发板操作系统鸿蒙

2022-01-10 15:30:11

2022-04-20 20:28:40

HDF 驱动框架鸿蒙操作系统

2022-04-18 10:37:01

鸿蒙操作系统开发工具

2022-06-07 10:33:29

Camera组件鸿蒙

2022-06-27 17:46:53

PythonFlask

2022-05-24 15:46:51

Wi-FiSTA模式

2022-05-11 14:54:02

输入法框架鸿蒙

2021-11-25 09:54:54

2022-06-14 15:07:04

IPC客户端服务端

2022-06-07 10:40:05

蓝牙鸿蒙

2022-04-01 15:18:04

HarmonyHDF 驱动鸿蒙

2022-05-16 11:50:45

HDF驱动框架

同话题下的热门内容

手把手教你用装饰器扩展 Python 计时器IOC-Golang 的 AOP 原理与应用Vue 里,多级菜单要如何设计才显得专业?分析了 700 万份工作需求,市场需求最高的八种编程语言是这些Vue 2.7 正式发布,代号为 Naruto手把手教你实现一个 Python 计时器2022 年编程语言趋势:Swift、Kotlin 热度持续增长,收入最高的五种语言竟是它们分布式事务(Seata) 四大模式详解

编辑推荐

太厉害了,终于有人能把TCP/IP协议讲的明明白白了!牛人5次面试腾讯不成功的经验HBase原理–所有Region切分的细节都在这里了Javascript如何监听页面刷新和关闭事件如何搭建一个HTTPS服务端
我收藏的内容
点赞
收藏

51CTO技术栈公众号