提交 b0c54a5a 编写于 作者: Z zengyawen

update docs.

Signed-off-by: Nzengyawen <zengyawen1@huawei.com>
上级 fa2e1fa8
# Ability开发
> **说明:**<br/>
> 当前文件夹内容已废弃,相关指南请查阅[应用模型](../application-models/Readme-CN.md)。
- [Ability框架概述](ability-brief.md)
- [应用上下文Context概述](context-userguide.md)
- FA模型
......
# Ability框架概述
# Ability框架概述
Ability是OpenHarmony系统对应用的基本抽象。
每个Ability是完成独立业务的应用组件,是系统调度应用的最小单元。一个应用可以包含一个或多个Ability。
Ability框架模型具有两种形态:
- 第一种形态称为FA模型。API 8及其更早版本的应用只能使用FA模型。FA模型将Ability分为Page Ability、Service Ability以及Data Ability几种类型。
- 第二种形态称为Stage模型,这是自API 9新增的模型。Stage模型将Ability分为UIAbility和ExtensionAbility两大类,其中ExtensionAbility又被扩展为ServiceExtensionAbility、FormExtensionAbility、DataShareExtensionAbility等一系列ExtensionAbility,以便满足更多的使用场景。
每个Ability是完成独立业务的应用组件,是系统调度应用的最小单元。一个应用可以包含一个或多个Ability。
Ability框架模型具有两种形态:
- 第一种形态称为FA模型。API 8及其更早版本的应用只能使用FA模型。FA模型将Ability分为Page Ability、Service Ability以及Data Ability几种类型。
- 第二种形态称为Stage模型,这是自API 9新增的模型。Stage模型将Ability分为UIAbility和ExtensionAbility两大类,其中ExtensionAbility又被扩展为ServiceExtensionAbility、FormExtensionAbility、DataShareExtensionAbility等一系列ExtensionAbility,以便满足更多的使用场景。
自API 9开始,Stage模型是主推的开发模型。
Stage模型的设计,主要是为了开发者更加方便地开发出分布式环境下的复杂应用。下表给出了两种模型在设计上的差异:
| 对比 | FA模型 | Stage模型 |
| -------------- | ------------------------------------------------------------ | -------------------------------------------------------- |
| 应用组件开发方式 | 类Web的开发方式。 | 面向对象的开发方式。 |
| 引擎实例 | 每个Ability实例独占一个虚拟机实例。 | 多个Ability实例可以共享同一个虚拟机实例。 |
| 进程内对象共享 | 不支持。 | 支持。 |
| 包描述文件 | 使用`config.json`描述HAP包和组件信息,组件必须使用固定的文件名。 | 使用`module.json5`描述HAP包和组件信息,可以指定入口文件名。 |
| 组件 | 提供PageAbility(页面展示),ServiceAbility(服务),DataAbility(数据分享)以及FormAbility(卡片)。 | 提供UIAbility(页面展示)、Extension(基于场景的服务扩展)。 |
除了上述设计上的差异外,对于开发者而言,两种模型的主要区别在于:
* Ability类型存在差异;
![favsstage](figures/favsstage.png)
* Ability生命周期存在差异;
![lifecycle](figures/lifecycle.png)
两种模型的基本介绍,详见[FA模型综述](fa-brief.md)[Stage模型综述](stage-brief.md)
Stage模型的设计,主要是为了开发者更加方便地开发出分布式环境下的复杂应用。下表给出了两种模型在设计上的差异:
| 对比 | FA模型 | Stage模型 |
| -------------- | ------------------------------------------------------------ | -------------------------------------------------------- |
| 应用组件开发方式 | 类Web的开发方式。 | 面向对象的开发方式。 |
| 引擎实例 | 每个Ability实例独占一个虚拟机实例。 | 多个Ability实例可以共享同一个虚拟机实例。 |
| 进程内对象共享 | 不支持。 | 支持。 |
| 包描述文件 | 使用`config.json`描述HAP包和组件信息,组件必须使用固定的文件名。 | 使用`module.json5`描述HAP包和组件信息,可以指定入口文件名。 |
| 组件 | 提供PageAbility(页面展示),ServiceAbility(服务),DataAbility(数据分享)以及FormAbility(卡片)。 | 提供UIAbility(页面展示)、Extension(基于场景的服务扩展)。 |
除了上述设计上的差异外,对于开发者而言,两种模型的主要区别在于:
* Ability类型存在差异;
![favsstage](figures/favsstage.png)
* Ability生命周期存在差异;
![lifecycle](figures/lifecycle.png)
两种模型的基本介绍,详见[FA模型综述](fa-brief.md)[Stage模型综述](stage-brief.md)
## 相关实例
### FA 模型
### FA 模型
- [Page内和Page间导航跳转(ArkTS)(API8)](https://gitee.com/openharmony/codelabs/tree/master/Ability/PageAbility)
### Stage 模型
- [Stage模型介绍(ArkTS)(API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/StageModel)
- [窗口扩展(ArkTS)(API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/WindowExtAbility)
- [系统任务管理(ArkTS)(API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/MissionManager)
- [仿桌面应用(ArkTS)(API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/Launcher)
- [Stage模型介绍(ArkTS)(API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/StageModel)
- [窗口扩展(ArkTS)(API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/WindowExtAbility)
- [系统任务管理(ArkTS)(API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/MissionManager)
- [仿桌面应用(ArkTS)(API9)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/Launcher)
# 测试框架使用指导
## 概述
Delegator测试框架是OpenHarmony提供的一套开发者应用自测试框架,旨在为开发者提供针对应用的自测试环境。开发者可以通过Delegator类启动对应Ability,并通过Delegator类提供的能力对Ability进行生命周期切换和监听,同时支持shellCMD输入和测试结果打印显示等功能。
## 约束与限制
测试框架相关接口只能在测试hap包中使用,只有通过`aa test`命令或者DevEco Studio启动测试环境后相关接口才能生效。
## 测试框架启动
测试框架启动有两种方式:
- 方式一:通过`aa test`命令启动。
- 方式二:通过DevEco Studio启动。
### aa test启动
开发者可通过 `aa test` 命令启动测试框架,开发者可以自行指定使用的TestRunner以及TestRunner所在hap包的package name或module name,具体命令示例如下:
**FA模型:**
```javascript
aa test -b BundleName -p com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20
```
**Stage模型:**
```javascript
aa test -b BundleName -m com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20
```
| 参数 | 是否必选 | 参数说明 |
| --------------- | -------- | ------------------------------------------------------------ |
| -b | 是 | TestRunner所在hap包的bundle name。 |
| -p | 是 | TestRunner所在hap包的package name,FA模型使用。 |
| -m | 是 | TestRunner所在hap包的module name,Stage模型使用。 |
| -s unittest | 是 | 启用的TestRunner名称,TestRunner名称和文件名需要保持一致。 |
| -w | 否 | 测试用例超时时间,单位为秒,如果未指定或指定小于等于0的整数,测试框架会一直等待测试代码调用finishTest才退出。 |
| -s \<key>\<value> | 否 | 支持以key-value的方式输入任何参数,输入的参数可通过AbilityDelegatorArgs.parameters以key-value的方式获取。示例:-s classname myTest,key为"-s classname",value为"myTest"。 |
| -D | 否 | 以Debug模式启动被测试应用。 |
| -h | 否 | 输出帮助信息。 |
### DevEco Studio启动
DevEco Studio启动相关介绍见 [OpenHarmony测试框架](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001263160453#section1034420367508)
## TestRunner介绍
TestRunner是测试框架测试流程入口类。当测试流程启动时,系统会调用TestRunner内相关接口,开发者需要派生该类,并重写onPrepare、onRun方法。DevEco Studio在创建应用模板时会初始化一个默认TestRunner,并在onRun方法启动默认的TestAbility。开发者也可以修改TestAbility测试代码内容,也可以修改默认的TestRunner内onPrepare、onRun方法,自行实现测试代码。具体详细内容请参考TestRunnerAPI接口说明[TestRunner](../reference/apis/js-apis-application-testRunner.md)
## AbilityDelegatorRegistry介绍
AbilityDelegatorRegistry是测试框架提供的AbilityDelegator仓库类。开发者可以使用AbilityDelegatorRegistry获取AbilityDelegator实例以及执行此次测试时传入和生成的相关参数AbilityDelegatorArgs。开发者可以使用AbilityDelegator调用测试框架提供的函数集进行测试验证。具体详细内容请参考AbilityDelegatorRegistry API接口说明[AbilityDelegatorRegistry](../reference/apis/js-apis-application-abilityDelegatorRegistry.md)
## AbilityDelegatorArgs介绍
AbilityDelegatorArgs是测试框架提供的测试参数类。开发者可以使用AbilityDelegatorArgs获取执行此次测试时传入和生成的相关参数。具体详细内容请参考AbilityDelegatorArgs API接口说明[AbilityDelegatorArgs](../reference/apis/js-apis-inner-application-abilityDelegatorArgs.md)
## AbilityMonitor介绍
AbilityMonitor是测试框架提供用来绑定并监听Ability类。开发者可以使用AbilityMonitor绑定Ability,并将AbilityMonitor添加到监听列表。绑定后Ability的创建、生命周期变化等会触发AbilityMonitor内相关回调函数,开发者可以在对应回调函数内进行测试验证。具体详细内容请参考AbilityMonitor API接口说明[AbilityMonitor](../reference/apis/js-apis-application-abilityMonitor.md)
**示例**
```javascript
import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.addAbilityMonitor(monitor).then(() => {
console.info("addAbilityMonitor promise");
});
```
## AbilityDelegator介绍
AbilityDelegator是测试框架主要功能类,提供了启动Ability、获取Ability示例、调度Ability生命周期、对Ability生命周期进行监听、打印测试结果等功能。
**导入模块**
```javascript
import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
```
```javascript
var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator()
```
### 启动Ability并监听Ability状态变化
配合AbilityMonitor使用,可以实现对Ability启动、Ability实例获取、监听状态变化功能。
**示例:**
```javascript
var abilityDelegator;
var ability;
var timeout = 100;
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.waitAbilityMonitor(monitor, timeout, (err, data) => {
ability = data;
console.info("waitAbilityMonitor callback");
});
var want = {
bundleName: "bundleName",
abilityName: "abilityName"
};
abilityDelegator.startAbility(want, (err, data) => {
console.info("startAbility callback");
});
```
### 调度Ability生命周期
AbilityDelegator提供对Ability生命周期进行显示调度的能力,支持Foreground、Background,配合AbilityMonitor中对Ability生命周期监听方法,可以完整的测试Ability生命周期变化。具体详细内容请参考AbilityDelegator API接口说明[AbilityDelegator](../reference/apis/js-apis-inner-application-abilityDelegator.md)
### 执行shellCMD命令
AbilityDelegator提供执行shellCMD命令功能,开发者可以在测试代码中执行shell命令,该功能仅在测试环境中生效,非测试环境该接口调用无效果。
**示例:**
```javascript
var abilityDelegator;
var cmd = "cmd";
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.executeShellCommand(cmd, (err, data) => {
console.info("executeShellCommand callback");
});
```
### 打印日志信息
AbilityDelegator提供打印日志信息功能,开发者可以在测试代码中输出过程日志信息到终端控制台。
**示例:**
```javascript
var abilityDelegator;
var msg = "msg";
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.print(msg, (err) => {
console.info("print callback");
});
```
### 结束测试并打印日志信息
AbilityDelegator提供主动结束测试的功能,开发者可以在测试代码中主动结束测试过程并输出日志码及信息到终端控制台。
**示例:**
```javascript
var abilityDelegator;
var msg = "msg";
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.finishTest(msg, 0, (err) => {
console.info("finishTest callback");
});
# 测试框架使用指导
## 概述
Delegator测试框架是OpenHarmony提供的一套开发者应用自测试框架,旨在为开发者提供针对应用的自测试环境。开发者可以通过Delegator类启动对应Ability,并通过Delegator类提供的能力对Ability进行生命周期切换和监听,同时支持shellCMD输入和测试结果打印显示等功能。
## 约束与限制
测试框架相关接口只能在测试hap包中使用,只有通过`aa test`命令或者DevEco Studio启动测试环境后相关接口才能生效。
## 测试框架启动
测试框架启动有两种方式:
- 方式一:通过`aa test`命令启动。
- 方式二:通过DevEco Studio启动。
### aa test启动
开发者可通过 `aa test` 命令启动测试框架,开发者可以自行指定使用的TestRunner以及TestRunner所在hap包的package name或module name,具体命令示例如下:
**FA模型:**
```javascript
aa test -b BundleName -p com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20
```
**Stage模型:**
```javascript
aa test -b BundleName -m com.example.myapplicationfaets -s unittest OpenHarmonyTestRunner -s class ActsAbilityTest -w 20
```
| 参数 | 是否必选 | 参数说明 |
| --------------- | -------- | ------------------------------------------------------------ |
| -b | 是 | TestRunner所在hap包的bundle name。 |
| -p | 是 | TestRunner所在hap包的package name,FA模型使用。 |
| -m | 是 | TestRunner所在hap包的module name,Stage模型使用。 |
| -s unittest | 是 | 启用的TestRunner名称,TestRunner名称和文件名需要保持一致。 |
| -w | 否 | 测试用例超时时间,单位为秒,如果未指定或指定小于等于0的整数,测试框架会一直等待测试代码调用finishTest才退出。 |
| -s \<key>\<value> | 否 | 支持以key-value的方式输入任何参数,输入的参数可通过AbilityDelegatorArgs.parameters以key-value的方式获取。示例:-s classname myTest,key为"-s classname",value为"myTest"。 |
| -D | 否 | 以Debug模式启动被测试应用。 |
| -h | 否 | 输出帮助信息。 |
### DevEco Studio启动
DevEco Studio启动相关介绍见 [OpenHarmony测试框架](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-openharmony-test-framework-0000001263160453#section1034420367508)
## TestRunner介绍
TestRunner是测试框架测试流程入口类。当测试流程启动时,系统会调用TestRunner内相关接口,开发者需要派生该类,并重写onPrepare、onRun方法。DevEco Studio在创建应用模板时会初始化一个默认TestRunner,并在onRun方法启动默认的TestAbility。开发者也可以修改TestAbility测试代码内容,也可以修改默认的TestRunner内onPrepare、onRun方法,自行实现测试代码。具体详细内容请参考TestRunnerAPI接口说明[TestRunner](../reference/apis/js-apis-application-testRunner.md)
## AbilityDelegatorRegistry介绍
AbilityDelegatorRegistry是测试框架提供的AbilityDelegator仓库类。开发者可以使用AbilityDelegatorRegistry获取AbilityDelegator实例以及执行此次测试时传入和生成的相关参数AbilityDelegatorArgs。开发者可以使用AbilityDelegator调用测试框架提供的函数集进行测试验证。具体详细内容请参考AbilityDelegatorRegistry API接口说明[AbilityDelegatorRegistry](../reference/apis/js-apis-application-abilityDelegatorRegistry.md)
## AbilityDelegatorArgs介绍
AbilityDelegatorArgs是测试框架提供的测试参数类。开发者可以使用AbilityDelegatorArgs获取执行此次测试时传入和生成的相关参数。具体详细内容请参考AbilityDelegatorArgs API接口说明[AbilityDelegatorArgs](../reference/apis/js-apis-inner-application-abilityDelegatorArgs.md)
## AbilityMonitor介绍
AbilityMonitor是测试框架提供用来绑定并监听Ability类。开发者可以使用AbilityMonitor绑定Ability,并将AbilityMonitor添加到监听列表。绑定后Ability的创建、生命周期变化等会触发AbilityMonitor内相关回调函数,开发者可以在对应回调函数内进行测试验证。具体详细内容请参考AbilityMonitor API接口说明[AbilityMonitor](../reference/apis/js-apis-application-abilityMonitor.md)
**示例**
```javascript
import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.addAbilityMonitor(monitor).then(() => {
console.info("addAbilityMonitor promise");
});
```
## AbilityDelegator介绍
AbilityDelegator是测试框架主要功能类,提供了启动Ability、获取Ability示例、调度Ability生命周期、对Ability生命周期进行监听、打印测试结果等功能。
**导入模块**
```javascript
import AbilityDelegatorRegistry from '@ohos.application.abilityDelegatorRegistry'
```
```javascript
var abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator()
```
### 启动Ability并监听Ability状态变化
配合AbilityMonitor使用,可以实现对Ability启动、Ability实例获取、监听状态变化功能。
**示例:**
```javascript
var abilityDelegator;
var ability;
var timeout = 100;
function onAbilityCreateCallback(data) {
console.info("onAbilityCreateCallback");
}
var monitor = {
abilityName: "abilityname",
onAbilityCreate: onAbilityCreateCallback
}
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.waitAbilityMonitor(monitor, timeout, (err, data) => {
ability = data;
console.info("waitAbilityMonitor callback");
});
var want = {
bundleName: "bundleName",
abilityName: "abilityName"
};
abilityDelegator.startAbility(want, (err, data) => {
console.info("startAbility callback");
});
```
### 调度Ability生命周期
AbilityDelegator提供对Ability生命周期进行显示调度的能力,支持Foreground、Background,配合AbilityMonitor中对Ability生命周期监听方法,可以完整的测试Ability生命周期变化。具体详细内容请参考AbilityDelegator API接口说明[AbilityDelegator](../reference/apis/js-apis-inner-application-abilityDelegator.md)
### 执行shellCMD命令
AbilityDelegator提供执行shellCMD命令功能,开发者可以在测试代码中执行shell命令,该功能仅在测试环境中生效,非测试环境该接口调用无效果。
**示例:**
```javascript
var abilityDelegator;
var cmd = "cmd";
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.executeShellCommand(cmd, (err, data) => {
console.info("executeShellCommand callback");
});
```
### 打印日志信息
AbilityDelegator提供打印日志信息功能,开发者可以在测试代码中输出过程日志信息到终端控制台。
**示例:**
```javascript
var abilityDelegator;
var msg = "msg";
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.print(msg, (err) => {
console.info("print callback");
});
```
### 结束测试并打印日志信息
AbilityDelegator提供主动结束测试的功能,开发者可以在测试代码中主动结束测试过程并输出日志码及信息到终端控制台。
**示例:**
```javascript
var abilityDelegator;
var msg = "msg";
abilityDelegator = AbilityDelegatorRegistry.getAbilityDelegator();
abilityDelegator.finishTest(msg, 0, (err) => {
console.info("finishTest callback");
});
```
\ No newline at end of file
# Stage模型综述
## 设计思想
​Stage模型的设计,是为了提供给开发者一个更好的开发方式,更好的适用于多设备、分布式场景。
​Stage模型的设计思想如下图所示。
![stagedesign](figures/stagedesign.png)
​Stage模型的设计基于如下三个出发点:
- **应用进程的有序管理**
随着设备的内存越来越大,系统中同时运行的进程数量也越来越多。当数百个进程同时运行时,如果没有有效的管理措施,则系统整体的功耗和性能将无法得到保证。Stage模型中,通过短时任务、长时任务、托管任务和延迟任务四种方法对后台进程做了有序约束。这样做使得前台进程的资源得以保障,最终能获得更好的用户体验。
- **原生支持跨端迁移和多端协同**
OpenHarmony是原生分布式的操作系统,应用框架需要从架构设计上使得组件更易于实现跨端迁移和多端协同。Stage模型通过Ability与UI分离及UI展示与服务能力合一等模型特性,实现这一设计目标。
- **支持多种设备的不同窗口形态**
Stage模型重新定义了Ability的生命周期。系统在架构上,将应用组件管理服务和窗口管理服务进行了彼此解耦,这样做可以方便的针对特定设备进行适配,以实现出不同的窗口形态。
## 基本概念
下图展示了Stage模型中的基本概念。
![stageconcept](figures/stageconcept.png)
- **HAP**:OpenHarmony应用编译、分发、加载的基本单位。与开发态的module一一对应。在应用内,moduleName是其唯一标识;
- **Bundle**:通过appid标识的OpenHarmony应用,Bundle可以包含多个HAP,每个应用都有一个bundleName,但是bundleName并不能唯一标识一个应用,appid中包含bundleName以及其他的更多信息,能够唯一标识一个应用;
- **AbilityStage**:对应HAP的运行期对象,在HAP首次加载到进程中时创建,运行期开发者可见;
- **Application**:对应Bundle的运行期对象,运行期开发者不可见;
- **Context**:提供运行期开发者可以调用的各种能力,Ability组件和各种ExtensionAbility都有各自不同的Context类,他们都继承自基类Context,基类提供包名、moduleName、路径等信息;
- **Ability**:提供生命周期回调,持有AbilityContext,支持组件的跨端迁移和多端协同;
- **ExtensionAbility**:基于场景的扩展能力统称,系统定义了多种场景的ExtensionAbility类,它们持有各自的ExtensionContext;
- **WindowStage**:本地窗口管理器;
- **Window**:应用窗口,持有一个ArkUI引擎实例;
- **ArkUI Page**:基于ArkUI开发的用户界面。
## 生命周期
# Stage模型综述
## 设计思想
​Stage模型的设计,是为了提供给开发者一个更好的开发方式,更好的适用于多设备、分布式场景。
​Stage模型的设计思想如下图所示。
![stagedesign](figures/stagedesign.png)
​Stage模型的设计基于如下三个出发点:
- **应用进程的有序管理**
随着设备的内存越来越大,系统中同时运行的进程数量也越来越多。当数百个进程同时运行时,如果没有有效的管理措施,则系统整体的功耗和性能将无法得到保证。Stage模型中,通过短时任务、长时任务、托管任务和延迟任务四种方法对后台进程做了有序约束。这样做使得前台进程的资源得以保障,最终能获得更好的用户体验。
- **原生支持跨端迁移和多端协同**
OpenHarmony是原生分布式的操作系统,应用框架需要从架构设计上使得组件更易于实现跨端迁移和多端协同。Stage模型通过Ability与UI分离及UI展示与服务能力合一等模型特性,实现这一设计目标。
- **支持多种设备的不同窗口形态**
Stage模型重新定义了Ability的生命周期。系统在架构上,将应用组件管理服务和窗口管理服务进行了彼此解耦,这样做可以方便的针对特定设备进行适配,以实现出不同的窗口形态。
## 基本概念
下图展示了Stage模型中的基本概念。
![stageconcept](figures/stageconcept.png)
- **HAP**:OpenHarmony应用编译、分发、加载的基本单位。与开发态的module一一对应。在应用内,moduleName是其唯一标识;
- **Bundle**:通过appid标识的OpenHarmony应用,Bundle可以包含多个HAP,每个应用都有一个bundleName,但是bundleName并不能唯一标识一个应用,appid中包含bundleName以及其他的更多信息,能够唯一标识一个应用;
- **AbilityStage**:对应HAP的运行期对象,在HAP首次加载到进程中时创建,运行期开发者可见;
- **Application**:对应Bundle的运行期对象,运行期开发者不可见;
- **Context**:提供运行期开发者可以调用的各种能力,Ability组件和各种ExtensionAbility都有各自不同的Context类,他们都继承自基类Context,基类提供包名、moduleName、路径等信息;
- **Ability**:提供生命周期回调,持有AbilityContext,支持组件的跨端迁移和多端协同;
- **ExtensionAbility**:基于场景的扩展能力统称,系统定义了多种场景的ExtensionAbility类,它们持有各自的ExtensionContext;
- **WindowStage**:本地窗口管理器;
- **Window**:应用窗口,持有一个ArkUI引擎实例;
- **ArkUI Page**:基于ArkUI开发的用户界面。
## 生命周期
AbilityStage及Ability是关于应用生命周期的关键对象。
[Ability框架概述](ability-brief.md)中,给出了FA模型与Stage模型的生命周期对比,因此这里仅对Ability生命周期切换以及和AbilityStage、WindowStage之间的调度关系进行介绍。
![stageabilitylifecyclecallback](figures/stageabilitylifecyclecallback.png)
[Ability框架概述](ability-brief.md)中,给出了FA模型与Stage模型的生命周期对比,因此这里仅对Ability生命周期切换以及和AbilityStage、WindowStage之间的调度关系进行介绍。
![stageabilitylifecyclecallback](figures/stageabilitylifecyclecallback.png)
为了实现多设备形态上的适配和多窗口的扩展,OpenHarmony对组件管理和窗口管理进行了解耦。
Stage模型定义Ability组件的生命周期,只包含创建、销毁、前后台等状态,而将与界面强相关的获焦、失焦状态都放在WindowStage之中,从而实现Ability与窗口之间的弱耦合;在服务侧,窗口管理服务依赖于组件管理服务,前者通知后者前后台变化,这样组件管理服务仅感知前后台变化,不感知焦点变化。
需要注意的是,在Ability中存在两个与WindowStage相关的生命周期状态onWindowStageCreate和onWindowStageDestroy,这两个生命周期状态的变化仅存在于具有显示能力的设备中。前者表示WindowStage已经创建完成,开发者可以通过执行loadContent的操作设置Ability需要加载的页面;后者在WindowStage销毁后调用,以便开发者对资源进行释放。
## Ability组件实例与任务
Ability组件有三种启动类型:
* **Singleton**:应用进程中只存在一个该类型的Ability实例,如下图Ability1;
* **Standard**:每次startAbility调用,都会在应用进程中创建一个该类型的实例,如下图Ability2的两个实例;
* **Specified**:允许开发者在系统创建Ability实例之前,为该实例创建一个key,后续每次创建该类型的Ability实例都会询问应用使用哪个key对应的Ability实例,来响应startAbility请求,如下图Ability3。
每个Ability实例都对应了一个近期任务中的Mission(任务)。
每个Ability实例对应的Mission都留有该Ability实例的快照,Ability实例销毁后,Mission中会继续保留Ability的类的信息和快照,直到用户删除,或者超过存储上限。
![AbilityComponentInstanceMission](figures/AbilityComponentInstanceMission.png)
## ExtensionAbility机制
Stage模型定义Ability组件的生命周期,只包含创建、销毁、前后台等状态,而将与界面强相关的获焦、失焦状态都放在WindowStage之中,从而实现Ability与窗口之间的弱耦合;在服务侧,窗口管理服务依赖于组件管理服务,前者通知后者前后台变化,这样组件管理服务仅感知前后台变化,不感知焦点变化。
需要注意的是,在Ability中存在两个与WindowStage相关的生命周期状态onWindowStageCreate和onWindowStageDestroy,这两个生命周期状态的变化仅存在于具有显示能力的设备中。前者表示WindowStage已经创建完成,开发者可以通过执行loadContent的操作设置Ability需要加载的页面;后者在WindowStage销毁后调用,以便开发者对资源进行释放。
## Ability组件实例与任务
Ability组件有三种启动类型:
* **Singleton**:应用进程中只存在一个该类型的Ability实例,如下图Ability1;
* **Standard**:每次startAbility调用,都会在应用进程中创建一个该类型的实例,如下图Ability2的两个实例;
* **Specified**:允许开发者在系统创建Ability实例之前,为该实例创建一个key,后续每次创建该类型的Ability实例都会询问应用使用哪个key对应的Ability实例,来响应startAbility请求,如下图Ability3。
每个Ability实例都对应了一个近期任务中的Mission(任务)。
每个Ability实例对应的Mission都留有该Ability实例的快照,Ability实例销毁后,Mission中会继续保留Ability的类的信息和快照,直到用户删除,或者超过存储上限。
![AbilityComponentInstanceMission](figures/AbilityComponentInstanceMission.png)
## ExtensionAbility机制
不同于页面展示的Ability,ExtensionAbility提供的是一种受限的运行环境。
ExtensionAbility组件具有如下特点:
- 运行在独立于主进程的单独进程中,与主进程无IPC,但共享一个存储沙箱;
- 独立的Context提供基于相应业务场景的API能力;
- 由系统触发创建,应用不能直接创建;
- ExtensionAbility和进程的生命周期受系统管理。
下图以卡片使用场景为例进行展示。系统提供了FormExtensionAbility基类,开发者通过派生提供卡片的具体信息。FormExtensionAbility实例及其所在的ExtensionAbility进程的整个生命周期,都是由系统服务FormManagerService进行管理。
![ExtensionAbility](figures/ExtensionAbility.png)
## 进程模型
ExtensionAbility组件具有如下特点:
- 运行在独立于主进程的单独进程中,与主进程无IPC,但共享一个存储沙箱;
- 独立的Context提供基于相应业务场景的API能力;
- 由系统触发创建,应用不能直接创建;
- ExtensionAbility和进程的生命周期受系统管理。
下图以卡片使用场景为例进行展示。系统提供了FormExtensionAbility基类,开发者通过派生提供卡片的具体信息。FormExtensionAbility实例及其所在的ExtensionAbility进程的整个生命周期,都是由系统服务FormManagerService进行管理。
![ExtensionAbility](figures/ExtensionAbility.png)
## 进程模型
OpenHarmony系统对于应用进程是有强管控策略的。对于开发者来说,没有自行配置多进程的能力。应用的所有进程都是由系统创建和管理的。
每个应用的进程可以分为三类:
- 主进程:运行UIAbility组件、页面和业务逻辑;
- Extension进程:运行应用中的ExtensionAbility派生类,该进程由系统中的特定场景的服务管理其生命周期;
- Render进程:专门为webview创建的进程,用于加载webview的渲染库。
下图展示了应用的进程模型。
![stageprocessmodel](figures/stageprocessmodel.png)
## 应用包结构
Stage模型的应用包的工程目录结构,请参考[OpenHarmony工程介绍](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-project-overview-0000001218440650#section56487581904)
对Stage模型的应用包结构的配置说明,请参考[应用包结构说明(Stage模型)](../quick-start/stage-structure.md)
## 相关实例
针对Stage模型下的Ability开发,有以下相关实例可供参考:
- [`StageModel`:Stage模型(ArkTS)(API9)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/StageModel)
- [`WindowExtAbility`:窗口扩展(ArkTS)(API9)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/WindowExtAbility)
- [`MissionManager`:系统任务管理(ArkTS)(API9)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/MissionManager)
- [`Launcher`:仿桌面应用(ArkTS)(API9)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/Launcher)
每个应用的进程可以分为三类:
- 主进程:运行UIAbility组件、页面和业务逻辑;
- Extension进程:运行应用中的ExtensionAbility派生类,该进程由系统中的特定场景的服务管理其生命周期;
- Render进程:专门为webview创建的进程,用于加载webview的渲染库。
下图展示了应用的进程模型。
![stageprocessmodel](figures/stageprocessmodel.png)
## 应用包结构
Stage模型的应用包的工程目录结构,请参考[OpenHarmony工程介绍](https://developer.harmonyos.com/cn/docs/documentation/doc-guides/ohos-project-overview-0000001218440650#section56487581904)
对Stage模型的应用包结构的配置说明,请参考[应用包结构说明(Stage模型)](../quick-start/stage-structure.md)
## 相关实例
针对Stage模型下的Ability开发,有以下相关实例可供参考:
- [`StageModel`:Stage模型(ArkTS)(API9)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/StageModel)
- [`WindowExtAbility`:窗口扩展(ArkTS)(API9)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/WindowExtAbility)
- [`MissionManager`:系统任务管理(ArkTS)(API9)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/MissionManager)
- [`Launcher`:仿桌面应用(ArkTS)(API9)(Full SDK)](https://gitee.com/openharmony/applications_app_samples/tree/master/ability/Launcher)
# WantAgent开发指导
## 场景简介
WantAgent封装了一个行为意图信息,可以通过WantAgent.trigger接口主动触发,也可以通过与通知绑定被动触发。
具体的行为包括:启动Ability和发布公共事件。
## 接口说明
| 接口名 | 接口描述 |
| ---------------------------------------------------------------------------------------------- | ----------- |
| getWantAgentInfo(info: WantAgentInfo, callback: AsyncCallback\<WantAgent\>) | 以异步回调形式创建WantAgent对象。 |
| getWantAgent(info: WantAgentInfo): Promise\<WantAgent\> | 以Promise形式创建WantAgent对象。 |
| trigger(agent: WantAgent, triggerInfo: TriggerInfo, callback?: Callback\<CompleteData\>) | 触发WantAgent。 |
## 开发步骤
1. 导入WantAgent模块。
```
import wantAgent from '@ohos.wantAgent';
```
2. 创建拉起Ability的WantAgentInfo信息。详细的WantAgentInfo信息数据类型及包含的参数请见[WantAgentInfo文档](../reference/apis/js-apis-wantAgent.md#wantagentinfo)介绍。
```
private wantAgentObj = null // 用于保存创建成功的wantAgent对象,后续使用其完成触发的动作。
// wantAgentInfo
var wantAgentInfo = {
wants: [
{
deviceId: "",
bundleName: "com.example.test",
abilityName: "com.example.test.MainAbility",
action: "",
entities: [],
uri: "",
parameters: {}
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG]
}
```
3. 创建发布公共事件的WantAgentInfo信息。
```
private wantAgentObj = null // 用于保存创建成功的WantAgent对象,后续使用其完成触发的动作。
// wantAgentInfo
var wantAgentInfo = {
wants: [
{
action: "event_name", // 设置事件名。
parameters: {}
}
],
operationType: wantAgent.OperationType.SEND_COMMON_EVENT,
requestCode: 0,
wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG]
}
```
4. 创建WantAgent,保存返回的WantAgent对象wantAgentObj,用于执行后续触发操作。
```
// 创建WantAgent
wantAgent.getWantAgent(wantAgentInfo, (err, wantAgentObj) => {
if (err.code) {
console.error("[WantAgent]getWantAgent err=" + JSON.stringify(err))
} else {
console.log("[WantAgent]getWantAgent success")
this.wantAgentObj = wantAgentObj
}
})
```
5. 触发WantAgent。
```
// 触发WantAgent。
var triggerInfo = {
code:0
}
wantAgent.trigger(wantAgentObj, triggerInfo, (completeData) => {
console.log("[WantAgent]getWantAgent success, completeData: ", + JSON.stringify(completeData))
})
```
# WantAgent开发指导
## 场景简介
WantAgent封装了一个行为意图信息,可以通过WantAgent.trigger接口主动触发,也可以通过与通知绑定被动触发。
具体的行为包括:启动Ability和发布公共事件。
## 接口说明
| 接口名 | 接口描述 |
| ---------------------------------------------------------------------------------------------- | ----------- |
| getWantAgentInfo(info: WantAgentInfo, callback: AsyncCallback\<WantAgent\>) | 以异步回调形式创建WantAgent对象。 |
| getWantAgent(info: WantAgentInfo): Promise\<WantAgent\> | 以Promise形式创建WantAgent对象。 |
| trigger(agent: WantAgent, triggerInfo: TriggerInfo, callback?: Callback\<CompleteData\>) | 触发WantAgent。 |
## 开发步骤
1. 导入WantAgent模块。
```
import wantAgent from '@ohos.wantAgent';
```
2. 创建拉起Ability的WantAgentInfo信息。详细的WantAgentInfo信息数据类型及包含的参数请见[WantAgentInfo文档](../reference/apis/js-apis-wantAgent.md#wantagentinfo)介绍。
```
private wantAgentObj = null // 用于保存创建成功的wantAgent对象,后续使用其完成触发的动作。
// wantAgentInfo
var wantAgentInfo = {
wants: [
{
deviceId: "",
bundleName: "com.example.test",
abilityName: "com.example.test.MainAbility",
action: "",
entities: [],
uri: "",
parameters: {}
}
],
operationType: wantAgent.OperationType.START_ABILITY,
requestCode: 0,
wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG]
}
```
3. 创建发布公共事件的WantAgentInfo信息。
```
private wantAgentObj = null // 用于保存创建成功的WantAgent对象,后续使用其完成触发的动作。
// wantAgentInfo
var wantAgentInfo = {
wants: [
{
action: "event_name", // 设置事件名。
parameters: {}
}
],
operationType: wantAgent.OperationType.SEND_COMMON_EVENT,
requestCode: 0,
wantAgentFlags:[wantAgent.WantAgentFlags.CONSTANT_FLAG]
}
```
4. 创建WantAgent,保存返回的WantAgent对象wantAgentObj,用于执行后续触发操作。
```
// 创建WantAgent
wantAgent.getWantAgent(wantAgentInfo, (err, wantAgentObj) => {
if (err.code) {
console.error("[WantAgent]getWantAgent err=" + JSON.stringify(err))
} else {
console.log("[WantAgent]getWantAgent success")
this.wantAgentObj = wantAgentObj
}
})
```
5. 触发WantAgent。
```
// 触发WantAgent。
var triggerInfo = {
code:0
}
wantAgent.trigger(wantAgentObj, triggerInfo, (completeData) => {
console.log("[WantAgent]getWantAgent success, completeData: ", + JSON.stringify(completeData))
})
```
Markdown is supported
0% .
You are about to add 0 people to the discussion. Proceed with caution.
先完成此消息的编辑!
想要评论请 注册