From fb3e28e889644ac87dbf4c80ff68ad6c8143d724 Mon Sep 17 00:00:00 2001 From: mingxihua Date: Wed, 1 Feb 2023 16:39:39 +0800 Subject: [PATCH] mingxihua@huawei.com.cn Signed-off-by: mingxihua --- .../reference/apis/js-apis-ability-context.md | 86 +++++++-- .../apis/js-apis-ability-dataUriUtils.md | 46 ++--- .../apis/js-apis-ability-errorCode.md | 10 +- .../apis/js-apis-ability-featureAbility.md | 164 ++++++++++-------- .../apis/js-apis-ability-particleAbility.md | 71 ++++---- .../js-apis-app-ability-abilityConstant.md | 4 +- .../apis/js-apis-app-ability-appManager.md | 8 +- .../js-apis-app-ability-missionManager.md | 2 +- .../apis/js-apis-app-ability-uiAbility.md | 45 ++--- .../apis/js-apis-app-ability-wantAgent.md | 6 +- .../apis/js-apis-application-ability.md | 9 +- .../js-apis-application-abilityConstant.md | 4 +- .../js-apis-application-abilityManager.md | 12 +- ...plication-accessibilityExtensionAbility.md | 2 +- .../apis/js-apis-application-appManager.md | 14 +- ...ner-application-serviceExtensionContext.md | 20 +++ ...apis-inner-application-uiAbilityContext.md | 45 ++++- zh-cn/application-dev/tools/aa-tool.md | 2 +- 18 files changed, 351 insertions(+), 199 deletions(-) diff --git a/zh-cn/application-dev/reference/apis/js-apis-ability-context.md b/zh-cn/application-dev/reference/apis/js-apis-ability-context.md index daa313f03a..c71cc797f3 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-ability-context.md +++ b/zh-cn/application-dev/reference/apis/js-apis-ability-context.md @@ -30,8 +30,8 @@ class MainAbility extends Ability { | 名称 | 类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | -| abilityInfo | AbilityInfo | 是 | 否 | Abilityinfo相关信息 | -| currentHapModuleInfo | HapModuleInfo | 是 | 否 | 当前hap包的信息 | +| abilityInfo | [AbilityInfo](js-apis-bundleManager-abilityInfo.md) | 是 | 否 | Abilityinfo相关信息 | +| currentHapModuleInfo | [HapModuleInfo](js-apis-bundleManager-hapModuleInfo.md) | 是 | 否 | 当前hap包的信息 | | config | [Configuration](js-apis-application-configuration.md) | 是 | 否 | 表示配置信息。 | ## AbilityContext.startAbility @@ -40,6 +40,11 @@ startAbility(want: Want, callback: AsyncCallback<void>): void; 启动Ability（callback形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -89,6 +94,11 @@ startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void& 启动Ability（callback形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -142,6 +152,11 @@ startAbility(want: Want, options?: StartOptions): Promise<void>; 启动Ability（promise形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -198,7 +213,12 @@ startAbility(want: Want, options?: StartOptions): Promise<void>; startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void; -启动Ability并在该Ability退出的时候返回执行结果（callback形式）。 +启动一个Ability。Ability被启动后，正常情况下可通过调用[terminateSelfWithResult](#abilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用者。异常情况下比如杀死Ability会返回异常信息给调用者（callback形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -248,7 +268,12 @@ startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void; -启动Ability并在该Ability退出的时候返回执行结果（callback形式）。 +启动一个Ability。Ability被启动后，正常情况下可通过调用[terminateSelfWithResult](#abilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用者。异常情况下比如杀死Ability会返回异常信息给调用者（callback形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -303,7 +328,12 @@ startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>; -启动Ability并在该Ability退出的时候返回执行结果（promise形式）。 +启动一个Ability。Ability被启动后，正常情况下可通过调用[terminateSelfWithResult](#abilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用者。异常情况下比如杀死Ability会返回异常信息给调用者（promise形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -363,6 +393,11 @@ startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncC 启动一个Ability并在该Ability帐号销毁时返回执行结果（callback形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 跨应用场景下，目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **需要权限**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -375,7 +410,7 @@ startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncC | -------- | -------- | -------- | -------- | | want | [Want](js-apis-application-want.md) | 是 | 启动Ability的want信息。 | | accountId | number | 是 | 系统帐号的帐号ID，详情参考[getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess)。 | -| callback | AsyncCallback\ | 是 | 启动Ability的回调函数，返回Ability结果。 | +| callback | AsyncCallback\<[AbilityResult](js-apis-inner-ability-abilityResult.md)\> | 是 | 启动Ability的回调函数，返回Ability结果。 | **错误码：** @@ -420,6 +455,11 @@ startAbilityForResultWithAccount(want: Want, accountId: number, options: StartOp 启动一个Ability并在该Ability帐号销毁时返回执行结果（callback形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **需要权限**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -481,6 +521,11 @@ startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartO 启动一个Ability并在该Ability帐号销毁时返回执行结果（promise形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **需要权限**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -499,7 +544,7 @@ startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartO | 类型 | 说明 | | -------- | -------- | -| Promise<AbilityResult> | 返回一个Promise，包含Ability结果。 | +| Promise<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 返回一个Promise，包含Ability结果。 | **错误码：** @@ -1034,7 +1079,7 @@ terminateSelf(): Promise<void>; terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void; -停止Ability，配合startAbilityForResult使用，返回给接口调用方AbilityResult信息（callback形式）。 +停止当前的Ability。如果该Ability是通过调用[startAbilityForResult](#abilitycontextstartabilityforresult)接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用[startAbilityForResult](#abilitycontextstartabilityforresult)接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者（callback形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -1090,6 +1135,7 @@ terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<voi terminateSelfWithResult(parameter: AbilityResult): Promise<void>; 停止Ability，配合startAbilityForResult使用，返回给接口调用方AbilityResult信息（promise形式）。 +停止当前的Ability。如果该Ability是通过调用[startAbilityForResult](#abilitycontextstartabilityforresult)接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用[startAbilityForResult](#abilitycontextstartabilityforresult)接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者（promise形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -1361,6 +1407,11 @@ startAbilityByCall(want: Want): Promise<Caller>; 启动指定Ability至前台或后台，同时获取其Caller通信接口，调用方可使用Caller与被启动的Ability进行通信。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **系统API**: 此接口为系统接口，三方应用不支持调用。 @@ -1450,6 +1501,11 @@ startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\< 根据account启动Ability（callback形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **需要权限**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -1506,6 +1562,11 @@ startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, ca 根据account启动Ability（callback形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **需要权限**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -1566,6 +1627,11 @@ startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): 根据account启动Ability（Promise形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **需要权限**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -1685,7 +1751,7 @@ setMissionIcon(icon: image.PixelMap, callback:AsyncCallback\): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| icon | image.PixelMap | 是 | 在最近的任务中显示的ability图标。 | +| icon | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 | 在最近的任务中显示的ability图标。 | | callback | AsyncCallback\ | 是 | 指定的回调函数的结果。 | **示例：** @@ -1727,7 +1793,7 @@ setMissionIcon(icon: image.PixelMap): Promise\; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| icon | image.PixelMap | 是 | 在最近的任务中显示的ability图标。 | +| icon | [image.PixelMap](js-apis-image.md#pixelmap7) | 是 | 在最近的任务中显示的ability图标。 | **返回值：** diff --git a/zh-cn/application-dev/reference/apis/js-apis-ability-dataUriUtils.md b/zh-cn/application-dev/reference/apis/js-apis-ability-dataUriUtils.md index 2a85d32b2c..0d5aaf26a2 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-ability-dataUriUtils.md +++ b/zh-cn/application-dev/reference/apis/js-apis-ability-dataUriUtils.md @@ -1,6 +1,6 @@ # @ohos.ability.dataUriUtils (DataUriUtils模块) -DataUriUtils模块提供用于处理使用DataAbilityHelper方案的对象的实用程序类的能力，包括获取，添加，更新给定uri的路径组件末尾的ID。 +DataUriUtils模块提供用于处理uri对象的能力，包括获取、绑定、删除和更新指定uri对象的路径末尾的ID。本模块将被app.ability.dataUriUtils模块替代，建议优先使用[@ohos.app.ability.dataUriUtils](js-apis-app-ability-dataUriUtils.md)模块。 > **说明：** > @@ -16,7 +16,7 @@ import dataUriUtils from '@ohos.ability.dataUriUtils'; getId(uri: string): number -获取附加到给定uri的路径组件末尾的ID。 +获取指定uri路径末尾的ID。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -24,18 +24,18 @@ getId(uri: string): number | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | --------------------------- | -| uri | string | 是 | 指示要从中获取ID的uri对象。 | +| uri | string | 是 | 表示uri对象。 | **返回值：** | 类型 | 说明 | | ------ | ------------------------ | -| number | 附加到路径组件末尾的ID。 | +| number | 返回uri路径末尾的ID。 | **示例：** ```ts -dataUriUtils.getId("com.example.dataUriUtils/1221") +let id = dataUriUtils.getId("com.example.dataUriUtils/1221"); ``` @@ -44,7 +44,7 @@ dataUriUtils.getId("com.example.dataUriUtils/1221") attachId(uri: string, id: number): string -将给定ID附加到给定uri的路径组件的末尾。 +将ID附加到uri的路径末尾。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -52,22 +52,22 @@ attachId(uri: string, id: number): string | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | --------------------------- | -| uri | string | 是 | 指示要从中获取ID的uri对象。 | -| id | number | 是 | 指示要附加的ID。 | +| uri | string | 是 | 表示uri对象。 | +| id | number | 是 | 表示要附加的ID。 | **返回值：** | 类型 | 说明 | | ------ | --------------------- | -| string | 附加给定ID的uri对象。 | +| string | 返回附加ID之后的uri对象。 | **示例：** ```ts -var idint = 1122; -dataUriUtils.attachId( +let id = 1122; +let uri = dataUriUtils.attachId( "com.example.dataUriUtils", - idint, + id, ) ``` @@ -77,7 +77,7 @@ dataUriUtils.attachId( deleteId(uri: string): string -从给定uri的路径组件的末尾删除ID。 +删除指定uri路径末尾的ID。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -85,18 +85,18 @@ deleteId(uri: string): string | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | --------------------------- | -| uri | string | 是 | 指示要从中删除ID的uri对象。 | +| uri | string | 是 | 表示要从中删除ID的uri对象。 | **返回值：** | 类型 | 说明 | | ------ | ------------------- | -| string | ID已删除的uri对象。 | +| string | 返回删除ID之后的uri对象。 | **示例：** ```ts -dataUriUtils.deleteId("com.example.dataUriUtils/1221") +let uri = dataUriUtils.deleteId("com.example.dataUriUtils/1221") ``` @@ -113,22 +113,22 @@ updateId(uri: string, id: number): string | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ------------------- | -| uri | string | 是 | 指示要更新的uri对象 | -| id | number | 是 | 指示新ID | +| uri | string | 是 | 表示uri对象 | +| id | number | 是 | 表示要更新的ID | **返回值：** | 类型 | 说明 | | ------ | --------------- | -| string | 更新的uri对象。 | +| string | 返回更新ID之后的uri对象。 | **示例：** ```ts -var idint = 1122; -dataUriUtils.updateId( - "com.example.dataUriUtils", - idint +let id = 1122; +let uri = dataUriUtils.updateId( + "com.example.dataUriUtils/1221", + id ) ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-ability-errorCode.md b/zh-cn/application-dev/reference/apis/js-apis-ability-errorCode.md index cc7f3cd647..b66275351e 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-ability-errorCode.md +++ b/zh-cn/application-dev/reference/apis/js-apis-ability-errorCode.md @@ -1,8 +1,6 @@ # @ohos.ability.errorCode (ErrorCode) -ErrorCode是定义启动功能时使用的错误代码。 - -本模块提供使用的错误代码的能力，包括没有错误，无效的参数等。 +ErrorCode定义启动Ability时返回的错误码，包括无效的参数、权限拒绝等。 > **说明：** > @@ -16,13 +14,13 @@ import errorCode from '@ohos.ability.errorCode' ## ErrorCode -定义启动功能时使用的错误代码。 +定义启动Ability时返回的错误码。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core | 名称 | 值 | 说明 | | ------------------------------ | ---- | ---------------------------------------- | -| NO_ERROR | 0 | 没有错误。 | +| NO_ERROR | 0 | 没有异常。 | | INVALID_PARAMETER | -1 | 无效的参数。 | | ABILITY_NOT_FOUND | -2 | 找不到ABILITY。 | -| PERMISSION_DENY | -3 | 拒绝许可。 | \ No newline at end of file +| PERMISSION_DENY | -3 | 权限拒绝。 | \ No newline at end of file diff --git a/zh-cn/application-dev/reference/apis/js-apis-ability-featureAbility.md b/zh-cn/application-dev/reference/apis/js-apis-ability-featureAbility.md index 580f5f20ab..ba2bdf14c8 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-ability-featureAbility.md +++ b/zh-cn/application-dev/reference/apis/js-apis-ability-featureAbility.md @@ -1,6 +1,6 @@ # @ohos.ability.featureAbility (FeatureAbility模块) -FeatureAbility模块提供带有UI设计与用户交互的能力，包括启动新的ability、获取dataAbilityHelper、设置此Page Ability、获取当前Ability对应的窗口，连接服务等。 +FeatureAbility模块提供与用户进行交互的Ability的能力，包括启动新的Ability、停止Ability、获取dataAbilityHelper对象、获取当前Ability对应的窗口，连接断连Service等。 > **说明：** > @@ -9,7 +9,7 @@ FeatureAbility模块提供带有UI设计与用户交互的能力，包括启动 ## 使用限制 -FeatureAbility模块的接口只能在Page类型的Ability调用 +FeatureAbility模块的接口只能在Page类型的Ability中调用 ## 导入模块 @@ -21,7 +21,12 @@ import featureAbility from '@ohos.ability.featureAbility'; startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\): void -启动新的ability（callback形式）。 +启动新的Ability（callback形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -30,7 +35,7 @@ startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\) | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------------------------- | ---- | -------------- | | parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | 是 | 表示被启动的Ability。 | -| callback | AsyncCallback\ | 是 | 被指定的回调方法。 | +| callback | AsyncCallback\ | 是 | 以callback的形式返回启动Ability的结果。 | **示例：** @@ -48,7 +53,7 @@ featureAbility.startAbility( deviceId: "", bundleName: "com.example.myapplication", /* FA模型中abilityName由package + Ability name组成 */ - abilityName: "com.example.entry.secondAbility", + abilityName: "com.example.myapplication.secondAbility", uri: "" }, }, @@ -64,7 +69,12 @@ featureAbility.startAbility( startAbility(parameter: StartAbilityParameter): Promise\ -启动新的ability（Promise形式）。 +启动新的Ability（Promise形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -74,6 +84,12 @@ startAbility(parameter: StartAbilityParameter): Promise\ | --------- | ---------------------------------------- | ---- | -------------- | | parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | 是 | 表示被启动的Ability。 | +**返回值：** + +| 类型 | 说明 | +| ---------------------------------------- | ------- | +| Promise\ | Promise形式返回启动Ability结果。 | + **示例：** ```ts @@ -90,7 +106,7 @@ featureAbility.startAbility( deviceId: "", bundleName: "com.example.myapplication", /* FA模型中abilityName由package + Ability name组成 */ - abilityName: "com.example.entry.secondAbility", + abilityName: "com.example.myapplication.secondAbility", uri: "" }, } @@ -103,7 +119,7 @@ featureAbility.startAbility( acquireDataAbilityHelper(uri: string): DataAbilityHelper -获取dataAbilityHelper。 +获取dataAbilityHelper对象。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -111,13 +127,13 @@ acquireDataAbilityHelper(uri: string): DataAbilityHelper | 参数名 | 类型 | 必填 | 说明 | | ---- | ------ | ---- | ------------ | -| uri | string | 是 | 指示要打开的文件的路径。 | +| uri | string | 是 | 表示要打开的文件的路径。 | **返回值：** | 类型 | 说明 | | ----------------- | ------------------------------- | -| DataAbilityHelper | 用来协助其他Ability访问DataAbility的工具类。 | +| [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | 用来协助其他Ability访问DataAbility的工具类。 | **示例：** @@ -132,7 +148,12 @@ var dataAbilityHelper = featureAbility.acquireDataAbilityHelper( startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback\): void -启动一个ability，并在该ability被销毁时返回执行结果（callback形式）。 +启动一个Ability。Ability被启动后，正常情况下可通过调用[terminateSelfWithResult](#featureabilityterminateselfwithresult7)接口使之终止并且返回结果给调用者。异常情况下比如杀死Ability会返回异常信息给调用者（callback形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -141,7 +162,7 @@ startAbilityForResult(parameter: StartAbilityParameter, callback: AsyncCallback\ | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------------------------- | ---- | -------------- | | parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | 是 | 表示被启动的Ability。 | -| callback | AsyncCallback\<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 被指定的回调方法。 | +| callback | AsyncCallback\<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 是 | 以callback的形式返回启动Ability结果。 | **示例：** @@ -159,7 +180,7 @@ featureAbility.startAbilityForResult( deviceId: "", bundleName: "com.example.myapplication", /* FA模型中abilityName由package + Ability name组成 */ - abilityName: "com.example.entry.secondAbility", + abilityName: "com.example.myapplication.secondAbility", uri:"" }, }, @@ -173,7 +194,12 @@ featureAbility.startAbilityForResult( startAbilityForResult(parameter: StartAbilityParameter): Promise\ -启动一个ability，并在该ability被销毁时返回执行结果（Promise形式）。 +启动一个Ability。Ability被启动后，正常情况下可通过调用[terminateSelfWithResult](#featureabilityterminateselfwithresult7)接口使之终止并且返回结果给调用者。异常情况下比如杀死Ability会返回异常信息给调用者（Promise形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -187,7 +213,7 @@ startAbilityForResult(parameter: StartAbilityParameter): Promise\ | 类型 | 说明 | | ---------------------------------------- | ------- | -| Promise\<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | 返回执行结果。 | +| Promise\<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Promise形式返回启动Ability结果。 | **示例：** @@ -205,7 +231,7 @@ featureAbility.startAbilityForResult( deviceId: "", bundleName: "com.example.myapplication", /* FA模型中abilityName由package + Ability name组成 */ - abilityName: "com.example.entry.secondAbility", + abilityName: "com.example.myapplication.secondAbility", uri:"", parameters: { @@ -229,7 +255,7 @@ featureAbility.startAbilityForResult( terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback\): void -设置此Page Ability将返回给调用者的结果代码和数据并破坏此Page Ability（callback形式）。 +停止当前的Ability。如果该Ability是通过调用[startAbilityForResult](#featureabilitystartabilityforresult7)接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用[startAbilityForResult](#featureabilitystartabilityforresult7)接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者（callback形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -237,8 +263,8 @@ terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback\ | 参数名 | 类型 | 必填 | 说明 | | --------- | ------------------------------- | ---- | -------------- | -| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 表示被启动的Ability。 | -| callback | AsyncCallback\ | 是 | 被指定的回调方法。 | +| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 表示停止Ability之后返回的结果。 | +| callback | AsyncCallback\ | 是 | 以callback的形式返回停止Ability结果。 | **示例：** @@ -257,7 +283,7 @@ featureAbility.terminateSelfWithResult( deviceId: "", bundleName: "com.example.myapplication", /* FA模型中abilityName由package + Ability name组成 */ - abilityName: "com.example.entry.secondAbility", + abilityName: "com.example.myapplication.secondAbility", uri:"", parameters: { mykey0: 2222, @@ -281,7 +307,7 @@ featureAbility.terminateSelfWithResult( terminateSelfWithResult(parameter: AbilityResult): Promise\ -设置此Page Ability将返回给调用者的结果代码和数据并破坏此Page Ability（Promise形式）。 +停止当前的Ability。如果该Ability是通过调用[startAbilityForResult](#featureabilitystartabilityforresult7)接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用[startAbilityForResult](#featureabilitystartabilityforresult7)接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者（Promise形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -289,13 +315,13 @@ terminateSelfWithResult(parameter: AbilityResult): Promise\ | 参数名 | 类型 | 必填 | 说明 | | --------- | ------------------------------- | ---- | ------------- | -| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 表示被启动的Ability | +| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | 是 | 表示停止Ability之后返回的结果 | **返回值：** | 类型 | 说明 | | -------------- | --------------- | -| Promise\ | 以Promise形式返回结果。 | +| Promise\ | 以Promise形式返回停止当前Ability结果。 | **示例：** @@ -314,7 +340,7 @@ featureAbility.terminateSelfWithResult( deviceId: "", bundleName: "com.example.myapplication", /* FA模型中abilityName由package + Ability name组成 */ - abilityName: "com.example.entry.secondAbility", + abilityName: "com.example.myapplication.secondAbility", uri:"", parameters: { mykey0: 2222, @@ -345,7 +371,7 @@ hasWindowFocus(callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------- | ---- | ---------------------------------------- | -| callback | AsyncCallback\ | 是 | 被指定的回调方法。
如果此Ability当前具有视窗焦点，则返回true；否则返回false。 | +| callback | AsyncCallback\ | 是 | 以callback的形式返回结果。
如果此Ability当前具有视窗焦点，则返回true；否则返回false。 | **示例：** @@ -368,7 +394,7 @@ hasWindowFocus(): Promise\ | 类型 | 说明 | | ----------------- | ------------------------------------- | -| Promise\ | 如果此Ability当前具有视窗焦点，则返回true；否则返回false。 | +| Promise\ | Promise形式返回结果，如果此Ability当前具有视窗焦点，则返回true；否则返回false。 | **示例：** @@ -383,7 +409,7 @@ featureAbility.hasWindowFocus().then((data) => { getWant(callback: AsyncCallback\): void -获取从Ability发送的Want（callback形式）。 +获取要拉起的Ability对应的Want（callback形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -391,7 +417,7 @@ getWant(callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------- | ---- | --------- | -| callback | AsyncCallback\<[Want](js-apis-application-want.md)> | 是 | 被指定的回调方法。 | +| callback | AsyncCallback\<[Want](js-apis-application-want.md)> | 是 | 以callback的形式返回want。 | **示例：** @@ -406,7 +432,7 @@ featureAbility.getWant((err, data) => { getWant(): Promise\ -获取从Ability发送的Want（Promise形式）。 +获取要拉起的Ability对应的Want（Promise形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -414,7 +440,7 @@ getWant(): Promise\ | 类型 | 说明 | | ----------------------- | ---------------- | -| Promise\<[Want](js-apis-application-want.md)> | 以Promise的形式返回结果。 | +| Promise\<[Want](js-apis-application-want.md)> | 以Promise的形式返回want。 | **示例：** @@ -453,7 +479,7 @@ context.getBundleName((err, data) => { terminateSelf(callback: AsyncCallback\): void -设置Page Ability返回给被调用方的结果代码和数据，并销毁此Page Ability（callback形式）。 +停止当前的Ability（callback形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -461,7 +487,7 @@ terminateSelf(callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------- | ---- | -------- | -| callback | AsyncCallback\ | 是 | 被指定的回调方法 | +| callback | AsyncCallback\ | 是 | 以callback的形式返回停止当前Ability结果 | **示例：** @@ -478,7 +504,7 @@ featureAbility.terminateSelf( terminateSelf(): Promise\ -设置Page Ability返回给被调用方的结果代码和数据，并销毁此Page Ability（Promise形式）。 +停止当前的Ability（Promise形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -486,7 +512,7 @@ terminateSelf(): Promise\ | 类型 | 说明 | | -------------- | ---------------- | -| Promise\ | 以Promise的形式返回结果。 | +| Promise\ | 以Promise的形式返回停止当前Ability结果。 | **示例：** @@ -501,7 +527,7 @@ featureAbility.terminateSelf().then((data) => { connectAbility(request: Want, options:ConnectOptions): number -将当前ability连接到指定ServiceAbility（callback形式）。 +将当前Ability与指定的ServiceAbility进行连接。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -510,13 +536,13 @@ connectAbility(request: Want, options:ConnectOptions): number | 参数名 | 类型 | 必填 | 说明 | | ------- | -------------- | ---- | --------------------- | | request | [Want](js-apis-application-want.md) | 是 | 表示被连接的ServiceAbility。 | -| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | 被指定的回调方法。 | +| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | 表示连接回调函数。 | **返回值：** | 类型 | 说明 | | ------ | -------------------- | -| number | 连接的ServiceAbilityID。 | +| number | 连接的ServiceAbility的ID(ID从0开始自增，每连接成功一次ID加1)。 | **示例：** @@ -536,7 +562,7 @@ var connectId = featureAbility.connectAbility( { deviceId: "", bundleName: "com.ix.ServiceAbility", - abilityName: "ServiceAbilityA", + abilityName: "com.ix.ServiceAbility.ServiceAbilityA", }, { onConnect: onConnectCallback, @@ -558,8 +584,8 @@ disconnectAbility(connection: number, callback:AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | ---------- | -------------------- | ---- | ----------------------- | -| connection | number | 是 | 指定断开连接的ServiceAbilityID | -| callback | AsyncCallback\ | 是 | 被指定的回调方法 | +| connection | number | 是 | 表示断开连接的ServiceAbility的ID | +| callback | AsyncCallback\ | 是 | 以callback的形式返回断开连接结果 | **示例：** @@ -578,7 +604,7 @@ function onFailedCallback(code){ var connectId = featureAbility.connectAbility( { bundleName: "com.ix.ServiceAbility", - abilityName: "ServiceAbilityA", + abilityName: "com.ix.ServiceAbility.ServiceAbilityA", }, { onConnect: onConnectCallback, @@ -605,13 +631,13 @@ disconnectAbility(connection: number): Promise\ | 参数名 | 类型 | 必填 | 说明 | | ---------- | ------ | ---- | ----------------------- | -| connection | number | 是 | 指定断开连接的ServiceAbilityID | +| connection | number | 是 | 表示断开连接的ServiceAbility的ID | **返回值：** | 类型 | 说明 | | -------------- | --------------- | -| Promise\ | 以Promise形式返回结果。 | +| Promise\ | 以Promise形式返回断开连接结果。 | **示例：** @@ -630,7 +656,7 @@ function onFailedCallback(code){ var connectId = featureAbility.connectAbility( { bundleName: "com.ix.ServiceAbility", - abilityName: "ServiceAbilityA", + abilityName: "com.ix.ServiceAbility.ServiceAbilityA", }, { onConnect: onConnectCallback, @@ -659,7 +685,7 @@ getWindow(callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | ----------------------------- | ---- | ----------------------------- | -| callback | AsyncCallback\ | 是 | 返回与当前Ability对应的窗口。 | +| callback | AsyncCallback\<[window.Window](js-apis-window.md#window)> | 是 | callback形式返回当前Ability对应的窗口。 | **示例：** @@ -681,7 +707,7 @@ getWindow(): Promise\; | 类型 | 说明 | | ----------------------- | ----------------------------- | -| Promise\ | 返回与当前Ability对应的窗口。 | +| Promise\<[window.Window](js-apis-window.md#window)> | Promise形式返回当前Ability对应的窗口。 | **示例：** @@ -693,7 +719,7 @@ featureAbility.getWindow().then((data) => { ## AbilityWindowConfiguration -使用时通过featureAbility.AbilityWindowConfiguration获取。 +表示当前Ability对应的窗口配置项，使用时通过featureAbility.AbilityWindowConfiguration获取。 **示例：** @@ -714,7 +740,7 @@ featureAbility.AbilityWindowConfiguration.WINDOW_MODE_UNDEFINED ## AbilityStartSetting -abilityStartSetting属性是一个定义为[key: string]: any的对象，key对应设定类型为：AbilityStartSetting枚举类型，value对应设定类型为：AbilityWindowConfiguration枚举类型。 +表示当前Ability对应的窗口属性，abilityStartSetting属性是一个定义为[key: string]: any的对象，key对应设定类型为：AbilityStartSetting枚举类型，value对应设定类型为：AbilityWindowConfiguration枚举类型。 使用时通过featureAbility.AbilityStartSetting获取。 @@ -734,7 +760,7 @@ featureAbility.AbilityStartSetting.BOUNDS_KEY ## ErrorCode -获取错误代码。 +表示错误码。 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel @@ -742,13 +768,13 @@ featureAbility.AbilityStartSetting.BOUNDS_KEY | ------------------------------ | ---- | ---------------------------------------- | | NO_ERROR7+ | 0 | 没有错误。 | | INVALID_PARAMETER7+ | -1 | 无效的参数。 | -| ABILITY_NOT_FOUND7+ | -2 | 找不到能力。 | -| PERMISSION_DENY7+ | -3 | 拒绝许可。 | +| ABILITY_NOT_FOUND7+ | -2 | 找不到ABILITY。 | +| PERMISSION_DENY7+ | -3 | 权限拒绝。 | ## DataAbilityOperationType -指示数据的操作类型。 +表示数据的操作类型。DataAbility批量操作数据时可以通过该枚举值指定操作类型 **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.FAModel @@ -761,24 +787,26 @@ featureAbility.AbilityStartSetting.BOUNDS_KEY ## flags说明 +表示处理Want的方式。 + **系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityBase | 名称 | 值 | 说明 | | ------------------------------------ | ---------- | ---------------------------------------- | -| FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | 指示对URI执行读取操作的授权。 | -| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | 指示对URI执行写入操作的授权。 | -| FLAG_ABILITY_FORWARD_RESULT | 0x00000004 | 将结果返回给元能力。 | -| FLAG_ABILITY_CONTINUATION | 0x00000008 | 确定是否可以将本地设备上的功能迁移到远程设备。 | -| FLAG_NOT_OHOS_COMPONENT | 0x00000010 | 指定组件是否属于OHOS。 | -| FLAG_ABILITY_FORM_ENABLED | 0x00000020 | 指定是否启动某个能力。 | -| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | 指示URI上可能持久化的授权。
**系统API**: 此接口为系统接口，三方应用不支持调用。 | -| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | 按照前缀匹配的方式验证URI权限。
**系统API**: 此接口为系统接口，三方应用不支持调用。 | -| FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | 支持分布式调度系统中的多设备启动。 | -| FLAG_START_FOREGROUND_ABILITY | 0x00000200 | 指示无论主机应用程序是否已启动，都将启动使用服务模板的功能。
**系统API**: 此接口为系统接口，三方应用不支持调用。 | -| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | 表示迁移是可拉回的。 | -| FLAG_INSTALL_ON_DEMAND | 0x00000800 | 如果未安装指定的功能，请安装该功能。 | -| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | 如果未安装，使用后台模式安装该功能。 | -| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | 指示清除其他任务的操作。可以为传递给 **[ohos.app.Context](js-apis-ability-context.md)** 中**startAbility**方法的**Want**设置此标志，并且必须与**flag_ABILITY_NEW_MISSION**一起使用。 | -| FLAG_ABILITY_NEW_MISSION | 0x10000000 | 指示在历史任务堆栈上创建任务的操作。 | -| FLAG_ABILITY_MISSION_TOP | 0x20000000 | 指示如果启动能力的现有实例已位于任务堆栈的顶部，则将重用该实例。否则，将创建一个新的能力实例。 | +| FLAG_AUTH_READ_URI_PERMISSION | 0x00000001 | 表示对URI执行读取操作的授权。 | +| FLAG_AUTH_WRITE_URI_PERMISSION | 0x00000002 | 表示对URI执行写入操作的授权。 | +| FLAG_ABILITY_FORWARD_RESULT | 0x00000004 | 表示将结果返回给源Ability。 | +| FLAG_ABILITY_CONTINUATION | 0x00000008 | 表示是否可以将本地设备上的Ability迁移到远端设备。 | +| FLAG_NOT_OHOS_COMPONENT | 0x00000010 | 表示组件是否不属于OHOS。 | +| FLAG_ABILITY_FORM_ENABLED | 0x00000020 | 表示某个Ability是否已经启动。 | +| FLAG_AUTH_PERSISTABLE_URI_PERMISSION | 0x00000040 | 表示URI上可能持久化的授权。
**系统API**: 此接口为系统接口，三方应用不支持调用。 | +| FLAG_AUTH_PREFIX_URI_PERMISSION | 0x00000080 | 表示按照前缀匹配的方式验证URI权限。
**系统API**: 此接口为系统接口，三方应用不支持调用。 | +| FLAG_ABILITYSLICE_MULTI_DEVICE | 0x00000100 | 表示支持分布式调度系统中的多设备启动。 | +| FLAG_START_FOREGROUND_ABILITY | 0x00000200 | 表示无论宿主应用是否已启动，都将使用前台模式启动Ability。
**系统API**: 此接口为系统接口，三方应用不支持调用。 | +| FLAG_ABILITY_CONTINUATION_REVERSIBLE | 0x00000400 | 表示迁移是否是可反向的。 | +| FLAG_INSTALL_ON_DEMAND | 0x00000800 | 表示如果未安装指定的Ability，将安装该Ability。 | +| FLAG_INSTALL_WITH_BACKGROUND_MODE | 0x80000000 | 表示如果未安装指定的Ability，将在后台安装该Ability。 | +| FLAG_ABILITY_CLEAR_MISSION | 0x00008000 | 表示清除其他任务的操作。可以为传递给 **[ohos.app.Context](js-apis-ability-context.md)** 中**startAbility**方法的**Want**设置此标志，并且必须与**flag_ABILITY_NEW_MISSION**一起使用。 | +| FLAG_ABILITY_NEW_MISSION | 0x10000000 | 表示在已有的任务栈上创建任务的操作。 | +| FLAG_ABILITY_MISSION_TOP | 0x20000000 | 表示如果启动的Ability的现有实例已位于任务栈顶，则将重用该实例。否则，将创建一个新的Ability实例。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-ability-particleAbility.md b/zh-cn/application-dev/reference/apis/js-apis-ability-particleAbility.md index e081616b43..c6dab933e0 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-ability-particleAbility.md +++ b/zh-cn/application-dev/reference/apis/js-apis-ability-particleAbility.md @@ -1,6 +1,6 @@ # @ohos.ability.particleAbility (ParticleAbility模块) -particleAbility模块提供了Service类型Ability的能力，包括启动、停止指定的particleAbility，获取dataAbilityHelper，连接、断开当前Ability与指定ServiceAbility等。 +particleAbility模块提供了操作Service类型的Ability的能力，包括启动、停止指定的particleAbility，获取dataAbilityHelper，连接、断连指定的ServiceAbility等。 > **说明：** > @@ -21,7 +21,12 @@ import particleAbility from '@ohos.ability.particleAbility' startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\): void -使用此方法启动指定的particleAbility（callback形式）。 +启动指定的particleAbility（callback形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -29,8 +34,8 @@ startAbility(parameter: StartAbilityParameter, callback: AsyncCallback\): | 参数名 | 类型 | 必填 | 说明 | | --------- | ----------------------------------------------- | ---- | ----------------- | -| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | 是 | 指示启动的ability | -| callback | AsyncCallback\ | 是 | 被指定的回调方法 | +| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | 是 | 表示启动的ability | +| callback | AsyncCallback\ | 是 | 以callback的形式返回启动Ability的结果 | **示例：** @@ -62,7 +67,12 @@ particleAbility.startAbility( startAbility(parameter: StartAbilityParameter): Promise\; -使用此方法启动指定的particleAbility（Promise形式）。 +启动指定的particleAbility（Promise形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（FA模型）](../../application-models/component-startup-rules-fa.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -70,13 +80,13 @@ startAbility(parameter: StartAbilityParameter): Promise\; | 参数名 | 类型 | 必填 | 说明 | | --------- | ----------------------------------------------- | ---- | ----------------- | -| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | 是 | 指示启动的ability | +| parameter | [StartAbilityParameter](js-apis-inner-ability-startAbilityParameter.md) | 是 | 表示启动的ability | **返回值：** | 类型 | 说明 | | -------------- | ------------------------- | -| Promise\ | 使用Promise形式返回结果。 | +| Promise\ | Promise形式返回启动Ability的结果。 | **示例：** @@ -107,7 +117,7 @@ particleAbility.startAbility( terminateSelf(callback: AsyncCallback\): void -终止particleAbility（callback形式）。 +销毁当前particleAbility（callback形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -115,7 +125,7 @@ terminateSelf(callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | -------------------- | ---- | -------------------- | -| callback | AsyncCallback\ | 是 | 表示被指定的回调方法 | +| callback | AsyncCallback\ | 是 | 以callback的形式返回停止当前Ability结果 | **示例：** @@ -133,7 +143,7 @@ particleAbility.terminateSelf( terminateSelf(): Promise\ -终止particleAbility（Promise形式）。 +销毁当前particleAbility（Promise形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -141,7 +151,7 @@ terminateSelf(): Promise\ | 类型 | 说明 | | -------------- | ------------------------- | -| Promise\ | 使用Promise形式返回结果。 | +| Promise\ | 使用Promise形式返回停止当前Ability结果。 | **示例：** @@ -159,7 +169,7 @@ particleAbility.terminateSelf().then((data) => { acquireDataAbilityHelper(uri: string): DataAbilityHelper -获取dataAbilityHelper。 +获取dataAbilityHelper对象。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -167,13 +177,13 @@ acquireDataAbilityHelper(uri: string): DataAbilityHelper | 参数名 | 类型 | 必填 | 说明 | | :--- | ------ | ---- | ------------------------ | -| uri | string | 是 | 指示要打开的文件的路径。 | +| uri | string | 是 | 表示要打开的文件的路径。 | **返回值：** | 类型 | 说明 | | ----------------- | -------------------------------------------- | -| DataAbilityHelper | 用来协助其他Ability访问DataAbility的工具类。 | +| [DataAbilityHelper](js-apis-inner-ability-dataAbilityHelper.md) | 用来协助其他Ability访问DataAbility的工具类。 | **示例：** @@ -270,7 +280,7 @@ startBackgroundRunning(id: number, request: NotificationRequest): Promise<voi | 类型 | 说明 | | -------------- | ------------------------- | -| Promise\ | 使用Promise形式返回结果。 | +| Promise\ | 使用Promise形式返回启动长时任务的结果。 | **示例**： @@ -326,7 +336,7 @@ cancelBackgroundRunning(callback: AsyncCallback<void>): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | callback | AsyncCallback<void> | 是 | callback形式返回启动长时任务的结果 | + | callback | AsyncCallback<void> | 是 | callback形式返回取消长时任务的结果 | **示例**： @@ -357,7 +367,7 @@ cancelBackgroundRunning(): Promise<void>; | 类型 | 说明 | | -------------- | ------------------------- | -| Promise\ | 使用Promise形式返回结果。 | +| Promise\ | 使用Promise形式返回取消长时任务的结果。 | **示例**： @@ -376,7 +386,7 @@ particleAbility.cancelBackgroundRunning().then(() => { connectAbility(request: Want, options:ConnectOptions): number -将当前ability连接到指定ServiceAbility（callback形式）。 +将当前ability与指定的ServiceAbility进行连接（callback形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -385,22 +395,13 @@ connectAbility(request: Want, options:ConnectOptions): number | 参数名 | 类型 | 必填 | 说明 | | ------- | -------------- | ---- | ---------------------------- | | request | [Want](js-apis-application-want.md) | 是 | 表示被连接的ServiceAbility。 | -| options | ConnectOptions | 是 | 被指定的回调方法。 | - +| options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | 是 | 连接回调方法。 | -**ConnectOptions类型说明：** - -**系统能力**：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.Core - -| 名称 | 类型 | 必填 | 说明 | -| ------------ | -------- | ---- | ------------------------- | -| onConnect | function | 是 | 连接成功时的回调函数。 | -| onDisconnect | function | 是 | 连接失败时的回调函数。 | -| onFailed | function | 是 | ConnectAbility调用失败时的回调函数。 | **示例**： ```ts +import particleAbility from '@ohos.ability.particleAbility' import rpc from '@ohos.rpc' function onConnectCallback(element, remote) { @@ -438,7 +439,7 @@ particleAbility.disconnectAbility(connId).then((data) => { disconnectAbility(connection: number, callback:AsyncCallback\): void; -将功能与服务功能断开连接。 +断开当前ability与指定ServiceAbility的连接（callback形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -451,7 +452,8 @@ disconnectAbility(connection: number, callback:AsyncCallback\): void; **示例**： ```ts -import rpc from '@ohos.rpc' +import particleAbility from '@ohos.ability.particleAbility'; +import rpc from '@ohos.rpc'; function onConnectCallback(element, remote) { console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); @@ -488,7 +490,7 @@ particleAbility.disconnectAbility(connId, (err) => { disconnectAbility(connection: number): Promise\; -将功能与服务功能断开连接。 +断开当前ability与指定ServiceAbility的连接（Promise形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel @@ -501,7 +503,8 @@ disconnectAbility(connection: number): Promise\; **示例**： ```ts -import rpc from '@ohos.rpc' +import particleAbility from '@ohos.ability.particleAbility'; +import rpc from '@ohos.rpc'; function onConnectCallback(element, remote) { console.log('ConnectAbility onConnect remote is proxy:' + (remote instanceof rpc.RemoteProxy)); @@ -537,7 +540,7 @@ particleAbility.disconnectAbility(connId).then((data) => { ## ErrorCode -获取错误代码。 +表示错误码。 **系统能力**：SystemCapability.Ability.AbilityRuntime.FAModel diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md index a32e976765..c26cebadb4 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-abilityConstant.md @@ -23,8 +23,8 @@ import AbilityConstant from '@ohos.app.ability.AbilityConstant'; | 名称 | 类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | -| launchReason | [LaunchReason](#abilityconstantlaunchreason)| 是 | 是 | 枚举类型，表示启动原因。 | -| lastExitReason | [LastExitReason](#abilityconstantlastexitreason) | 是 | 是 | 枚举类型，表示最后退出原因。 | +| launchReason | [LaunchReason](#abilityconstantlaunchreason)| 是 | 是 | 指示启动原因。 | +| lastExitReason | [LastExitReason](#abilityconstantlastexitreason) | 是 | 是 | 表示最后退出原因。 | ## AbilityConstant.LaunchReason diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-appManager.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-appManager.md index 34cec4de8b..d150ed4402 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-appManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-appManager.md @@ -588,7 +588,7 @@ try { getForegroundApplications(callback: AsyncCallback\>): void; -获取当前所有前台应用的信息。该应用信息由[AppStateData](js-apis-inner-application-appStateData.md)定义。 +获取所有当前处于前台的应用信息。该应用信息由[AppStateData](js-apis-inner-application-appStateData.md)定义。 **需要权限**：ohos.permission.GET_RUNNING_INFO @@ -608,7 +608,7 @@ getForegroundApplications(callback: AsyncCallback\>): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| callback | AsyncCallback\> | 是 | 以Promise方式返回接口运行结果及应用状态数据数组，可进行错误处理或其他自定义处理。 | +| callback | AsyncCallback\> | 是 | 以Callback方式返回接口运行结果及应用状态数据数组，可进行错误处理或其他自定义处理。 | **示例：** @@ -633,7 +633,7 @@ try { getForegroundApplications(): Promise\>; -获取当前所有前台应用的信息。该应用信息由[AppStateData](js-apis-inner-application-appStateData.md)定义。 +获取所有当前处于前台的应用信息。该应用信息由[AppStateData](js-apis-inner-application-appStateData.md)定义。 **需要权限**：ohos.permission.GET_RUNNING_INFO @@ -645,7 +645,7 @@ getForegroundApplications(): Promise\>; | 类型 | 说明 | | -------- | -------- | -| Promise\> | 返回前台进程应用程序的数组。 | +| Promise\> | 以Promise形式返回所有当前处于前台的应用信息。 | **错误码**： diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-missionManager.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-missionManager.md index 80adf4b8d8..5ffbebe7a6 100755 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-missionManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-missionManager.md @@ -32,7 +32,7 @@ on(type:"mission", listener: MissionListener): number; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | listener | MissionListener | 是 | 系统任务监听方法。 | + | listener | [MissionListener](js-apis-inner-application-missionListener.md) | 是 | 系统任务监听方法。 | **返回值：** diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-uiAbility.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-uiAbility.md index 6d9f7d70b7..e61cb00cca 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-uiAbility.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-uiAbility.md @@ -42,7 +42,7 @@ Ability创建时回调，执行初始化业务逻辑操作。 | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | want | [Want](js-apis-app-ability-want.md) | 是 | 当前Ability的Want类型信息，包括ability名称、bundle名称等。 | - | param | AbilityConstant.LaunchParam | 是 | 创建 ability、上次异常退出的原因信息。 | + | param | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | 是 | 创建 ability、上次异常退出的原因信息。 | **示例：** @@ -67,7 +67,7 @@ onWindowStageCreate(windowStage: window.WindowStage): void | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | windowStage | window.WindowStage | 是 | WindowStage相关信息。 | + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | WindowStage相关信息。 | **示例：** @@ -111,7 +111,7 @@ onWindowStageRestore(windowStage: window.WindowStage): void | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | windowStage | window.WindowStage | 是 | WindowStage相关信息。 | + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | WindowStage相关信息。 | **示例：** @@ -199,13 +199,13 @@ onContinue(wantParam : {[key: string]: any}): AbilityConstant.OnContinueResult; | 类型 | 说明 | | -------- | -------- | - | AbilityConstant.OnContinueResult | 继续的结果。 | + | [AbilityConstant.OnContinueResult](js-apis-app-ability-abilityConstant.md#abilityconstantoncontinueresult) | 继续的结果。 | **示例：** ```ts - import AbilityConstant from "@ohos.application.AbilityConstant" - class myAbility extends Ability { + import AbilityConstant from "@ohos.app.ability.AbilityConstant" + class MyUIAbility extends UIAbility { onContinue(wantParams) { console.log('onContinue'); wantParams["myData"] = "my1234567"; @@ -219,7 +219,7 @@ onContinue(wantParam : {[key: string]: any}): AbilityConstant.OnContinueResult; onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void; -当ability的启动模式设置为单例时回调会被调用。 +当传入新的Want，ability再次被拉起时会回调执行该方法。 **系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore @@ -227,17 +227,18 @@ onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | want | [Want](js-apis-application-want.md) | 是 | Want类型参数，如ability名称，包名等。 | - | launchParams | AbilityConstant.LaunchParam | 是 | Ability启动的原因、上次异常退出的原因信息。 | + | want | [Want](js-apis-app-ability-want.md) | 是 | Want类型参数，如ability名称，包名等。 | + | launchParams | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | 是 | UIAbility启动的原因、上次异常退出的原因信息。 | **示例：** ```ts - class myAbility extends Ability { - onNewWant(want) { + class MyUIAbility extends UIAbility { + onNewWant(want, launchParams) { console.log('onNewWant, want:' + want.abilityName); - } - } + console.log('onNewWant, launchParams:' + JSON.stringify(launchParams)); + } + } ``` ## Ability.onDump @@ -290,9 +291,9 @@ onSaveState(reason: AbilityConstant.StateType, wantParam : {[key: string]: any}) **示例：** ```ts -import AbilityConstant from '@ohos.application.AbilityConstant' +import AbilityConstant from '@ohos.app.ability.AbilityConstant' -class myAbility extends Ability { +class MyUIAbility extends UIAbility { onSaveState(reason, wantParam) { console.log('onSaveState'); wantParam["myData"] = "my1234567"; @@ -320,7 +321,7 @@ call(method: string, data: rpc.Sequenceable): Promise<void>; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | method | string | 是 | 约定的服务端注册事件字符串。 | - | data | rpc.Sequenceable | 是 | 由开发者实现的Sequenceable可序列化数据。 | + | data | [rpc.Sequenceable](js-apis-rpc.md#sequenceabledeprecated) | 是 | 由开发者实现的Sequenceable可序列化数据。 | **返回值：** @@ -401,13 +402,13 @@ callWithResult(method: string, data: rpc.Sequenceable): Promise<rpc.MessagePa | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | method | string | 是 | 约定的服务端注册事件字符串。 | - | data | rpc.Sequenceable | 是 | 由开发者实现的Sequenceable可序列化数据。 | + | data | [rpc.Sequenceable](js-apis-rpc.md#sequenceabledeprecated) | 是 | 由开发者实现的Sequenceable可序列化数据。 | **返回值：** | 类型 | 说明 | | -------- | -------- | - | Promise<rpc.MessageParcel> | Promise形式返回通用组件服务端应答数据。 | + | Promise<[rpc.MessageParcel](js-apis-rpc.md#sequenceabledeprecated)> | Promise形式返回通用组件服务端应答数据。 | **错误码：** @@ -527,7 +528,7 @@ release(): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | callback | OnReleaseCallBack | 是 | 返回onRelease回调结果。 | + | callback | [OnReleaseCallBack](#onreleasecallback) | 是 | 返回onRelease回调结果。 | **示例：** @@ -571,7 +572,7 @@ release(): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | type | string | 是 | 监听releaseCall事件，固定为'release'。 | - | callback | OnReleaseCallback | 是 | 返回onRelease回调结果。 | + | callback | [OnReleaseCallBack](#onreleasecallback) | 是 | 返回onRelease回调结果。 | **错误码：** @@ -627,7 +628,7 @@ on(method: string, callback: CalleeCallback): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | | method | string | 是 | 与客户端约定的通知消息字符串。 | - | callback | CalleeCallback | 是 | 一个rpc.MessageParcel类型入参的js通知同步回调函数, 回调函数至少要返回一个空的rpc.Sequenceable数据对象, 其他视为函数执行错误。 | + | callback | [CalleeCallback](#calleecallback) | 是 | 一个[rpc.MessageParcel](js-apis-rpc.md#sequenceabledeprecated)类型入参的js通知同步回调函数, 回调函数至少要返回一个空的[rpc.Sequenceable](js-apis-rpc.md#sequenceabledeprecated)数据对象, 其他视为函数执行错误。 | **错误码：** @@ -739,4 +740,4 @@ off(method: string): void; | 名称 | 可读 | 可写 | 类型 | 说明 | | -------- | -------- | -------- | -------- | -------- | -| (indata: rpc.MessageParcel) | 是 | 否 | rpc.Sequenceable | 被调用方注册的消息侦听器函数接口的原型。 | +| (indata: [rpc.MessageParcel](js-apis-rpc.md#sequenceabledeprecated)) | 是 | 否 | [rpc.Sequenceable](js-apis-rpc.md#sequenceabledeprecated) | 被调用方注册的消息侦听器函数接口的原型。 | diff --git a/zh-cn/application-dev/reference/apis/js-apis-app-ability-wantAgent.md b/zh-cn/application-dev/reference/apis/js-apis-app-ability-wantAgent.md index 20aa63ed78..b2f5750404 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-app-ability-wantAgent.md +++ b/zh-cn/application-dev/reference/apis/js-apis-app-ability-wantAgent.md @@ -85,7 +85,7 @@ getWantAgent(info: WantAgentInfo): Promise\ | 参数名 | 类型 | 必填 | 说明 | | ---- | ------------- | ---- | ------------- | -| info | WantAgentInfo | 是 | WantAgent信息。 | +| info | [WantAgentInfo](js-apis-inner-wantAgent-wantAgentInfo.md) | 是 | WantAgent信息。 | **返回值：** @@ -451,7 +451,7 @@ getWant(agent: WantAgent, callback: AsyncCallback\): void | 参数名 | 类型 | 必填 | 说明 | | -------- | --------------------- | ---- | ------------------------------- | | agent | WantAgent | 是 | WantAgent对象。 | -| callback | AsyncCallback\ | 是 | 获取WantAgent对象want的回调方法。 | +| callback | AsyncCallback\<[Want](js-apis-app-ability-want.md)\> | 是 | 获取WantAgent对象want的回调方法。 | **示例：** @@ -752,7 +752,7 @@ trigger(agent: WantAgent, triggerInfo: TriggerInfo, callback?: AsyncCallback\ | 否 | 主动激发WantAgent实例的回调方法。 | +| callback | AsyncCallback\<[CompleteData](#completedata)\> | 否 | 主动激发WantAgent实例的回调方法。 | **示例：** diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-ability.md b/zh-cn/application-dev/reference/apis/js-apis-application-ability.md index 892e1d64dc..df08aed5ec 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-application-ability.md +++ b/zh-cn/application-dev/reference/apis/js-apis-application-ability.md @@ -67,7 +67,7 @@ onWindowStageCreate(windowStage: window.WindowStage): void | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | windowStage | window.WindowStage | 是 | WindowStage相关信息。 | + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | WindowStage相关信息。 | **示例：** @@ -111,7 +111,7 @@ onWindowStageRestore(windowStage: window.WindowStage): void | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | - | windowStage | window.WindowStage | 是 | WindowStage相关信息。 | + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | 是 | WindowStage相关信息。 | **示例：** @@ -219,7 +219,7 @@ onContinue(wantParam : {[key: string]: any}): AbilityConstant.OnContinueResult; onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void; -当ability的启动模式设置为单例时回调会被调用。 +当传入新的Want，ability再次被拉起时会回调执行该方法。 **系统能力**：SystemCapability.Ability.AbilityRuntime.AbilityCore @@ -234,8 +234,9 @@ onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void; ```ts class myAbility extends Ability { - onNewWant(want) { + onNewWant(want, launchParams) { console.log('onNewWant, want:' + want.abilityName); + console.log('onNewWant, launchParams:' + JSON.stringify(launchParams)); } } ``` diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-abilityConstant.md b/zh-cn/application-dev/reference/apis/js-apis-application-abilityConstant.md index afd313ca4a..5d203e6525 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-application-abilityConstant.md +++ b/zh-cn/application-dev/reference/apis/js-apis-application-abilityConstant.md @@ -21,8 +21,8 @@ import AbilityConstant from '@ohos.application.AbilityConstant'; | 名称 | 类型 | 可读 | 可写 | 说明 | | -------- | -------- | -------- | -------- | -------- | -| launchReason | LaunchReason| 是 | 是 | 指示启动原因。 | -| lastExitReason | LastExitReason | 是 | 是 | 表示最后退出原因。 | +| launchReason | [LaunchReason](#abilityconstantlaunchreason)| 是 | 是 | 指示启动原因。 | +| lastExitReason | [LastExitReason](#abilityconstantlastexitreason) | 是 | 是 | 表示最后退出原因。 | ## AbilityConstant.LaunchReason diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-abilityManager.md b/zh-cn/application-dev/reference/apis/js-apis-application-abilityManager.md index b734967666..2ae3d364bd 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-application-abilityManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-application-abilityManager.md @@ -112,7 +112,7 @@ getAbilityRunningInfos(callback: AsyncCallback\>): vo | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------------------------- | ---- | -------------- | -| callback | AsyncCallback\> | 是 | 被指定的回调方法。 | +| callback | AsyncCallback\> | 是 | 被指定的回调方法。 | **示例**： @@ -138,7 +138,7 @@ getAbilityRunningInfos(): Promise\> | 类型 | 说明 | | ---------------------------------------- | ------- | -| Promise\> | 返回执行结果。 | +| Promise\> | 返回执行结果。 | **示例**： @@ -167,7 +167,7 @@ getExtensionRunningInfos(upperLimit: number, callback: AsyncCallback\> | 是 | 被指定的回调方法。 | +| callback | AsyncCallback\> | 是 | 被指定的回调方法。 | **示例**： @@ -201,7 +201,7 @@ getExtensionRunningInfos(upperLimit: number): Promise\> | 返回执行结果。 | +| Promise\> | 返回执行结果。 | **示例**： @@ -229,7 +229,7 @@ getTopAbility(callback: AsyncCallback\): void; | 参数名 | 类型 | 必填 | 说明 | | --------- | ---------------------------------------- | ---- | -------------- | -| callback | AsyncCallback\ | 是 | 被指定的回调方法。 | +| callback | AsyncCallback\<[ElementName](js-apis-bundleManager-elementName.md)> | 是 | 被指定的回调方法。 | **示例**： @@ -253,7 +253,7 @@ getTopAbility(): Promise\; | 类型 | 说明 | | ---------------------------------------- | ------- | -| Promise\| 返回执行结果。 | +| Promise\<[ElementName](js-apis-bundleManager-elementName.md)>| 返回执行结果。 | **示例**： diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-accessibilityExtensionAbility.md b/zh-cn/application-dev/reference/apis/js-apis-application-accessibilityExtensionAbility.md index 2804125a07..ef6a02866b 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-application-accessibilityExtensionAbility.md +++ b/zh-cn/application-dev/reference/apis/js-apis-application-accessibilityExtensionAbility.md @@ -31,7 +31,7 @@ import AccessibilityExtensionAbility from '@ohos.application.AccessibilityExtens | 名称 | 类型 | 可读 | 可写 | 说明 | | --------- | ---------------------------------------- | ---- | ---- | ---------- | | eventType | [accessibility.EventType](js-apis-accessibility.md#EventType) \| [accessibility.WindowUpdateType](js-apis-accessibility.md#WindowUpdateType) \| [TouchGuideType](#touchguidetype) \| [GestureType](#gesturetype) \| [PageUpdateType](#pageupdatetype) | 是 | 否 | 具体事件类型。 | -| target | AccessibilityElement | 是 | 否 | 发生事件的目标组件。 | +| target | [AccessibilityElement](js-apis-inner-application-accessibilityExtensionContext.md#accessibilityelement9) | 是 | 否 | 发生事件的目标组件。 | | timeStamp | number | 是 | 否 | 事件时间戳。 | ## GestureType diff --git a/zh-cn/application-dev/reference/apis/js-apis-application-appManager.md b/zh-cn/application-dev/reference/apis/js-apis-application-appManager.md index f3f51dfbed..f68e0d1735 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-application-appManager.md +++ b/zh-cn/application-dev/reference/apis/js-apis-application-appManager.md @@ -171,7 +171,7 @@ getProcessRunningInfos(): Promise\>; | 类型 | 说明 | | -------- | -------- | -| Promise\> | 获取有关运行进程的信息。 | +| Promise\> | 获取有关运行进程的信息。 | **示例：** @@ -199,7 +199,7 @@ getProcessRunningInfos(callback: AsyncCallback\>): vo | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| callback | AsyncCallback\> | 是 | 获取有关运行进程的信息。 | +| callback | AsyncCallback\> | 是 | 获取有关运行进程的信息。 | **示例：** @@ -420,8 +420,8 @@ unregisterApplicationStateObserver(observerId: number): Promise\; getForegroundApplications(callback: AsyncCallback\>): void; -获取前台进程的应用程序。 - +获取所有当前处于前台的应用信息。该应用信息由[AppStateData](js-apis-inner-application-appStateData.md)定义。 + **需要权限**：ohos.permission.GET_RUNNING_INFO **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -432,7 +432,7 @@ getForegroundApplications(callback: AsyncCallback\>): void; | 参数名 | 类型 | 必填 | 说明 | | -------- | -------- | -------- | -------- | -| callback | AsyncCallback\> | 是 | 表示应用的状态数据。 | +| callback | AsyncCallback\> | 是 | callback形式返回所有当前处于前台的应用信息。 | **示例：** @@ -451,7 +451,7 @@ getForegroundApplications(callback: AsyncCallback\>): void; getForegroundApplications(): Promise\>; -获取前台进程的应用程序。 +获取所有当前处于前台的应用信息。该应用信息由[AppStateData](js-apis-inner-application-appStateData.md)定义。 **需要权限**：ohos.permission.GET_RUNNING_INFO @@ -463,7 +463,7 @@ getForegroundApplications(): Promise\>; | 类型 | 说明 | | -------- | -------- | -| Promise\> | 返回进程运行信息的数组。 | +| Promise\> | Promise形式返回所有当前处于前台的应用信息。 | **示例：** diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-serviceExtensionContext.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-serviceExtensionContext.md index 85861abfda..72a3fab79f 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-serviceExtensionContext.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-serviceExtensionContext.md @@ -245,6 +245,11 @@ startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\< 根据account启动Ability（callback形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **系统API**: 此接口为系统接口，三方应用不支持调用。 @@ -316,6 +321,11 @@ startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, ca 根据account启动Ability（callback形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **系统API**: 此接口为系统接口，三方应用不支持调用。 @@ -392,6 +402,11 @@ startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): 根据account启动Ability（Promise形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **系统API**: 此接口为系统接口，三方应用不支持调用。 @@ -1300,6 +1315,11 @@ startAbilityByCall(want: Want): Promise<Caller>; 启动指定Ability至前台或后台，同时获取其Caller通信接口，调用方可使用Caller与被启动的Ability进行通信。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **系统API**：此接口为系统接口，三方应用不支持调用。 diff --git a/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md b/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md index 176c5601ce..212a2428e5 100644 --- a/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md +++ b/zh-cn/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md @@ -25,6 +25,11 @@ startAbility(want: Want, callback: AsyncCallback<void>): void; 启动Ability（callback形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -91,6 +96,11 @@ startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void& 启动Ability（callback形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -161,6 +171,11 @@ startAbility(want: Want, options?: StartOptions): Promise<void>; 启动Ability（promise形式）。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** @@ -234,7 +249,12 @@ startAbility(want: Want, options?: StartOptions): Promise<void>; startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void; -启动Ability并在该Ability退出的时候返回执行结果（callback形式）。 +启动一个Ability。Ability被启动后，正常情况下可通过调用[terminateSelfWithResult](#uiabilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用者。异常情况下比如杀死Ability会返回异常信息给调用者（callback形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -301,7 +321,12 @@ startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void; -启动Ability并在该Ability退出的时候返回执行结果（callback形式）。 +启动一个Ability。Ability被启动后，正常情况下可通过调用[terminateSelfWithResult](#uiabilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用者。异常情况下比如杀死Ability会返回异常信息给调用者（callback形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -373,7 +398,12 @@ startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>; -启动Ability并在该Ability退出的时候返回执行结果（promise形式）。 +启动一个Ability。Ability被启动后，正常情况下可通过调用[terminateSelfWithResult](#uiabilitycontextterminateselfwithresult)接口使之终止并且返回结果给调用者。异常情况下比如杀死Ability会返回异常信息给调用者（promise形式）。 + +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -1251,7 +1281,7 @@ terminateSelf(): Promise<void>; terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void; -停止Ability，配合startAbilityForResult使用，返回给接口调用方AbilityResult信息（callback形式）。 +停止当前的Ability。如果该Ability是通过调用[startAbilityForResult](#uiabilitycontextstartabilityforresult)接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用[startAbilityForResult](#uiabilitycontextstartabilityforresult)接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者（callback形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -1310,7 +1340,7 @@ terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<voi terminateSelfWithResult(parameter: AbilityResult): Promise<void>; -停止Ability，配合startAbilityForResult使用，返回给接口调用方AbilityResult信息（promise形式）。 +停止当前的Ability。如果该Ability是通过调用[startAbilityForResult](#uiabilitycontextstartabilityforresult)接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用[startAbilityForResult](#uiabilitycontextstartabilityforresult)接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者（promise形式）。 **系统能力**：SystemCapability.Ability.AbilityRuntime.Core @@ -1607,6 +1637,11 @@ startAbilityByCall(want: Want): Promise<Caller>; 启动指定Ability至前台或后台，同时获取其Caller通信接口，调用方可使用Caller与被启动的Ability进行通信。 +使用规则： + - 调用方应用位于后台时，使用该接口启动Ability需申请`ohos.permission.START_ABILITIES_FROM_BACKGROUND`权限 + - 目标Ability的visible属性若配置为false，调用方应用需申请`ohos.permission.START_INVISIBLE_ABILITY`权限 + - 组件启动规则详见：[组件启动规则（Stage模型）](../../application-models/component-startup-rules.md) + **系统能力**：SystemCapability.Ability.AbilityRuntime.Core **参数：** diff --git a/zh-cn/application-dev/tools/aa-tool.md b/zh-cn/application-dev/tools/aa-tool.md index fef305b1cd..3a5665c276 100644 --- a/zh-cn/application-dev/tools/aa-tool.md +++ b/zh-cn/application-dev/tools/aa-tool.md @@ -68,7 +68,7 @@ Ability assistant（Ability助手，简称为aa），是实现应用及测试用 | -------- | -------- | -------- | | -h/--help | - | 帮助信息。 | | -a/--all | - | 打印所有mission内的应用组件信息。 | - | -l/--mission-list | type（缺省打印全部） | 打印任务栈信息。
可取值：
- NORMAL
- DEFAULT_STANDARD
- DEFAULT_SINGLE
- LAUNCHER | + | -l/--mission-list | type（缺省打印全部） | 服务侧为了方便管理任务链，内部维护了4种类型的任务链。
可取值：
- NORMAL: 正常启动的任务链(比如A拉起B拉起C, 则对应的任务链是A->B->C)
- DEFAULT_STANDARD: 已经被破坏的任务链中的任务, 启动模式为standard的任务被放到该任务链中, 这里面的任务之间没有关联关系
- DEFAULT_SINGLE: 已经被破坏的任务链中的任务, 启动模式为singleton的任务被放到该任务链中, 这里面的任务之间没有关联关系
- LAUNCHER: launcher的任务链 | | -e/--extension | elementName | 打印扩展组件信息。 | | -u/--userId | UserId | 打印指定UserId的栈信息，需要和其他参数组合使用，例如aa dump -a -u 100、aa dump -d -u 100。 | | -d/--data | - | 打印DataAbility相关信息。 | -- GitLab