【鸿蒙南向开发】OpenHarmony应用开发模型详解

开发环境

IDE： DevEco Studio 3.0 Release（Build Version: 3.0.0.993）

SDK：Api Version8 和 9

Ability 模型

Ability 分为 FA 和 Stage 两种模型，在 API 8 及其更早版本的应用程序只能使用 FA 模型进行开发，而从 API 9 开始，Ability 框架引入了 Stage 模型作为第二种应用框架形态。FA 与 Stage 这两种模型在工程目录结构，配置文件以及在应用上下文 context 能力的运用上有较大区别。

工程结构

FA 模型目录结构

└── entry
    └── src
        └── main
            ├── ets
            |   └── MainAbility      //应用/服务的入口
            |       ├── pages        //MainAbility包含的页面
            |       |   └── index.ets     //pages列表中的第一个页面，即应用的首页入口
            |       └── app.ets       //承载Ability生命周期
            ├── resources         //用于存放应用/服务所用到的资源文件，如图形、多媒体、字符串、布局文件等
            |   └── base          
            |       ├── element     //包括字符串、整型数、颜色、样式等资源的json文件，每个资源均由json格式进行定义
            |       |   └── string.json
            |       └── media      //多媒体文件，如图形、视频、音频等文件，支持的文件格式包括：.png、.gif、.mp3、.mp4等
            |           └── icon.png
            └── config.json

Stage 模型目录结构

├── AppScope
|   ├── resources
|   |   └── base
|   |       ├── element    //包括字符串、整型数、颜色、样式等资源的json文件，每个资源均由json格式进行定义
|   |       |   └── string.json   
|   |       └── media      //多媒体文件，如图形、视频、音频等文件，支持的文件格式包括：.png、.gif、.mp3、.mp4等
|   |           └── app_icon.png    
|   └── app.json5     //应用的全局配置，同一应用的不同.hap文件必须使用相同的应用配置
└── entry      //OpenHarmony工程模块，编译构建生成一个Hap包
    └── src
        └── main
            ├── ets     //用于存放ets源码
            |   ├── Application      //模块的入口
            |   |   └── AbilityStage.ts    
            |   ├── MainAbility      //模块对应ability的入口
            |   |   └── MainAbility.ts     
            |   └── pages       //模块包含的页面
            |       └── index.ets   
            ├── resources     
            |   └── base 
            |       ├── element
            |       |   └── string.json
            |       ├── media
            |       |   └── icon.png
            |       └── profile
            |           └── main_pages.json   
            └── module.json5

配置文件

FA 模型(config.json)
config.json 由 app、deviceConfig 和 module 三个部分组成，缺一不可。配置文件的内部结构说明如下表。

表配置文件的内部结构说明

module 对象的内部结构中 abilities 对象的内部结构说明

表 1 metaData 对象的内部结构说明

表 2 uriPermission 对象的内部结构说明

abilities 示例：

"abilities": [
    {
        "name": ".MainAbility",
        "description": "test main ability",
        "icon": "$media:ic_launcher",
        "label": "$media:example",
        "launchType": "standard",
        "orientation": "unspecified",
        "permissions": [], 
        "visible": true,
        "skills": [
            {
                "actions": [
                    "action.system.home"
                ],
                "entities": [
                    "entity.system.home"
                ]
            }
        ],
        "configChanges": [
            "locale", 
            "layout", 
            "fontSize", 
            "orientation"
        ], 
        "type": "page",
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:red",
        "removeMissionAfterTerminate": true
    },
    {
        "name": ".PlayService",
        "description": "example play ability",
        "icon": "$media:ic_launcher",
        "label": "$media:example",
        "launchType": "standard",
        "orientation": "unspecified",
        "visible": false,
        "skills": [
            {
                "actions": [
                    "action.play.music",
                    "action.stop.music"
                ],
                "entities": [
                    "entity.audio"
                ]
            }
        ],
        "type": "service",
        "backgroundModes": [
            "audioPlayback"
        ]
    },
    {
        "name": ".UserADataAbility",
        "type": "data",
        "uri": "dataability://com.example.world.test.UserADataAbility",
        "visible": true
    }
]

Stage 模型(module.json5)

配置文件由 app 和 module 这两个部分组成，缺一不可。配置文件的内部结构说明如下表。

表 配置文件的内部结构说明

module 对象的内部结构中 abilities 对象的内部结构说明

abilities 示例

{
    "abilities": [{
        "name": "MainAbility",
        "srcEntrance": "./ets/login/MyLoginAbility.ts",
        "launchType":"standard",
        "description": "$string:description_main_ability",
        "icon": "$media:icon",
        "label": "Login",
        "permissions": [],
        "metadata": [],
        "visible": true,
        "continuable": true,
        "skills": [{
            "actions": ["action.system.home"],
            "entities": ["entity.system.home"],
            "uris": []
        }],
        "backgroundModes": [
            "dataTransfer",
            "audioPlayback",
            "audioRecording",
            "location",
            "bluetoothInteraction",
            "multiDeviceConnection",
            "wifiInteraction",
            "voip",
            "taskKeeping"
        ],
        "startWindowIcon": "$media:icon",
        "startWindowBackground": "$color:red",
        "removeMissionAfterTerminate": true,
        "orientation": " ",
        "supportWindowMode": ["fullscreen", "split", "floating"],
        "maxWindowRatio": 3.5,
        "minWindowRatio": 0.5,
        "maxWindowWidth": 2560,
        "minWindowWidth": 1400,
        "maxWindowHeight": 300,
        "minWindowHeight": 200,
        "excludeFromMissions": false
    }]
}

应用上下文

Context 是应用中对象的上下文，提供获取应用程序环境信息的能力。

OpenHarmony 的应用框架分为 FA 模型和 Stage 两种模型。对应存在两套 Context 机制适配两种应用框架模型，其中 application/BaseContext 属于通用的 Context 基类，里面包含一个属性 stageMode，用来区分开发模型是 FA 还是 Stage。

只有 app/Context 中的方法属于 FA 模型对应的 Context。该模式下，应用级别的 Context 和 Ability 级别的 Context 都是该类型的实例，如果在应用级别的 Context 里面调用了 Ability 级别的方法，会产生错误。所以开发者需要注意 Context 实例所代表的实际含义。

除了 app/Context 之外的 Context 都属于 Stage 模型，分别有 application/Context、application/ApplicationContext、application/AbilityStageContext、application/ExtensionContext、application/AbilityContext、application/FormExtensionContext 等 Context。

FA 模型的 Context

只有 app/Context 中的方法属于 FA 模型对应的 Context，FA 模型只有一个 Context 定义。

Context 中所有的功能都是通过方法来提供的，它提供了一些 featureAbility 中不存在的方法，相当于 featureAbility 的一个扩展和补全。

使用说明

Context 对象是在 featureAbility 中创建实例，并通过 featureAbility 的 getContext()接口返回，因此在使用 Context 时，必须导入 @ohos.ability.featureAbility 库。

示例

import featureAbility from '@ohos.ability.featureAbility'
// 获取Context并调用相关方法
let context = featureAbility.getContext();
context.getOrCreateLocalDir()

Stage 模型的 Context

Stage 模型下，每个 Ability 中都包含了一个 Context 属性，由 AbilityContext 实现操作 Ability 的方法(如 startAbility、connectAbility 等)。

AbilityContext 是 Ability 的上下文环境，继承自 Context，Context 里面提供了应用的一些基础信息：resourceManager、applicationInfo、cacheDir、area 等，还有应用的一些基本方法：createBundleContext 等。

AbilityContext 模块提供允许访问特定于 ability 的资源的能力，包括对 Ability 的启动、停止的设置、获取 caller 通信接口、拉起弹窗请求用户授权等。

使用说明

在 Ability 生命周期中使用 AbilityContext 的功能，需要通过 Ability 子类实例 context 获取。

示例

import Ability from '@ohos.application.Ability'
class MainAbility extends Ability {
    ... ...
    onWindowStageCreate(windowStage) {
        // 通过子类实例context(后者)，获取AbilityContext并调用相关方法
        let context = this.context;
    }
    ... ...
}

在 UI 页面或其他自定义方法页面，可通过全局 getContext 函数调用 AbilityContext 相关功能，getContext 中的 this 参数指向当前 UI 组件名或方法名，作为全局 getContext 函数的区分。

getContext 函数属于 Context 类型，此时的 Context 是一个定义上下文的模拟对象。

示例

@Entry
@Component
export struct Index {
    private context = getContext(this)
    ...
    aboutToAppear() {
        this.context.filesDir
    }
}

常见错误使用方式

Stage 模型通过 globalThis 去获取 Context

案例

在生命周期中使用 globalThis 获取 Abilitycontext 的能力，然后在 UI 页面使用 globalThis 去调用 Abilitycontext 的相关方法，如下实例：

//MainAbility.ts
onWindowStageCreate(windowStage) {
    // Main window is created, set main page for this ability
    console.log("[Demo] MainAbility onWindowStageCreate")
        // 通过globalThis.context调用子类context，获取AbilityContext并调用相关方法
    globalThis.context = this.context
    windowStage.setUIContent(this.context, "pages/nav", null)
}
​
//index.ets
@Entry
@Component
struct Index {
    aboutToAppear() {
        globalThis.context.filesDir
    }

    build() {
        ...
    }
}
​

原因

在 API8 的 FA 模型下，每个 Ability 实例有一个 js 虚拟机实例，所以可以从 js 引擎的 global 对象上，获取到一个全局的 Ability 实例，但是在新的模型（Stage 模型）下，整个应用进程共用一个 js 虚拟机实例，其中可以运行多个 Ability 实例，这样就不存在一个全局的 Ability 实例。

如果开发者在新的模型（Stage 模型）下，调用的 API 实现仍然走到了获取全局 Ability 实例的方法，就可能会发生错误或者崩溃。

FA 模型和 Stage 模型中 context 功能差异

FA 模型 AbilityContext API 特有接口功能介绍

StageAbilityContext API 特有接口功能介绍

写在最后

有很多小伙伴不知道学习哪些鸿蒙开发技术？不知道需要重点掌握哪些鸿蒙应用开发知识点？而且学习时频繁踩坑，最终浪费大量时间。所以有一份实用的鸿蒙（HarmonyOS NEXT）用来跟着学习是非常有必要的。

这份鸿蒙（HarmonyOS NEXT）文档包含了鸿蒙开发必掌握的核心知识要点，内容包含了（ArkTS、ArkUI开发组件、Stage模型、多端部署、分布式应用开发、音频、视频、WebGL、OpenHarmony多媒体技术、Napi组件、OpenHarmony内核、OpenHarmony南向开发、鸿蒙项目实战等等）鸿蒙（HarmonyOS NEXT）技术知识点。

希望这一份鸿蒙学习文档能够给大家带来帮助，有需要的小伙伴自行领取，限时开源，先到先得~无套路领取！！

获取这份完整版高清学习路线，请点击→纯血版全套鸿蒙HarmonyOS学习文档

鸿蒙（HarmonyOS NEXT）5.0最新学习路线

有了路线图，怎么能没有学习文档呢，小编也准备了一份联合鸿蒙官方发布笔记整理收纳的一套系统性的鸿蒙（OpenHarmony ）学习手册（共计1236页）与鸿蒙（OpenHarmony ）开发入门教学视频，内容包含：ArkTS、ArkUI、Web开发、应用模型、资源分类…等知识点。

获取以上完整版高清学习路线，请点击→纯血版全套鸿蒙HarmonyOS学习文档

《鸿蒙 (OpenHarmony)开发入门教学视频》

《鸿蒙生态应用开发V3.0白皮书》

《鸿蒙 (OpenHarmony)开发基础到实战手册》

OpenHarmony北向、南向开发环境搭建

《鸿蒙开发基础》

●ArkTS语言
●安装DevEco Studio
●运用你的第一个ArkTS应用
●ArkUI声明式UI开发
.……

《鸿蒙开发进阶》

●Stage模型入门
●网络管理
●数据管理
●电话服务
●分布式应用开发
●通知与窗口管理
●多媒体技术
●安全技能
●任务管理
●WebGL
●国际化开发
●应用测试
●DFX面向未来设计
●鸿蒙系统移植和裁剪定制
……

《鸿蒙进阶实战》

●ArkTS实践
●UIAbility应用
●网络案例
……

获取以上完整鸿蒙HarmonyOS学习文档，请点击→纯血版全套鸿蒙HarmonyOS学习文档