From 8338169dc7e4973bd7810626a8e1a85caf022d0e Mon Sep 17 00:00:00 2001 From: Gloria Date: Tue, 28 Feb 2023 17:11:32 +0800 Subject: [PATCH] Update docs against 14122+14515+14833 Signed-off-by: wusongqing --- .../application-models/actions-entities.md | 4 +- .../application-context-stage.md | 21 +-- .../explicit-implicit-want-mappings.md | 8 +- .../hop-multi-device-collaboration.md | 112 ++++++------ .../mission-management-launch-type.md | 3 +- .../mission-management-overview.md | 4 +- .../serviceextensionability.md | 15 +- .../start-serviceability.md | 2 +- .../uiability-data-sync-with-ui.md | 84 ++++----- .../uiability-intra-device-interaction.md | 78 ++++---- .../application-models/want-overview.md | 13 +- en/readme/test.md | 173 ++++++++++-------- 12 files changed, 267 insertions(+), 250 deletions(-) diff --git a/en/application-dev/application-models/actions-entities.md b/en/application-dev/application-models/actions-entities.md index 85dfb9523c..5c5aed302c 100644 --- a/en/application-dev/application-models/actions-entities.md +++ b/en/application-dev/application-models/actions-entities.md @@ -1,6 +1,6 @@ # Common action and entities Values -The [action](../reference/apis/js-apis-ability-wantConstant.md#wantconstantaction) field specifies the common operation (such as viewing, sharing, and application details) to be performed by the caller. In implicit Want, you can define this field and use it together with **uri** or **parameters** to specify the operation to be performed on the data, for example, viewing URI data. For example, if the URI is a website and the action is **ohos.want.action.viewData**, the ability that supports website viewing is matched. Declaring the **action** field in Want indicates that the invoked application should support the declared operation. The **actions** field under **skills** in the configuration file indicates the operations supported by the application. +**action**: Action to take, such as viewing, sharing, and application details, by the caller. In implicit Want, you can define this field and use it together with **uri** or **parameters** to specify the operation to be performed on the data, for example, viewing URI data. For example, if the URI is a website and the action is **ohos.want.action.viewData**, the ability that supports website viewing is matched. Declaring the **action** field in Want indicates that the invoked application should support the declared operation. The **actions** field under **skills** in the configuration file indicates the operations supported by the application. **Common action Values** @@ -14,7 +14,7 @@ The [action](../reference/apis/js-apis-ability-wantConstant.md#wantconstantactio - **ACTION_VIEW_MULTIPLE_DATA**: action of launching the UI for sending multiple data records. -The [entities](../reference/apis/js-apis-ability-wantConstant.md#wantconstantentity) field specifies the additional category information (such as browser and video player) of the target ability. It is a supplement to **action** in implicit Want. You can define this field to filter application categories, for example, browser. Declaring the **entities** field in Want indicates that the invoked application should belong to the declared category. The **entities** field under **skills** in the configuration file indicates the categories supported by the application. +**entities**: Category information (such as browser and video player) of the target ability. It is a supplement to **action** in implicit Want. You can define this field to filter application categories, for example, browser. Declaring the **entities** field in Want indicates that the invoked application should belong to the declared category. The **entities** field under **skills** in the configuration file indicates the categories supported by the application. **Common entities Values** diff --git a/en/application-dev/application-models/application-context-stage.md b/en/application-dev/application-models/application-context-stage.md index 4bb36b6640..de07a3600a 100644 --- a/en/application-dev/application-models/application-context-stage.md +++ b/en/application-dev/application-models/application-context-stage.md @@ -10,11 +10,11 @@ ![context-inheritance](figures/context-inheritance.png) - The figure below illustrates the holding relationship of contexts. - + ![context-holding](figures/context-holding.png) - The following describes the information provided by different contexts. - - [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md): Each UIAbility has the **Context** attribute, which provides APIs to operate the ability, obtain the ability configuration, and more. + - [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md): Each UIAbility has the **Context** attribute, which provides APIs to operate an application component, obtain the application component configuration, and more. ```ts import UIAbility from '@ohos.app.ability.UIAbility'; @@ -25,6 +25,10 @@ } } ``` + + > **NOTE** + > + > For details about how to obtain the context of a **UIAbility** instance on the page, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability). - Scenario-specific [ExtensionContext](../reference/apis/js-apis-inner-application-extensionContext.md): For example, ServiceExtensionContext, inherited from ExtensionContext, provides APIs related to background services. ```ts @@ -47,7 +51,7 @@ } } ``` - - [ApplicationContext](../reference/apis/js-apis-inner-application-applicationContext.md): application-level context. It provides APIs for subscribing to ability lifecycle changes, system memory changes, and system environment changes. The application-level context can be obtained from UIAbility, ExtensionAbility, and AbilityStage. + - [ApplicationContext](../reference/apis/js-apis-inner-application-applicationContext.md): application-level context. It provides APIs for subscribing to application component lifecycle changes, system memory changes, and system environment changes. The application-level context can be obtained from UIAbility, ExtensionAbility, and AbilityStage. ```ts import UIAbility from '@ohos.app.ability.UIAbility'; @@ -179,13 +183,10 @@ The base class **Context** provides the [createBundleContext(bundleName:string)] > To obtain the context of another application: > > - Request the **ohos.permission.GET_BUNDLE_INFO_PRIVILEGED** permission. For details, see [Permission Application Guide](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file). - > - > - This is a system API and cannot be called by third-party applications. - > > - This is a system API and cannot be called by third-party applications. For example, application information displayed on the home screen includes the application name and icon. The home screen application calls the foregoing method to obtain the context information, so as to obtain the resource information including the application name and icon. - + ```ts import UIAbility from '@ohos.app.ability.UIAbility'; @@ -198,7 +199,6 @@ The base class **Context** provides the [createBundleContext(bundleName:string)] } } ``` - - Call **createModuleContext(bundleName:string, moduleName:string)** to obtain the context of a specified module of another application. After obtaining the context, you can obtain the resource information of that module. > **NOTE** @@ -206,9 +206,6 @@ The base class **Context** provides the [createBundleContext(bundleName:string)] > To obtain the context of a specified module of another application: > > - Request the **ohos.permission.GET_BUNDLE_INFO_PRIVILEGED** permission. For details, see [Permission Application Guide](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file). - > - > - This is a system API and cannot be called by third-party applications. - > > - This is a system API and cannot be called by third-party applications. ```ts @@ -223,7 +220,7 @@ The base class **Context** provides the [createBundleContext(bundleName:string)] } } ``` - + - Call **createModuleContext(moduleName:string)** to obtain the context of another module in the current application. After obtaining the context, you can obtain the resource information of that module. ```ts diff --git a/en/application-dev/application-models/explicit-implicit-want-mappings.md b/en/application-dev/application-models/explicit-implicit-want-mappings.md index 3e68e8ed85..16854efb92 100644 --- a/en/application-dev/application-models/explicit-implicit-want-mappings.md +++ b/en/application-dev/application-models/explicit-implicit-want-mappings.md @@ -50,7 +50,7 @@ The system matches the **want** parameter (including the **action**, **entities* ### Matching Rules of action in the want Parameter -The system matches the [action](../reference/apis/js-apis-ability-wantConstant.md#wantconstantaction) attribute in the **want** parameter passed by the caller against **actions** under **skills** of the abilities. +The system matches the **action** attribute in the **want** parameter passed by the caller against **actions** under **skills** of the abilities. - If **action** in the passed **want** parameter is specified but **actions** under **skills** of an ability is unspecified, the matching fails. @@ -62,12 +62,12 @@ The system matches the [action](../reference/apis/js-apis-ability-wantConstant.m **Figure 1** Matching rules of action in the want parameter - ![want-action](figures/want-action.png) + ![want-action](figures/want-action.png) ### Matching Rules of entities in the want Parameter -The system matches the [entities](../reference/apis/js-apis-ability-wantConstant.md#wantconstantentity) attribute in the **want** parameter passed by the caller against **entities** under **skills** of the abilities. +The system matches the **entities** attribute in the **want** parameter passed by the caller against **entities** under **skills** of the abilities. - If **entities** in the passed **want** parameter is unspecified but **entities** under **skills** of an ability is specified, the matching is successful. @@ -117,7 +117,7 @@ To simplify the description, **uri** and **type** passed in the **want** paramet Figure 4 Matching rules of uri and type in the want parameter -![want-uri-type2](figures/want-uri-type2.png) +![want-uri-type2](figures/want-uri-type2.png) ### Matching Rules of uri diff --git a/en/application-dev/application-models/hop-multi-device-collaboration.md b/en/application-dev/application-models/hop-multi-device-collaboration.md index 3a6fa2646a..fe22c3b33d 100644 --- a/en/application-dev/application-models/hop-multi-device-collaboration.md +++ b/en/application-dev/application-models/hop-multi-device-collaboration.md @@ -93,7 +93,7 @@ On device A, touch the **Start** button provided by the initiator application to } ``` -4. Set the target component parameters, and call **startAbility()** to start UIAbility or ServiceExtensionAbility. +4. Set the target component parameters, and call [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to start UIAbility or ServiceExtensionAbility. ```ts let want = { @@ -382,68 +382,68 @@ The following describes how to implement multi-device collaboration through cros ```ts export default class MySequenceable { - num: number = 0 - str: string = "" + num: number = 0; + str: string = ""; constructor(num, string) { - this.num = num - this.str = string + this.num = num; + this.str = string; } marshalling(messageParcel) { - messageParcel.writeInt(this.num) - messageParcel.writeString(this.str) - return true + messageParcel.writeInt(this.num); + messageParcel.writeString(this.str); + return true; } unmarshalling(messageParcel) { - this.num = messageParcel.readInt() - this.str = messageParcel.readString() - return true + this.num = messageParcel.readInt(); + this.str = messageParcel.readString(); + return true; } } ``` 4. Implement **Callee.on** and **Callee.off**. - In the following example, the **MSG_SEND_METHOD** listener is registered in **onCreate()** of the ability and deregistered in **onDestroy()**. After receiving sequenceable data, the application processes the data and returns the data result. You need to implement processing based on service requirements. - - ```ts - const TAG: string = '[CalleeAbility]' - const MSG_SEND_METHOD: string = 'CallSendMsg' - - function sendMsgCallback(data) { - console.info('CalleeSortFunc called') - - // Obtain the sequenceable data sent by the caller ability. - let receivedData = new MySequenceable(0, '') - data.readSequenceable(receivedData) - console.info(`receiveData[${receivedData.num}, ${receivedData.str}]`) - - // Process the data. - // Return the sequenceable data result to the caller ability. - return new MySequenceable(receivedData.num + 1, `send ${receivedData.str} succeed`) - } - - export default class CalleeAbility extends Ability { - onCreate(want, launchParam) { - try { - this.callee.on(MSG_SEND_METHOD, sendMsgCallback) - } catch (error) { - console.info(`${MSG_SEND_METHOD} register failed with error ${JSON.stringify(error)}`) - } - } - - onDestroy() { - try { - this.callee.off(MSG_SEND_METHOD) - } catch (error) { - console.error(TAG, `${MSG_SEND_METHOD} unregister failed with error ${JSON.stringify(error)}`) - } - } - } - ``` - + In the following example, the **MSG_SEND_METHOD** listener is registered in **onCreate()** of the ability and deregistered in **onDestroy()**. After receiving sequenceable data, the application processes the data and returns the data result. You need to implement processing based on service requirements. + + ```ts + const TAG: string = '[CalleeAbility]'; + const MSG_SEND_METHOD: string = 'CallSendMsg'; + + function sendMsgCallback(data) { + console.info('CalleeSortFunc called'); + + // Obtain the sequenceable data sent by the caller ability. + let receivedData = new MySequenceable(0, ''); + data.readSequenceable(receivedData); + console.info(`receiveData[${receivedData.num}, ${receivedData.str}]`); + + // Process the data. + // Return the sequenceable data result to the caller ability. + return new MySequenceable(receivedData.num + 1, `send ${receivedData.str} succeed`); + } + + export default class CalleeAbility extends Ability { + onCreate(want, launchParam) { + try { + this.callee.on(MSG_SEND_METHOD, sendMsgCallback); + } catch (error) { + console.info(`${MSG_SEND_METHOD} register failed with error ${JSON.stringify(error)}`); + } + } + + onDestroy() { + try { + this.callee.off(MSG_SEND_METHOD); + } catch (error) { + console.error(TAG, `${MSG_SEND_METHOD} unregister failed with error ${JSON.stringify(error)}`); + } + } + } + ``` + 4. Obtain the caller object and access the callee ability. 1. Import the **UIAbility** module. @@ -458,8 +458,8 @@ The following describes how to implement multi-device collaboration through cros ```ts async onButtonGetRemoteCaller() { - var caller = undefined - var context = this.context + var caller = undefined; + var context = this.context; context.startAbilityByCall({ deviceId: getRemoteDeviceId(), @@ -467,16 +467,16 @@ The following describes how to implement multi-device collaboration through cros abilityName: 'CalleeAbility' }).then((data) => { if (data != null) { - caller = data - console.info('get remote caller success') + caller = data; + console.info('get remote caller success'); // Register the onRelease() listener of the caller ability. caller.onRelease((msg) => { - console.info(`remote caller onRelease is called ${msg}`) + console.info(`remote caller onRelease is called ${msg}`); }) - console.info('remote caller register OnRelease succeed') + console.info('remote caller register OnRelease succeed'); } }).catch((error) => { - console.error(`get remote caller failed with ${error}`) + console.error(`get remote caller failed with ${error}`); }) } ``` diff --git a/en/application-dev/application-models/mission-management-launch-type.md b/en/application-dev/application-models/mission-management-launch-type.md index 72b6dbf80d..267ed5011f 100644 --- a/en/application-dev/application-models/mission-management-launch-type.md +++ b/en/application-dev/application-models/mission-management-launch-type.md @@ -10,7 +10,7 @@ The following describes how the mission list manager manages the UIAbility insta **Figure 1** Missions and singleton mode ![mission-and-singleton](figures/mission-and-singleton.png) -- **standard**: Each time **startAbility()** is called, a UIAbility instance is created in the application process. +- **standard**: Each time [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, a **UIAbility** instance is created in the application process. **Figure 2** Missions and standard mode ![mission-and-standard](figures/mission-and-standard.png) @@ -30,4 +30,3 @@ Every mission retains a snapshot of the UIAbility instance. After the UIAbility > **NOTE** > > The **specified** mode is supported in the stage model only. - diff --git a/en/application-dev/application-models/mission-management-overview.md b/en/application-dev/application-models/mission-management-overview.md index b6f6668f7c..3346e8105d 100644 --- a/en/application-dev/application-models/mission-management-overview.md +++ b/en/application-dev/application-models/mission-management-overview.md @@ -28,7 +28,7 @@ Missions are managed by system applications (such as home screen), rather than t - Switch a mission to the foreground. -A UIAbility instance corresponds to an independent mission. Therefore, when an application calls the **startAbility()** method to start a UIAbility, a mission is created. +A UIAbility instance corresponds to an independent mission. Therefore, when an application calls [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to start a UIAbility, a mission is created. To call [missionManager](../reference/apis/js-apis-application-missionManager.md) to manage missions, the home screen application must request the **ohos.permission.MANAGE_MISSIONS** permission. For details about the configuration, see [Permission Application Guide](../security/accesstoken-guidelines.md#declaring-permissions-in-the-configuration-file). @@ -36,6 +36,8 @@ To call [missionManager](../reference/apis/js-apis-application-missionManager.md You can use **missionManager** to manage missions, for example, listening for mission changes, obtaining mission information or snapshots, and clearing, locking, or unlocking missions. The sample code is as follows: + + ```ts import missionManager from '@ohos.app.ability.missionManager' diff --git a/en/application-dev/application-models/serviceextensionability.md b/en/application-dev/application-models/serviceextensionability.md index c4ffdbd980..d64d884b1e 100644 --- a/en/application-dev/application-models/serviceextensionability.md +++ b/en/application-dev/application-models/serviceextensionability.md @@ -1,5 +1,6 @@ # ServiceExtensionAbility + [ServiceExtensionAbility](../reference/apis/js-apis-app-ability-serviceExtensionAbility.md) is an ExtensionAbility component of the service type that provides extension capabilities related to background services. @@ -40,28 +41,24 @@ This feature applies only to system applications. [ServiceExtensionAbility](../r ![ServiceExtensionAbility-lifecycle](figures/ServiceExtensionAbility-lifecycle.png) - **onCreate** - -This callback is triggered when a service is created for the first time. You can perform initialization operations, for example, registering a common event listener. + This callback is triggered when a service is created for the first time. You can perform initialization operations, for example, registering a common event listener. > **NOTE** -> + > > If a service has been created, starting it again does not trigger the **onCreate()** callback. - **onRequest** - -This callback is triggered when another component calls the **startServiceExtensionAbility()** method to start the service. After being started, the service runs in the background. + This callback is triggered when another component calls the **startServiceExtensionAbility()** method to start the service. After being started, the service runs in the background. - **onConnect** - -This callback is triggered when another component calls the **connectServiceExtensionAbility()** method to connect to the service. In this method, a remote proxy object (IRemoteObject) is returned, through which the client communicates with the server by means of RPC. + This callback is triggered when another component calls the **connectServiceExtensionAbility()** method to connect to the service. In this method, a remote proxy object (IRemoteObject) is returned, through which the client communicates with the server by means of RPC. - **onDisconnect** - -This callback is triggered when a component calls the **disconnectServiceExtensionAbility()** method to disconnect from the service. + This callback is triggered when a component calls the **disconnectServiceExtensionAbility()** method to disconnect from the service. - **onDestroy** diff --git a/en/application-dev/application-models/start-serviceability.md b/en/application-dev/application-models/start-serviceability.md index f3b0f6aeab..e07428f13a 100644 --- a/en/application-dev/application-models/start-serviceability.md +++ b/en/application-dev/application-models/start-serviceability.md @@ -27,7 +27,7 @@ async function startServiceAbility() { ``` -In the preceding code, **startAbility()** is used to start the ServiceAbility. +In the preceding code, [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is used to start the ServiceAbility. - If the ServiceAbility is not running, the system calls **onStart()** to initialize the ServiceAbility, and then calls **onCommand()** on the ServiceAbility. diff --git a/en/application-dev/application-models/uiability-data-sync-with-ui.md b/en/application-dev/application-models/uiability-data-sync-with-ui.md index c0cabf26d0..9ed8c8d6f3 100644 --- a/en/application-dev/application-models/uiability-data-sync-with-ui.md +++ b/en/application-dev/application-models/uiability-data-sync-with-ui.md @@ -3,17 +3,16 @@ Based on the OpenHarmony application model, you can use any of the following ways to implement data synchronization between the UIAbility component and UI: -- EventHub: The [base class Context](application-context-stage.md) provides the EventHub capability. It is implemented based on the publish/subscribe (pub/sub) pattern. Your application subscribes to an event and when the event occurs, receives a notification. - -- globalThis: It is a global object accessible in the ArkTS engine instance. -- LocalStorage/AppStorage: See [State Management of Application-Level Variables](../quick-start/arkts-state-mgmt-application-level.md). +- [Using EventHub for Data Synchronization](#using-eventhub-for-data-synchronization): The **EventHub** object is provided by the base class **Context**. Events are transferred using the publish/subscribe (pub/sub) pattern. Specifically, after subscribing to an event, your application will receive the event and process it accordingly when the event is published. +- [Using globalThis for Data Synchronization](#using-globalthis-for-data-synchronization): **globalThis** is a global object inside the ArkTS engine instance and can be accessed by components such as UIAbility, ExtensionAbility, and Page. +- [Using AppStorage or LocalStorage for Data Synchronization](#using-appstorage-or-localstorage-for-data-synchronization): ArkUI provides two application-level state management solutions: AppStorage and LocalStorage, which implement application- and UIAbility-level data synchronization, respectively. ## Using EventHub for Data Synchronization -[EventHub](../reference/apis/js-apis-inner-application-eventHub.md) provides an event mechanism at the UIAbility or ExtensionAbility component level. Centered on the UIAbility or ExtensionAbility component, EventHub provides data communication capabilities for subscribing to, unsubscribing from, and triggering events. +[EventHub](../reference/apis/js-apis-inner-application-eventHub.md) provides an event mechanism for the UIAbility or ExtensionAbility component so that they can subscribe to, unsubscribe from, and trigger events. -Before using EventHub, you must obtain an EventHub object, which is provided by the [base class Context](application-context-stage.md). This section uses EventHub as an example to describe how to implement data synchronization between the UIAbility component and the UI. +Before using the APIs provided by **EventHub**, you must obtain an **EventHub** object, which is provided by the [base class Context](application-context-stage.md). This section uses EventHub as an example to describe how to implement data synchronization between the UIAbility component and the UI. 1. Call [eventHub.on()](../reference/apis/js-apis-inner-application-eventHub.md#eventhubon) in the UIAbility in either of the following ways to register a custom event **event1**. @@ -81,17 +80,16 @@ Before using EventHub, you must obtain an EventHub object, which is provided by 4. After **event1** is used, you can call [eventHub.off()](../reference/apis/js-apis-inner-application-eventHub.md#eventhuboff) to unsubscribe from the event. ```ts - // context is the ability context of the UIAbility instance. + // context is the ability-level context of the UIAbility instance. this.context.eventHub.off('event1'); ``` ## Using globalThis for Data Synchronization - **globalThis** is a global object inside the [ArkTS engine instance](thread-model-stage.md) and can be used by UIAbility, ExtensionAbility, and Page inside the engine. Therefore, you can use **globalThis** for data synchronization. - **Figure 1** Using globalThis for data synchronization +**Figure 1** Using globalThis for data synchronization ![globalThis1](figures/globalThis1.png) @@ -99,18 +97,18 @@ Before using EventHub, you must obtain an EventHub object, which is provided by The following describes how to use **globalThis** in three scenarios. Precautions are provided as well. - [Using globalThis Between UIAbility and Page](#using-globalthis-between-uiability-and-page) -- [Using globalThis Between UIAbility and UIAbility](##using-globalthis-between-uiability-and-uiability) +- [Using globalThis Between UIAbility and UIAbility](#using-globalthis-between-uiability-and-uiability) - [Use globalThis Between UIAbility and ExtensionAbility](#using-globalthis-between-uiability-and-extensionability) - [Precautions for Using globalThis](#precautions-for-using-globalthis) ### Using globalThis Between UIAbility and Page -You can use **globalThis** to bind attributes or methods to implement data synchronization between the UIAbility component and UI. For example, if you bind the **want** parameter in the UIAbility component, you can use the **want** parameter information on the UI corresponding to the UIAbility component. +By binding attributes or methods to **globalThis**, you can implement data synchronization between the UIAbility component and UI. For example, if you bind the **want** parameter in the UIAbility component, you can use the **want** parameter information on the UI corresponding to the UIAbility component. -1. When **startAbility()** is called to start a UIAbility instance, the **onCreate()** callback is invoked, and the **want** parameter can be passed in the callback. Therefore, you can bind the **want** parameter to **globalThis**. +1. When [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called to start a UIAbility instance, the **onCreate()** callback is invoked, and the **want** parameter can be passed in the callback. Therefore, you can bind the **want** parameter to **globalThis**. ```ts - import UIAbility from '@ohos.app.ability.UIAbility' + import UIAbility from '@ohos.app.ability.UIAbility'; export default class EntryAbility extends UIAbility { onCreate(want, launch) { @@ -144,29 +142,29 @@ You can use **globalThis** to bind attributes or methods to implement data synch ### Using globalThis Between UIAbility and UIAbility -To implement data synchronization between two UIAbility components in the same application, you can bind data to **globalThis**. For example, you can save data in **globalThis** in AbilityA and obtain the data from AbilityB. +To implement data synchronization between two UIAbility components in the same application, you can bind data to **globalThis**. For example, you can save data in **globalThis** in UIAbilityA and obtain the data from UIAbilityB. -1. AbilityA stores a string and binds it to globalThis. +1. UIAbilityA stores a string and binds it to globalThis. ```ts import UIAbility from '@ohos.app.ability.UIAbility' - export default class AbilityA extends UIAbility { + export default class UIAbilityA extends UIAbility { onCreate(want, launch) { - globalThis.entryAbilityStr = 'AbilityA'; // AbilityA stores the string "AbilityA" to globalThis. + globalThis.entryAbilityStr = 'UIAbilityA'; // UIAbilityA stores the string "UIAbilityA" to globalThis. // ... } } ``` -2. Obtain the data from AbilityB. +2. Obtain the data from UIAbilityB. ```ts import UIAbility from '@ohos.app.ability.UIAbility' - export default class AbilityB extends UIAbility { + export default class UIAbilityB extends UIAbility { onCreate(want, launch) { - // AbilityB reads the name from globalThis and outputs it. + // UIAbilityB reads name from globalThis and outputs it. console.info('name from entryAbilityStr: ' + globalThis.entryAbilityStr); // ... } @@ -176,17 +174,17 @@ To implement data synchronization between two UIAbility components in the same a ### Using globalThis Between UIAbility and ExtensionAbility -To implement data synchronization between the UIAbility and ExtensionAbility components in the same application, you can bind data to **globalThis**. For example, you can save data in **globalThis** in AbilityA and obtain the data from ServiceExtensionAbility. +To implement data synchronization between the UIAbility and ExtensionAbility components in the same application, you can bind data to **globalThis**. For example, you can save data in **globalThis** in UIAbilityA and obtain the data from ServiceExtensionAbility. -1. AbilityA stores a string and binds it to globalThis. +1. UIAbilityA stores a string and binds it to globalThis. ```ts import UIAbility from '@ohos.app.ability.UIAbility' - export default class AbilityA extends UIAbility { + export default class UIAbilityA extends UIAbility { onCreate(want, launch) { - // AbilityA stores the string "AbilityA" to globalThis. - globalThis.entryAbilityStr = 'AbilityA'; + // UIAbilityA stores the string "UIAbilityA" to globalThis. + globalThis.entryAbilityStr = 'UIAbilityA'; // ... } } @@ -209,11 +207,11 @@ To implement data synchronization between the UIAbility and ExtensionAbility com ### Precautions for Using globalThis - **Figure 2** Precautions for globalThis +**Figure 2** Precautions for globalThis - ![globalThis2](figures/globalThis2.png) +![globalThis2](figures/globalThis2.png) -- In the stage model, all the UIAbility components in a process share one ArkTS engine instance. When using **globalThis**, do not store objects with the same name. For example, if AbilityA and AbilityB use **globalThis** to store two objects with the same name, the object stored earlier will be overwritten. +- In the stage model, all the UIAbility components in a process share one ArkTS engine instance. When using **globalThis**, do not store objects with the same name. For example, if UIAbilityA and UIAbilityB use **globalThis** to store two objects with the same name, the object stored earlier will be overwritten. - This problem does not occur in the FA model because each UIAbility component uses an independent engine. @@ -221,20 +219,20 @@ To implement data synchronization between the UIAbility and ExtensionAbility com The following provides an example to describe the object overwritten problem in the stage model. -1. In the AbilityA file, [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) is stored in **globalThis**. +1. In the UIAbilityA file, [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) is stored in **globalThis**. ```ts import UIAbility from '@ohos.app.ability.UIAbility' - export default class AbilityA extends UIAbility { + export default class UIAbilityA extends UIAbility { onCreate(want, launch) { - globalThis.context = this.context; // AbilityA stores the context in globalThis. + globalThis.context = this.context; // UIAbilityA stores the context in globalThis. // ... } } ``` -2. Obtain and use [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) on the page of Ability A. After the AbilityA instance is used, switch it to the background. +2. Obtain and use [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) on the page of UIAbilityA. After the UIAbilityA instance is used, switch it to the background. ```ts @Entry @@ -254,21 +252,21 @@ The following provides an example to describe the object overwritten problem in } ``` -3. In the AbilityB file, [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) is stored in **globalThis** and has the same name as that in the AbilityA file. +3. In the UIAbilityB file, [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) is stored in **globalThis** and has the same name as that in the UIAbilityA file. ```ts import UIAbility from '@ohos.app.ability.UIAbility' - export default class AbilityB extends UIAbility { + export default class UIAbilityB extends UIAbility { onCreate(want, launch) { - // AbilityB overwrites the context stored by AbilityA in globalThis. + // UIAbilityB overwrites the context stored by UIAbilityA in globalThis. globalThis.context = this.context; // ... } } ``` -4. Obtain and use [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) on the page of Ability B. The obtained **globalThis.context** is the value of [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) in AbilityB. +4. Obtain and use [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) on the page of UIAbilityB. The obtained **globalThis.context** is the value of [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) in UIAbilityB. ```ts @Entry @@ -288,27 +286,27 @@ The following provides an example to describe the object overwritten problem in } ``` -5. Switch the AbilityB instance to the background and switch the AbilityA instance to the foreground. In this case, AbilityA will not enter the **onCreate()** lifecycle again. +5. Switch the UIAbilityB instance to the background and switch the UIAbilityA instance to the foreground. In this case, UIAbilityA will not enter the **onCreate()** lifecycle again. ```ts import UIAbility from '@ohos.app.ability.UIAbility' - export default class AbilityA extends UIAbility { - onCreate(want, launch) { // AbilityA will not enter this lifecycle. + export default class UIAbilityA extends UIAbility { + onCreate(want, launch) { // UIAbilityA will not enter this lifecycle. globalThis.context = this.context; // ... } } ``` -6. When the page of AbilityA is displayed, the obtained **globalThis.context** is [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) of AbilityB instead of AbilityA. An error occurs. +6. When the page of UIAbilityA is displayed, the obtained **globalThis.context** is [UIAbilityContext](../reference/apis/js-apis-inner-application-uiAbilityContext.md) of UIAbilityB instead of UIAbilityA. An error occurs. ```ts @Entry @Component struct Index { onPageShow() { - let ctx = globalThis.context; // The context in globalThis is the context of AbilityB. + let ctx = globalThis.context; // The context in globalThis is the context of UIAbilityB. let permissions=['com.example.permission']; ctx.requestPermissionsFromUser(permissions,(result) => { // Using this object causes a process breakdown. console.info('requestPermissionsFromUser result:' + JSON.stringify(result)); @@ -320,3 +318,7 @@ The following provides an example to describe the object overwritten problem in } } ``` + +## Using AppStorage or LocalStorage for Data Synchronization + +ArkUI provides AppStorage and LocalStorage to implement application- and UIAbility-level data synchronization, respectively. Both solutions can be used to manage the application state, enhance application performance, and improve user experience. The AppStorage is a global state manager and is applicable when multiple UIAbilities share the same state data. The LocalStorage is a local state manager that manages state data used inside a single UIAbility. They help you control the application state more flexibly and improve the maintainability and scalability of applications. For details, see [State Management of Application-Level Variables](../quick-start/arkts-state-mgmt-application-level.md). 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 5efbe34173..ac3c18e36d 100644 --- a/en/application-dev/application-models/uiability-intra-device-interaction.md +++ b/en/application-dev/application-models/uiability-intra-device-interaction.md @@ -26,7 +26,7 @@ This scenario is possible when an application contains multiple UIAbility compon Assume that your application has two UIAbility components: EntryAbility and FuncAbility, either in the same module or different modules. You are required to start FuncAbility from EntryAbility. -1. In EntryAbility, call **startAbility()** to start UIAbility. The [want](../reference/apis/js-apis-app-ability-want.md) parameter is the entry parameter for starting the UIAbility instance. In the **want** parameter, **bundleName** indicates the bundle name of the application to start; **abilityName** indicates the name of the UIAbility to start; **moduleName** is required only when the target UIAbility belongs to a different module; **parameters** is used to carry custom information. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability). +1. In EntryAbility, call [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) to start UIAbility. The [want](../reference/apis/js-apis-app-ability-want.md) parameter is the entry parameter for starting the UIAbility instance. In the **want** parameter, **bundleName** indicates the bundle name of the application to start; **abilityName** indicates the name of the UIAbility to start; **moduleName** is required only when the target UIAbility belongs to a different module; **parameters** is used to carry custom information. 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 = { @@ -62,21 +62,27 @@ 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. +3. To stop the **UIAbility** instance after the FuncAbility service is complete, call [terminateSelf()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself) in FuncAbility. ```ts - // context is the ability context of the UIAbility instance to stop. + // context is the ability-level context of the UIAbility instance to stop. this.context.terminateSelf((err) => { // ... }); ``` + + > **NOTE** + > + > When [terminateSelf()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself) is called to stop the **UIAbility** instance, the snapshot of the instance is retained by default. That is, the mission corresponding to the instance is still displayed in Recents. If you do not want to retain the snapshot, set **removeMissionAfterTerminate** under the [abilities](../quick-start/module-configuration-file.md#abilities) tag to **true** in the [module.json5 file](../quick-start/module-configuration-file.md) of the corresponding UIAbility. + +4. To stop all UIAbility instances of the application, call [killProcessBySelf()](../reference/apis/js-apis-inner-application-applicationContext.md#applicationcontextkillallprocesses9) of [ApplicationContext](../reference/apis/js-apis-inner-application-applicationContext.md) to stop all processes of the application. ## Starting UIAbility in the Same Application and Obtaining the Return Result When starting FuncAbility from EntryAbility, you want the result to be returned after the FuncAbility service is finished. For example, your application uses two independent UIAbility components to carry the entry and sign-in functionalities. After the sign-in operation is finished in the sign-in UIAbility, the sign-in result needs to be returned to the entry UIAbility. -1. In EntryAbility, call **startAbilityForResult()** to start FuncAbility. Use **data** in the asynchronous callback to receive information returned after FuncAbility stops itself. For details about how to obtain the context, see [Obtaining the Context of UIAbility](uiability-usage.md#obtaining-the-context-of-uiability). +1. In EntryAbility, call [startAbilityForResult()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to start FuncAbility. Use **data** in the asynchronous callback to receive information returned after FuncAbility stops itself. 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 = { @@ -96,7 +102,7 @@ When starting FuncAbility from EntryAbility, you want the result to be returned }) ``` -2. Call **terminateSelfWithResult()** to stop FuncAbility. Use the input parameter **abilityResult** to carry the information that FuncAbility needs to return to EntryAbility. +2. Call [terminateSelfWithResult()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to stop FuncAbility. Use the input parameter **abilityResult** to carry the information that FuncAbility needs to return to EntryAbility. ```ts const RESULT_CODE: number = 1001; @@ -111,13 +117,13 @@ When starting FuncAbility from EntryAbility, you want the result to be returned }, }, } - // context is the ability context of the callee UIAbility. + // context is the ability-level context of the callee 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()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) 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; @@ -145,11 +151,11 @@ There are two ways to start **UIAbility**: [explicit and implicit](want-overview - 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()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability) is called, the want parameter specifies a series of parameters such as **entities** and **actions**. **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. -1. Install multiple document applications on your device. In the **module.json5** file of each UIAbility component, configure [entities](../reference/apis/js-apis-ability-wantConstant.md#wantconstantentity) and [actions](../reference/apis/js-apis-ability-wantConstant.md#wantconstantaction) under **skills**. +1. Install multiple document applications on your device. In the [module.json5 file](../quick-start/module-configuration-file.md) of each UIAbility component, configure **entities** and **actions** under **skills**. ```json { @@ -196,13 +202,13 @@ This section describes how to start the UIAbility of another application through ``` The following figure shows the effect. When you click **Open PDF**, a dialog box is displayed for you to select. - + ![uiability-intra-device-interaction](figures/uiability-intra-device-interaction.png) -3. To stop the **UIAbility** instance after the document application is used, call **terminateSelf()**. +3. To stop the **UIAbility** instance after the document application is used, call [terminateSelf()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateself). ```ts - // context is the ability context of the UIAbility instance to stop. + // context is the ability-level context of the UIAbility instance to stop. this.context.terminateSelf((err) => { // ... }); @@ -211,9 +217,9 @@ 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()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult). 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**. +1. In the [module.json5 file](../quick-start/module-configuration-file.md) of the UIAbility corresponding to the payment application, set **entities** and **actions** under **skills**. ```json { @@ -239,7 +245,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()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) 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. ```ts let wantInfo = { @@ -259,7 +265,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()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) to stop the payment UIAbility and return the **abilityResult** parameter. ```ts const RESULT_CODE: number = 1001; @@ -274,13 +280,13 @@ If you want to obtain the return result when using implicit Want to start the UI }, }, } - // context is the ability context of the callee UIAbility. + // context is the ability-level context of the callee 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 the [startAbilityForResult()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult) method. The value of **RESULT_CODE** must be the same as that returned by [terminateSelfWithResult()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextterminateselfwithresult). ```ts const RESULT_CODE: number = 1001; @@ -443,7 +449,7 @@ Ability call is usually used in the following scenarios: The following figure shows the ability call process. -**Figure 1** Ability call process +Figure 1 Ability call process ![call](figures/call.png) @@ -490,24 +496,23 @@ For the callee ability, implement the callback to receive data and the methods t Set **launchType** of the callee ability to **singleton** in the **module.json5** file. -| JSON Field| Description| -| -------- | -------- | -| "launchType" | Ability launch type. Set this parameter to **singleton**.| + | JSON Field| Description| + | -------- | -------- | + | "launchType" | Ability launch type. Set this parameter to **singleton**.| -An example of the ability configuration is as follows: + An example of the ability configuration is as follows: - - ```json - "abilities":[{ - "name": ".CalleeAbility", - "srcEntrance": "./ets/CalleeAbility/CalleeAbility.ts", - "launchType": "singleton", - "description": "$string:CalleeAbility_desc", - "icon": "$media:icon", - "label": "$string:CalleeAbility_label", - "visible": true - }] - ``` + ```json + "abilities":[{ + "name": ".CalleeAbility", + "srcEntrance": "./ets/CalleeAbility/CalleeAbility.ts", + "launchType": "singleton", + "description": "$string:CalleeAbility_desc", + "icon": "$media:icon", + "label": "$string:CalleeAbility_label", + "visible": true + }] + ``` 2. Import the **UIAbility** module. @@ -519,7 +524,6 @@ An example of the ability configuration is as follows: 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. - ```ts export default class MySequenceable { num: number = 0 @@ -548,7 +552,6 @@ An example of the ability configuration is as follows: 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 sequenceable 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 const TAG: string = '[CalleeAbility]'; const MSG_SEND_METHOD: string = 'CallSendMsg'; @@ -598,7 +601,6 @@ An example of the ability configuration is as follows: 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. - ```ts // Register the onRelease() listener of the caller ability. private regOnRelease(caller) { diff --git a/en/application-dev/application-models/want-overview.md b/en/application-dev/application-models/want-overview.md index 876f0a4e3e..1ce771daf1 100644 --- a/en/application-dev/application-models/want-overview.md +++ b/en/application-dev/application-models/want-overview.md @@ -3,17 +3,16 @@ ## Definition and Usage of Want -[Want](../reference/apis/js-apis-app-ability-want.md) is used as the carrier to transfer information between application components. It is used as a parameter of **startAbility()** to specify the startup target and information that needs to be carried during startup, for example, **bundleName** and **abilityName**, which respectively indicate the bundle name of the target ability and the ability name in the bundle. For example, when UIAbilityA starts UIAbilityB and needs to transfer some data to UIAbilityB, it can use Want to transfer the data. +[Want](../reference/apis/js-apis-app-ability-want.md) is an object that transfers information between application components. It is often used as a parameter of [startAbility()](../reference/apis/js-apis-inner-application-uiAbilityContext.md#uiabilitycontextstartability). For example, when UIAbilityA needs to start UIAbilityB and transfer some data to UIAbilityB, it can use the **want** parameter in **startAbility()** to transfer the data. **Figure 1** Want usage - -![usage-of-want](figures/usage-of-want.png) +![usage-of-want](figures/usage-of-want.png) ## Types of Want -- **Explicit Want**: A type of Want with **abilityName** and **bundleName** specified when starting an ability. - When there is an explicit object to process the request, the target ability can be started by specifying the bundle name and ability name in Want. Explicit Want is usually used to start a known ability. +- **Explicit Want**: If **abilityName** and **bundleName** are specified when starting an ability, explicit Want is used. + Explicit Want is usually used to start a known target ability in the same application. The target ability is started by specifying **bundleName** of the application where the target ability is located and **abilityName** in the **Want** object. When there is an explicit object to process the request, explicit Want is a simple and effective way to start the target ability. ```ts let wantInfo = { @@ -23,8 +22,8 @@ } ``` -- **Implicit Want**: A type of Want with **abilityName** unspecified when starting the ability. - Implicit Want can be used when the object used to process the request is unclear and the current application wants to use a capability (defined by the [skills tag](../quick-start/module-configuration-file.md#skills)) provided by another application. For example, you can use implicit Want to describe a request for opening a link, since you do not care which application is used to open the link. The system matches all applications that support the request. +- **Implicit Want**: If **abilityName** is not specified when starting the ability, implicit Want is used. + Implicit Want can be used when the object used to process the request is unclear and the current application wants to use a capability (defined by the [skills tag](../quick-start/module-configuration-file.md#skills)) provided by another application. The system matches all applications that declare to support the capability. For example, for a link open request, the system matches all applications that support the request and provides the available ones for users to select. ```ts diff --git a/en/readme/test.md b/en/readme/test.md index d4410e5ab0..d5c6a903b4 100644 --- a/en/readme/test.md +++ b/en/readme/test.md @@ -58,7 +58,9 @@ subsystem # Subsystem │ ... ``` -> **NOTE**
Test cases are classified into common test cases and device-specific test cases. You are advised to place common test cases in the **common** directory and device-specific test cases in the directories of the related devices. +> **NOTE** +> +> Test cases are classified into common test cases and device-specific test cases. You are advised to place common test cases in the **common** directory and device-specific test cases in the directories of the related devices. ### Writing Test Cases This test framework supports test cases written in multiple programming languages and provides different templates for different languages. @@ -68,7 +70,8 @@ This test framework supports test cases written in multiple programming language - Naming rules for source files The source file name of test cases must be the same as that of the test suite. The file names must use lowercase letters and in the [Function]\_[Sub-function]\_**test** format. More specific sub-functions can be added as required. -Example: + Example: + ``` calculator_sub_test.cpp ``` @@ -127,7 +130,7 @@ Example: The procedure is as follows: 1. Add comment information to the test case file header. - Enter the header comment in the standard format. For details, see [Code Specifications] (https://gitee.com/openharmony/docs/blob/master/en/contribute/code-contribution.md). + Enter the header comment in the standard format. For details, see [Code Specifications](https://gitee.com/openharmony/docs/blob/master/en/contribute/code-contribution.md). 2. Add the test framework header file and namespace. ``` @@ -135,14 +138,12 @@ Example: using namespace testing::ext; ``` - - 3. Add the header file of the test class. - ``` + 3. Add the header file of the test class. + ``` #include "calculator.h" ``` - 4. Define the test suite (test class). - ``` + ``` class CalculatorSubTest : public testing::Test { public: static void SetUpTestCase(void); @@ -169,60 +170,55 @@ Example: void CalculatorSubTest::TearDown(void) { // Set a teardown function, which will be called after each test case. - } - ``` - > **NOTE**
When defining a test suite, ensure that the test suite name is the same as the target to build and uses the upper camel case style. + } + ``` + > **NOTE** + > + > When defining a test suite, ensure that the test suite name is the same as the target to build and uses the upper camel case style. 5. Add implementation of the test cases, including test case comments and logic. - - ``` - /** - - * @tc.name: integer_sub_001 - - * @tc.desc: Verify the sub function. - - * @tc.type: FUNC - - * @tc.require: Issue Number - */ - HWTEST_F(CalculatorSubTest, integer_sub_001, TestSize.Level1) - { - // Step 1 Call the function to obtain the test result. - int actual = Sub(4, 0); - - // Step 2 Use an assertion to compare the obtained result with the expected result. - EXPECT_EQ(4, actual); - } - ``` + ``` + /** + * @tc.name: integer_sub_001 + * @tc.desc: Verify the sub function. + * @tc.type: FUNC + * @tc.require: Issue Number + */ + HWTEST_F(CalculatorSubTest, integer_sub_001, TestSize.Level1) + { + // Step 1 Call the function to obtain the test result. + int actual = Sub(4，0)； + + // Step 2 Use an assertion to compare the obtained result with the expected result. + EXPECT_EQ(4, actual); + } + ``` The following test case templates are provided for your reference. - | Template | Description | + | Template | Description | | --------------- | ------------------------------------------------------------ | - | HWTEST(A,B,C) | Use this template if the test case execution does not depend on setup or teardown. | + | HWTEST(A,B,C) | Use this template if the test case execution does not depend on setup or teardown. | | HWTEST_F(A,B,C) | Use this template if the test case execution (excluding parameters) depends on setup and teardown. | | HWTEST_P(A,B,C) | Use this template if the test case execution (including parameters) depends on setup and teardown. | - In the template names: + In the template names: - *A* indicates the test suite name. - + - *B* indicates the test case name, which is in the *Function*\_*No.* format. The *No.* is a three-digit number starting from **001**. - *C* indicates the test case level. There are five test case levels: guard-control level 0 and non-guard-control level 1 to level 4. Of levels 1 to 4, a smaller value indicates a more important function verified by the test case. - - > **NOTE** > > - The expected result of each test case must have an assertion. - >- The test case level must be specified. + > - The test case level must be specified. > - It is recommended that the test be implemented step by step according to the template. - >- The comment must contain the test case name, description, type, and requirement number, which are in the @tc.*xxx*: *value* format. The test case description must be in the @tc.xxx format. The test case type @tc.type can be any of the following: - + > - The comment must contain the test case name, description, type, and requirement number, which are in the @tc.*xxx*: *value* format. The test case description must be in the @tc.xxx format. The test case type @tc.type can be any of the following: + | Test Case Type | Code | - | ---------------- | ---- | + | ---------------- | ---- | | Function test | FUNC | | Performance test | PERF | | Reliability test | RELI | @@ -339,7 +335,7 @@ When a test case is executed, the test framework searches for the build file of The following provides templates for different languages for your reference. - **Test case build file example (C++)** - ``` + ```c++ import("//build/test.gni") @@ -386,8 +382,10 @@ The following provides templates for different languages for your reference. ``` module_output_path = "subsystem_examples/calculator" ``` - > **NOTE**
The output path is ***Part name*/*Module name***. - + > **NOTE** + > + > The output path is ***Part name*/*Module name***. + 4. Configure the directories for dependencies. ``` @@ -397,7 +395,9 @@ The following provides templates for different languages for your reference. include_dirs = [ "../../../include" ] } ``` - > **NOTE**
Generally, the dependency directories are configured here and directly referenced in the build script of the test case. + > **NOTE** + > + > Generally, the dependency directories are configured here and directly referenced in the build script of the test case. 5. Set the output build file for the test cases. @@ -418,8 +418,8 @@ The following provides templates for different languages for your reference. ] sources += [ "calculator_sub_test.cpp" ] configs = [ ":module_private_config" ] - deps = [ "//third_party/googletest:gtest_main" ] - } + deps = [ "//third_party/googletest:gtest_main" ] + } ``` > **NOTE** @@ -429,27 +429,25 @@ The following provides templates for different languages for your reference. > - **ohos_systemtest**: system test > - **ohos_performancetest**: performance test > - **ohos_securitytest**: security test - > - **ohos_reliabilitytest**: reliability test + > - **ohos_reliabilitytest**: reliability test > - **ohos_distributedtest**: distributed test - + 7. Group the test case files by test type. - - ``` - group("unittest") { - testonly = true - deps = [":CalculatorSubTest"] - } - ``` + + ``` + group("unittest") { + testonly = true + deps = [":CalculatorSubTest"] + } + ``` > **NOTE** > > Grouping test cses by test type allows you to execute a specific type of test cases when required. - ​ - -- **Test case build file example (JavaScript)** +- **Test case build file example (JavaScript)** ​ - ``` + ```javascript import("//build/test.gni") @@ -484,7 +482,9 @@ The following provides templates for different languages for your reference. ``` module_output_path = "subsystem_examples/app_info" ``` - > **NOTE**
The output path is ***Part name*/*Module name***. + > **NOTE** + > + > The output path is ***Part name*/*Module name***. 4. Set the output build file for the test cases. @@ -492,9 +492,10 @@ The following provides templates for different languages for your reference. ohos_js_unittest("GetAppInfoJsTest") { } ``` - > **NOTE**
- >- Use the **ohos\_js\_unittest** template to define the JavaScript test suite. Pay attention to the difference between JavaScript and C++. - >- The file generated for the JavaScript test suite must be in .hap format and named after the test suite name defined here. The test suite name must end with **JsTest**. + > **NOTE** + > + > - Use the **ohos\_js\_unittest** template to define the JavaScript test suite. Pay attention to the difference between JavaScript and C++. + > - The file generated for the JavaScript test suite must be in .hap format and named after the test suite name defined here. The test suite name must end with **JsTest**. 5. Configure the **config.json** file and signature file, which are mandatory. @@ -576,7 +577,9 @@ The following provides templates for different languages for your reference. deps = [ ":GetAppInfoJsTest" ] } ``` - > **NOTE**
Grouping test cases by test type allows you to execute a specific type of test cases when required. + > **NOTE** + > + > Grouping test cases by test type allows you to execute a specific type of test cases when required. #### Configuring ohos.build @@ -597,7 +600,9 @@ Configure the part build file to associate with specific test cases. ] } ``` -> **NOTE**
**test_list** contains the test cases of the corresponding module. +> **NOTE** +> +> **test_list** contains the test cases of the corresponding module. ### Configuring Test Case Resources Test case resources include external file resources, such as image files, video files, and third-party libraries, required for test case execution. @@ -623,7 +628,8 @@ Perform the following steps: resource_config_file = "//system/subsystem/partA/test/resource/calculator/ohos_test.xml" } ``` - >**NOTE**
+ >**NOTE** + > >- **target_name** indicates the test suite name defined in the **BUILD.gn** file in the **test** directory. >- **preparer** indicates the action to perform before the test suite is executed. >- **src="res"** indicates that the test resources are in the **resource** directory under the **test** directory. @@ -678,7 +684,9 @@ Before executing test cases, you need to modify the configuration based on the d ``` ->**NOTE**
If HDC is connected to the device before the test cases are executed, you only need to configure the device IP address and port number, and retain the default settings for other parameters. +>**NOTE** +> +>If HDC is connected to the device before the test cases are executed, you only need to configure the device IP address and port number, and retain the default settings for other parameters. ### Executing Test Cases on Windows #### Building Test Cases @@ -689,16 +697,19 @@ Test cases cannot be built on Windows. You need to run the following command to ``` When the build is complete, the test cases are automatically saved in **out/hispark_taurus/packages/phone/images/tests**. ->**NOTE**
In the command, **hispark_taurus_standard** indicates the product supported by the current version, and **make_test** indicates all test cases. You can set the build options based on requirements:
-> - --**product-name**: specifies the name of the product to build. It is mandatory. -> - --**build-target**: specifies the target to build. It is optional. +>**NOTE** +> +>In the command, **hispark_taurus_standard** indicates the product supported by the current version, and **make_test** indicates all test cases. You can set the build options based on requirements:
+> +>- --**product-name**: specifies the name of the product to build. It is mandatory. +>- --**build-target**: specifies the target to build. It is optional. #### Setting Up the Execution Environment 1. On Windows, create the **Test** directory in the test framework and then create the **testcase** directory in the **Test** directory. 2. Copy **developertest** and **xdevice** from the Linux environment to the **Test** directory on Windows, and copy the test cases to the **testcase** directory. - > **NOTE**
+ > **NOTE** > > Port the test framework and test cases from the Linux environment to the Windows environment for subsequent execution. 3. Modify the **user_config.xml** file. @@ -712,7 +723,9 @@ When the build is complete, the test cases are automatically saved in **out/hisp D:\Test\testcase\tests ``` - >**NOTE**
`` indicates whether to build test cases. `` indicates the path for searching for test cases. + >**NOTE** + > + >`` indicates whether to build test cases. `` indicates the path for searching for test cases. #### Executing Test Cases 1. Start the test framework. @@ -746,13 +759,17 @@ To enable test cases to be executed on a remote Linux server or a Linux VM, map hdc_std kill hdc_std -m -s 0.0.0.0:8710 ``` - >**NOTE**
The IP address and port number are default values. + >**NOTE** + > + >The IP address and port number are default values. 2. On the HDC client, run the following command: ``` hdc_std -s xx.xx.xx.xx:8710 list targets ``` - >**NOTE**
Enter the IP address of the device to test. + >**NOTE** + > + >Enter the IP address of the device to test. #### Executing Test Cases 1. Start the test framework. @@ -787,7 +804,9 @@ You can obtain the test result in the following directory: ``` test/developertest/reports/xxxx_xx_xx_xx_xx_xx ``` ->**NOTE**
The folder for test reports is automatically generated. +>**NOTE** +> +>The folder for test reports is automatically generated. The folder contains the following files: | Type| Description| -- GitLab