【鸿蒙南向开发】OpenHarmony 源码解析之JavaScript API框架(NAPI)

1 简介

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

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

1.2 OpenHarmony架构图

1.3 JS UI架构

JS UI框架包括应用层（Application）、前端框架层（Framework）、引擎层（Engine）和平台适配层（Porting Layer），其架构如下图所示：

1.4 NAPI架构

NAPI机制属于JS UI框架中的前端框架层，其架构图如下：

1.5 JS API实现方式

OpenHarmony上JS API实现方式有两种，分别是：JSI机制、NAPI机制。

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

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

2 NAPI机制介绍

2.1 实现原则

• 优先封装异步方法！同步方法可待社区反馈需要时再行添加；
• 若引擎开启Promise特性支持，则异步方法必须同时支持Callback方式和Promise方式；
• 使用哪种方式由应用开发者决定，是否传递Callback进行区分。不传递Callback即为Promise方式，方法执行结果为Promise实例对象；
• L0到L1设备上受限于硬件水平，只实现Callback方式的异步方法；
• L2到L5设备上，必须实现同时支持Callback方式和Promise方式的异步方法。

2.2 异步编程模型

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

2.2.1 Promise 异步模型

Promise对象：

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

Promise特点： 作为对象，Promise有两个特点：

• 对象的状态不受外界影响；

• 一旦状态改变了就不会再变，也就是说任何时候Promise都只有一种状态。

2.2.2 Callback 异步模型

• 用户在调用这些接口的时候，接口实现将异步执行任务；

• 任务执行结果以参数的形式提供给用户注册的回调函数；

• 这些参数的第一个是 Error 或 undefined 类型，分别表示执行出错与正常。

3 实现步骤

3.1 模块注册

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

• 命名：@ohos.模块名

• 注意：

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

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

• 示例：

  static napi