From b0c54a5aef5ec7dca5f372022e57dee4bf4a0d74 Mon Sep 17 00:00:00 2001 From: zengyawen Date: Mon, 12 Dec 2022 10:06:34 +0800 Subject: [PATCH] update docs. Signed-off-by: zengyawen --- .../Readme-CN.md | 3 + .../ability-assistant-guidelines.md | 0 .../ability-brief.md | 78 +-- .../ability-delegator.md | 360 ++++++------ .../context-userguide.md | 0 .../continuationmanager.md | 548 +++++++++--------- .../fa-brief.md | 0 .../fa-dataability.md | 0 .../fa-formability.md | 0 .../fa-pageability.md | 0 .../fa-serviceability.md | 0 .../AbilityComponentInstanceMission.png | Bin .../figures/ExtensionAbility.png | Bin .../figures/aa-dump-a.PNG | Bin .../figures/aa-dump-i.PNG | Bin .../figures/aa-dump-l.PNG | Bin .../figures/contextIntroduction.png | Bin .../figures/continuation-info.png | Bin .../figures/continuationManager.png | Bin .../figures/fa-dataability-uri.png | Bin .../figures/fa-form-example.png | Bin .../figures/fa-pageAbility-lifecycle.png | Bin .../figures/fa-threading-model.png | Bin .../figures/favsstage.png | Bin .../figures/lifecycle.png | Bin .../figures/page-ability-lifecycle.png | Bin .../figures/stage-call.png | Bin .../figures/stageabilitylifecyclecallback.png | Bin .../figures/stageconcept.png | Bin .../figures/stagedesign.png | Bin .../figures/stageprocessmodel.png | Bin .../public_sys-resources/icon-caution.gif | Bin .../public_sys-resources/icon-danger.gif | Bin .../public_sys-resources/icon-note.gif | Bin .../public_sys-resources/icon-notice.gif | Bin .../public_sys-resources/icon-tip.gif | Bin .../public_sys-resources/icon-warning.gif | Bin .../stage-ability-continuation.md | 0 .../stage-ability.md | 0 .../stage-brief.md | 228 ++++---- .../stage-call.md | 0 .../stage-formextension.md | 0 .../stage-serviceextension.md | 0 .../wantagent.md | 176 +++--- 44 files changed, 698 insertions(+), 695 deletions(-) rename zh-cn/application-dev/{ability => ability-deprecated}/Readme-CN.md (87%) rename zh-cn/application-dev/{ability => ability-deprecated}/ability-assistant-guidelines.md (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/ability-brief.md (98%) rename zh-cn/application-dev/{ability => ability-deprecated}/ability-delegator.md (97%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/context-userguide.md (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/continuationmanager.md (97%) rename zh-cn/application-dev/{ability => ability-deprecated}/fa-brief.md (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/fa-dataability.md (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/fa-formability.md (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/fa-pageability.md (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/fa-serviceability.md (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/AbilityComponentInstanceMission.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/ExtensionAbility.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/aa-dump-a.PNG (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/figures/aa-dump-i.PNG (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/figures/aa-dump-l.PNG (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/figures/contextIntroduction.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/continuation-info.png (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/figures/continuationManager.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/fa-dataability-uri.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/fa-form-example.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/fa-pageAbility-lifecycle.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/fa-threading-model.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/favsstage.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/lifecycle.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/page-ability-lifecycle.png (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/figures/stage-call.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/stageabilitylifecyclecallback.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/stageconcept.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/stagedesign.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/figures/stageprocessmodel.png (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-caution.gif (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-danger.gif (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-note.gif (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-notice.gif (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-tip.gif (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-warning.gif (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/stage-ability-continuation.md (100%) mode change 100755 => 100644 rename zh-cn/application-dev/{ability => ability-deprecated}/stage-ability.md (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/stage-brief.md (98%) rename zh-cn/application-dev/{ability => ability-deprecated}/stage-call.md (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/stage-formextension.md (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/stage-serviceextension.md (100%) rename zh-cn/application-dev/{ability => ability-deprecated}/wantagent.md (97%) diff --git a/zh-cn/application-dev/ability/Readme-CN.md b/zh-cn/application-dev/ability-deprecated/Readme-CN.md similarity index 87% rename from zh-cn/application-dev/ability/Readme-CN.md rename to zh-cn/application-dev/ability-deprecated/Readme-CN.md index e691463188..4472d7d1b8 100644 --- a/zh-cn/application-dev/ability/Readme-CN.md +++ b/zh-cn/application-dev/ability-deprecated/Readme-CN.md @@ -1,5 +1,8 @@ # Ability开发 +> **说明：**
+> 当前文件夹内容已废弃，相关指南请查阅[应用模型](../application-models/Readme-CN.md)。 + - [Ability框架概述](ability-brief.md) - [应用上下文Context概述](context-userguide.md) - FA模型 diff --git a/zh-cn/application-dev/ability/ability-assistant-guidelines.md b/zh-cn/application-dev/ability-deprecated/ability-assistant-guidelines.md similarity index 100% rename from zh-cn/application-dev/ability/ability-assistant-guidelines.md rename to zh-cn/application-dev/ability-deprecated/ability-assistant-guidelines.md diff --git a/zh-cn/application-dev/ability/ability-brief.md b/zh-cn/application-dev/ability-deprecated/ability-brief.md similarity index 98% rename from zh-cn/application-dev/ability/ability-brief.md rename to zh-cn/application-dev/ability-deprecated/ability-brief.md index f7a4e18664..e889c585c2 100644 --- a/zh-cn/application-dev/ability/ability-brief.md +++ b/zh-cn/application-dev/ability-deprecated/ability-brief.md @@ -1,47 +1,47 @@ -# 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) diff --git a/zh-cn/application-dev/ability/ability-delegator.md b/zh-cn/application-dev/ability-deprecated/ability-delegator.md old mode 100755 new mode 100644 similarity index 97% rename from zh-cn/application-dev/ability/ability-delegator.md rename to zh-cn/application-dev/ability-deprecated/ability-delegator.md index cc4ba53225..1a6dc8e016 --- a/zh-cn/application-dev/ability/ability-delegator.md +++ b/zh-cn/application-dev/ability-deprecated/ability-delegator.md @@ -1,181 +1,181 @@ -# 测试框架使用指导 - -## 概述 -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的方式输入任何参数，输入的参数可通过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的方式输入任何参数，输入的参数可通过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 diff --git a/zh-cn/application-dev/ability/context-userguide.md b/zh-cn/application-dev/ability-deprecated/context-userguide.md similarity index 100% rename from zh-cn/application-dev/ability/context-userguide.md rename to zh-cn/application-dev/ability-deprecated/context-userguide.md diff --git a/zh-cn/application-dev/ability/continuationmanager.md b/zh-cn/application-dev/ability-deprecated/continuationmanager.md similarity index 97% rename from zh-cn/application-dev/ability/continuationmanager.md rename to zh-cn/application-dev/ability-deprecated/continuationmanager.md index 925037056e..68a3db4c0c 100644 --- a/zh-cn/application-dev/ability/continuationmanager.md +++ b/zh-cn/application-dev/ability-deprecated/continuationmanager.md @@ -1,275 +1,275 @@ -# ContinuationManager开发指导 - -> 说明：本模块接口用于拉起系统中的设备选择模块，由于该模块功能暂不完备，因此**流转能力整体暂不支持用于应用开发**。 - -## 场景简介 -随着全场景多设备生活方式的不断深入，用户拥有的设备越来越多，每个设备都能在适合的场景下提供良好的体验，但是，每个设备也有使用场景的局限。流转能力致力于打破设备界限，多设备联动，使用户应用程序可分可合、可流转，实现体验升级。 - -continuationManager作为流转能力的入口，主要用于拉起系统中的设备选择模块供用户选择，待选择设备后，会给用户返回已选择的远端设备信息，用户可以根据远端设备信息发起跨端迁移或多端协同操作。 - -![continuationManager](figures/continuationManager.png) - -## 接口说明 -| 接口名 | 接口描述 | -| ---------------------------------------------------------------------------------------------- | ----------- | -| registerContinuation(callback: AsyncCallback\): void | 注册流转管理服务，并获取对应的注册token，无过滤条件(AsyncCallback)。 | -| registerContinuation(options: ContinuationExtraParams, callback: AsyncCallback\): void | 注册流转管理服务，并获取对应的注册token(AsyncCallback)。 | -| registerContinuation(options?: ContinuationExtraParams): Promise\ | 连接流转管理服务，并获取对应的注册token(Promise)。 | -| on(type: "deviceSelected", token: number, callback: Callback\>): void | 监听设备连接状态(Callback)。 | -| on(type: "deviceUnselected", token: number, callback: Callback\>): void | 监听设备断开状态(Callback)。 | -| off(type: "deviceSelected", token: number): void | 取消监听设备连接状态。 | -| off(type: "deviceUnselected", token: number): void | 取消监听设备断开状态。 | -| startContinuationDeviceManager(token: number, callback: AsyncCallback\): void | 拉起设备选择模块，可显示组网内可选择设备列表信息，无过滤条件(AsyncCallback)。 | -| startContinuationDeviceManager(token: number, options: ContinuationExtraParams, callback: AsyncCallback\): void | 拉起设备选择模块，可显示组网内可选择设备列表信息(AsyncCallback)。 | -| startContinuationDeviceManager(token: number, options?: ContinuationExtraParams): Promise\ | 拉起设备选择模块，可显示组网内可选择设备列表信息(Promise)。 | -| updateContinuationState(token: number, deviceId: string, status: DeviceConnectState, callback: AsyncCallback\): void | 通知设备选择模块，更新当前的流转状态(AsyncCallback)。 | -| updateContinuationState(token: number, deviceId: string, status: DeviceConnectState): Promise\ | 通知设备选择模块，更新当前的流转状态(Promise)。 | -| unregisterContinuation(token: number, callback: AsyncCallback\): void | 取消注册流转管理服务，传入注册时获取的token进行取消注册(AsyncCallback)。 | -| unregisterContinuation(token: number): Promise\ | 取消注册流转管理服务，传入注册时获取的token进行取消注册(Promise)。 | - -## 开发步骤 -1. 导入continuationManager模块。 - - ```ts - import continuationManager from '@ohos.continuation.continuationManager'; - ``` - -2. 申请分布式权限 DISTRIBUTED_DATASYNC。 - - 权限申请在FA平台和Stage平台有区别，FA平台需要在`config.json`里面进行配置请求权限，示例代码如下： - - ```json - { - "module": { - "reqPermissions": [ - { - "name": "ohos.permission.DISTRIBUTED_DATASYNC" - } - ] - } - } - ``` - - 这个权限还需要在应用首次启动的时候弹窗获取用户授权，可以通过如下代码实现： - - ```ts - import abilityAccessCtrl from "@ohos.abilityAccessCtrl"; - import bundle from '@ohos.bundle'; - import featureAbility from '@ohos.ability.featureAbility'; - - async function requestPermission() { - let permissions: Array = [ - "ohos.permission.DISTRIBUTED_DATASYNC" - ]; - let needGrantPermission: boolean = false; - let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); - let applicationInfo = await bundle.getApplicationInfo('ohos.samples.etsDemo', 0, 100); - for (let i = 0; i < permissions.length; i++) { - let result = await atManager.verifyAccessToken(applicationInfo.accessTokenId, permissions[i]); - //判断是否未申请该权限 - if (result == abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { - needGrantPermission = true; - break; - } - } - // 如果未申请该权限，则需要调用requestPermissionsFromUser接口申请权限 - if (needGrantPermission) { - await featureAbility.getContext().requestPermissionsFromUser(permissions, 1); - } else { - console.info('app permission already granted'); - } - } - ``` - - Stage平台需要在`module.json5`里面进行配置请求权限，示例代码如下： - - ```json - { - "module": { - "requestPermissions": [ - { - "name": "ohos.permission.DISTRIBUTED_DATASYNC" - } - ] - } - } - ``` - - ```ts - import abilityAccessCtrl from "@ohos.abilityAccessCtrl"; - import bundle from '@ohos.bundle'; - - async function requestPermission() { - let permissions: Array = [ - "ohos.permission.DISTRIBUTED_DATASYNC" - ]; - let needGrantPermission: boolean = false; - let atManger: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); - let applicationInfo = await bundle.getApplicationInfo('ohos.samples.continuationmanager', 0, 100); - for (const permission of permissions) { - try { - let grantStatus = await atManger.verifyAccessToken(applicationInfo.accessTokenId, permission); - //判断是否未申请该权限 - if (grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_DENIED) { - needGrantPermission = true; - break; - } - } catch (err) { - console.error('app permission query grant status error' + JSON.stringify(err)); - needGrantPermission = true; - break; - } - } - // 如果未申请该权限，则需要调用requestPermissionsFromUser接口申请权限 - if (needGrantPermission) { - try { - // globalThis.context即Ability.context,需提前在MainAbility.ts文件中赋值 - await globalThis.context.requestPermissionsFromUser(permissions); - } catch (err) { - console.error('app permission request permissions error' + JSON.stringify(err)); - } - } else { - console.info('app permission already granted'); - } - } - ``` - -3. 注册流转管理服务，获取对应的注册token。 - - 注册流转管理服务的代码示例如下： - - ```ts - let token: number = -1; // 用于保存注册成功并返回的token，后续使用其完成监听设备连接/断开状态、拉起设备选择模块以及更新流转状态的动作 - try { - continuationManager.registerContinuation().then((data) => { - console.info('registerContinuation finished, ' + JSON.stringify(data)); - token = data; // 获取到对应的注册token，并赋值给token变量 - }).catch((err) => { - console.error('registerContinuation failed, cause: ' + JSON.stringify(err)); - }); - } catch (err) { - console.error('registerContinuation failed, cause: ' + JSON.stringify(err)); - } - ``` - -4. 监听设备状态。 - - 监听设备连接状态的代码示例如下： - - ```ts - let remoteDeviceId: string = ""; // 用于保存用户选择的远端设备信息，后续使用其完成跨端迁移或多端协同操作 - - try { - // 参数token为注册token - continuationManager.on("deviceSelected", token, (continuationResults) => { - console.info('registerDeviceSelectedCallback len: ' + continuationResults.length); - if (continuationResults.length <= 0) { - console.info('no selected device'); - return; - } - remoteDeviceId = continuationResults[0].id; // 将选择的第一个远端设备deviceId赋值给remoteDeviceId变量 - - // 将remoteDeviceId参数传给want - let want = { - deviceId: remoteDeviceId, - bundleName: 'ohos.samples.continuationmanager', - abilityName: 'MainAbility' - }; - globalThis.abilityContext.startAbility(want).then((data) => { - console.info('StartRemoteAbility finished, ' + JSON.stringify(data)); - }).catch((err) => { - console.error('StartRemoteAbility failed, cause: ' + JSON.stringify(err)); - }); - }); - } catch (err) { - console.error('on failed, cause: ' + JSON.stringify(err)); - } - ``` - - 上述多端协同操作为Stage平台的跨设备拉起，FA平台详情见[PageAbility开发指导](fa-pageability.md)。 - - 同时用户还可通知设备选择模块，更新当前的流转状态，代码示例如下： - - ```ts - // 设置设备流转状态 - let deviceConnectStatus: continuationManager.DeviceConnectState = continuationManager.DeviceConnectState.CONNECTED; - - // 参数token为注册token，参数remoteDeviceId为获取到的remoteDeviceId - try { - continuationManager.updateContinuationState(token, remoteDeviceId, deviceConnectStatus).then((data) => { - console.info('updateContinuationState finished, ' + JSON.stringify(data)); - }).catch((err) => { - console.error('updateContinuationState failed, cause: ' + JSON.stringify(err)); - }); - } catch (err) { - console.error('updateContinuationState failed, cause: ' + JSON.stringify(err)); - } - ``` - - 监听设备断开状态，方便用户终止跨端迁移或多端协同操作，代码示例如下： - - ```ts - try { - // 参数token为注册token - continuationManager.on("deviceUnselected", token, (continuationResults) => { - console.info('onDeviceUnselected len: ' + continuationResults.length); - if (continuationResults.length <= 0) { - console.info('no unselected device'); - return; - } - - // 更新设备流转状态 - let unselectedDeviceId: string = continuationResults[0].id; // 将取消选择的第一个远端设备deviceId赋值给unselectedDeviceId变量 - let deviceConnectStatus: continuationManager.DeviceConnectState = continuationManager.DeviceConnectState.DISCONNECTING; // 设备断开状态 - - // 参数token为注册token，参数unselectedDeviceId为获取到的unselectedDeviceId - continuationManager.updateContinuationState(token, unselectedDeviceId, deviceConnectStatus).then((data) => { - console.info('updateContinuationState finished, ' + JSON.stringify(data)); - }).catch((err) => { - console.error('updateContinuationState failed, cause: ' + JSON.stringify(err)); - }); - }); - } catch (err) { - console.error('updateContinuationState failed, cause: ' + JSON.stringify(err)); - } - ``` - -5. 拉起设备选择模块，可显示组网内可选择设备列表信息，供用户选择。 - - 拉起设备选择模块的代码示例如下： - - ```ts - // 过滤参数 - let continuationExtraParams = { - deviceType: ["00E"], // 设备类型 - continuationMode: continuationManager.ContinuationMode.COLLABORATION_SINGLE // 设备选择模块单选模式 - }; - - try { - // 参数token为注册token - continuationManager.startContinuationDeviceManager(token, continuationExtraParams).then((data) => { - console.info('startContinuationDeviceManager finished, ' + JSON.stringify(data)); - }).catch((err) => { - console.error('startContinuationDeviceManager failed, cause: ' + JSON.stringify(err)); - }); - } catch (err) { - console.error('startContinuationDeviceManager failed, cause: ' + JSON.stringify(err)); - } - ``` - -6. 当用户不打算再进行跨端迁移或多端协同操作时，可以传入注册时获取的token进行取消注册。 - - 取消注册流转管理服务的代码示例如下： - - ```ts - try { - // 参数token为注册token - continuationManager.unregisterContinuation(token).then((data) => { - console.info('unregisterContinuation finished, ' + JSON.stringify(data)); - }).catch((err) => { - console.error('unregisterContinuation failed, cause: ' + JSON.stringify(err)); - }); - } catch (err) { - console.error('unregisterContinuation failed, cause: ' + JSON.stringify(err)); - } +# ContinuationManager开发指导 + +> 说明：本模块接口用于拉起系统中的设备选择模块，由于该模块功能暂不完备，因此**流转能力整体暂不支持用于应用开发**。 + +## 场景简介 +随着全场景多设备生活方式的不断深入，用户拥有的设备越来越多，每个设备都能在适合的场景下提供良好的体验，但是，每个设备也有使用场景的局限。流转能力致力于打破设备界限，多设备联动，使用户应用程序可分可合、可流转，实现体验升级。 + +continuationManager作为流转能力的入口，主要用于拉起系统中的设备选择模块供用户选择，待选择设备后，会给用户返回已选择的远端设备信息，用户可以根据远端设备信息发起跨端迁移或多端协同操作。 + +![continuationManager](figures/continuationManager.png) + +## 接口说明 +| 接口名 | 接口描述 | +| ---------------------------------------------------------------------------------------------- | ----------- | +| registerContinuation(callback: AsyncCallback\): void | 注册流转管理服务，并获取对应的注册token，无过滤条件(AsyncCallback)。 | +| registerContinuation(options: ContinuationExtraParams, callback: AsyncCallback\): void | 注册流转管理服务，并获取对应的注册token(AsyncCallback)。 | +| registerContinuation(options?: ContinuationExtraParams): Promise\ | 连接流转管理服务，并获取对应的注册token(Promise)。 | +| on(type: "deviceSelected", token: number, callback: Callback\>): void | 监听设备连接状态(Callback)。 | +| on(type: "deviceUnselected", token: number, callback: Callback\>): void | 监听设备断开状态(Callback)。 | +| off(type: "deviceSelected", token: number): void | 取消监听设备连接状态。 | +| off(type: "deviceUnselected", token: number): void | 取消监听设备断开状态。 | +| startContinuationDeviceManager(token: number, callback: AsyncCallback\): void | 拉起设备选择模块，可显示组网内可选择设备列表信息，无过滤条件(AsyncCallback)。 | +| startContinuationDeviceManager(token: number, options: ContinuationExtraParams, callback: AsyncCallback\): void | 拉起设备选择模块，可显示组网内可选择设备列表信息(AsyncCallback)。 | +| startContinuationDeviceManager(token: number, options?: ContinuationExtraParams): Promise\ | 拉起设备选择模块，可显示组网内可选择设备列表信息(Promise)。 | +| updateContinuationState(token: number, deviceId: string, status: DeviceConnectState, callback: AsyncCallback\): void | 通知设备选择模块，更新当前的流转状态(AsyncCallback)。 | +| updateContinuationState(token: number, deviceId: string, status: DeviceConnectState): Promise\ | 通知设备选择模块，更新当前的流转状态(Promise)。 | +| unregisterContinuation(token: number, callback: AsyncCallback\): void | 取消注册流转管理服务，传入注册时获取的token进行取消注册(AsyncCallback)。 | +| unregisterContinuation(token: number): Promise\ | 取消注册流转管理服务，传入注册时获取的token进行取消注册(Promise)。 | + +## 开发步骤 +1. 导入continuationManager模块。 + + ```ts + import continuationManager from '@ohos.continuation.continuationManager'; + ``` + +2. 申请分布式权限 DISTRIBUTED_DATASYNC。 + + 权限申请在FA平台和Stage平台有区别，FA平台需要在`config.json`里面进行配置请求权限，示例代码如下： + + ```json + { + "module": { + "reqPermissions": [ + { + "name": "ohos.permission.DISTRIBUTED_DATASYNC" + } + ] + } + } + ``` + + 这个权限还需要在应用首次启动的时候弹窗获取用户授权，可以通过如下代码实现： + + ```ts + import abilityAccessCtrl from "@ohos.abilityAccessCtrl"; + import bundle from '@ohos.bundle'; + import featureAbility from '@ohos.ability.featureAbility'; + + async function requestPermission() { + let permissions: Array = [ + "ohos.permission.DISTRIBUTED_DATASYNC" + ]; + let needGrantPermission: boolean = false; + let atManager: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); + let applicationInfo = await bundle.getApplicationInfo('ohos.samples.etsDemo', 0, 100); + for (let i = 0; i < permissions.length; i++) { + let result = await atManager.verifyAccessToken(applicationInfo.accessTokenId, permissions[i]); + //判断是否未申请该权限 + if (result == abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { + needGrantPermission = true; + break; + } + } + // 如果未申请该权限，则需要调用requestPermissionsFromUser接口申请权限 + if (needGrantPermission) { + await featureAbility.getContext().requestPermissionsFromUser(permissions, 1); + } else { + console.info('app permission already granted'); + } + } + ``` + + Stage平台需要在`module.json5`里面进行配置请求权限，示例代码如下： + + ```json + { + "module": { + "requestPermissions": [ + { + "name": "ohos.permission.DISTRIBUTED_DATASYNC" + } + ] + } + } + ``` + + ```ts + import abilityAccessCtrl from "@ohos.abilityAccessCtrl"; + import bundle from '@ohos.bundle'; + + async function requestPermission() { + let permissions: Array = [ + "ohos.permission.DISTRIBUTED_DATASYNC" + ]; + let needGrantPermission: boolean = false; + let atManger: abilityAccessCtrl.AtManager = abilityAccessCtrl.createAtManager(); + let applicationInfo = await bundle.getApplicationInfo('ohos.samples.continuationmanager', 0, 100); + for (const permission of permissions) { + try { + let grantStatus = await atManger.verifyAccessToken(applicationInfo.accessTokenId, permission); + //判断是否未申请该权限 + if (grantStatus === abilityAccessCtrl.GrantStatus.PERMISSION_DENIED) { + needGrantPermission = true; + break; + } + } catch (err) { + console.error('app permission query grant status error' + JSON.stringify(err)); + needGrantPermission = true; + break; + } + } + // 如果未申请该权限，则需要调用requestPermissionsFromUser接口申请权限 + if (needGrantPermission) { + try { + // globalThis.context即Ability.context,需提前在MainAbility.ts文件中赋值 + await globalThis.context.requestPermissionsFromUser(permissions); + } catch (err) { + console.error('app permission request permissions error' + JSON.stringify(err)); + } + } else { + console.info('app permission already granted'); + } + } + ``` + +3. 注册流转管理服务，获取对应的注册token。 + + 注册流转管理服务的代码示例如下： + + ```ts + let token: number = -1; // 用于保存注册成功并返回的token，后续使用其完成监听设备连接/断开状态、拉起设备选择模块以及更新流转状态的动作 + try { + continuationManager.registerContinuation().then((data) => { + console.info('registerContinuation finished, ' + JSON.stringify(data)); + token = data; // 获取到对应的注册token，并赋值给token变量 + }).catch((err) => { + console.error('registerContinuation failed, cause: ' + JSON.stringify(err)); + }); + } catch (err) { + console.error('registerContinuation failed, cause: ' + JSON.stringify(err)); + } + ``` + +4. 监听设备状态。 + + 监听设备连接状态的代码示例如下： + + ```ts + let remoteDeviceId: string = ""; // 用于保存用户选择的远端设备信息，后续使用其完成跨端迁移或多端协同操作 + + try { + // 参数token为注册token + continuationManager.on("deviceSelected", token, (continuationResults) => { + console.info('registerDeviceSelectedCallback len: ' + continuationResults.length); + if (continuationResults.length <= 0) { + console.info('no selected device'); + return; + } + remoteDeviceId = continuationResults[0].id; // 将选择的第一个远端设备deviceId赋值给remoteDeviceId变量 + + // 将remoteDeviceId参数传给want + let want = { + deviceId: remoteDeviceId, + bundleName: 'ohos.samples.continuationmanager', + abilityName: 'MainAbility' + }; + globalThis.abilityContext.startAbility(want).then((data) => { + console.info('StartRemoteAbility finished, ' + JSON.stringify(data)); + }).catch((err) => { + console.error('StartRemoteAbility failed, cause: ' + JSON.stringify(err)); + }); + }); + } catch (err) { + console.error('on failed, cause: ' + JSON.stringify(err)); + } + ``` + + 上述多端协同操作为Stage平台的跨设备拉起，FA平台详情见[PageAbility开发指导](fa-pageability.md)。 + + 同时用户还可通知设备选择模块，更新当前的流转状态，代码示例如下： + + ```ts + // 设置设备流转状态 + let deviceConnectStatus: continuationManager.DeviceConnectState = continuationManager.DeviceConnectState.CONNECTED; + + // 参数token为注册token，参数remoteDeviceId为获取到的remoteDeviceId + try { + continuationManager.updateContinuationState(token, remoteDeviceId, deviceConnectStatus).then((data) => { + console.info('updateContinuationState finished, ' + JSON.stringify(data)); + }).catch((err) => { + console.error('updateContinuationState failed, cause: ' + JSON.stringify(err)); + }); + } catch (err) { + console.error('updateContinuationState failed, cause: ' + JSON.stringify(err)); + } + ``` + + 监听设备断开状态，方便用户终止跨端迁移或多端协同操作，代码示例如下： + + ```ts + try { + // 参数token为注册token + continuationManager.on("deviceUnselected", token, (continuationResults) => { + console.info('onDeviceUnselected len: ' + continuationResults.length); + if (continuationResults.length <= 0) { + console.info('no unselected device'); + return; + } + + // 更新设备流转状态 + let unselectedDeviceId: string = continuationResults[0].id; // 将取消选择的第一个远端设备deviceId赋值给unselectedDeviceId变量 + let deviceConnectStatus: continuationManager.DeviceConnectState = continuationManager.DeviceConnectState.DISCONNECTING; // 设备断开状态 + + // 参数token为注册token，参数unselectedDeviceId为获取到的unselectedDeviceId + continuationManager.updateContinuationState(token, unselectedDeviceId, deviceConnectStatus).then((data) => { + console.info('updateContinuationState finished, ' + JSON.stringify(data)); + }).catch((err) => { + console.error('updateContinuationState failed, cause: ' + JSON.stringify(err)); + }); + }); + } catch (err) { + console.error('updateContinuationState failed, cause: ' + JSON.stringify(err)); + } + ``` + +5. 拉起设备选择模块，可显示组网内可选择设备列表信息，供用户选择。 + + 拉起设备选择模块的代码示例如下： + + ```ts + // 过滤参数 + let continuationExtraParams = { + deviceType: ["00E"], // 设备类型 + continuationMode: continuationManager.ContinuationMode.COLLABORATION_SINGLE // 设备选择模块单选模式 + }; + + try { + // 参数token为注册token + continuationManager.startContinuationDeviceManager(token, continuationExtraParams).then((data) => { + console.info('startContinuationDeviceManager finished, ' + JSON.stringify(data)); + }).catch((err) => { + console.error('startContinuationDeviceManager failed, cause: ' + JSON.stringify(err)); + }); + } catch (err) { + console.error('startContinuationDeviceManager failed, cause: ' + JSON.stringify(err)); + } + ``` + +6. 当用户不打算再进行跨端迁移或多端协同操作时，可以传入注册时获取的token进行取消注册。 + + 取消注册流转管理服务的代码示例如下： + + ```ts + try { + // 参数token为注册token + continuationManager.unregisterContinuation(token).then((data) => { + console.info('unregisterContinuation finished, ' + JSON.stringify(data)); + }).catch((err) => { + console.error('unregisterContinuation failed, cause: ' + JSON.stringify(err)); + }); + } catch (err) { + console.error('unregisterContinuation failed, cause: ' + JSON.stringify(err)); + } ``` \ No newline at end of file diff --git a/zh-cn/application-dev/ability/fa-brief.md b/zh-cn/application-dev/ability-deprecated/fa-brief.md similarity index 100% rename from zh-cn/application-dev/ability/fa-brief.md rename to zh-cn/application-dev/ability-deprecated/fa-brief.md diff --git a/zh-cn/application-dev/ability/fa-dataability.md b/zh-cn/application-dev/ability-deprecated/fa-dataability.md similarity index 100% rename from zh-cn/application-dev/ability/fa-dataability.md rename to zh-cn/application-dev/ability-deprecated/fa-dataability.md diff --git a/zh-cn/application-dev/ability/fa-formability.md b/zh-cn/application-dev/ability-deprecated/fa-formability.md similarity index 100% rename from zh-cn/application-dev/ability/fa-formability.md rename to zh-cn/application-dev/ability-deprecated/fa-formability.md diff --git a/zh-cn/application-dev/ability/fa-pageability.md b/zh-cn/application-dev/ability-deprecated/fa-pageability.md similarity index 100% rename from zh-cn/application-dev/ability/fa-pageability.md rename to zh-cn/application-dev/ability-deprecated/fa-pageability.md diff --git a/zh-cn/application-dev/ability/fa-serviceability.md b/zh-cn/application-dev/ability-deprecated/fa-serviceability.md similarity index 100% rename from zh-cn/application-dev/ability/fa-serviceability.md rename to zh-cn/application-dev/ability-deprecated/fa-serviceability.md diff --git a/zh-cn/application-dev/ability/figures/AbilityComponentInstanceMission.png b/zh-cn/application-dev/ability-deprecated/figures/AbilityComponentInstanceMission.png similarity index 100% rename from zh-cn/application-dev/ability/figures/AbilityComponentInstanceMission.png rename to zh-cn/application-dev/ability-deprecated/figures/AbilityComponentInstanceMission.png diff --git a/zh-cn/application-dev/ability/figures/ExtensionAbility.png b/zh-cn/application-dev/ability-deprecated/figures/ExtensionAbility.png similarity index 100% rename from zh-cn/application-dev/ability/figures/ExtensionAbility.png rename to zh-cn/application-dev/ability-deprecated/figures/ExtensionAbility.png diff --git a/zh-cn/application-dev/ability/figures/aa-dump-a.PNG b/zh-cn/application-dev/ability-deprecated/figures/aa-dump-a.PNG old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/figures/aa-dump-a.PNG rename to zh-cn/application-dev/ability-deprecated/figures/aa-dump-a.PNG diff --git a/zh-cn/application-dev/ability/figures/aa-dump-i.PNG b/zh-cn/application-dev/ability-deprecated/figures/aa-dump-i.PNG old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/figures/aa-dump-i.PNG rename to zh-cn/application-dev/ability-deprecated/figures/aa-dump-i.PNG diff --git a/zh-cn/application-dev/ability/figures/aa-dump-l.PNG b/zh-cn/application-dev/ability-deprecated/figures/aa-dump-l.PNG old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/figures/aa-dump-l.PNG rename to zh-cn/application-dev/ability-deprecated/figures/aa-dump-l.PNG diff --git a/zh-cn/application-dev/ability/figures/contextIntroduction.png b/zh-cn/application-dev/ability-deprecated/figures/contextIntroduction.png similarity index 100% rename from zh-cn/application-dev/ability/figures/contextIntroduction.png rename to zh-cn/application-dev/ability-deprecated/figures/contextIntroduction.png diff --git a/zh-cn/application-dev/ability/figures/continuation-info.png b/zh-cn/application-dev/ability-deprecated/figures/continuation-info.png old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/figures/continuation-info.png rename to zh-cn/application-dev/ability-deprecated/figures/continuation-info.png diff --git a/zh-cn/application-dev/ability/figures/continuationManager.png b/zh-cn/application-dev/ability-deprecated/figures/continuationManager.png similarity index 100% rename from zh-cn/application-dev/ability/figures/continuationManager.png rename to zh-cn/application-dev/ability-deprecated/figures/continuationManager.png diff --git a/zh-cn/application-dev/ability/figures/fa-dataability-uri.png b/zh-cn/application-dev/ability-deprecated/figures/fa-dataability-uri.png similarity index 100% rename from zh-cn/application-dev/ability/figures/fa-dataability-uri.png rename to zh-cn/application-dev/ability-deprecated/figures/fa-dataability-uri.png diff --git a/zh-cn/application-dev/ability/figures/fa-form-example.png b/zh-cn/application-dev/ability-deprecated/figures/fa-form-example.png similarity index 100% rename from zh-cn/application-dev/ability/figures/fa-form-example.png rename to zh-cn/application-dev/ability-deprecated/figures/fa-form-example.png diff --git a/zh-cn/application-dev/ability/figures/fa-pageAbility-lifecycle.png b/zh-cn/application-dev/ability-deprecated/figures/fa-pageAbility-lifecycle.png similarity index 100% rename from zh-cn/application-dev/ability/figures/fa-pageAbility-lifecycle.png rename to zh-cn/application-dev/ability-deprecated/figures/fa-pageAbility-lifecycle.png diff --git a/zh-cn/application-dev/ability/figures/fa-threading-model.png b/zh-cn/application-dev/ability-deprecated/figures/fa-threading-model.png similarity index 100% rename from zh-cn/application-dev/ability/figures/fa-threading-model.png rename to zh-cn/application-dev/ability-deprecated/figures/fa-threading-model.png diff --git a/zh-cn/application-dev/ability/figures/favsstage.png b/zh-cn/application-dev/ability-deprecated/figures/favsstage.png similarity index 100% rename from zh-cn/application-dev/ability/figures/favsstage.png rename to zh-cn/application-dev/ability-deprecated/figures/favsstage.png diff --git a/zh-cn/application-dev/ability/figures/lifecycle.png b/zh-cn/application-dev/ability-deprecated/figures/lifecycle.png similarity index 100% rename from zh-cn/application-dev/ability/figures/lifecycle.png rename to zh-cn/application-dev/ability-deprecated/figures/lifecycle.png diff --git a/zh-cn/application-dev/ability/figures/page-ability-lifecycle.png b/zh-cn/application-dev/ability-deprecated/figures/page-ability-lifecycle.png old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/figures/page-ability-lifecycle.png rename to zh-cn/application-dev/ability-deprecated/figures/page-ability-lifecycle.png diff --git a/zh-cn/application-dev/ability/figures/stage-call.png b/zh-cn/application-dev/ability-deprecated/figures/stage-call.png similarity index 100% rename from zh-cn/application-dev/ability/figures/stage-call.png rename to zh-cn/application-dev/ability-deprecated/figures/stage-call.png diff --git a/zh-cn/application-dev/ability/figures/stageabilitylifecyclecallback.png b/zh-cn/application-dev/ability-deprecated/figures/stageabilitylifecyclecallback.png similarity index 100% rename from zh-cn/application-dev/ability/figures/stageabilitylifecyclecallback.png rename to zh-cn/application-dev/ability-deprecated/figures/stageabilitylifecyclecallback.png diff --git a/zh-cn/application-dev/ability/figures/stageconcept.png b/zh-cn/application-dev/ability-deprecated/figures/stageconcept.png similarity index 100% rename from zh-cn/application-dev/ability/figures/stageconcept.png rename to zh-cn/application-dev/ability-deprecated/figures/stageconcept.png diff --git a/zh-cn/application-dev/ability/figures/stagedesign.png b/zh-cn/application-dev/ability-deprecated/figures/stagedesign.png similarity index 100% rename from zh-cn/application-dev/ability/figures/stagedesign.png rename to zh-cn/application-dev/ability-deprecated/figures/stagedesign.png diff --git a/zh-cn/application-dev/ability/figures/stageprocessmodel.png b/zh-cn/application-dev/ability-deprecated/figures/stageprocessmodel.png similarity index 100% rename from zh-cn/application-dev/ability/figures/stageprocessmodel.png rename to zh-cn/application-dev/ability-deprecated/figures/stageprocessmodel.png diff --git a/zh-cn/application-dev/ability/public_sys-resources/icon-caution.gif b/zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-caution.gif old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/public_sys-resources/icon-caution.gif rename to zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-caution.gif diff --git a/zh-cn/application-dev/ability/public_sys-resources/icon-danger.gif b/zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-danger.gif old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/public_sys-resources/icon-danger.gif rename to zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-danger.gif diff --git a/zh-cn/application-dev/ability/public_sys-resources/icon-note.gif b/zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-note.gif old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/public_sys-resources/icon-note.gif rename to zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-note.gif diff --git a/zh-cn/application-dev/ability/public_sys-resources/icon-notice.gif b/zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-notice.gif old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/public_sys-resources/icon-notice.gif rename to zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-notice.gif diff --git a/zh-cn/application-dev/ability/public_sys-resources/icon-tip.gif b/zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-tip.gif old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/public_sys-resources/icon-tip.gif rename to zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-tip.gif diff --git a/zh-cn/application-dev/ability/public_sys-resources/icon-warning.gif b/zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-warning.gif old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/public_sys-resources/icon-warning.gif rename to zh-cn/application-dev/ability-deprecated/public_sys-resources/icon-warning.gif diff --git a/zh-cn/application-dev/ability/stage-ability-continuation.md b/zh-cn/application-dev/ability-deprecated/stage-ability-continuation.md old mode 100755 new mode 100644 similarity index 100% rename from zh-cn/application-dev/ability/stage-ability-continuation.md rename to zh-cn/application-dev/ability-deprecated/stage-ability-continuation.md diff --git a/zh-cn/application-dev/ability/stage-ability.md b/zh-cn/application-dev/ability-deprecated/stage-ability.md similarity index 100% rename from zh-cn/application-dev/ability/stage-ability.md rename to zh-cn/application-dev/ability-deprecated/stage-ability.md diff --git a/zh-cn/application-dev/ability/stage-brief.md b/zh-cn/application-dev/ability-deprecated/stage-brief.md similarity index 98% rename from zh-cn/application-dev/ability/stage-brief.md rename to zh-cn/application-dev/ability-deprecated/stage-brief.md index 3c8b11d151..199b999a7c 100644 --- a/zh-cn/application-dev/ability/stage-brief.md +++ b/zh-cn/application-dev/ability-deprecated/stage-brief.md @@ -1,122 +1,122 @@ -# 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) diff --git a/zh-cn/application-dev/ability/stage-call.md b/zh-cn/application-dev/ability-deprecated/stage-call.md similarity index 100% rename from zh-cn/application-dev/ability/stage-call.md rename to zh-cn/application-dev/ability-deprecated/stage-call.md diff --git a/zh-cn/application-dev/ability/stage-formextension.md b/zh-cn/application-dev/ability-deprecated/stage-formextension.md similarity index 100% rename from zh-cn/application-dev/ability/stage-formextension.md rename to zh-cn/application-dev/ability-deprecated/stage-formextension.md diff --git a/zh-cn/application-dev/ability/stage-serviceextension.md b/zh-cn/application-dev/ability-deprecated/stage-serviceextension.md similarity index 100% rename from zh-cn/application-dev/ability/stage-serviceextension.md rename to zh-cn/application-dev/ability-deprecated/stage-serviceextension.md diff --git a/zh-cn/application-dev/ability/wantagent.md b/zh-cn/application-dev/ability-deprecated/wantagent.md similarity index 97% rename from zh-cn/application-dev/ability/wantagent.md rename to zh-cn/application-dev/ability-deprecated/wantagent.md index f193385c27..5ce8f9a049 100644 --- a/zh-cn/application-dev/ability/wantagent.md +++ b/zh-cn/application-dev/ability-deprecated/wantagent.md @@ -1,88 +1,88 @@ -# WantAgent开发指导 -## 场景简介 -WantAgent封装了一个行为意图信息，可以通过WantAgent.trigger接口主动触发，也可以通过与通知绑定被动触发。 - -具体的行为包括：启动Ability和发布公共事件。 - -## 接口说明 -| 接口名 | 接口描述 | -| ---------------------------------------------------------------------------------------------- | ----------- | -| getWantAgentInfo(info: WantAgentInfo, callback: AsyncCallback\) | 以异步回调形式创建WantAgent对象。 | -| getWantAgent(info: WantAgentInfo): Promise\ | 以Promise形式创建WantAgent对象。 | -| trigger(agent: WantAgent, triggerInfo: TriggerInfo, callback?: Callback\) | 触发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对象。 | +| getWantAgent(info: WantAgentInfo): Promise\ | 以Promise形式创建WantAgent对象。 | +| trigger(agent: WantAgent, triggerInfo: TriggerInfo, callback?: Callback\) | 触发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)) + }) + ``` -- GitLab