OpenHarmony开源鸿蒙学习入门--API8升级到API9_harmonyos api8 与 api9差异

OpenHarmony开源鸿蒙学习入门–API8升级到API9

前言

首先做API升级的工作，我们一定要先了解API 9的有哪些新特性。做到心中有数。
之后在对比API 8与API 9的区别是什么？如此才能有的放矢，知道做升级应该处理什么。
简要的思路是，先收集API9 官方的信息，上一篇博客已经做过概述，详情见 ==》OpenHarmony开源鸿蒙学习入门–Ability,FA和Stage基本概念理解
因为根据收集到信息，我们已经知道，API 8和9的项目文件包结构有了很大的变化。所以接下来我们需要创建API 8的demo项目。和API 9的demo项目。一是用来对比差异，二是进行模拟的升级操作。

一、新建API 9的DEMO项目

（1）对比创建项目的设置选项：

API 8 创建项目的设置选项：

API 9 创建项目的设置选项：

对比可见，设置项目API 9之后，UI框架语言只能用eTS。
且Model类型也只能选择Stage。【理论上有两个选项，应该是可以自己选择，Stage or FA。但是目前选择点不动FA选项，既然不能选择FA，官方为何不隐藏这个选项呢。费解。】

并且会有不稳定提示：
The SDK of API 9 is now in trial and may be unstable
api9的sdk目前正处于试验过程中，可能还不稳定

（2）项目创建成功之后的设置：

创建项目成功之后，会提示：

npm notice created a lockfile as package-lock.json. You should commit this file.
解决办法：
在package.json中增加private字段，再重新Rebuid，notice就没了

重新Rebuild之后，提示：
hvigor WARN: Will skip sign ‘hap’,
because no valid signingConfig is configured for ‘default’ product
解决办法：
设置项目的自动签名。
Project Structure --> Signing Configs

项目没有任何报错和警告提示，正常编译成功后。我们梳理一下，API 9项目的文件结构。

二、API 8与 API 9的项目文件结构差异：

API 8项目文件结构：

API 9项目文件结构：

!](https://img-blog.csdnimg.cn/adac756439a04590bc54da88a0d6f251.png)

（1）项目配置文件的差异：
API 9的State项目不再使用API8用于管理包信息的config.json。而是使用module.json描述HAP包和组件信息，可以指定入口文件名。

main-->module.json5

{
  "module": {
    "name": "entry",
    "type": "entry",
    "srcEntrance": "./ets/Application/AbilityStage.ts",
    "description": "$string:entry_desc",
    "mainElement": "MainAbility",
    "deviceTypes": [
      "phone",
      "tablet"
    ],
    "deliveryWithInstall": true,
    "installationFree": false,
    "pages": "$profile:main_pages", 【这里调用了profile文件夹的json文件】
    "uiSyntax": "ets",
    "abilities": [
      {
        "name": "MainAbility",
        "srcEntrance": "./ets/MainAbility/MainAbility.ts",
        "description": "$string:MainAbility_desc",
        "icon": "$media:icon",
        "label": "$string:MainAbility_label",
        "visible": true,
        "skills": [
          {
            "entities": [
              "entity.system.home"
            ],
            "actions": [
              "action.system.home"
            ]
          }
        ]
      }
    ]
  }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

（2）项目跳转路径的差异：
在resources文件夹下，多了一个profile文件夹，有个json文件叫做main_pages。根据文件调用可知，是用于项目界面选择。

mian-->resources-->profile-->main_pages.json

{
  "src": [
    "pages/index"
  ]
}

1
2
3
4
5
6
7
8

API 8的config.json 在API 9被拆成了两个部分，路径配置文件main_pages和APP参数设置文件夹AppScope。

{
  "app": {
    "bundleName": "com.example.testapi9project",
    "vendor": "example",
    "versionCode": 1000000,
    "versionName": "1.0.0",
    "icon": "$media:app_icon",
    "label": "$string:app_name",
    "distributedNotificationEnabled": true
  }
}

1
2
3
4
5
6
7
8
9
10
11
12

观察API 9的app.json5文件可知，就是把原先config.json中的app节点单独抽离出来，并且把app 名字和图标也放到一起了，新增了一个属性为distributedNotificationEnabled分布式消息启用，目前还没试过。

最大的变化就是ets文件夹下了。
API 9 多了两个文件夹，分别是Application：

main--》ets--》Application--》AbilityStage.ts

AbilityStage：对应HAP的运行期类，在HAP首次加载到进程中时创建，运行期开发者可见；

Stage模型定义Ability组件的生命周期，只包含创建、销毁、前后台等状态，
而将与界面相关内容强相关的获焦、失焦状态放在WindowStage之中，从而实现Ability与窗口之间的弱耦合。

import AbilityStage from "@ohos.application.AbilityStage"

export default class MyAbilityStage extends AbilityStage {
    onCreate() {
        console.log("[Demo] MyAbilityStage onCreate")
    }
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14

还有MainAbility：

main--》ets--》MainAbility--》MainAbility.ts

Ability：提供生命周期回调，持有AbilityContext，支持组件迁移/协同;

import Ability from '@ohos.application.Ability'

export default class MainAbility extends Ability {
    onCreate(want, launchParam) {
        console.log("[Demo] MainAbility onCreate")
        globalThis.abilityWant = want;
    }

    onDestroy() {
        console.log("[Demo] MainAbility onDestroy")
    }

    onWindowStageCreate(windowStage) {
        // Main window is created, set main page for this ability
        console.log("[Demo] MainAbility onWindowStageCreate")

        windowStage.setUIContent(this.context, "pages/index", null)
    }

    onWindowStageDestroy() {
        // Main window is destroyed, release UI related resources
        console.log("[Demo] MainAbility onWindowStageDestroy")
    }

    onForeground() {
        // Ability has brought to foreground
        console.log("[Demo] MainAbility onForeground")
    }

    onBackground() {
        // Ability has back to background
        console.log("[Demo] MainAbility onBackground")
    }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

Ability生命周期切换以及和AbilityStage、WindowStage之间的调度关系：

项目升级到API 9之后，官方建议除了UI类需要用 .ets 文件，其他逻辑类不涉及华为ets语言的类，都用 .ts文件。从新建的项目中就能发现，只有index.ets 是 eTS文件。

对比可见API 8的pages文件夹和子文件index.ets 没有任何变化。

总结来说，API 8 到 API 9最大的变化，就在于使用Stage model后，生命周期的管理变化了。没有app.ets这个类了。而是多了MainAbility和AbilityStage这两个类进行管理。生命周期具体差异，参见上一篇博客最底下有图==》OpenHarmony开源鸿蒙学习入门–Ability,FA和Stage基本概念理解

（3）总结API 8与 API 9的差异：
在我看来，最大的差异是从创建项目时，选择model为Stage开始埋下的伏笔。按理来说，如果API 9也能选择FA模式，理论上项目文件结构是不用改变的。但是只要选择了Stage模式就会有很大的变化。

第一个是项目配置文件的区别，从config.json 改变为 module.json5

第二个就是生命周期管理的差异，取消了app.ets，新增了MainAbility和AbilityStage。

三、API 8升级到 API 9的修改点：
（1）首先需要对UI文件路径管理的逻辑修改迁移修改。
原先API 8都是在config.json中的pages节点逐一配置，入口文件一般为数组的第一个路径。

      "pages": [
          "pages/index1"
          "pages/index2"
          "pages/index3"
        ],
1
2
3
4
5

而API 9 将路径list单独抽取出来，新建了一个profile-main_pages.json进行管理。

{
  "src": [
    "pages/index"
  ]
}

1
2
3
4
5
6

（2）之后对app相关信息进行修改，将包名，图标，名字等修改到AppScope下的app.json5中

（3）然后修改原app.ets中的生命周期监听逻辑，挪到新的两个类中进行管理

值得注意的是，单例写法，在API 9中需要修改，原先我们都是这么写，在API 8中是没有问题的。但是API 9中会有问题，原因在于引用类的时候，相当于重新创建了该类，所以需要将对象的声明放到类之外，或者使用globalThis引用赋值。

API 8中的写法：
  private static mMapManager = null

  public static Ins(): MapManager{
    if (this.mMapManager == null) {
      this.mMapManager  = new MapManager()
    }
    return this.mMapManager
  }
1
2
3
4
5
6
7
8
9

let mMapManager = null
  
export default class MapManager {

  public static Ins(): MapManager{
    if (mMapManager == null) {
      mMapManager  = new MapManager()
    }
    return mMapManager
  }
}
1
2
3
4
5
6
7
8
9
10
11

 我建议这种写法
 
  public static Ins(): MapManager{
    if (globalThis.MapManager == null) {
      globalThis.MapManager = new MapManager()
    }
    return globalThis.MapManager
  }
1
2
3
4
5
6
7
8

理论上应该还有些API接口的更新和弃用，目前还没遇到，后续补充ing