From ff994a8ff91c86b5afe654635c0cb8c9e00cc077 Mon Sep 17 00:00:00 2001 From: Gloria Date: Wed, 24 May 2023 10:06:20 +0800 Subject: [PATCH] Update docs against 17648 Signed-off-by: wusongqing --- .../uiability-intra-device-interaction.md | 150 +++++---- .../apis/js-apis-app-ability-uiAbility.md | 314 +++++++++--------- ...apis-inner-application-uiAbilityContext.md | 192 +++++------ 3 files changed, 331 insertions(+), 325 deletions(-) diff --git a/en/application-dev/application-models/uiability-intra-device-interaction.md b/en/application-dev/application-models/uiability-intra-device-interaction.md index 4d57492b9e..2ab44d2f5c 100644 --- a/en/application-dev/application-models/uiability-intra-device-interaction.md +++ b/en/application-dev/application-models/uiability-intra-device-interaction.md @@ -17,7 +17,7 @@ This topic describes the UIAbility interaction modes in the following scenarios. - [Starting a Specified Page of UIAbility](#starting-a-specified-page-of-uiability) -- [Using Ability Call to Implement UIAbility Interaction (for System Applications Only)](#using-ability-call-to-implement-uiability-interaction-for-system-applications-only) +- [Using Call to Implement UIAbility Interaction (for System Applications Only)](#using-call-to-implement-uiability-interaction-for-system-applications-only) ## Starting UIAbility in the Same Application @@ -38,7 +38,7 @@ Assume that your application has two UIAbility components: EntryAbility and Func info: 'From the Index page of EntryAbility', }, } - // context is the ability-level context of the initiator UIAbility. + // context is the AbilityContext of the initiator UIAbility. this.context.startAbility(wantInfo).then(() => { // ... }).catch((err) => { @@ -54,7 +54,7 @@ Assume that your application has two UIAbility components: EntryAbility and Func export default class FuncAbility extends UIAbility { onCreate(want, launchParam) { - // Receive the parameters passed by the caller UIAbility. + // Receive the parameters passed by the initiator UIAbility. let funcAbilityWant = want; let info = funcAbilityWant?.parameters?.info; // ... @@ -65,7 +65,7 @@ Assume that your application has two UIAbility components: EntryAbility and Func 3. To stop the **UIAbility** instance after the FuncAbility service is complete, call **terminateSelf()** in FuncAbility. ```ts - // context is the ability-level context of the UIAbility instance to stop. + // context is the UIAbilityContext of the UIAbility instance to stop. this.context.terminateSelf((err) => { // ... }); @@ -88,7 +88,7 @@ When starting FuncAbility from EntryAbility, you want the result to be returned info: 'From the Index page of EntryAbility', }, } - // context is the ability-level context of the initiator UIAbility. + // context is the AbilityContext of the initiator UIAbility. this.context.startAbilityForResult(wantInfo).then((data) => { // ... }).catch((err) => { @@ -111,23 +111,23 @@ When starting FuncAbility from EntryAbility, you want the result to be returned }, }, } - // context is the ability-level context of the callee UIAbility. + // context is the AbilityContext of the target UIAbility. this.context.terminateSelfWithResult(abilityResult, (err) => { // ... }); ``` -3. After FuncAbility stops itself, EntryAbility uses the **startAbilityForResult()** method to receive the information returned by FuncAbility. The value of **RESULT_CODE** must be the same as the preceding value. +3. After FuncAbility stops itself, EntryAbility uses **startAbilityForResult()** to receive the information returned by FuncAbility. The value of **RESULT_CODE** must be the same as the preceding value. ```ts const RESULT_CODE: number = 1001; // ... - // context is the ability-level context of the initiator UIAbility. + // context is the AbilityContext of the initiator UIAbility. this.context.startAbilityForResult(want).then((data) => { if (data?.resultCode === RESULT_CODE) { - // Parse the information returned by the callee UIAbility. + // Parse the information returned by the target UIAbility. let info = data.want?.parameters?.info; // ... } @@ -139,13 +139,13 @@ When starting FuncAbility from EntryAbility, you want the result to be returned ## Starting UIAbility of Another Application -Generally, the user only needs to do a common operation (for example, selecting a document application to view the document content) to start the UIAbility of another application. The [implicit Want launch mode](want-overview.md#types-of-want) is recommended. The system identifies a matched UIAbility and starts it based on the **want** parameter of the caller. +Generally, the user only needs to do a common operation (for example, selecting a document application to view the document content) to start the UIAbility of another application. The [implicit Want launch mode](want-overview.md#types-of-want) is recommended. The system identifies a matched UIAbility and starts it based on the **want** parameter of the initiator UIAbility. There are two ways to start **UIAbility**: [explicit and implicit](want-overview.md). - Explicit Want launch: This mode is used to start a determined UIAbility component of an application. You need to set **bundleName** and **abilityName** of the target application in the **want** parameter. -- Implicit Want launch: The user selects a UIAbility to start based on the matching conditions. That is, the UIAbility to start is not determined (the **abilityName** parameter is not specified). When the **startAbility()** method is called, the **want** parameter specifies a series of parameters such as [entities](../reference/apis/js-apis-ability-wantConstant.md#wantconstantentity) and [actions](../reference/apis/js-apis-ability-wantConstant.md#wantconstantaction). **entities** provides additional type information of the target UIAbility, such as the browser or video player. **actions** specifies the common operations to perform, such as viewing, sharing, and application details. Then the system analyzes the **want** parameter to find the right UIAbility to start. You usually do not know whether the target application is installed and what **bundleName** and **abilityName** of the target application are. Therefore, implicit Want launch is usually used to start the UIAbility of another application. +- Implicit Want launch: The user selects a UIAbility to start based on the matching conditions. That is, the UIAbility to start is not determined (the **abilityName** parameter is not specified). When **startAbility()** is called, the **want** parameter specifies a series of parameters such as [entities](../reference/apis/js-apis-ability-wantConstant.md#wantconstantentity) and [actions](../reference/apis/js-apis-ability-wantConstant.md#wantconstantaction). **entities** provides category information of the target UIAbility, such as the browser or video player. **actions** specifies the common operations to perform, such as viewing, sharing, and application details. Then the system analyzes the **want** parameter to find the right UIAbility to start. You usually do not know whether the target application is installed and what **bundleName** and **abilityName** of the target application are. Therefore, implicit Want launch is usually used to start the UIAbility of another application. This section describes how to start the UIAbility of another application through implicit Want. @@ -175,7 +175,7 @@ This section describes how to start the UIAbility of another application through } ``` -2. Include **entities** and **actions** of the caller's **want** parameter into **entities** and **actions** under **skills** of the target UIAbility. After the system matches the UIAbility that meets the **entities** and **actions** information, a dialog box is displayed, showing the list of matched UIAbility instances for users to select. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability). +2. Include **entities** and **actions** of the initiator UIAbility's **want** parameter into **entities** and **actions** under **skills** of the target UIAbility. After the system matches the UIAbility that meets the **entities** and **actions** information, a dialog box is displayed, showing the list of matched UIAbility instances for users to select. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability). ```ts let wantInfo = { @@ -187,7 +187,7 @@ This section describes how to start the UIAbility of another application through entities: ['entity.system.default'], } - // context is the ability-level context of the initiator UIAbility. + // context is the AbilityContext of the initiator UIAbility. this.context.startAbility(wantInfo).then(() => { // ... }).catch((err) => { @@ -202,7 +202,7 @@ This section describes how to start the UIAbility of another application through 3. To stop the **UIAbility** instance after the document application is used, call **terminateSelf()**. ```ts - // context is the ability-level context of the UIAbility instance to stop. + // context is the UIAbilityContext of the UIAbility instance to stop. this.context.terminateSelf((err) => { // ... }); @@ -211,7 +211,7 @@ This section describes how to start the UIAbility of another application through ## Starting UIAbility of Another Application and Obtaining the Return Result -If you want to obtain the return result when using implicit Want to start the UIAbility of another application, use the **startAbilityForResult()** method. An example scenario is that the main application needs to start a third-party payment application and obtain the payment result. +If you want to obtain the return result when using implicit Want to start the UIAbility of another application, use **startAbilityForResult()**. An example scenario is that the main application needs to start a third-party payment application and obtain the payment result. 1. In the **module.json5** file of the UIAbility corresponding to the payment application, set [entities](../reference/apis/js-apis-ability-wantConstant.md#wantconstantentity) and [actions](../reference/apis/js-apis-ability-wantConstant.md#wantconstantaction) under **skills**. @@ -239,7 +239,7 @@ If you want to obtain the return result when using implicit Want to start the UI } ``` -2. Call the **startAbilityForResult()** method to start the UIAbility of the payment application. Include **entities** and **actions** of the caller's **want** parameter into **entities** and **actions** under **skills** of the target UIAbility. Use **data** in the asynchronous callback to receive the information returned to the caller after the payment UIAbility stops itself. After the system matches the UIAbility that meets the **entities** and **actions** information, a dialog box is displayed, showing the list of matched UIAbility instances for users to select. +2. Call **startAbilityForResult()** to start the UIAbility of the payment application. Include **entities** and **actions** of the initiator UIAbility's **want** parameter into **entities** and **actions** under **skills** of the target UIAbility. Use **data** in the asynchronous callback to receive the information returned to the initiator UIAbility after the payment UIAbility stops itself. After the system matches the UIAbility that meets the **entities** and **actions** information, a dialog box is displayed, showing the list of matched UIAbility instances for users to select. ```ts let wantInfo = { @@ -251,7 +251,7 @@ If you want to obtain the return result when using implicit Want to start the UI entities: ['entity.system.default'], } - // context is the ability-level context of the initiator UIAbility. + // context is the AbilityContext of the initiator UIAbility. this.context.startAbilityForResult(wantInfo).then((data) => { // ... }).catch((err) => { @@ -259,7 +259,7 @@ If you want to obtain the return result when using implicit Want to start the UI }) ``` -3. After the payment is finished, call the **terminateSelfWithResult()** method to stop the payment UIAbility and return the **abilityResult** parameter. +3. After the payment is finished, call **terminateSelfWithResult()** to stop the payment UIAbility and return the **abilityResult** parameter. ```ts const RESULT_CODE: number = 1001; @@ -274,13 +274,13 @@ If you want to obtain the return result when using implicit Want to start the UI }, }, } - // context is the ability-level context of the callee UIAbility. + // context is the AbilityContext of the target UIAbility. this.context.terminateSelfWithResult(abilityResult, (err) => { // ... }); ``` -4. Receive the information returned by the payment application in the callback of the **startAbilityForResult()** method. The value of **RESULT_CODE** must be the same as that returned by **terminateSelfWithResult()**. +4. Receive the information returned by the payment application in the callback of **startAbilityForResult()**. The value of **RESULT_CODE** must be the same as that returned by **terminateSelfWithResult()**. ```ts const RESULT_CODE: number = 1001; @@ -289,10 +289,10 @@ If you want to obtain the return result when using implicit Want to start the UI // Want parameter information. }; - // context is the ability-level context of the initiator UIAbility. + // context is the AbilityContext of the initiator UIAbility. this.context.startAbilityForResult(want).then((data) => { if (data?.resultCode === RESULT_CODE) { - // Parse the information returned by the callee UIAbility. + // Parse the information returned by the target UIAbility. let payResult = data.want?.parameters?.payResult; // ... } @@ -309,7 +309,7 @@ A UIAbility component can have multiple pages. When it is started in different s ### Specifying a Startup Page -When the caller UIAbility starts another UIAbility, it usually needs to redirect to a specified page. For example, FuncAbility contains two pages: Index (corresponding to the home page) and Second (corresponding to function A page). You can configure the specified page URL in the **want** parameter by adding a custom parameter to **parameters** in **want**. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability). +When the initiator UIAbility starts another UIAbility, it usually needs to redirect to a specified page. For example, FuncAbility contains two pages: Index (corresponding to the home page) and Second (corresponding to function A page). You can configure the specified page URL in the **want** parameter by adding a custom parameter to **parameters** in **want**. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability). ```ts @@ -322,7 +322,7 @@ let wantInfo = { router: 'funcA', }, } -// context is the ability-level context of the initiator UIAbility. +// context is the AbilityContext of the initiator UIAbility. this.context.startAbility(wantInfo).then(() => { // ... }).catch((err) => { @@ -344,12 +344,12 @@ export default class FuncAbility extends UIAbility { funcAbilityWant; onCreate(want, launchParam) { - // Receive the parameters passed by the caller UIAbility. + // Receive the parameters passed by the initiator UIAbility. this.funcAbilityWant = want; } onWindowStageCreate(windowStage: Window.WindowStage) { - // Main window is created. Set a main page for this ability. + // Main window is created. Set a main page for this UIAbility. let url = 'pages/Index'; if (this.funcAbilityWant?.parameters?.router) { if (this.funcAbilityWant.parameters.router === 'funA') { @@ -379,7 +379,7 @@ In summary, when a UIAbility instance of application A has been created and the export default class FuncAbility extends UIAbility { onNewWant(want, launchParam) { - // Receive the parameters passed by the caller UIAbility. + // Receive the parameters passed by the initiator UIAbility. globalThis.funcAbilityWant = want; // ... } @@ -413,85 +413,86 @@ In summary, when a UIAbility instance of application A has been created and the > **NOTE** > -> When the [launch type of the callee UIAbility](uiability-launch-type.md) is set to **standard**, a new instance is created each time the callee UIAbility is started. In this case, the [onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant) callback will not be invoked. +> When the [launch type of the target UIAbility](uiability-launch-type.md) is set to **standard**, a new instance is created each time the target UIAbility is started. In this case, the [onNewWant()](../reference/apis/js-apis-app-ability-uiAbility.md#abilityonnewwant) callback will not be invoked. -## Using Ability Call to Implement UIAbility Interaction (for System Applications Only) +## Using Call to Implement UIAbility Interaction (for System Applications Only) -Ability call is an extension of the UIAbility capability. It enables the UIAbility to be invoked by and communicate with external systems. The UIAbility invoked can be either started in the foreground or created and run in the background. You can use the ability call to implement data sharing between two UIAbility instances (caller ability and callee ability) through IPC. +Call is an extension of the UIAbility capability. It enables the UIAbility to be invoked by and communicate with external systems. The UIAbility invoked can be either started in the foreground or created and run in the background. You can use the call to implement data sharing between two UIAbility instances (CallerAbility and CalleeAbility) through IPC. -The core API used for the ability call is **startAbilityByCall**, which differs from **startAbility** in the following ways: +The core API used for the call is **startAbilityByCall**, which differs from **startAbility** in the following ways: -- **startAbilityByCall** supports ability launch in the foreground and background, whereas **startAbility** supports ability launch in the foreground only. +- **startAbilityByCall** supports UIAbility launch in the foreground and background, whereas **startAbility** supports UIAbility launch in the foreground only. -- The caller ability can use the caller object returned by **startAbilityByCall** to communicate with the callee ability, but **startAbility** does not provide the communication capability. +- The CallerAbility can use the caller object returned by **startAbilityByCall** to communicate with the CalleeAbility, but **startAbility** does not provide the communication capability. -Ability call is usually used in the following scenarios: +Call is usually used in the following scenarios: -- Communicating with the callee ability +- Communicating with the CalleeAbility -- Starting the callee ability in the background +- Starting the CalleeAbility in the background -**Table 1** Terms used in the ability call +**Table 1** Terms used in the call | **Term**| Description| | -------- | -------- | -| CallerAbility | UIAbility that triggers the ability call.| -| CalleeAbility | UIAbility invoked by the ability call.| -| Caller | Object returned by **startAbilityByCall** and used by the caller ability to communicate with the callee ability.| -| Callee | Object held by the callee ability to communicate with the caller ability.| +| CallerAbility| UIAbility that triggers the call.| +| CalleeAbility | UIAbility invoked by the call.| +| Caller | Object returned by **startAbilityByCall** and used by the CallerAbility to communicate with the CalleeAbility.| +| Callee | Object held by the CalleeAbility to communicate with the CallerAbility.| -The following figure shows the ability call process. +The following figure shows the call process. - Figure 1 Ability call process +Figure 1 Call process - ![call](figures/call.png) + ![call](figures/call.png) -- The caller ability uses **startAbilityByCall** to obtain a caller object and uses **call()** of the caller object to send data to the callee ability. +- The CallerAbility uses **startAbilityByCall** to obtain a caller object and uses **call()** of the caller object to send data to the CalleeAbility. -- The callee ability, which holds a **Callee** object, uses **on()** of the **Callee** object to register a callback. This callback is invoked when the callee ability receives data from the caller ability. +- The CalleeAbility, which holds a **Callee** object, uses **on()** of the **Callee** object to register a callback. This callback is invoked when the CalleeAbility receives data from the CallerAbility. > **NOTE** -> 1. Currently, only system applications can use the ability call. +> 1. Currently, only system applications can use the call. > -> 2. The launch type of the callee ability must be **singleton**. +> 2. The launch type of the CalleeAbility must be **singleton**. > -> 3. Both local (intra-device) and cross-device ability calls are supported. The following describes how to initiate a local call. For details about how to initiate a cross-device ability call, see [Using Cross-Device Ability Call](hop-multi-device-collaboration.md#using-cross-device-ability-call). +> 3. Both local (intra-device) and cross-device calls are supported. The following describes how to initiate a local call. For details about how to initiate a cross-device call, see [Using Cross-Device Call](hop-multi-device-collaboration.md#using-cross-device-call). ### Available APIs -The following table describes the main APIs used for the ability call. For details, see [AbilityContext](../reference/apis/js-apis-app-ability-uiAbility.md#caller). +The following table describes the main APIs used for the call. For details, see [AbilityContext](../reference/apis/js-apis-app-ability-uiAbility.md#caller). - **Table 2** Ability call APIs + **Table 2** Call APIs | API| Description| | -------- | -------- | | startAbilityByCall(want: Want): Promise<Caller> | Starts a UIAbility in the foreground (through the **want** configuration) or background (default) and obtains the caller object for communication with the UIAbility. For details, see [AbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md#abilitycontextstartabilitybycall) or [ServiceExtensionContext](../reference/apis/js-apis-inner-application-serviceExtensionContext.md#serviceextensioncontextstartabilitybycall).| -| on(method: string, callback: CalleeCallBack): void | Callback invoked when the callee ability registers a method.| -| off(method: string): void | Callback invoked when the callee ability deregisters a method.| -| call(method: string, data: rpc.Parcelable): Promise<void> | Sends agreed parcelable data to the callee ability.| -| callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence> | Sends agreed parcelable data to the callee ability and obtains the agreed parcelable data returned by the callee ability.| +| on(method: string, callback: CalleeCallBack): void | Callback invoked when the CalleeAbility registers a method.| +| off(method: string): void | Callback invoked when the CalleeAbility deregisters a method.| +| call(method: string, data: rpc.Parcelable): Promise<void> | Sends agreed parcelable data to the CalleeAbility.| +| callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence> | Sends agreed parcelable data to the CalleeAbility and obtains the agreed parcelable data returned by the CalleeAbility.| | release(): void | Releases the caller object.| | on(type: "release", callback: OnReleaseCallback): void | Callback invoked when the caller object is released.| -The implementation of using the ability call for UIAbility interaction involves two parts. +The implementation of using the call for UIAbility interaction involves two parts. -- [Creating a Callee Ability](#creating-a-callee-ability) +- [Creating a CalleeAbility](#creating-a-calleeability) -- [Accessing the Callee Ability](#accessing-the-callee-ability) +- [Accessing the CalleeAbility](#accessing-the-calleeability) -### Creating a Callee Ability +### Creating a CalleeAbility -For the callee ability, implement the callback to receive data and the methods to marshal and unmarshal data. When data needs to be received, use **on()** to register a listener. When data does not need to be received, use **off()** to deregister the listener. +For the CalleeAbility, implement the callback to receive data and the methods to marshal and unmarshal data. When data needs to be received, use **on()** to register a listener. When data does not need to be received, use **off()** to deregister the listener. -1. Configure the ability launch type. - Set **launchType** of the callee ability to **singleton** in the **module.json5** file. +1. Configure the launch type of the UIAbility. + + Set **launchType** of the CalleeAbility to **singleton** in the **module.json5** file. | JSON Field| Description| | -------- | -------- | - | "launchType" | Ability launch type. Set this parameter to **singleton**.| + | "launchType" | UIAbility launch type. Set this parameter to **singleton**.| An example of the ability configuration is as follows: @@ -511,11 +512,12 @@ For the callee ability, implement the callback to receive data and the methods t 2. Import the **UIAbility** module. ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import UIAbility from '@ohos.app.ability.UIAbility'; ``` 3. Define the agreed parcelable data. - The data formats sent and received by the caller and callee abilities must be consistent. In the following example, the data formats are number and string. + + The data formats sent and received by the CallerAbility and CalleeAbility must be consistent. In the following example, the data formats are number and string. ```ts @@ -543,7 +545,8 @@ For the callee ability, implement the callback to receive data and the methods t ``` 4. Implement **Callee.on** and **Callee.off**. - The time to register a listener for the callee ability depends on your application. The data sent and received before the listener is registered and that after the listener is deregistered are not processed. In the following example, the **MSG_SEND_METHOD** listener is registered in **onCreate** of the ability and deregistered in **onDestroy**. After receiving parcelable data, the application processes the data and returns the data result. You need to implement processing based on service requirements. The sample code is as follows: + + The time to register a listener for the CalleeAbility depends on your application. The data sent and received before the listener is registered and that after the listener is deregistered are not processed. In the following example, the **MSG_SEND_METHOD** listener is registered in **onCreate** of the UIAbility and deregistered in **onDestroy**. After receiving parcelable data, the application processes the data and returns the data result. You need to implement processing based on service requirements. The sample code is as follows: ```ts @@ -553,17 +556,17 @@ For the callee ability, implement the callback to receive data and the methods t function sendMsgCallback(data) { console.info('CalleeSortFunc called'); - // Obtain the parcelable data sent by the caller ability. + // Obtain the parcelable data sent by the CallerAbility. let receivedData = new MyParcelable(0, ''); data.readParcelable(receivedData); console.info(`receiveData[${receivedData.num}, ${receivedData.str}]`); // Process the data. - // Return the parcelable data result to the caller ability. + // Return the parcelable data result to the CallerAbility. return new MyParcelable(receivedData.num + 1, `send ${receivedData.str} succeed`); } - export default class CalleeAbility extends Ability { + export default class CalleeAbility extends UIAbility { onCreate(want, launchParam) { try { this.callee.on(MSG_SEND_METHOD, sendMsgCallback); @@ -583,20 +586,21 @@ For the callee ability, implement the callback to receive data and the methods t ``` -### Accessing the Callee Ability +### Accessing the CalleeAbility 1. Import the **UIAbility** module. ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import UIAbility from '@ohos.app.ability.UIAbility'; ``` 2. Obtain the caller interface. - The **context** attribute of the ability implements **startAbilityByCall** to obtain the caller object for communication. The following example uses **this.context** to obtain the **context** attribute of the ability, uses **startAbilityByCall** to start the callee ability, obtain the caller object, and register the **onRelease** listener of the caller ability. You need to implement processing based on service requirements. + + The **context** attribute of the UIAbility implements **startAbilityByCall** to obtain the caller object for communication. The following example uses **this.context** to obtain the **UIAbilityContext**, uses **startAbilityByCall** to start the CalleeAbility, obtain the caller object, and register the **onRelease** listener of the CallerAbility. You need to implement processing based on service requirements. ```ts - // Register the onRelease() listener of the caller ability. + // Register the onRelease() listener of the CallerAbility. private regOnRelease(caller) { try { caller.on("release", (msg) => { diff --git a/en/application-dev/reference/apis/js-apis-app-ability-uiAbility.md b/en/application-dev/reference/apis/js-apis-app-ability-uiAbility.md index 6ec45dc97e..4037fc0903 100644 --- a/en/application-dev/reference/apis/js-apis-app-ability-uiAbility.md +++ b/en/application-dev/reference/apis/js-apis-app-ability-uiAbility.md @@ -1,11 +1,11 @@ # @ohos.app.ability.UIAbility (UIAbility) -The **Ability** module manages the ability lifecycle and context, such as creating and destroying an ability, and dumping client information. +The **UIAbility** module manages the UIAbility lifecycle and context, such as creating and destroying a UIAbility, and dumping client information. -This module provides the following common ability-related functions: +This module provides the following common UIAbility-related functions: -- [Caller](#caller): implements sending of sequenceable data to the target ability when an ability (caller ability) invokes the target ability (callee ability). -- [Callee](#callee): implements callbacks for registration and deregistration of caller notifications. +- [Caller](#caller): Implements sending of parcelable data to the target UIAbility when the CallerAbility invokes the target UIAbility (CalleeAbility). +- [Callee](#callee): Implements callbacks for caller notification registration and deregistration. > **NOTE** > @@ -15,39 +15,39 @@ This module provides the following common ability-related functions: ## Modules to Import ```ts -import Ability from '@ohos.app.ability.UIAbility'; +import UIAbility from '@ohos.app.ability.UIAbility'; ``` ## Attributes **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore -| Name| Type| Readable| Writable| Description| +| Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| context | [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md) | Yes| No| Context of the ability.| -| launchWant | [Want](js-apis-app-ability-want.md) | Yes| No| Parameters for starting the ability.| -| lastRequestWant | [Want](js-apis-app-ability-want.md) | Yes| No| Parameters used when the ability was started last time.| -| callee | [Callee](#callee) | Yes| No| Object that invokes the stub service.| +| context | [UIAbilityContext](js-apis-inner-application-uiAbilityContext.md) | Yes| No| Context of the UIAbility.| +| launchWant | [Want](js-apis-app-ability-want.md) | Yes| No| Parameters for starting the UIAbility.| +| lastRequestWant | [Want](js-apis-app-ability-want.md) | Yes| No| Parameters used when the UIAbility was started last time.| +| callee | [Callee](#callee) | Yes| No| Object that invokes the stub service.| -## Ability.onCreate +## UIAbility.onCreate onCreate(want: Want, param: AbilityConstant.LaunchParam): void; -Called to initialize the service logic when an ability is created. +Called to initialize the service logic when a UIAbility is created. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| want | [Want](js-apis-app-ability-want.md) | Yes| Information related to this ability, including the ability name and bundle name.| -| param | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | Yes| Parameters for starting the ability, and the reason for the last abnormal exit.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-app-ability-want.md) | Yes| Information related to this UIAbility, including the ability name and bundle name.| + | param | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | Yes| Parameters for starting the UIAbility, and the reason for the last abnormal exit.| **Example** ```ts - class myAbility extends Ability { + class myUIAbility extends UIAbility { onCreate(want, param) { console.log('onCreate, want:' + want.abilityName); } @@ -55,24 +55,24 @@ Called to initialize the service logic when an ability is created. ``` -## Ability.onWindowStageCreate +## UIAbility.onWindowStageCreate onWindowStageCreate(windowStage: window.WindowStage): void -Called when a **WindowStage** is created for this ability. +Called when a **WindowStage** is created for this UIAbility. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** information.| - -**Example** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** information.| +**Example** + ```ts - class myAbility extends Ability { + class myUIAbility extends UIAbility { onWindowStageCreate(windowStage) { console.log('onWindowStageCreate'); } @@ -80,18 +80,18 @@ Called when a **WindowStage** is created for this ability. ``` -## Ability.onWindowStageDestroy +## UIAbility.onWindowStageDestroy onWindowStageDestroy(): void -Called when the **WindowStage** is destroyed for this ability. +Called when the **WindowStage** is destroyed for this UIAbility. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore -**Example** - +**Example** + ```ts - class myAbility extends Ability { + class myUIAbility extends UIAbility { onWindowStageDestroy() { console.log('onWindowStageDestroy'); } @@ -99,24 +99,24 @@ Called when the **WindowStage** is destroyed for this ability. ``` -## Ability.onWindowStageRestore +## UIAbility.onWindowStageRestore onWindowStageRestore(windowStage: window.WindowStage): void -Called when the **WindowStage** is restored during the migration of this ability, which is a multi-instance ability. +Called when the **WindowStage** is restored during the migration of this UIAbility, which is a multi-instance UIAbility. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** information.| - -**Example** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | windowStage | [window.WindowStage](js-apis-window.md#windowstage9) | Yes| **WindowStage** information.| +**Example** + ```ts - class myAbility extends Ability { + class myUIAbility extends UIAbility { onWindowStageRestore(windowStage) { console.log('onWindowStageRestore'); } @@ -124,18 +124,18 @@ Called when the **WindowStage** is restored during the migration of this ability ``` -## Ability.onDestroy +## UIAbility.onDestroy onDestroy(): void; -Called when this ability is destroyed to clear resources. +Called when this UIAbility is destroyed to clear resources. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore -**Example** - +**Example** + ```ts - class myAbility extends Ability { + class myUIAbility extends UIAbility { onDestroy() { console.log('onDestroy'); } @@ -143,17 +143,18 @@ Called when this ability is destroyed to clear resources. ``` -## Ability.onForeground +## UIAbility.onForeground onForeground(): void; -Called when this ability is switched from the background to the foreground. +Called when this UIAbility is switched from the background to the foreground. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore -**Example** +**Example** + ```ts - class myAbility extends Ability { + class myUIAbility extends UIAbility { onForeground() { console.log('onForeground'); } @@ -161,18 +162,18 @@ Called when this ability is switched from the background to the foreground. ``` -## Ability.onBackground +## UIAbility.onBackground onBackground(): void; -Called when this ability is switched from the foreground to the background. +Called when this UIAbility is switched from the foreground to the background. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore -**Example** - +**Example** + ```ts - class myAbility extends Ability { + class myUIAbility extends UIAbility { onBackground() { console.log('onBackground'); } @@ -180,28 +181,28 @@ Called when this ability is switched from the foreground to the background. ``` -## Ability.onContinue +## UIAbility.onContinue onContinue(wantParam : {[key: string]: any}): AbilityConstant.OnContinueResult; -Called to save data during the ability migration preparation process. +Called to save data during the UIAbility migration preparation process. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| wantParam | {[key: string]: any} | Yes| **want** parameter.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | wantParam | {[key: string]: any} | Yes| **want** parameter.| **Return value** -| Type| Description| -| -------- | -------- | -| [AbilityConstant.OnContinueResult](js-apis-app-ability-abilityConstant.md#abilityconstantoncontinueresult) | Continuation result.| - -**Example** + | Type| Description| + | -------- | -------- | + | [AbilityConstant.OnContinueResult](js-apis-app-ability-abilityConstant.md#abilityconstantoncontinueresult) | Continuation result.| +**Example** + ```ts import AbilityConstant from '@ohos.app.ability.AbilityConstant'; class MyUIAbility extends UIAbility { @@ -214,23 +215,23 @@ Called to save data during the ability migration preparation process. ``` -## Ability.onNewWant +## UIAbility.onNewWant onNewWant(want: Want, launchParams: AbilityConstant.LaunchParam): void; -Called when a new Want is passed in and this ability is started again. +Called when a new Want is passed in and this UIAbility is started again. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| want | [Want](js-apis-app-ability-want.md) | Yes| Want information, such as the ability name and bundle name.| -| launchParams | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | Yes| Reason for the ability startup and the last abnormal exit.| - -**Example** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | want | [Want](js-apis-app-ability-want.md) | Yes| Want information, such as the ability name and bundle name.| + | launchParams | [AbilityConstant.LaunchParam](js-apis-app-ability-abilityConstant.md#abilityconstantlaunchparam) | Yes| Reason for the UIAbility startup and the last abnormal exit.| +**Example** + ```ts class MyUIAbility extends UIAbility { onNewWant(want, launchParams) { @@ -240,7 +241,7 @@ Called when a new Want is passed in and this ability is started again. } ``` -## Ability.onDump +## UIAbility.onDump onDump(params: Array\): Array\; @@ -250,14 +251,14 @@ Dumps client information. **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| params | Array\ | Yes| Parameters in the form of a command.| - -**Example** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | params | Array\ | Yes| Parameters in the form of a command.| +**Example** + ```ts - class myAbility extends Ability { + class myUIAbility extends UIAbility { onDump(params) { console.log('dump, params:' + JSON.stringify(params)); return ['params']; @@ -266,26 +267,26 @@ Dumps client information. ``` -## Ability.onSaveState +## UIAbility.onSaveState onSaveState(reason: AbilityConstant.StateType, wantParam : {[key: string]: any}): AbilityConstant.OnSaveResult; -Called when the framework automatically saves the ability state in the case of an application fault. This API is used together with [appRecovery](js-apis-app-ability-appRecovery.md). If automatic state saving is enabled, **onSaveState** is called to save the state of this ability. +Called when the framework automatically saves the UIAbility state in the case of an application fault. This API is used together with [appRecovery](js-apis-app-ability-appRecovery.md). If automatic state saving is enabled, **onSaveState** is called to save the state of this UIAbility. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| reason | [AbilityConstant.StateType](js-apis-app-ability-abilityConstant.md#abilityconstantstatetype) | Yes| Reason for triggering the callback to save the ability state.| -| wantParam | {[key: string]: any} | Yes| **want** parameter.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | reason | [AbilityConstant.StateType](js-apis-application-abilityConstant.md#abilityconstantstatetype) | Yes| Reason for triggering the callback to save the UIAbility state.| + | wantParam | {[key: string]: any} | Yes| **want** parameter.| **Return value** -| Type| Description| -| -------- | -------- | -| AbilityConstant.OnSaveResult | Whether the ability state is saved.| + | Type| Description| + | -------- | -------- | + | AbilityConstant.OnSaveResult | Whether the UIAbility state is saved.| **Example** @@ -305,28 +306,28 @@ class MyUIAbility extends UIAbility { ## Caller -Implements sending of parcelable data to the target ability when the CallerAbility invokes the target ability (CalleeAbility). +Implements sending of parcelable data to the target UIAbility when the CallerAbility invokes the target UIAbility (CalleeAbility). ## Caller.call call(method: string, data: rpc.Sequenceable): Promise<void>; -Sends parcelable data to the target ability. +Sends parcelable data to the target UIAbility. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the parcelable data.| -| data | [rpc.Parcelable](js-apis-rpc.md#parcelable9) | Yes| Parcelable data. You need to customize the data.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | method | string | Yes| Notification message string negotiated between the two UIAbilities. The message is used to instruct the callee to register a function to receive the parcelable data.| + | data | [rpc.Parcelable](js-apis-rpc.md#parcelable9) | Yes| Parcelable data. You need to customize the data.| **Return value** -| Type| Description| -| -------- | -------- | -| Promise<void> | Promise used to return a response.| + | Type| Description| + | -------- | -------- | + | Promise<void> | Promise used to return a response.| **Error codes** @@ -335,10 +336,10 @@ Sends parcelable data to the target ability. | 401 | If the input parameter is not valid parameter. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). -**Example** - +**Example** + ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import UIAbility from '@ohos.app.ability.UIAbility'; class MyMessageAble{ // Custom parcelable data structure. name:'' str:'' @@ -360,9 +361,9 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error return true; } }; - let method = 'call_Function'; // Notification message string negotiated by the two abilities. + let method = 'call_Function'; // Notification message string negotiated by the two UIAbilities. let caller; - export default class MainAbility extends Ability { + export default class MainUIAbility extends UIAbility { onWindowStageCreate(windowStage) { this.context.startAbilityByCall({ bundleName: 'com.example.myservice', @@ -392,22 +393,22 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence>; -Sends parcelable data to the target ability and obtains the parcelable data returned by the target ability. +Sends parcelable data to the target UIAbility and obtains the parcelable data returned by the target UIAbility. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| method | string | Yes| Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the parcelable data.| -| data | [rpc.Parcelable](js-apis-rpc.md#parcelable9) | Yes| Parcelable data. You need to customize the data.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | method | string | Yes| Notification message string negotiated between the two UIAbilities. The message is used to instruct the callee to register a function to receive the parcelable data.| + | data | [rpc.Parcelable](js-apis-rpc.md#parcelable9) | Yes| Parcelable data. You need to customize the data.| **Return value** -| Type| Description| -| -------- | -------- | -| Promise<[rpc.MessageSequence](js-apis-rpc.md#messagesequence9)> | Promise used to return the parcelable data from the target ability.| + | Type| Description| + | -------- | -------- | + | Promise<[rpc.MessageSequence](js-apis-rpc.md#messagesequence9)> | Promise used to return the parcelable data from the target UIAbility.| **Error codes** @@ -419,7 +420,7 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error **Example** ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import UIAbility from '@ohos.app.ability.UIAbility'; class MyMessageAble{ name:'' str:'' @@ -443,7 +444,7 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error }; let method = 'call_Function'; let caller; - export default class MainAbility extends Ability { + export default class MainUIAbility extends UIAbility { onWindowStageCreate(windowStage) { this.context.startAbilityByCall({ bundleName: 'com.example.myservice', @@ -475,9 +476,9 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error release(): void; -Releases the caller interface of the target ability. +Releases the caller interface of the target UIAbility. -**System capability**: SystemCapability.UIAbility.UIAbilityRuntime.UIAbilityCore +**System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Error codes** @@ -488,12 +489,12 @@ Releases the caller interface of the target ability. | 16200002 | Callee invalid. The callee does not exist. | | 16000050 | Internal Error. | -**Example** - +**Example** + ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import UIAbility from '@ohos.app.ability.UIAbility'; let caller; - export default class MainAbility extends Ability { + export default class MainUIAbility extends UIAbility { onWindowStageCreate(windowStage) { this.context.startAbilityByCall({ bundleName: 'com.example.myservice', @@ -519,22 +520,22 @@ Releases the caller interface of the target ability. onRelease(callback: OnReleaseCallBack): void; -Registers a callback that is invoked when the stub on the target ability is disconnected. +Registers a callback that is invoked when the stub on the target UIAbility is disconnected. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| callback | [OnReleaseCallBack](#onreleasecallback) | Yes| Callback used to return the result.| - -**Example** + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | callback | [OnReleaseCallBack](#onreleasecallback) | Yes| Callback used to return the result.| +**Example** + ```ts - import Ability from '@ohos.application.Ability'; + import UIAbility from '@ohos.application.Ability'; let caller; - export default class MainAbility extends Ability { + export default class MainUIAbility extends UIAbility { onWindowStageCreate(windowStage) { this.context.startAbilityByCall({ bundleName: 'com.example.myservice', @@ -562,16 +563,16 @@ Registers a callback that is invoked when the stub on the target ability is disc on(type: 'release', callback: OnReleaseCallback): void; -Registers a callback that is invoked when the stub on the target ability is disconnected. +Registers a callback that is invoked when the stub on the target UIAbility is disconnected. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| type | string | Yes| Event type. The value is fixed at **release**.| -| callback | [OnReleaseCallBack](#onreleasecallback) | Yes| Callback used to return the result.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | type | string | Yes| Event type. The value is fixed at **release**.| + | callback | [OnReleaseCallBack](#onreleasecallback) | Yes| Callback used to return the result.| **Error codes** @@ -580,12 +581,12 @@ Registers a callback that is invoked when the stub on the target ability is disc | 401 | If the input parameter is not valid parameter. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). -**Example** - +**Example** + ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import UIAbility from '@ohos.app.ability.UIAbility'; let caller; - export default class MainAbility extends Ability { + export default class MainUIAbility extends UIAbility { onWindowStageCreate(windowStage) { this.context.startAbilityByCall({ bundleName: 'com.example.myservice', @@ -613,7 +614,7 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error off(type: 'release', callback: OnReleaseCallback): void; -Deregisters a callback that is invoked when the stub on the target ability is disconnected. This capability is reserved. +Deregisters a callback that is invoked when the stub on the target UIAbility is disconnected. This capability is reserved. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore @@ -631,8 +632,8 @@ Deregisters a callback that is invoked when the stub on the target ability is di | 401 | If the input parameter is not valid parameter. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). -**Example** - +**Example** + ```ts let caller; export default class MainUIAbility extends UIAbility { @@ -665,7 +666,7 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error off(type: 'release'): void; -Deregisters a callback that is invoked when the stub on the target ability is disconnected. This capability is reserved. +Deregisters a callback that is invoked when the stub on the target UIAbility is disconnected. This capability is reserved. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore @@ -682,8 +683,8 @@ Deregisters a callback that is invoked when the stub on the target ability is di | 401 | If the input parameter is not valid parameter. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). -**Example** - +**Example** + ```ts let caller; export default class MainUIAbility extends UIAbility { @@ -720,17 +721,17 @@ Implements callbacks for caller notification registration and deregistration. on(method: string, callback: CalleeCallback): void; -Registers a caller notification callback, which is invoked when the target ability registers a function. +Registers a caller notification callback, which is invoked when the target UIAbility registers a function. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| method | string | Yes| Notification message string negotiated between the two abilities.| -| callback | [CalleeCallback](#calleecallback) | Yes| JS notification synchronization callback of the [rpc.MessageSequence](js-apis-rpc.md#messagesequence9) type. The callback must return at least one empty [rpc.Parcelable](js-apis-rpc.md#parcelable9) object. Otherwise, the function execution fails.| - + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | method | string | Yes| Notification message string negotiated between the two UIAbilities.| + | callback | [CalleeCallback](#calleecallback) | Yes| JS notification synchronization callback of the [rpc.MessageSequence](js-apis-rpc.md#messagesequence9) type. The callback must return at least one empty [rpc.Parcelable](js-apis-rpc.md#parcelable9) object. Otherwise, the function execution fails.| + **Error codes** | ID| Error Message| @@ -741,7 +742,7 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error **Example** ```ts - import Ability from '@ohos.app.ability.UIAbility'; + import UIAbility from '@ohos.app.ability.UIAbility'; class MyMessageAble{ name:'' str:'' @@ -770,7 +771,7 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error pdata.readParcelable(msg); return new MyMessageAble('test1', 'Callee test'); } - export default class MainAbility extends Ability { + export default class MainUIAbility extends UIAbility { onCreate(want, launchParam) { console.log('Callee onCreate is called'); try { @@ -787,15 +788,15 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error off(method: string): void; -Deregisters a caller notification callback, which is invoked when the target ability registers a function. +Deregisters a caller notification callback, which is invoked when the target UIAbility registers a function. **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore **Parameters** -| Name| Type| Mandatory| Description| -| -------- | -------- | -------- | -------- | -| method | string | Yes| Registered notification message string.| + | Name| Type| Mandatory| Description| + | -------- | -------- | -------- | -------- | + | method | string | Yes| Registered notification message string.| **Error codes** @@ -804,12 +805,13 @@ Deregisters a caller notification callback, which is invoked when the target abi | 401 | If the input parameter is not valid parameter. | For details about the error codes, see [Ability Error Codes](../errorcodes/errorcode-ability.md). -**Example** +**Example** + ```ts import Ability from '@ohos.app.ability.UIAbility'; let method = 'call_Function'; - export default class MainAbility extends Ability { + export default class MainUIAbility extends UIAbility { onCreate(want, launchParam) { console.log('Callee onCreate is called'); try { @@ -828,9 +830,9 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore -| Name| Readable| Writable| Type| Description| +| Name| Readable| Writable| Type| Description| | -------- | -------- | -------- | -------- | -------- | -| (msg: string) | Yes| No| function | Prototype of the listener function registered by the caller.| +| (msg: string) | Yes| No| function | Prototype of the listener function registered by the caller.| ## CalleeCallback @@ -838,6 +840,6 @@ For details about the error codes, see [Ability Error Codes](../errorcodes/error **System capability**: SystemCapability.Ability.AbilityRuntime.AbilityCore -| Name| Readable| Writable| Type| Description| +| Name| Readable| Writable| Type| Description| | -------- | -------- | -------- | -------- | -------- | | (indata: [rpc.MessageSequence](js-apis-rpc.md#messagesequence9)) | Yes| No| [rpc.Parcelable](js-apis-rpc.md#parcelable9) | Prototype of the listener function registered by the callee.| diff --git a/en/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md b/en/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md index 563a039ac7..3495114c5b 100644 --- a/en/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md +++ b/en/application-dev/reference/apis/js-apis-inner-application-uiAbilityContext.md @@ -15,7 +15,7 @@ This module provides APIs for accessing UIAbility-specific resources. You can us | Name| Type| Readable| Writable| Description| | -------- | -------- | -------- | -------- | -------- | -| abilityInfo | [AbilityInfo](js-apis-bundleManager-abilityInfo.md) | Yes| No| Ability information.| +| abilityInfo | [AbilityInfo](js-apis-bundleManager-abilityInfo.md) | Yes| No| UIAbility information.| | currentHapModuleInfo | [HapModuleInfo](js-apis-bundleManager-hapModuleInfo.md) | Yes| No| Information about the current HAP.| | config | [Configuration](js-apis-app-ability-configuration.md) | Yes| No| Configuration information.| @@ -23,11 +23,11 @@ This module provides APIs for accessing UIAbility-specific resources. You can us startAbility(want: Want, callback: AsyncCallback<void>): void; -Starts an ability. This API uses an asynchronous callback to return the result. +Starts a UIAbility. This API uses an asynchronous callback to return the result. Observe the following when using this API: - - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. - - If **visible** of the target ability is **false**, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. + - If an application running in the background needs to call this API to start a UIAbility, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. + - If **visible** of the target UIAbility is **false**, the initiator UIAbility must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -36,7 +36,7 @@ Observe the following when using this API: | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Error codes** @@ -94,11 +94,11 @@ Observe the following when using this API: startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void; -Starts an ability with the start options specified. This API uses an asynchronous callback to return the result. +Starts a UIAbility with the start options specified. This API uses an asynchronous callback to return the result. Observe the following when using this API: - - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. - - If **visible** of the target ability is **false**, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. + - If an application running in the background needs to call this API to start a UIAbility, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. + - If **visible** of the target UIAbility is **false**, the initiator UIAbility must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -107,8 +107,8 @@ Observe the following when using this API: | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| -| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the UIAbility.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Error codes** @@ -169,11 +169,11 @@ Observe the following when using this API: startAbility(want: Want, options?: StartOptions): Promise<void>; -Starts an ability. This API uses a promise to return the result. +Starts a UIAbility. This API uses a promise to return the result. Observe the following when using this API: - - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. - - If **visible** of the target ability is **false**, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. + - If an application running in the background needs to call this API to start a UIAbility, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. + - If **visible** of the target UIAbility is **false**, the initiator UIAbility must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -182,8 +182,8 @@ Observe the following when using this API: | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| -| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the UIAbility.| **Return value** @@ -249,14 +249,14 @@ Observe the following when using this API: startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void; -Starts an ability. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability: - - Normally, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. - - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. - - If different applications call this API to start an ability that uses the singleton mode and then call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability, the normal result is returned to the last caller, and an error message, in which **resultCode** is **-1**, is returned to others. +Starts a UIAbility. This API uses an asynchronous callback to return the result when the UIAbility is terminated. The following situations may be possible for a started UIAbility: + - Normally, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the UIAbility. The result is returned to the initiator UIAbility. + - If an exception occurs, for example, the UIAbility is killed, an error message, in which **resultCode** is **-1**, is returned to the initiator UIAbility. + - If different applications call this API to start a UIAbility that uses the singleton mode and then call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the UIAbility, the normal result is returned to the last initiator UIAbility, and an error message, in which **resultCode** is **-1**, is returned to others. Observe the following when using this API: - - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. - - If **visible** of the target ability is **false**, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. + - If an application running in the background needs to call this API to start a UIAbility, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. + - If **visible** of the target UIAbility is **false**, the initiator UIAbility must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -265,7 +265,7 @@ Observe the following when using this API: | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want |[Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want |[Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| **Error codes** @@ -324,14 +324,14 @@ Observe the following when using this API: startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void; -Starts an ability with the start options specified. This API uses an asynchronous callback to return the result when the ability is terminated. The following situations may be possible for a started ability: - - Normally, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. - - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. - - If different applications call this API to start an ability that uses the singleton mode and then call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability, the normal result is returned to the last caller, and an error message, in which **resultCode** is **-1**, is returned to others. +Starts a UIAbility with the start options specified. This API uses an asynchronous callback to return the result when the UIAbility is terminated. The following situations may be possible for a started UIAbility: + - Normally, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the UIAbility. The result is returned to the initiator UIAbility. + - If an exception occurs, for example, the UIAbility is killed, an error message, in which **resultCode** is **-1**, is returned to the initiator UIAbility. + - If different applications call this API to start a UIAbility that uses the singleton mode and then call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the UIAbility, the normal result is returned to the last initiator UIAbility, and an error message, in which **resultCode** is **-1**, is returned to others. Observe the following when using this API: - - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. - - If **visible** of the target ability is **false**, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. + - If an application running in the background needs to call this API to start a UIAbility, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. + - If **visible** of the target UIAbility is **false**, the initiator UIAbility must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -340,8 +340,8 @@ Observe the following when using this API: | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want |[Want](js-apis-application-want.md) | Yes| Want information about the target ability.| -| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| +| want |[Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the UIAbility.| | callback | AsyncCallback<[AbilityResult](js-apis-inner-ability-abilityResult.md)> | Yes| Callback used to return the result.| **Error codes** @@ -404,14 +404,14 @@ Observe the following when using this API: startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>; -Starts an ability. This API uses a promise to return the result when the ability is terminated. The following situations may be possible to an ability after it is started: - - Normally, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability. The result is returned to the caller. - - If an exception occurs, for example, the ability is killed, an error message, in which **resultCode** is **-1**, is returned to the caller. - - If different applications call this API to start an ability that uses the singleton mode and then call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the ability, the normal result is returned to the last caller, and an error message, in which **resultCode** is **-1**, is returned to others. +Starts a UIAbility. This API uses a promise to return the result when the UIAbility is terminated. The following situations may be possible for a started UIAbility: + - Normally, you can call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the UIAbility. The result is returned to the initiator UIAbility. + - If an exception occurs, for example, the UIAbility is killed, an error message, in which **resultCode** is **-1**, is returned to the initiator UIAbility. + - If different applications call this API to start a UIAbility that uses the singleton mode and then call [terminateSelfWithResult](#uiabilitycontextterminateselfwithresult) to terminate the UIAbility, the normal result is returned to the last initiator UIAbility, and an error message, in which **resultCode** is **-1**, is returned to others. Observe the following when using this API: - - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. - - If **visible** of the target ability is **false**, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. + - If an application running in the background needs to call this API to start a UIAbility, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. + - If **visible** of the target UIAbility is **false**, the initiator UIAbility must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -420,8 +420,8 @@ Observe the following when using this API: | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| -| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the UIAbility.| **Return value** @@ -487,7 +487,7 @@ Observe the following when using this API: startAbilityForResultWithAccount(want: Want, accountId: number, callback: AsyncCallback\): void; -Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result when the ability is terminated. +Starts a UIAbility with the account ID specified. This API uses an asynchronous callback to return the result when the UIAbility is terminated. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -499,7 +499,7 @@ Starts an ability with the account ID specified. This API uses an asynchronous c | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -562,7 +562,7 @@ Starts an ability with the account ID specified. This API uses an asynchronous c startAbilityForResultWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\): void; -Starts an ability with the start options and account ID specified. This API uses an asynchronous callback to return the result when the ability is terminated. +Starts a UIAbility with the start options and account ID specified. This API uses an asynchronous callback to return the result when the UIAbility is terminated. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -574,9 +574,9 @@ Starts an ability with the start options and account ID specified. This API uses | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the ability.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | Yes| Parameters used for starting the UIAbility.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** @@ -641,7 +641,7 @@ Starts an ability with the start options and account ID specified. This API uses startAbilityForResultWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\; -Starts an ability with the account ID specified. This API uses a promise to return the result when the ability is terminated. +Starts a UIAbility with the account ID specified. This API uses a promise to return the result when the UIAbility is terminated. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -653,9 +653,9 @@ Starts an ability with the account ID specified. This API uses a promise to retu | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the UIAbility.| **Return value** @@ -733,7 +733,7 @@ Starts a ServiceExtensionAbility. This API uses an asynchronous callback to retu | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** @@ -794,7 +794,7 @@ Starts a ServiceExtensionAbility. This API uses a promise to return the result. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| **Error codes** @@ -856,7 +856,7 @@ Starts a ServiceExtensionAbility with the account ID specified. This API uses an | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -918,7 +918,7 @@ Starts a ServiceExtensionAbility with the account ID specified. This API uses a | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| **Error codes** @@ -980,7 +980,7 @@ Stops a ServiceExtensionAbility in the same application. This API uses an asynch | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** @@ -1038,7 +1038,7 @@ Stops a ServiceExtensionAbility in the same application. This API uses a promise | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| **Error codes** @@ -1097,7 +1097,7 @@ Stops a ServiceExtensionAbility with the account ID specified in the same applic | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -1160,7 +1160,7 @@ Stops a ServiceExtensionAbility with the account ID specified in the same applic | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| **Error codes** @@ -1210,7 +1210,7 @@ Stops a ServiceExtensionAbility with the account ID specified in the same applic terminateSelf(callback: AsyncCallback<void>): void; -Terminates this ability. This API uses an asynchronous callback to return the result. +Terminates this UIAbility. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -1251,7 +1251,7 @@ Terminates this ability. This API uses an asynchronous callback to return the re terminateSelf(): Promise<void>; -Terminates this ability. This API uses a promise to return the result. +Terminates this UIAbility. This API uses a promise to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -1290,7 +1290,7 @@ Terminates this ability. This API uses a promise to return the result. terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void; -Terminates this ability. If the ability is started by calling [startAbilityForResult](#uiabilitycontextstartabilityforresult), the result is returned to the caller in the form of an asynchronous callback when **terminateSelfWithResult** is called. Otherwise, no result is returned to the caller when **terminateSelfWithResult** is called. +Terminates this UIAbility. If the UIAbility is started by calling [startAbilityForResult](#uiabilitycontextstartabilityforresult), the result is returned to the initiator UIAbility in the form of an asynchronous callback when **terminateSelfWithResult** is called. Otherwise, no result is returned to the initiator UIAbility when **terminateSelfWithResult** is called. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -1298,7 +1298,7 @@ Terminates this ability. If the ability is started by calling [startAbilityForRe | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the caller.| +| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the initiator UIAbility.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Error codes** @@ -1320,7 +1320,7 @@ Terminates this ability. If the ability is started by calling [startAbilityForRe abilityName: 'SecondAbility' } let resultCode = 100; - // AbilityResult information returned to the caller. + // AbilityResult information returned to the initiator UIAbility. let abilityResult = { want, resultCode @@ -1349,7 +1349,7 @@ Terminates this ability. If the ability is started by calling [startAbilityForRe terminateSelfWithResult(parameter: AbilityResult): Promise<void>; -Terminates this ability. If the ability is started by calling [startAbilityForResult](#uiabilitycontextstartabilityforresult), the result is returned to the caller in the form of a promise when **terminateSelfWithResult** is called. Otherwise, no result is returned to the caller when **terminateSelfWithResult** is called. +Terminates this UIAbility. If the UIAbility is started by calling [startAbilityForResult](#uiabilitycontextstartabilityforresult), the result is returned to the initiator UIAbility in the form of a promise when **terminateSelfWithResult** is called. Otherwise, no result is returned to the initiator UIAbility when **terminateSelfWithResult** is called. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -1357,7 +1357,7 @@ Terminates this ability. If the ability is started by calling [startAbilityForRe | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the caller.| +| parameter | [AbilityResult](js-apis-inner-ability-abilityResult.md) | Yes| Information returned to the initiator UIAbility.| **Return value** @@ -1385,7 +1385,7 @@ Terminates this ability. If the ability is started by calling [startAbilityForRe abilityName: 'SecondAbility' } let resultCode = 100; - // AbilityResult information returned to the caller. + // AbilityResult information returned to the initiator UIAbility. let abilityResult = { want, resultCode @@ -1413,7 +1413,7 @@ Terminates this ability. If the ability is started by calling [startAbilityForRe connectServiceExtensionAbility(want: Want, options: ConnectOptions): number; -Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERVICE** template. +Connects this UIAbility to a UIAbility that uses the **AbilityInfo.AbilityType.SERVICE** template. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -1421,14 +1421,14 @@ Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERV | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | No| Parameters for the connection.| **Return value** | Type| Description| | -------- | -------- | -| number | Result code of the ability connection.| +| number | Result code of the UIAbility connection.| **Error codes** @@ -1471,7 +1471,7 @@ Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERV connectServiceExtensionAbilityWithAccount(want: Want, accountId: number, options: ConnectOptions): number; -Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERVICE** template, with the account ID specified. +Connects this UIAbility to a UIAbility that uses the **AbilityInfo.AbilityType.SERVICE** template, with the account ID specified. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -1483,7 +1483,7 @@ Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERV | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | options | [ConnectOptions](js-apis-inner-ability-connectOptions.md) | No| Parameters for the connection.| @@ -1491,7 +1491,7 @@ Connects this ability to an ability that uses the **AbilityInfo.AbilityType.SERV | Type| Description| | -------- | -------- | -| number | Result code of the ability connection.| +| number | Result code of the UIAbility connection.| **Error codes** @@ -1545,7 +1545,7 @@ Disconnects a connection. This API uses a promise to return the result. | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| connection | number | Yes| Result code of the ability connection.| +| connection | number | Yes| Result code of the UIAbility connection.| **Return value** @@ -1602,7 +1602,7 @@ Disconnects a connection. This API uses an asynchronous callback to return the r | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| connection | number | Yes| Result code of the ability connection.| +| connection | number | Yes| Result code of the UIAbility connection.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** @@ -1644,11 +1644,11 @@ Disconnects a connection. This API uses an asynchronous callback to return the r startAbilityByCall(want: Want): Promise<Caller>; -Starts an ability in the foreground or background and obtains the caller object for communicating with the ability. +Starts a UIAbility in the foreground or background and obtains the caller object for communicating with the UIAbility. Observe the following when using this API: - - If an application running in the background needs to call this API to start an ability, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. - - If **visible** of the target ability is **false**, the caller must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. + - If an application running in the background needs to call this API to start a UIAbility, it must have the **ohos.permission.START_ABILITIES_FROM_BACKGROUND** permission. + - If **visible** of the target UIAbility is **false**, the initiator UIAbility must have the **ohos.permission.START_INVISIBLE_ABILITY** permission. - For details about the startup rules for the components in the stage model, see [Component Startup Rules (Stage Model)](../../application-models/component-startup-rules.md). **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -1657,7 +1657,7 @@ Observe the following when using this API: | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Information about the ability to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId** (optional), and **parameters** (optional). If **deviceId** is left blank or null, the local ability is started. If **parameters** is left blank or null, the ability is started in the background.| +| want | [Want](js-apis-application-want.md) | Yes| Information about the UIAbility to start, including **abilityName**, **moduleName**, **bundleName**, **deviceId** (optional), and **parameters** (optional). If **deviceId** is left blank or null, the local UIAbility is started. If **parameters** is left blank or null, the UIAbility is started in the background.| **Return value** @@ -1667,12 +1667,12 @@ Observe the following when using this API: **Example** - Start an ability in the background. + Start a UIAbility in the background. ```ts let caller = undefined; - // Start an ability in the background by not passing parameters. + // Start a UIAbility in the background by not passing parameters. let wantBackground = { bundleName: 'com.example.myservice', moduleName: 'entry', @@ -1698,12 +1698,12 @@ Observe the following when using this API: } ``` - Start an ability in the foreground. + Start a UIAbility in the foreground. ```ts let caller = undefined; - // Start an ability in the foreground with 'ohos.aafwk.param.callAbilityToForeground' in parameters set to true. + // Start a UIAbility in the foreground with ohos.aafwk.param.callAbilityToForeground in parameters set to true. let wantForeground = { bundleName: 'com.example.myservice', moduleName: 'entry', @@ -1736,7 +1736,7 @@ Observe the following when using this API: startAbilityWithAccount(want: Want, accountId: number, callback: AsyncCallback\): void; -Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result. +Starts a UIAbility with the account ID specified. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -1748,7 +1748,7 @@ Starts an ability with the account ID specified. This API uses an asynchronous c | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| | callback | AsyncCallback\ | Yes| Callback used to return the result.| @@ -1810,7 +1810,7 @@ Starts an ability with the account ID specified. This API uses an asynchronous c startAbilityWithAccount(want: Want, accountId: number, options: StartOptions, callback: AsyncCallback\): void; -Starts an ability with the account ID specified. This API uses an asynchronous callback to return the result. +Starts a UIAbility with the start options and account ID specified. This API uses an asynchronous callback to return the result. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -1822,9 +1822,9 @@ Starts an ability with the account ID specified. This API uses an asynchronous c | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the UIAbility.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Error codes** @@ -1888,7 +1888,7 @@ Starts an ability with the account ID specified. This API uses an asynchronous c startAbilityWithAccount(want: Want, accountId: number, options?: StartOptions): Promise\; -Starts an ability with the account ID specified. This API uses a promise to return the result. +Starts a UIAbility with the account ID specified. This API uses a promise to return the result. **Required permissions**: ohos.permission.INTERACT_ACROSS_LOCAL_ACCOUNTS @@ -1900,9 +1900,9 @@ Starts an ability with the account ID specified. This API uses a promise to retu | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| want | [Want](js-apis-application-want.md) | Yes| Want information about the target ability.| +| want | [Want](js-apis-application-want.md) | Yes| Want information about the target UIAbility.| | accountId | number | Yes| ID of a system account. For details, see [getCreatedOsAccountsCount](js-apis-osAccount.md#getosaccountlocalidfromprocess).| -| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the ability.| +| options | [StartOptions](js-apis-app-ability-startOptions.md) | No| Parameters used for starting the UIAbility.| **Error codes** @@ -2023,7 +2023,7 @@ Requests permissions from the user by displaying a dialog box. This API uses a p setMissionLabel(label: string, callback:AsyncCallback<void>): void; -Sets a label for this ability in the mission. This API uses an asynchronous callback to return the result. +Sets a label for this UIAbility in the mission. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -2031,7 +2031,7 @@ Sets a label for this ability in the mission. This API uses an asynchronous call | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| label | string | Yes| Label of the ability to set.| +| label | string | Yes| Label of the UIAbility to set.| | callback | AsyncCallback<void> | Yes| Callback used to return the result.| **Example** @@ -2047,7 +2047,7 @@ Sets a label for this ability in the mission. This API uses an asynchronous call setMissionLabel(label: string): Promise<void>; -Sets a label for this ability in the mission. This API uses a promise to return the result. +Sets a label for this UIAbility in the mission. This API uses a promise to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -2055,7 +2055,7 @@ Sets a label for this ability in the mission. This API uses a promise to return | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| label | string | Yes| Label of the ability to set.| +| label | string | Yes| Label of the UIAbility to set.| **Return value** @@ -2076,7 +2076,7 @@ Sets a label for this ability in the mission. This API uses a promise to return setMissionIcon(icon: image.PixelMap, callback:AsyncCallback\): void; -Sets an icon for this ability in the mission. This API uses an asynchronous callback to return the result. +Sets an icon for this UIAbility in the mission. This API uses an asynchronous callback to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -2086,7 +2086,7 @@ Sets an icon for this ability in the mission. This API uses an asynchronous call | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| icon | image.PixelMap | Yes| Icon of the ability to set.| +| icon | image.PixelMap | Yes| Icon of the UIAbility to set.| | callback | AsyncCallback\ | Yes| Callback used to return the result.| **Example** @@ -2118,7 +2118,7 @@ Sets an icon for this ability in the mission. This API uses an asynchronous call setMissionIcon(icon: image.PixelMap): Promise\; -Sets an icon for this ability in the mission. This API uses a promise to return the result. +Sets an icon for this UIAbility in the mission. This API uses a promise to return the result. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -2128,7 +2128,7 @@ Sets an icon for this ability in the mission. This API uses a promise to return | Name| Type| Mandatory| Description| | -------- | -------- | -------- | -------- | -| icon | image.PixelMap | Yes| Icon of the ability to set.| +| icon | image.PixelMap | Yes| Icon of the UIAbility to set.| **Return value** @@ -2167,7 +2167,7 @@ Sets an icon for this ability in the mission. This API uses a promise to return restoreWindowStage(localStorage: LocalStorage) : void; -Restores the window stage data for this ability. +Restores the window stage data for this UIAbility. **System capability**: SystemCapability.Ability.AbilityRuntime.Core @@ -2188,7 +2188,7 @@ Restores the window stage data for this ability. isTerminating(): boolean; -Checks whether this ability is in the terminating state. +Checks whether this UIAbility is in the terminating state. **System capability**: SystemCapability.Ability.AbilityRuntime.Core -- GitLab