JS Mock开发

1. 基础

• API所在目录：
  interface/sdk-js/api

• JS Mock所在目录：
  third_party/jsframework/runtime/main/extend/systemplugin/napi

• 背景
  当前ACE JS应用在DevEco中的PC预览运行环境仅包含ACE子系统代码，不包含其他子系统代码，所以当前无法提供与真机上类似的JS API的功能。
  为了避免开发者在使用JS API时引起页面报错或阻塞页面显示等问题，需要将对应的JS API在Pc预览上进行mock，使得开发者在js中实现的逻辑可以继续执行。
  注意：JS预览器功能依赖于电脑显卡的OpenGL版本，OpenGL版本要求为3.2及以上。（通常桌面云上的版本较低，请使用PC验证）

• 注意事项
  蓝区代码一定要在蓝区环境push到gitee，在黄区push是典型的信息安全违规操作，如没有蓝区环境，请与对应接口华为方人员联系。不要在黄区push！不要在黄区push！不要在黄区push！

2. 实现

• JS API Mock开发文档: link

2.1 新建文件（如无）

1. 在third_party/jsframework/runtime/main/extend/systemplugin/napi目录下增加对应的js文件,文件命名格式与dts文件保持一致。
   例如@ohos.accessibility.d.ts则其对应的js文件名为ohos_accessibility.js

2.2 实现接口

• JS API Mock时，原则是对应对象的成员变量和成员函数要与d.ts文件保持一致

• 接口日志打印需要保持格式一致，为：
  console.warn(‘xxx.xxx interface mocked in the Previewer. How this interface works on the Previewer may be different from that on a real device.’);

• 此处xxx需要替换为对应的对象名称和接口名称，且大小写需要与d.ts文件保持一致。避免在PC预览上提示开发者当前接口被mock时，造成疑惑。如：

• 如果成员变量的属性非基本属性则需先实现自定义属性的定义，在完成该成员属性的定义

class

export的使用，在d.ts中含有class需被其他对象调用其属性值，使用关键字export修饰class

7.3 基本类包含属性和方法

namespace

namespace

2.3 实现返回值

3.JS API Mock时，JS API返回值和异步回调函数的入参，promise的入参要与d.ts文件定义保持一致。
3.1 AysncCallback函数的入参实现，data：T为void类型
在d.ts文件中的定义：
输入图片说明
在mock中的实现：
输入图片说明
3.2 AysncCallback函数的入参实现，data：T非void类型
在d.ts文件中的定义：
输入图片说明
在mock中的实现：
输入图片说明
注意：无论是哪种异步回调函数入参都需要和d.ts文件中定义保持一致
3.3 Callback函数的入参实现，data：T非void类型
在d.ts文件中的定义：
输入图片说明
在Mock中的实现：
输入图片说明
3.3 promise的入参实现（可对照3.1和3.2实例比较）：
在d.ts文件中的定义：
输入图片说明
在Mock中的实现：
输入图片说明
4.如果子系统下面包含多级目录，如mutimedia下面有多个插件media、image等，可以按照dts文件分成多个js文件：
输入图片说明
5.枚举类型作为返回参数时，或者作为回调入参，promise入参时不能直接定义为object。如：
输入图片说明
建议定义为 const osAccountTypeMock = "[PC Preview] unknown OsAccountTypeMock"返回，如果能够确定对应接口里面的枚举返回值，可以返回对应值的mock。
6.枚举类型有作为函数入参时，为防止开发者作为入参使用枚举值时，PC预览不能识别具体枚举参数而报错，需要枚举类型在mock代码中定义。如在d.ts中定义的枚举为：
输入图片说明
mock中增加对应的枚举定义：
输入图片说明
7.class类型定义和实现：
JS API Mock实现class定义需要和d.ts中定义保持一致：
7.1 基本类的定义和实现
在d.ts中的定义：
输入图片说明
在Mock中的定义和实现，要注意静态属性的定义，放在class外：
输入图片说明
7.2 子类的定义和实现：
输入图片说明
在Mock中的定义和实现，在子类继承父类中，super作为函数调用，只能写在子类的构造函数（constructor）里，super代表的是父类的构造函数：
输入图片说明
7.3 基本类包含属性和方法
在d.ts中的定义：
输入图片说明
在Mock中的定义和实现：
输入图片说明
7.4 定义接口（interface）的实现

2.4 枚举类型

3. 验证

3.1 验证环境

1. 使用DevEco Studio 3.0 Beta1及以上版本（使用API9）
   蓝区DevEco获取地址: link

2. 当前验证的功能为DevEco提供的PC预览功能，不依赖任何真机环境，在PC环境下DevEco中运行，请确认验证环境。

3.2 编译替换SDK

1. 下载代码后第一次编译，需要下载预编译二进制工具链
   ./build/prebuilts_download.sh

2. 删除之前目录
   rm -fr out/sdk/ohos-sdk/windows/previewer/common

3. 编译PC预览动态库
   ./build.sh --product-name ohos-sdk

4. 替换SDK
   Openharmony SDK，将编译PC预览动态库中编译出来的out/sdk/ohos-sdk/windows/previewer/common下所有内容替换到DevEco中使用的SDK路径下的previewer/5.x.x.x/common目录下。

5. 替换后白屏
   编译PC预览动态库中编译出来的out/sdk/ohos-sdk/windows/ets或js目录下的三个文件夹，需要替换DevEco使用的SDK路径下ets/或js/5.x.x.x(ide版本会显示不同)/目录下，注意，只替换这几个文件夹不替换对应路径下的配置文件，然后在ets/或js/5.x.x.x（ide版本会显示不同）/build-tools/ets-load目录下执行npm install

2.1.5 提交代码
1.代码提交前，需要自查格式，确保格式没有问题
2.蓝区mock代码需要加入版权头(如果是对2021的mock内容修改改为2021-2022，如果是2022新增mock文件，则改为2022)

3.代码提交前， 需按照d.ts自检补充3.2测试验收三点要求。在蓝区提交的代码一定要在蓝区自验证，并且发给胡益锁wx1119949review时要附上提交链接和对应的d.ts文件链接以及蓝区自验证截图。review完成后，找黄施昱00369912合入
4.代码提交步骤参考：https://gitee.com/openharmony/docs/blob/master/zh-cn/contribute/%E8%B4%A1%E7%8C%AE%E6%B5%81%E7%A8%8B.md 需要符合对应的代码编程规范然后按照贡献流程提交代码。
5.代码需要在蓝区提交至https：//gitee.com/openharmony/third_party_jsframework的master分支， API8的需要先合入master后合入3.1release分支，API9的需要合入master分支

3.测试验收
Mock相关规范可以参考JS API Mock扫描规范：https://gitee.com/huyisuo/third_party_jsframework/wikis/JS%20API%20Mock%20%E6%89%AB%E6%8F%8F%E8%A7%84%E8%8C%83
JS API 是已评审过的d.ts为准编写的JS Moc代码。验收时，应以d.ts为准，在PC预览上使用对应的JS API，执行到对应逻辑时确认以下三点：
1.接口类型实现与d.ts定义一致，即：同步接口、异步回调接口，promise接口等。
2.日志打印提示开发者当前接口时被mock，与真机环境存在差异。
3.接口返回或回调参数数据结构与d.ts一致，保证基本的数据结构框架，数据内容可能与真机存在差异。

fsf

在jsframework代码仓（third_party/jsframework目录下）编写JS API Mock代码,JS API Mock主要分成以下两种情况：
1.1.通过NAPI机制将c++ api封装成JS API(Openharmony框架使用)

注意，在实现对应的JS API方法是，需要在方法中打印日志，提示开发者，当前接口在PC预览场景下被mock，提示日志格式为： console.warn(‘xxx.xxx interface mocked in the Previewer. How this interface works on the Previewer may be different from that on a real device.’);
例如：third_party/jsframework/runtime/main/extend/systemplugin/napi目录下增加ohos_zlib.js文件，则此处xxx需要对应替换为对应接口名称如：zlib.zipFile。
输入图片说明
2.将实现的JS API Mock添加到third_party/jsframework/runtime/main/extend/systemplugin/napi/index.js文件中，以便PC预览时，通过requireNapi调用该API Mock。
输入图片说明
1.3.实现JS API Mock过程中需要注意的地方
tips:为保证dts文件和mock文件的高度统一性，故此在命名中强调以下规范：
最外层的export function统一命名为mockxxx，其次mock的定义对象和接口要与d.ts文件包括大小写保持一致。