ability_ability_runtime/README_zh.md

元能力子系统

简介

元能力子系统实现对Ability的运行及生命周期进行统一的调度和管理，应用进程能够支撑多个Ability，Ability具有跨应用进程间和同一进程内调用的能力。Ability管理服务统一调度和管理应用中各Ability，并对Ability的生命周期变更进行管理。

元能力子系统架构图说明：

• Ability Kit为Ability的运行提供基础的运行环境支撑。Ability是系统调度应用的最小单元，是能够完成一个独立功能的组件，一个应用可以包含一个或多个Ability。Ability分为FA（Feature Ability）和PA（Particle Ability）两种类，其中FA支持Page Ability，PA支持Service Ability和Data Ability。

• Ability管理服务（AbilityManagerService）：用于协调各Ability运行关系、及对生命周期进行调度的系统服务。

  • Ability栈管理模块（AbilityStackManager）负责维护各个Ability之间跳转的先后关系。
  • 连接管理模块（AbilityConnectManager）是Ability管理服务对Service类型Ability连接管理的模块。
  • 数据管理模块（DataAbilityManager）是Ability管理服务对Data类型Ability管理的模块。
  • App管理服务调度模块（AppScheduler）提供Ability管理服务对用户程序管理服务进行调度管理的能力。
  • Ability调度模块（AbilityScheduler）提供对Ability进行调度管理的能力。
  • 生命周期调度模块（LifecycleDeal）是Ability管理服务对Ability的生命周期事件进行管理调度的模块。

Ability生命周期介绍（Ability Life Cycle）是Ability被调度到INACTIVE、ACTIVE、BACKGROUND等各个状态的统称（主要涉及PageAbility类型和ServiceAbility类型的Ability）。

• PageAbility类型的Ability生命周期流转如下图所示

• ServiceAbility类型的Ability生命周期流转如下图所示

Ability生命周期状态说明：

• UNINITIALIZED：未初始状态，为临时状态，Ability被创建后会由UNINITIALIZED状态进入INITIAL状态。

• INITIAL：初始化状态，也表示停止状态，表示当前Ability未运行，Ability被启动后由INITIAL态进入INACTIVE状态。

• INACTIVE：未激活状态，表示当前窗口已显示但是无焦点状态，由于Window暂未支持焦点的概念，当前状态与ACTIVE一致。

• ACTIVE：前台激活状态，表示当前窗口已显示，并获取焦点，Ability在退到后台之前先由ACTIVE状态进入INACTIVE状态。

• BACKGROUND: 后台状态，表示当前Ability退到后台，Ability在被销毁后由BACKGROUND状态进入INITIAL状态，或者重新被激活后由BACKGROUND状态进入ACTIVE状态。

PageAbility类型Ability生命周期回调如下图所示：

ServiceAbility类型Ability生命周期回调如下图所示:

目录

foundation/
└──foundation/aafwk/standard
   ├── frameworks
   │   └── kits
   │       └── ability						# AbilityKit实现的核心代码
   ├── interfaces
   │   └── innerkits
   │        └── want						# Ability之间交互的信息载体的对外接口
   └── services
       ├── abilitymgr						# Ability管理服务框架代码
       ├── common							# 日志组件目录
       ├── test								# 测试目录
       └── tools							# aa命令代码目录

使用说明

启动Abiltiy

启动新的ability(callback形式)

• startAbility参数描述

名称	读写属性	类型	必填	描述
parameter	读写	StartAbilityParameter	是	表示被启动的Ability
callback	只读	AsyncCallback	是	被指定的回调方法

• StartAbilityParameter类型说明

名称	读写属性	类型	必填	描述
want	读写	want	是	表示需要包含有关目标启动能力的信息
abilityStartSetting	只读	string	否	指示启动能力中使用的特殊启动设置

• want类型说明

名称	读写属性	类型	必填	描述
deviceId	读写	string	否	设备id
bundleName	读写	string	否	Bundle名
abilityName	读写	string	否	Ability 名
uri	读写	string	否	请求中URI的描述
type	读写	string	否	Want中类型的说明
flags	读写	number	否	Want中标志的选项，必填
action	读写	string	否	Want中对操作的描述
parameters	读写	{[key: string]: any}	否	Want中WantParams对象的描述
entities	读写	string	否	对象中实体的描述

• 返回值

  void

• 示例

import featureAbility from '@ohos.ability.featureAbility'
function addSlotsCallBack(err) {
	console.info("==========================>startAbility=======================>");
}
featureAbility.startAbility(
        {
        want:
        {
            action: "",
            entities: [""],
            type: "",
            options: {
                // indicates the grant to perform read operations on the URI
                authReadUriPermission: true,
                // indicates the grant to perform write operations on the URI
                authWriteUriPermission: true,
                // support forward intent result to origin ability
                abilityForwardResult: true,
                // used for marking the ability start-up is triggered by continuation
                abilityContinuation: true,
                // specifies whether a component does not belong to ohos
                notOhosComponent: true,
                // specifies whether an ability is started
                abilityFormEnabled: true,
                // indicates the grant for possible persisting on the URI.
                authPersistableUriPermission: true,
                // indicates the grant for possible persisting on the URI.
                authPrefixUriPermission: true,
                // support distributed scheduling system start up multiple devices
                abilitySliceMultiDevice: true,
                // indicates that an ability using the service template is started regardless of whether the
                // host application has been started.
                startForegroundAbility: true,
                // install the specified ability if it's not installed.
                installOnDemand: true,
                // return result to origin ability slice
                abilitySliceForwardResult: true,
                // install the specified ability with background mode if it's not installed.
                installWithBackgroundMode: true
            },
            deviceId: "",
            bundleName: "com.example.startability",
            abilityName: "com.example.startability.MainAbility",
            uri: ""
        },
    },
  );
)

启动新的ability(Promise形式)

• startAbility参数描述

名称	读写属性	类型	必填	描述
parameter	读写	StartAbilityParameter	是	表示被启动的Ability

• StartAbilityParameter类型说明

名称	读写属性	类型	必填	描述
want	读写	want	是	表示需要包含有关目标启动能力的信息
abilityStartSetting	只读	string	否	指示启动能力中使用的特殊启动设置

• want类型说明

名称	读写属性	类型	必填	描述
deviceId	读写	string	否	设备id
bundleName	读写	string	否	Bundle名
abilityName	读写	string	否	Ability 名字
uri	读写	string	否	请求中URI的描述
type	读写	string	否	Want中类型的说明
flags	读写	number	否	Want中标志的选项，必填
action	读写	string	否	Want中对操作的描述
parameters	读写	{[key: string]: any}	否	Want中WantParams对象的描述
entities	读写	string	否	对象中实体的描述

• 返回值

  void

• 示例

import featureAbility from '@ohos.ability.featureAbility'
featureAbility.startAbility(
    {
        want:
        {
            action: "action.system.home",
            entities: ["entity.system.home"],
            type: "MIMETYPE",
            options: {
                // indicates the grant to perform read operations on the URI
                authReadUriPermission: true,
                // indicates the grant to perform write operations on the URI
                authWriteUriPermission: true,
                // support forward intent result to origin ability
                abilityForwardResult: true,
                // used for marking the ability start-up is triggered by continuation
                abilityContinuation: true,
                // specifies whether a component does not belong to ohos
                notOhosComponent: true,
                // specifies whether an ability is started
                abilityFormEnabled: true,
                // indicates the grant for possible persisting on the URI.
                authPersistableUriPermission: true,
                // indicates the grant for possible persisting on the URI.
                authPrefixUriPermission: true,
                // support distributed scheduling system start up multiple devices
                abilitySliceMultiDevice: true,
                // indicates that an ability using the service template is started regardless of whether the
                // host application has been started.
                startForegroundAbility: true,
                // install the specified ability if it's not installed.
                installOnDemand: true,
                // return result to origin ability slice
                abilitySliceForwardResult: true,
                // install the specified ability with background mode if it's not installed.
                installWithBackgroundMode: true
            },
            deviceId: "",
            bundleName: "com.example.startability",
            abilityName: "com.example.startability.MainAbility",
            uri: ""
        },
    }
   ).then((void) => {
	console.info("==========================>startAbility=======================>");
});

停止Ability

设置page ability返回给被调用方的结果代码和数据，并销毁此page ability(callback形式)

• 参数描述

名称	读写属性	类型	必填	描述
callback	只读	AsyncCallback<void>	是	被指定的回调方法

• 返回值

  void

• 示例

import featureAbility from '@ohos.ability.featureability';
function terminateSelfCallBack(err) {
	console.info("==========================>terminateSelfCallBack=======================>");
}
featureAbility.terminateSelf()

设置page ability返回给被调用方的结果代码和数据，并销毁此page ability(Promise形式)

• 参数描述

  Null

• 返回值

• void

• 示例

import featureAbility from '@ohos.ability.featureability';
featureAbility.terminateSelf().then((void) => {		    console.info("==========================>terminateSelfCallBack=======================>");
});

aa命令

aa help

命令	描述
aa help	显示aa命令帮助信息

aa start

命令	描述
aa start [-d ] -a -b [-D]	启动ability，设备ID 可空

示例：
aa start -d 12345 -a com.ohos.app.MainAbility -b com.ohos.app -D

aa dump

命令	描述
aa dump -a	打印栈中的Ability信息

aa force-stop

命令	描述
aa force-stop	强制停止application

示例：
aa force-stop com.ohos.app

相关仓

元能力子系统

appexecfwk_standard

aafwk_standard