From fceb9375256c4c0d816211da602460222c296322 Mon Sep 17 00:00:00 2001 From: Gloria Date: Wed, 21 Dec 2022 16:43:35 +0800 Subject: [PATCH] Update docs against 12380 Signed-off-by: wusongqing --- .../Readme-EN.md | 3 + .../ability-assistant-guidelines.md | 8 +- .../ability-brief.md | 0 .../ability-delegator.md | 10 +- .../context-userguide.md | 12 +- .../continuationmanager.md | 2 +- .../ability-deprecated/fa-brief.md | 43 ++ .../fa-dataability.md | 2 +- .../fa-formability.md | 2 +- .../fa-pageability.md | 2 +- .../ability-deprecated/fa-serviceability.md | 335 +++++++++++++++ .../AbilityComponentInstanceMission.png | Bin .../figures/ExtensionAbility.png | Bin .../figures/aa-dump-a.PNG | Bin .../figures/aa-dump-i.PNG | Bin .../figures/aa-dump-l.PNG | Bin .../figures/contextIntroduction.png | Bin .../figures/continuation-info.png | Bin .../figures/continuationManager.png | Bin .../figures/fa-dataability-uri.png | Bin .../figures/fa-form-example.png | Bin .../figures/fa-pageAbility-lifecycle.png | Bin .../figures/fa-threading-model.png | Bin .../figures/favsstage.png | Bin .../figures/lifecycle.png | Bin .../figures/page-ability-lifecycle.png | Bin .../figures/stage-call.png | Bin .../figures/stageabilitylifecyclecallback.png | Bin .../figures/stageconcept.png | Bin .../figures/stagedesign.png | Bin .../figures/stageprocessmodel.png | Bin .../public_sys-resources/icon-caution.gif | Bin .../public_sys-resources/icon-danger.gif | Bin .../public_sys-resources/icon-note.gif | Bin .../public_sys-resources/icon-notice.gif | Bin .../public_sys-resources/icon-tip.gif | Bin .../public_sys-resources/icon-warning.gif | Bin .../stage-ability-continuation.md | 6 +- .../stage-ability.md | 6 +- .../ability-deprecated/stage-brief.md | 114 +++++ .../stage-call.md | 2 +- .../stage-formextension.md | 8 +- .../stage-serviceextension.md | 3 +- .../wantagent.md | 2 - en/application-dev/ability/fa-brief.md | 35 -- .../ability/fa-serviceability.md | 400 ------------------ en/application-dev/ability/stage-brief.md | 105 ----- .../application-models/Readme-EN.md | 2 + 48 files changed, 531 insertions(+), 571 deletions(-) rename en/application-dev/{ability => ability-deprecated}/Readme-EN.md (88%) rename en/application-dev/{ability => ability-deprecated}/ability-assistant-guidelines.md (90%) rename en/application-dev/{ability => ability-deprecated}/ability-brief.md (100%) rename en/application-dev/{ability => ability-deprecated}/ability-delegator.md (96%) rename en/application-dev/{ability => ability-deprecated}/context-userguide.md (94%) rename en/application-dev/{ability => ability-deprecated}/continuationmanager.md (99%) create mode 100644 en/application-dev/ability-deprecated/fa-brief.md rename en/application-dev/{ability => ability-deprecated}/fa-dataability.md (99%) rename en/application-dev/{ability => ability-deprecated}/fa-formability.md (99%) rename en/application-dev/{ability => ability-deprecated}/fa-pageability.md (99%) create mode 100644 en/application-dev/ability-deprecated/fa-serviceability.md rename en/application-dev/{ability => ability-deprecated}/figures/AbilityComponentInstanceMission.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/ExtensionAbility.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/aa-dump-a.PNG (100%) rename en/application-dev/{ability => ability-deprecated}/figures/aa-dump-i.PNG (100%) rename en/application-dev/{ability => ability-deprecated}/figures/aa-dump-l.PNG (100%) rename en/application-dev/{ability => ability-deprecated}/figures/contextIntroduction.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/continuation-info.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/continuationManager.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/fa-dataability-uri.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/fa-form-example.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/fa-pageAbility-lifecycle.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/fa-threading-model.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/favsstage.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/lifecycle.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/page-ability-lifecycle.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/stage-call.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/stageabilitylifecyclecallback.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/stageconcept.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/stagedesign.png (100%) rename en/application-dev/{ability => ability-deprecated}/figures/stageprocessmodel.png (100%) rename en/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-caution.gif (100%) rename en/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-danger.gif (100%) rename en/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-note.gif (100%) rename en/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-notice.gif (100%) rename en/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-tip.gif (100%) rename en/application-dev/{ability => ability-deprecated}/public_sys-resources/icon-warning.gif (100%) rename en/application-dev/{ability => ability-deprecated}/stage-ability-continuation.md (98%) rename en/application-dev/{ability => ability-deprecated}/stage-ability.md (98%) create mode 100644 en/application-dev/ability-deprecated/stage-brief.md rename en/application-dev/{ability => ability-deprecated}/stage-call.md (99%) rename en/application-dev/{ability => ability-deprecated}/stage-formextension.md (98%) rename en/application-dev/{ability => ability-deprecated}/stage-serviceextension.md (99%) rename en/application-dev/{ability => ability-deprecated}/wantagent.md (99%) delete mode 100644 en/application-dev/ability/fa-brief.md delete mode 100644 en/application-dev/ability/fa-serviceability.md delete mode 100644 en/application-dev/ability/stage-brief.md create mode 100644 en/application-dev/application-models/Readme-EN.md diff --git a/en/application-dev/ability/Readme-EN.md b/en/application-dev/ability-deprecated/Readme-EN.md similarity index 88% rename from en/application-dev/ability/Readme-EN.md rename to en/application-dev/ability-deprecated/Readme-EN.md index 6a11f497d3..5c803a4755 100644 --- a/en/application-dev/ability/Readme-EN.md +++ b/en/application-dev/ability-deprecated/Readme-EN.md @@ -1,5 +1,8 @@ # Ability Development +> **NOTE**
+> This folder is deprecated. Read [Application Models](../application-models/Readme-EN.md) instead. + - [Ability Framework Overview](ability-brief.md) - [Context Usage](context-userguide.md) - FA Model diff --git a/en/application-dev/ability/ability-assistant-guidelines.md b/en/application-dev/ability-deprecated/ability-assistant-guidelines.md similarity index 90% rename from en/application-dev/ability/ability-assistant-guidelines.md rename to en/application-dev/ability-deprecated/ability-assistant-guidelines.md index 4d7b0edb2b..d2e45f5d54 100644 --- a/en/application-dev/ability/ability-assistant-guidelines.md +++ b/en/application-dev/ability-deprecated/ability-assistant-guidelines.md @@ -73,10 +73,10 @@ The ability assistant enables you to start applications, atomic services, and te | -a/--all | - | Prints ability information in all missions. | | -l/--mission-list | type (All logs are printed if this parameter is left unspecified.)| Prints mission stack information.
The following values are available for **type**:
- NORMAL
- DEFAULT_STANDARD
- DEFAULT_SINGLE
- LAUNCHER | | -e/--extension | elementName | Prints extended component information. | - | -u/--userId | UserId | Prints stack information of a specified user ID. This parameter must be used together with other parameters.
Example commands: aa **dump -a -u 100** and **aa dump -d -u 100**. | - | -d/--data | - | Prints Data ability information. | - | -i/--ability | AbilityRecord ID | Prints detailed information about a specified ability. | - | -c/--client | - | Prints detailed ability information. This parameter must be used together with other parameters.
Example commands: **aa dump -a -c** and **aa dump -i 21 -c**. | + | -u/--userId | UserId | Prints stack information of a specified user ID. This parameter must be used together with other parameters.
Example commands: aa **dump -a -u 100** and **aa dump -d -u 100**.| + | -d/--data | - | Prints Data ability information. | + | -i/--ability | AbilityRecord ID | Prints detailed information about a specified ability. | + | -c/--client | - | Prints detailed ability information. This parameter must be used together with other parameters.
Example commands: **aa dump -a -c** and **aa dump -i 21 -c**.| **Method** diff --git a/en/application-dev/ability/ability-brief.md b/en/application-dev/ability-deprecated/ability-brief.md similarity index 100% rename from en/application-dev/ability/ability-brief.md rename to en/application-dev/ability-deprecated/ability-brief.md diff --git a/en/application-dev/ability/ability-delegator.md b/en/application-dev/ability-deprecated/ability-delegator.md similarity index 96% rename from en/application-dev/ability/ability-delegator.md rename to en/application-dev/ability-deprecated/ability-delegator.md index 5fd0293efd..b32d472176 100644 --- a/en/application-dev/ability/ability-delegator.md +++ b/en/application-dev/ability-deprecated/ability-delegator.md @@ -46,19 +46,19 @@ For details about how to use DevEco Studio to start the test framework, see [Ope ## Introduction to TestRunner -**TestRunner** is the entry class of the test framework test process. When the test process is started, the system calls related APIs in **TestRunner**. You need to inherit this class and override the **onPrepare** and **onRun** APIs. When creating an application template, DevEco Studio initializes the default **TestRunner** and starts the default **TestAbility** in the **onRun** API. You can modify the test code of **TestAbility** or override **onPrepare** and **onRun** in **TestRunner** to implement your own test code. For details, see [TestRunner](../reference/apis/js-apis-testRunner.md). +**TestRunner** is the entry class of the test framework test process. When the test process is started, the system calls related APIs in **TestRunner**. You need to inherit this class and override the **onPrepare** and **onRun** APIs. When creating an application template, DevEco Studio initializes the default **TestRunner** and starts the default **TestAbility** in the **onRun** API. You can modify the test code of **TestAbility** or override **onPrepare** and **onRun** in **TestRunner** to implement your own test code. For details, see [TestRunner](../reference/apis/js-apis-application-testRunner.md). ## Introduction to AbilityDelegatorRegistry -**AbilityDelegatorRegistry** is the **AbilityDelegator** repository class provided by the test framework. You can use **AbilityDelegatorRegistry** to obtain an **AbilityDelegator** instance and the input and generated parameters **AbilityDelegatorArgs** during the test. You can use **AbilityDelegator** to invoke the function set provided by the test framework for testing and verification. For details, see [AbilityDelegatorRegistry](../reference/apis/js-apis-abilityDelegatorRegistry.md). +**AbilityDelegatorRegistry** is the **AbilityDelegator** repository class provided by the test framework. You can use **AbilityDelegatorRegistry** to obtain an **AbilityDelegator** instance and the input and generated parameters **AbilityDelegatorArgs** during the test. You can use **AbilityDelegator** to invoke the function set provided by the test framework for testing and verification. For details, see [AbilityDelegatorRegistry](../reference/apis/js-apis-application-abilityDelegatorRegistry.md). ## Introduction to AbilityDelegatorArgs -**AbilityDelegatorArgs** is a test parameter class provided by the test framework. You can use **AbilityDelegatorArgs** to obtain the parameters passed and generated during the test. For details, see [AbilityDelegatorArgs](../reference/apis/js-apis-application-abilityDelegatorArgs.md). +**AbilityDelegatorArgs** is a test parameter class provided by the test framework. You can use **AbilityDelegatorArgs** to obtain the parameters passed and generated during the test. For details, see [AbilityDelegatorArgs](../reference/apis/js-apis-inner-application-abilityDelegatorArgs.md). ## Introduction to AbilityMonitor -**AbilityMonitor** is provided by the test framework for binding to and listening for abilities. You can use **AbilityMonitor** to bind to an **Ability** instance and add **AbilityMonitor** to the listening list. When **AbilityMonitor** is bound to an ability, the creation and lifecycle changes of the ability will trigger the related callback in **AbilityMonitor**. You can test and verify the ability in these callbacks. For details, see [AbilityMonitor](../reference/apis/js-apis-application-abilityMonitor.md). +**AbilityMonitor** is provided by the test framework for binding to and listening for abilities. You can use **AbilityMonitor** to bind to an **Ability** instance and add **AbilityMonitor** to the listening list. When **AbilityMonitor** is bound to an ability, the creation and lifecycle changes of the ability will trigger the related callback in **AbilityMonitor**. You can test and verify the ability in these callbacks. For details, see [AbilityMonitor](../reference/apis/js-apis-inner-application-abilityMonitor.md). **Example** @@ -131,7 +131,7 @@ abilityDelegator.startAbility(want, (err, data) => { ### Scheduling the Ability Lifecycle -**AbilityDelegator** provides APIs to display and schedule the ability lifecycle and supports the foreground and background. It works with **AbilityMonitor** to listen for the ability lifecycle. For details, see [AbilityDelegator](../reference/apis/js-apis-application-abilityDelegator.md). +**AbilityDelegator** provides APIs to display and schedule the ability lifecycle and supports the foreground and background. It works with **AbilityMonitor** to listen for the ability lifecycle. For details, see [AbilityDelegator](../reference/apis/js-apis-inner-application-abilityDelegator.md). ### Running a Shell Command diff --git a/en/application-dev/ability/context-userguide.md b/en/application-dev/ability-deprecated/context-userguide.md similarity index 94% rename from en/application-dev/ability/context-userguide.md rename to en/application-dev/ability-deprecated/context-userguide.md index 17fd6b5eb7..ac65d92cb9 100644 --- a/en/application-dev/ability/context-userguide.md +++ b/en/application-dev/ability-deprecated/context-userguide.md @@ -4,12 +4,12 @@ **Context** provides the capability of obtaining contextual information of an application. -The OpenHarmony application framework has two models: Feature Ability (FA) model and stage model. Correspondingly, there are two sets of context mechanisms. **application/BaseContext** is a common context base class. It uses the **stageMode** attribute to specify whether the context is used for the stage model. - -- FA model - - Only the methods in **app/Context** can be used for the context in the FA model. Both the application-level context and ability-level context are instances of this type. If an ability-level method is invoked in the application-level context, an error occurs. Therefore, you must pay attention to the actual meaning of the **Context** instance. + The OpenHarmony application framework has two models: Feature Ability (FA) model and stage model. Correspondingly, there are two sets of context mechanisms. **application/BaseContext** is a common context base class. It uses the **stageMode** attribute to specify whether the context is used for the stage model. +- FA model + +Only the methods in **app/Context** can be used for the context in the FA model. Both the application-level context and ability-level context are instances of this type. If an ability-level method is invoked in the application-level context, an error occurs. Therefore, you must pay attention to the actual meaning of the **Context** instance. + - Stage model The stage model has the following types of contexts: **application/Context**, **application/ApplicationContext**, **application/AbilityStageContext**, **application/ExtensionContext**, **application/AbilityContext**, and **application/FormExtensionContext**. For details about these contexts and how to use them, see [Context in the Stage Model](#context-in-the-stage-model). @@ -239,7 +239,7 @@ export default class MainAbility extends Ability { ### application/FormExtensionContext -For details, see [FormExtensionContext](../reference/apis/js-apis-formextensioncontext.md). +For details, see [FormExtensionContext](../reference/apis/js-apis-inner-application-formExtensionContext.md). ### Obtaining the Context on an ArkTS Page diff --git a/en/application-dev/ability/continuationmanager.md b/en/application-dev/ability-deprecated/continuationmanager.md similarity index 99% rename from en/application-dev/ability/continuationmanager.md rename to en/application-dev/ability-deprecated/continuationmanager.md index 20c272e75a..0ba79f95ac 100644 --- a/en/application-dev/ability/continuationmanager.md +++ b/en/application-dev/ability-deprecated/continuationmanager.md @@ -188,7 +188,7 @@ As the entry of the ability continuation capability, **continuationManager** is } ``` - The preceding multi-device collaboration operation is performed across devices in the stage model. For details about this operation in the FA model, see [Page Ability Development](https://gitee.com/openharmony/docs/blob/master/en/application-dev/ability/fa-pageability.md). + The preceding multi-device collaboration operation is performed across devices in the stage model. For details about this operation in the FA model, see [Page Ability Development](fa-pageability.md). You can also instruct the device selection module to update the device connection state. The sample code is as follows: diff --git a/en/application-dev/ability-deprecated/fa-brief.md b/en/application-dev/ability-deprecated/fa-brief.md new file mode 100644 index 0000000000..5ad79cfe25 --- /dev/null +++ b/en/application-dev/ability-deprecated/fa-brief.md @@ -0,0 +1,43 @@ +# FA Model Overview + +## Overall Architecture + +Ability is the entry for application development in OpenHarmony. + +The core of ability development is the processing on ability lifecycle callbacks. + +The Feature Ability (FA) model can be used only for application development using API version 8 and earlier versions. In this model, there are PageAbility, ServiceAbility, DataAbility, and FormAbility. +- PageAbility implements the ArkUI and provides the capability for interacting with users. +- ServiceAbility does not have a UI. It runs in the background and provides custom services for other abilities to invoke. +- DataAbility does not have a UI. It runs in the background and enables other abilities to insert, delete, and query data. +- FormAbility is used to implement widgets, a new UI display form available on OpenHarmony devices. + +> Note: Starting from API version 9, the stage model is recommended for application development. + +## Lifecycle + +Among all abilities, PageAbility has the most complex lifecycle, because it has a UI and acts as a touchpoint for interacting with users. +**The following figure shows the lifecycle of PageAbility.** + +![fa-pageAbility-lifecycle](figures/fa-pageAbility-lifecycle.png) + +The other abilities do not involve foreground and background switch or the **onShow** and **onHide** callbacks. +You can override the lifecycle callbacks in **app.js** or **app.ets** to process application logic. + +The **app.js** file provides only the **onCreate** and **onDestroy** callbacks, and the **app.ets** file provides the callbacks covering the entire lifecycle. + +## Process and Thread Model + +Each application runs in a process. In the FA model, each ability runs in an independent VM. + +When an ability is started, an application process as well as a thread for this ability is created. For an application that has multiple abilities, each ability runs in an independent thread. In the FA model, each ability is bound to an independent VM instance. In this way, abilities are isolated from each other. + +![fa-threading-model](figures/fa-threading-model.png) + +## Application Package Structure + +For details about the project directory structure of the FA model, see [OpenHarmony Project Overview](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-project-overview-0000001218440650#section4154183910141). + +For details about how to configure the application package structure of the FA model, see [Application Package Structure Configuration File](../quick-start/application-configuration-file-overview-fa.md). + + \ No newline at end of file diff --git a/en/application-dev/ability/fa-dataability.md b/en/application-dev/ability-deprecated/fa-dataability.md similarity index 99% rename from en/application-dev/ability/fa-dataability.md rename to en/application-dev/ability-deprecated/fa-dataability.md index e3fd895c2a..8d94e8f225 100644 --- a/en/application-dev/ability/fa-dataability.md +++ b/en/application-dev/ability-deprecated/fa-dataability.md @@ -148,7 +148,7 @@ The basic dependency packages include: 1. Create a Data ability helper. - For details about the APIs provided by **DataAbilityHelper**, see [DataAbilityHelper Module](../reference/apis/js-apis-dataAbilityHelper.md). + For details about the APIs provided by **DataAbilityHelper**, see [DataAbilityHelper Module](../reference/apis/js-apis-inner-ability-dataAbilityHelper.md). ```js // Different from the URI defined in the config.json file, the URI passed in the parameter has an extra slash (/), because there is a DeviceID parameter between the second and the third slash (/). import featureAbility from '@ohos.ability.featureAbility' diff --git a/en/application-dev/ability/fa-formability.md b/en/application-dev/ability-deprecated/fa-formability.md similarity index 99% rename from en/application-dev/ability/fa-formability.md rename to en/application-dev/ability-deprecated/fa-formability.md index 377d5e4b8f..a91ca4b9ba 100644 --- a/en/application-dev/ability/fa-formability.md +++ b/en/application-dev/ability-deprecated/fa-formability.md @@ -43,7 +43,7 @@ The table below describes the **LifecycleForm** APIs, which represent the lifecy | onDestroy(formId: string): void | Called to notify the widget provider that a widget has been destroyed. | | onAcquireFormState?(want: Want): formInfo.FormState | Called to instruct the widget provider to receive the status query result of a widget. | -The table below describes the **FormProvider** APIs. For details, see [FormProvider](../reference/apis/js-apis-formprovider.md). +The table below describes the **FormProvider** APIs. For details, see [FormProvider](../reference/apis/js-apis-application-formProvider.md). **Table 2** FormProvider APIs diff --git a/en/application-dev/ability/fa-pageability.md b/en/application-dev/ability-deprecated/fa-pageability.md similarity index 99% rename from en/application-dev/ability/fa-pageability.md rename to en/application-dev/ability-deprecated/fa-pageability.md index f6eb705953..2f4741b80e 100644 --- a/en/application-dev/ability/fa-pageability.md +++ b/en/application-dev/ability-deprecated/fa-pageability.md @@ -61,7 +61,7 @@ By default, **singleton** is used. | API | Description | | --------------------------------------------------- | --------------- | -| void startAbility(parameter: StartAbilityParameter) | Starts an ability. | +| void startAbility(parameter: StartAbilityParameter) | Starts an ability. | | Context getContext(): | Obtains the application context.| | void terminateSelf() | Terminates the ability. | | bool hasWindowFocus() | Checks whether the ability has focus. | diff --git a/en/application-dev/ability-deprecated/fa-serviceability.md b/en/application-dev/ability-deprecated/fa-serviceability.md new file mode 100644 index 0000000000..cf766f35f7 --- /dev/null +++ b/en/application-dev/ability-deprecated/fa-serviceability.md @@ -0,0 +1,335 @@ +# Service Ability Development + +## When to Use +A Service ability is used to run tasks in the background, such as playing music or downloading files. It does not provide a UI for user interaction. Service abilities can be started by other applications or abilities and can keep running in the background even after the user switches to another application. + +## Lifecycle APIs + +**Table 1** Service ability lifecycle APIs +|API|Description| +|:------|:------| +|onStart?(): void|Called to initialize a Service ability when the Service ability is being created. This callback is invoked only once in the entire lifecycle of a Service ability.| +|onCommand?(want: Want, startId: number): void|Called every time a Service ability is created on the client. You can collect calling statistics and perform initialization operations in this callback.| +|onConnect?(want: Want): rpc.RemoteObject|Called when another ability is connected to the Service ability.| +|onDisconnect?(want: Want): void|Called when another ability is disconnected from the Service ability.| +|onStop?(): void|Called when the Service ability is being destroyed. You should override this callback for your Service ability to clear its resources, such as threads and registered listeners.| + +The differences between **onCommand()** and **onConnect()** are as follows: + - The **onCommand()** callback is triggered each time the client starts the Service ability by calling **startAbility** or **startAbilityForResult**. + - The **onConnect()** callback is triggered each time the client establishes a new connection with the Service ability by calling **connectAbility**. + +## How to Develop + +### Creating and Registering a Service Ability + +1. Override the Service ability-related lifecycle callbacks to implement your own logic for processing interaction requests. + + + + ```ts + export default { + onStart() { + console.log('ServiceAbility onStart'); + }, + onCommand(want, startId) { + console.log('ServiceAbility onCommand'); + }, + onConnect(want) { + console.log('ServiceAbility OnConnect'); + // Below lists the implementation of ServiceAbilityStub. + return new ServiceAbilityStub('test'); + }, + onDisconnect(want) { + console.log('ServiceAbility OnDisConnect'); + }, + onStop() { + console.log('ServiceAbility onStop'); + } + } + ``` + +2. Register a Service ability. + + Declare the Service ability in the **config.json** file by setting its **type** attribute to **service**. + + ```json + { + "module": { + "abilities": [ + { + "name": ".ServiceAbility", + "type": "service", + "visible": true + ... + } + ] + ... + } + ... + } + ``` + + + +### Starting a Service Ability + +The **Ability** class provides the **startAbility()** API for you to start another Service ability by passing a **Want** object. + +To set information about the target Service ability, you can first construct a **Want** object with the **bundleName** and **abilityName** parameters specified. + +- **bundleName** specifies the bundle name of the target application. +- **abilityName** specifies the target ability name. + +The following code snippet shows how to start a Service ability running on the local device: + +```ts +import featureAbility from '@ohos.ability.featureAbility' + +featureAbility.startAbility( + { + want: + { + bundleName: "com.jstest.service", + abilityName: "com.jstest.service.ServiceAbility" + } + } +).then((err) => { + console.log("startService success"); +}).catch (err => { + console.log("startService FAILED"); +}); +``` + +In the preceding code, the **startAbility()** API is used to start the Service ability. +- If the Service ability is not running, the system initializes the Service ability, and calls **onStart()** and **onCommand()** on the Service ability in sequence. +- If the Service ability is running, the system directly calls **onCommand()** on the Service ability. + +The following code snippet shows how to start a Service ability running on the remote device. For details, see [Connecting to a Remote Service Ability](#connecting-to-a-remote-service-ability). + +```ts +import featureAbility from '@ohos.ability.featureAbility' + +featureAbility.startAbility( + { + want: + { + deviceId: remoteDeviceId, // Remote device ID. + bundleName: "com.jstest.service", + abilityName: "com.jstest.service.ServiceAbility" + } + } +).then((err) => { + console.log("startService success"); +}).catch (err => { + console.log("startService FAILED"); +}); +``` + + +### Stopping a Service Ability + + In normal cases, a Service ability can be stopped by itself or by the system. + - The Service ability can call **particleAbility.terminateSelf()** to stop itself. + - If the application process where the Service ability is located exits, the Service ability is reclaimed along with the process. + - If the Service ability is only accessed through **connectAbility()** (the **onCommand()** callback has never been triggered), the system stops the Service ability when the last connection to the Service ability is disconnected. + +### Connecting to a Local Service Ability + +If a Service ability wants to interact with a Page ability or a Service ability in another application, you must first create a connection. A Service ability allows other abilities to connect to it through **connectAbility()**. + + +You can use either of the following methods to connect to a Service ability: + +1. Using the IDL to automatically generate code + + Use OpenHarmony Interface Definition Language (IDL) to automatically generate the corresponding client, server, and **IRemoteObject** code. For details, see [Development Using TS](../IDL/idl-guidelines.md#development-using-ts). + +2. Writing code in the corresponding file + + When using **connectAbility()**, pass the **Want** and **ConnectOptions** objects of the target Service ability, where **ConnectOptions** encapsulates the following three callbacks that need to be implemented. + - **onConnect()**: callback used for processing when the Service ability is connected. + - **onDisconnect()**: callback used for processing when the Service ability is disconnected. + - **onFailed()**: callback used for processing when the connection to the Service ability fails. + + The following code snippet shows how to implement the callbacks: + + ```ts + import prompt from '@system.prompt' + + var option = { + onConnect: function onConnectCallback(element, proxy) { + console.log(`onConnectLocalService onConnectDone`); + if (proxy === null) { + prompt.showToast({ + message: "Connect service failed" + }); + return; + } + // After obtaining the proxy of the Service ability, the calling ability can communicate with the Service ability. + let data = rpc.MessageParcel.create(); + let reply = rpc.MessageParcel.create(); + let option = new rpc.MessageOption(); + data.writeString("InuptString"); + proxy.sendRequest(0, data, reply, option); + prompt.showToast({ + message: "Connect service success" + }); + }, + onDisconnect: function onDisconnectCallback(element) { + console.log(`onConnectLocalService onDisconnectDone element:${element}`); + prompt.showToast({ + message: "Disconnect service success" + }); + }, + onFailed: function onFailedCallback(code) { + console.log(`onConnectLocalService onFailed errCode:${code}`); + prompt.showToast({ + message: "Connect local service onFailed" + }); + } + }; + ``` + + The following code snippet shows how to connect to a local Service ability: + + ```ts + import featureAbility from '@ohos.ability.featureAbility' + + let want = { + bundleName: "com.jstest.service", + abilityName: "com.jstest.service.ServiceAbility" + }; + let connectId = featureAbility.connectAbility(want, option); + ``` + + When a Service ability is connected, the **onConnect()** callback is invoked and returns an **IRemoteObject** defining the proxy used for communicating with the Service ability. OpenHarmony provides the default implementation of **IRemoteObject**. You can inherit **rpc.RemoteObject** to create a custom implementation class for interaction with the Service ability. For details, see the [RPC API Reference](..\reference\apis\js-apis-rpc.md). + + The following code snippet shows how the Service ability returns itself to the calling ability: + + ```ts + import rpc from "@ohos.rpc" + + class ServiceAbilityStub extends rpc.RemoteObject { + constructor(des: any) { + if (typeof des === 'string') { + super(des); + } else { + console.log("Error, the input param is not string"); + return; + } + } + + onRemoteRequest(code: number, data: any, reply: any, option: any) { + console.log("onRemoteRequest called"); + // Execute the service logic. + if (code === 1) { + // Sort the input strings. + let string = data.readString(); + console.log(`Input string = ${string}`); + let result = Array.from(string).sort().join(''); + console.log(`Output result = ${result}`); + reply.writeString(result); + } else { + console.log(`Unknown request code`); + } + return true; + } + } + + export default { + onStart() { + console.log('ServiceAbility onStart'); + }, + onCommand(want, startId) { + console.log('ServiceAbility onCommand'); + }, + onConnect(want) { + console.log('ServiceAbility OnConnect'); + return new ServiceAbilityStub('ServiceAbilityRemoteObject'); + }, + onDisconnect(want) { + console.log('ServiceAbility OnDisConnect'); + }, + onStop() { + console.log('ServiceAbility onStop'); + } + } + ``` + +### Connecting to a Remote Service Ability + +This feature applies only to system applications. The method of creating a **ConnectOptions** object for connecting to a remote Service ability is similar to that for connecting to a local Service ability. The differences are as follows: + - The application must apply for the data synchronization permission from the user. + - **Want** of the target Service ability must contain the remote device ID. + +> **NOTE** +> +> The **getTrustedDeviceList** API of **DeviceManager** is open only to system applications. Currently, only system applications can connect to a remote Service ability. +> +> For details about the API definition, see [Device Management](..\reference\apis\js-apis-device-manager.md). + +The data synchronization permission is required in the cross-device scenario. Configure the permission in the **config.json** file. + +```json +{ + ... + "module": { + ... + "reqPermissions": [{ + "name": "ohos.permission.DISTRIBUTED_DATASYNC" + }] + } +} +``` + +The **DISTRIBUTED_DATASYNC** permission is user granted. Therefore, your application, when being started, must display a dialog box to request the permission. The sample code is as follows: + +```ts +import abilityAccessCtrl from "@ohos.abilityAccessCtrl" +import bundle from '@ohos.bundle' + +async function RequestPermission() { + console.info('RequestPermission begin'); + let array: Array = ["ohos.permission.DISTRIBUTED_DATASYNC"]; + let bundleFlag = 0; + let tokenID = undefined; + let userID = 100; + let appInfo = await bundle.getApplicationInfo('ohos.samples.etsDemo', bundleFlag, userID); + tokenID = appInfo.accessTokenId; + let atManager = abilityAccessCtrl.createAtManager(); + let requestPermissions: Array = []; + for (let i = 0;i < array.length; i++) { + let result = await atManager.verifyAccessToken(tokenID, array[i]); + console.info("verifyAccessToken result:" + JSON.stringify(result)); + if (result != abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { + requestPermissions.push(array[i]); + } + } + console.info("requestPermissions:" + JSON.stringify(requestPermissions)); + if (requestPermissions.length == 0 || requestPermissions == []) { + return; + } + let context = featureAbility.getContext(); + context.requestPermissionsFromUser(requestPermissions, 1, (data)=>{ + console.info("data:" + JSON.stringify(data)); + }); + console.info('RequestPermission end'); +} +``` + +To obtain the device ID, import the **@ohos.distributedHardware.deviceManager** module, which provides **getTrustedDeviceList** to obtain the remote device ID. For details about how to use the API, see [Device Management](..\reference\apis\js-apis-device-manager.md). + +To connect to a remote Service ability, you only need to define **deviceId** in **Want**. The sample code is as follows: + +```ts +import featureAbility from '@ohos.ability.featureAbility' + +let want = { + deviceId: remoteDeviceId, + bundleName: "com.jstest.service", + abilityName: "com.jstest.service.ServiceAbility" +}; +let connectId = featureAbility.connectAbility(want, option); +``` + +The other implementations are the same as those for the connection to a local Service ability. For details, see the sample code provided under [Connecting to a Local Service Ability](#connecting-to-a-local-service-ability). diff --git a/en/application-dev/ability/figures/AbilityComponentInstanceMission.png b/en/application-dev/ability-deprecated/figures/AbilityComponentInstanceMission.png similarity index 100% rename from en/application-dev/ability/figures/AbilityComponentInstanceMission.png rename to en/application-dev/ability-deprecated/figures/AbilityComponentInstanceMission.png diff --git a/en/application-dev/ability/figures/ExtensionAbility.png b/en/application-dev/ability-deprecated/figures/ExtensionAbility.png similarity index 100% rename from en/application-dev/ability/figures/ExtensionAbility.png rename to en/application-dev/ability-deprecated/figures/ExtensionAbility.png diff --git a/en/application-dev/ability/figures/aa-dump-a.PNG b/en/application-dev/ability-deprecated/figures/aa-dump-a.PNG similarity index 100% rename from en/application-dev/ability/figures/aa-dump-a.PNG rename to en/application-dev/ability-deprecated/figures/aa-dump-a.PNG diff --git a/en/application-dev/ability/figures/aa-dump-i.PNG b/en/application-dev/ability-deprecated/figures/aa-dump-i.PNG similarity index 100% rename from en/application-dev/ability/figures/aa-dump-i.PNG rename to en/application-dev/ability-deprecated/figures/aa-dump-i.PNG diff --git a/en/application-dev/ability/figures/aa-dump-l.PNG b/en/application-dev/ability-deprecated/figures/aa-dump-l.PNG similarity index 100% rename from en/application-dev/ability/figures/aa-dump-l.PNG rename to en/application-dev/ability-deprecated/figures/aa-dump-l.PNG diff --git a/en/application-dev/ability/figures/contextIntroduction.png b/en/application-dev/ability-deprecated/figures/contextIntroduction.png similarity index 100% rename from en/application-dev/ability/figures/contextIntroduction.png rename to en/application-dev/ability-deprecated/figures/contextIntroduction.png diff --git a/en/application-dev/ability/figures/continuation-info.png b/en/application-dev/ability-deprecated/figures/continuation-info.png similarity index 100% rename from en/application-dev/ability/figures/continuation-info.png rename to en/application-dev/ability-deprecated/figures/continuation-info.png diff --git a/en/application-dev/ability/figures/continuationManager.png b/en/application-dev/ability-deprecated/figures/continuationManager.png similarity index 100% rename from en/application-dev/ability/figures/continuationManager.png rename to en/application-dev/ability-deprecated/figures/continuationManager.png diff --git a/en/application-dev/ability/figures/fa-dataability-uri.png b/en/application-dev/ability-deprecated/figures/fa-dataability-uri.png similarity index 100% rename from en/application-dev/ability/figures/fa-dataability-uri.png rename to en/application-dev/ability-deprecated/figures/fa-dataability-uri.png diff --git a/en/application-dev/ability/figures/fa-form-example.png b/en/application-dev/ability-deprecated/figures/fa-form-example.png similarity index 100% rename from en/application-dev/ability/figures/fa-form-example.png rename to en/application-dev/ability-deprecated/figures/fa-form-example.png diff --git a/en/application-dev/ability/figures/fa-pageAbility-lifecycle.png b/en/application-dev/ability-deprecated/figures/fa-pageAbility-lifecycle.png similarity index 100% rename from en/application-dev/ability/figures/fa-pageAbility-lifecycle.png rename to en/application-dev/ability-deprecated/figures/fa-pageAbility-lifecycle.png diff --git a/en/application-dev/ability/figures/fa-threading-model.png b/en/application-dev/ability-deprecated/figures/fa-threading-model.png similarity index 100% rename from en/application-dev/ability/figures/fa-threading-model.png rename to en/application-dev/ability-deprecated/figures/fa-threading-model.png diff --git a/en/application-dev/ability/figures/favsstage.png b/en/application-dev/ability-deprecated/figures/favsstage.png similarity index 100% rename from en/application-dev/ability/figures/favsstage.png rename to en/application-dev/ability-deprecated/figures/favsstage.png diff --git a/en/application-dev/ability/figures/lifecycle.png b/en/application-dev/ability-deprecated/figures/lifecycle.png similarity index 100% rename from en/application-dev/ability/figures/lifecycle.png rename to en/application-dev/ability-deprecated/figures/lifecycle.png diff --git a/en/application-dev/ability/figures/page-ability-lifecycle.png b/en/application-dev/ability-deprecated/figures/page-ability-lifecycle.png similarity index 100% rename from en/application-dev/ability/figures/page-ability-lifecycle.png rename to en/application-dev/ability-deprecated/figures/page-ability-lifecycle.png diff --git a/en/application-dev/ability/figures/stage-call.png b/en/application-dev/ability-deprecated/figures/stage-call.png similarity index 100% rename from en/application-dev/ability/figures/stage-call.png rename to en/application-dev/ability-deprecated/figures/stage-call.png diff --git a/en/application-dev/ability/figures/stageabilitylifecyclecallback.png b/en/application-dev/ability-deprecated/figures/stageabilitylifecyclecallback.png similarity index 100% rename from en/application-dev/ability/figures/stageabilitylifecyclecallback.png rename to en/application-dev/ability-deprecated/figures/stageabilitylifecyclecallback.png diff --git a/en/application-dev/ability/figures/stageconcept.png b/en/application-dev/ability-deprecated/figures/stageconcept.png similarity index 100% rename from en/application-dev/ability/figures/stageconcept.png rename to en/application-dev/ability-deprecated/figures/stageconcept.png diff --git a/en/application-dev/ability/figures/stagedesign.png b/en/application-dev/ability-deprecated/figures/stagedesign.png similarity index 100% rename from en/application-dev/ability/figures/stagedesign.png rename to en/application-dev/ability-deprecated/figures/stagedesign.png diff --git a/en/application-dev/ability/figures/stageprocessmodel.png b/en/application-dev/ability-deprecated/figures/stageprocessmodel.png similarity index 100% rename from en/application-dev/ability/figures/stageprocessmodel.png rename to en/application-dev/ability-deprecated/figures/stageprocessmodel.png diff --git a/en/application-dev/ability/public_sys-resources/icon-caution.gif b/en/application-dev/ability-deprecated/public_sys-resources/icon-caution.gif similarity index 100% rename from en/application-dev/ability/public_sys-resources/icon-caution.gif rename to en/application-dev/ability-deprecated/public_sys-resources/icon-caution.gif diff --git a/en/application-dev/ability/public_sys-resources/icon-danger.gif b/en/application-dev/ability-deprecated/public_sys-resources/icon-danger.gif similarity index 100% rename from en/application-dev/ability/public_sys-resources/icon-danger.gif rename to en/application-dev/ability-deprecated/public_sys-resources/icon-danger.gif diff --git a/en/application-dev/ability/public_sys-resources/icon-note.gif b/en/application-dev/ability-deprecated/public_sys-resources/icon-note.gif similarity index 100% rename from en/application-dev/ability/public_sys-resources/icon-note.gif rename to en/application-dev/ability-deprecated/public_sys-resources/icon-note.gif diff --git a/en/application-dev/ability/public_sys-resources/icon-notice.gif b/en/application-dev/ability-deprecated/public_sys-resources/icon-notice.gif similarity index 100% rename from en/application-dev/ability/public_sys-resources/icon-notice.gif rename to en/application-dev/ability-deprecated/public_sys-resources/icon-notice.gif diff --git a/en/application-dev/ability/public_sys-resources/icon-tip.gif b/en/application-dev/ability-deprecated/public_sys-resources/icon-tip.gif similarity index 100% rename from en/application-dev/ability/public_sys-resources/icon-tip.gif rename to en/application-dev/ability-deprecated/public_sys-resources/icon-tip.gif diff --git a/en/application-dev/ability/public_sys-resources/icon-warning.gif b/en/application-dev/ability-deprecated/public_sys-resources/icon-warning.gif similarity index 100% rename from en/application-dev/ability/public_sys-resources/icon-warning.gif rename to en/application-dev/ability-deprecated/public_sys-resources/icon-warning.gif diff --git a/en/application-dev/ability/stage-ability-continuation.md b/en/application-dev/ability-deprecated/stage-ability-continuation.md similarity index 98% rename from en/application-dev/ability/stage-ability-continuation.md rename to en/application-dev/ability-deprecated/stage-ability-continuation.md index 701b730a83..7a11716f18 100644 --- a/en/application-dev/ability/stage-ability-continuation.md +++ b/en/application-dev/ability-deprecated/stage-ability-continuation.md @@ -301,11 +301,13 @@ In the ability continuation scenario, the distributed data object is used to syn ### Restrictions -1. The continuation must be performed between the same ability, which means the same bundle name, module name, and ability name. For details, see [Application Package Structure Configuration File](../quick-start/stage-structure.md). +1. The continuation must be performed between the same ability, which means the same bundle name, module name, and ability name. For details, see [Application Package Structure Configuration File](../quick-start/module-configuration-file.md). 2. Currently, the application can only implement the continuation capability. The continuation action must be initiated by the system. ### Best Practice - For better user experience, you are advised to use the **wantParam** parameter to transmit data smaller than 100 KB and use distributed objects to transmit data larger than 100 KB. +For better user experience, you are advised to use the **wantParam** parameter to transmit data smaller than 100 KB and use distributed objects to transmit data larger than 100 KB. + + \ No newline at end of file diff --git a/en/application-dev/ability/stage-ability.md b/en/application-dev/ability-deprecated/stage-ability.md similarity index 98% rename from en/application-dev/ability/stage-ability.md rename to en/application-dev/ability-deprecated/stage-ability.md index d09585b255..97ba5cff5c 100644 --- a/en/application-dev/ability/stage-ability.md +++ b/en/application-dev/ability-deprecated/stage-ability.md @@ -1,6 +1,6 @@ # Ability Development ## When to Use -Ability development in the [stage model](stage-brief.md) is significantly different from that in the FA model. The stage model requires you to declare the application package structure in the **module.json5** and **app.json5** files during application development. For details about the configuration file, see [Application Package Structure Configuration File](../quick-start/stage-structure.md). To develop an ability based on the stage model, implement the following logic: +Ability development in the [stage model](stage-brief.md) is significantly different from that in the FA model. The stage model requires you to declare the application package structure in the **module.json5** and **app.json5** files during application development. For details about the configuration file, see [Application Package Structure Configuration File](../quick-start/application-package-structure-stage.md). To develop an ability based on the stage model, implement the following logic: - Create an ability that supports screen viewing and human-machine interaction. You must implement the following scenarios: ability lifecycle callbacks, obtaining ability configuration, requesting permissions, and notifying environment changes. - Start an ability. You need to implement ability startup on the same device, on a remote device, or with a specified UI page. - Call abilities. For details, see [Call Development](stage-call.md). @@ -30,7 +30,7 @@ By default, the singleton mode is used. The following is an example of the **mod ``` ## Creating an Ability ### Available APIs -The table below describes the APIs provided by the **AbilityStage** class, which has the **context** attribute. For details about the APIs, see [AbilityStage](../reference/apis/js-apis-application-abilitystage.md). +The table below describes the APIs provided by the **AbilityStage** class, which has the **context** attribute. For details about the APIs, see [AbilityStage](../reference/apis/js-apis-app-ability-abilityStage.md). **Table 1** AbilityStage APIs |API|Description| @@ -321,3 +321,5 @@ struct Index { } } ``` + + \ No newline at end of file diff --git a/en/application-dev/ability-deprecated/stage-brief.md b/en/application-dev/ability-deprecated/stage-brief.md new file mode 100644 index 0000000000..2d5474e2c2 --- /dev/null +++ b/en/application-dev/ability-deprecated/stage-brief.md @@ -0,0 +1,114 @@ +# Stage Model Overview + +## Design Ideas + +The stage model is designed to provide a better application development mode in the distributed environment. + +The following figure shows the design ideas of the stage model. + +![stagedesign](figures/stagedesign.png) + +The stage model is designed based on the following considerations: + +- Efficient management of application processes + +As the device memory becomes larger, the number of processes concurrently running in the system increases. If the number of concurrent processes reaches several hundreds, the overall power consumption and performance of the system will be adversely affected without effective management measures. To restrict the behavior of background processes, the stage model uses four measures: transient task, continuous task, agent task, and Work Scheduler task. With these measures, foreground processes will obtain guaranteed resources, thereby delivering a better user experience. + +- Native support for cross-device migration and multi-device collaboration + +OpenHarmony is a native distributed OS. Its application framework must be designed for easier component migration and collaboration across devices. The stage model achieves this design objective by providing features such as separation between ability and UI as well as integration of UI display and service capabilities. + +- Different window forms for various device types + +The stage model redefines the ability lifecycle. In terms of architecture, the component manager and window manager are decoupled. This facilitates adaptation between window forms and device types. + +## Basic Concepts + +The following figure shows the basic concepts in the stage model. + +![stageconcept](figures/stageconcept.png) + +- **HAP**: basic unit for building, distributing, and loading OpenHarmony applications. Each HAP corresponds to a module in the development state. In an application, **moduleName** uniquely identifies a module. +- **Bundle**: an OpenHarmony application identified by **appid**. A bundle can contain multiple HAP files. Each application has a **bundleName**. However, **bundleName** must be used together with **appid** and other information to uniquely identify an application. +- **AbilityStage**: runtime object of an HAP. It is created when the HAP is loaded to the process for the first time and is visible to developers in the runtime. +- **Application**: runtime object of a bundle. It is invisible to developers in the runtime. +- **Context**: base class that provides APIs in the runtime to obtain information such as the bundle name, module name, and path. The **Context** classes of the Ability and ExtensionAbility components inherit from this class. +- **Ability**: provides lifecycle callbacks, holds the ability context, and supports cross-device component migration and multi-device collaboration. +- **ExtensionAbility**: general name of scenario-based Extension abilities. The system defines multiple scenario-based **ExtensionAbility** classes, each of which has its own **ExtensionContext**. +- **WindowStage**: local window manager. +- **Window**: application window, which holds an ArkUI engine instance. +- **ArkUI Page**: UI developed based on ArkUI. + + +## Lifecycle + +The ability and ability stage are key objects in the application lifecycle. + +For details about the lifecycle differences between the stage model and FA model, see [Ability Framework Overview](ability-brief.md). This section focuses on the ability lifecycle transition and the scheduling relationships between the ability, ability stage, and window stage. + +![stageabilitylifecyclecallback](figures/stageabilitylifecyclecallback.png) + +To implement device adaptation and multi-window scalability, OpenHarmony decouples the component manager from the window manager. + +The ability lifecycle defined in the stage model includes only the creation, destruction, foreground, and background states. The gain focus and lose focus states that are closely related to UI are defined in the window stage. This implements weak coupling between the abilities and windows. On the service side, the window manager notifies the component manager of the foreground and background state changes, so the component manager only senses the foreground and background state changes but not the focus changes. + +There are two lifecycle states related to the window stage in **Ability**: **onWindowStageCreate** and **onWindowStageDestroy**. They are valid only for devices with the display capability. **onWindowStageCreate** is invoked when a window stage is created, where you can call **loadContent** to set pages to be loaded for the ability. **onWindowStageDestroy** is invoked when the window stage is destroyed, where you can release resources. + + +## Ability Instances and Missions + +Abilities can be started in any of the following modes: + +* **Singleton**: For each type of ability, only one instance exists in the application process. **Ability1** in the figure below is started in singleton mode. +* **Standard**: Each time **startAbility** is called, an instance of the specified ability type is created in the application process. **Ability2** in the figure below is started in standard mode. +* **Specified**: Before creating an **Ability** instance, you can create a key for the instance. Each time **startAbility** is called, the system asks the application which ability instance (corresponding to a key) will be used. **Ability3** in the figure below is started in specified mode. + +Each **Ability** instance corresponds to a mission in **Recents**. + +The mission corresponding to an ability instance has a snapshot of the ability instance. After the ability instance is destroyed, the ability class information and snapshot are retained in the mission until the user deletes the information or the storage space reaches the upper limit. + + ![AbilityComponentInstanceMission](figures/AbilityComponentInstanceMission.png) + +## ExtensionAbility Mechanism + +Different from the ability used for UI display, ExtensionAbility provides a restricted running environment. + +ExtensionAbility has the following features: + +- Its process runs independently from the main process but shares the same storage sandbox with the main process. There is no inter-process communication (IPC) between the ExtensionAbility process and the main process. + +- It has an independent context that provides scenario-specific APIs. + +- It is created by the system, rather than by applications. + +- The lifecycles of the ExtensionAbility component and process are managed by the system. + +The following figure uses the widget an example. **FormExtensionAbility** is the base class. You can inherit from this class to provide widget information. The lifecycle of the **FormExtensionAbility** instance and that of the ExtensionAbility process where the instance is located are managed by a system service named **FormManagerService**. + +![ExtensionAbility](figures/ExtensionAbility.png) + +## Process Model + +OpenHarmony forces strong control policies on application processes. No APIs are provided to configure multiple processes. All application processes are created and managed by the system. + +The processes of an application can be classified into three types: + +- Main process: runs the **UIAbility** component, UI, and service logic. + +- Extension process: runs classes derived from **ExtensionAbility** in the application. The lifecycle of this process is managed by a scenario-specific system service. + +- Render process: created for the WebView and used to load the WebView rendering library. + + The following figure shows the process model of an application. + + ![stageprocessmodel](figures/stageprocessmodel.png) + + + +## Application Package Structure + +For details about the project directory structure of the stage model, see [OpenHarmony Project Overview](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-project-overview-0000001218440650#section56487581904). + +For details about how to configure the application package structure of the stage model, see [Application Package Structure Configuration File](../quick-start/application-configuration-file-overview-stage.md). + + \ No newline at end of file diff --git a/en/application-dev/ability/stage-call.md b/en/application-dev/ability-deprecated/stage-call.md similarity index 99% rename from en/application-dev/ability/stage-call.md rename to en/application-dev/ability-deprecated/stage-call.md index 5c29001e5c..e447dc4fd8 100644 --- a/en/application-dev/ability/stage-call.md +++ b/en/application-dev/ability-deprecated/stage-call.md @@ -34,7 +34,7 @@ The table below describes the ability call APIs. For details, see [Ability](../r **Table 2** Ability call APIs |API|Description| |:------|:------| -|startAbilityByCall(want: Want): Promise\|Starts an ability in the foreground (through the **want** configuration) or background (default) and obtains the **Caller** object for communication with the ability. For details, see [AbilityContext](../reference/apis/js-apis-ability-context.md#abilitycontextstartabilitybycall) or [ServiceExtensionContext](../reference/apis/js-apis-service-extension-context.md#serviceextensioncontextstartabilitybycall).| +|startAbilityByCall(want: Want): Promise\|Starts an ability in the foreground (through the **want** configuration) or background (default) and obtains the **Caller** object for communication with the ability. For details, see [AbilityContext](../reference/apis/js-apis-ability-context.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.Sequenceable): Promise\|Sends agreed sequenceable data to the callee ability.| diff --git a/en/application-dev/ability/stage-formextension.md b/en/application-dev/ability-deprecated/stage-formextension.md similarity index 98% rename from en/application-dev/ability/stage-formextension.md rename to en/application-dev/ability-deprecated/stage-formextension.md index fa90f267c1..c45b33732a 100644 --- a/en/application-dev/ability/stage-formextension.md +++ b/en/application-dev/ability-deprecated/stage-formextension.md @@ -31,7 +31,7 @@ Stage widget development refers to the development conducted by the widget provi ## Available APIs -The **FormExtension** class has the following APIs. For details, see [FormExtension](../reference/apis/js-apis-formextension.md). +The **FormExtension** class has the following APIs. For details, see [FormExtension](../reference/apis/js-apis-app-form-formExtensionAbility.md). **Table 1** FormExtension APIs @@ -45,7 +45,7 @@ The **FormExtension** class has the following APIs. For details, see [FormExtens | onDestroy(formId: string): void | Called to notify the widget provider that a **Form** instance (widget) has been destroyed. | | onConfigurationUpdated(config: Configuration): void; | Called when the configuration of the environment where the widget is running is updated. | -The **FormExtension** class also has a member context, that is, the **FormExtensionContext** class. For details, see [FormExtensionContext](../reference/apis/js-apis-formextensioncontext.md). +The **FormExtension** class also has a member context, that is, the **FormExtensionContext** class. For details, see [FormExtensionContext](../reference/apis/js-apis-inner-application-formExtensionContext.md). **Table 2** FormExtensionContext APIs @@ -54,7 +54,7 @@ The **FormExtension** class also has a member context, that is, the **FormExtens | startAbility(want: Want, callback: AsyncCallback<void>): void | Starts an ability. This API uses an asynchronous callback to return the result. (This is a system API and cannot be called by third-party applications.)| | startAbility(want: Want): Promise<void> | Starts an ability. This API uses a promise to return the result. (This is a system API and cannot be called by third-party applications.)| -For details about the **FormProvider** APIs, see [FormProvider](../reference/apis/js-apis-formprovider.md). +For details, see [FormProvider](../reference/apis/js-apis-application-formProvider.md). **Table 3** FormProvider APIs @@ -412,4 +412,4 @@ The following is an example: } } } - ``` \ No newline at end of file + ``` diff --git a/en/application-dev/ability/stage-serviceextension.md b/en/application-dev/ability-deprecated/stage-serviceextension.md similarity index 99% rename from en/application-dev/ability/stage-serviceextension.md rename to en/application-dev/ability-deprecated/stage-serviceextension.md index 0d634ebe67..98cae5914f 100644 --- a/en/application-dev/ability/stage-serviceextension.md +++ b/en/application-dev/ability-deprecated/stage-serviceextension.md @@ -71,4 +71,5 @@ OpenHarmony does not support creation of a Service Extension ability for third-p console.log('onDestroy'); } } - ``` \ No newline at end of file + ``` + diff --git a/en/application-dev/ability/wantagent.md b/en/application-dev/ability-deprecated/wantagent.md similarity index 99% rename from en/application-dev/ability/wantagent.md rename to en/application-dev/ability-deprecated/wantagent.md index 5a85bab15b..4b1854d1a5 100644 --- a/en/application-dev/ability/wantagent.md +++ b/en/application-dev/ability-deprecated/wantagent.md @@ -2,8 +2,6 @@ ## When to Use The **WantAgent** class encapsulates want information that specifies a particular action, which can be starting an ability or publishing a common event. You can either call **wantAgent.trigger** to trigger a **WantAgent** directly or add a **WantAgent** to a notification so that it will be triggered when users tap the notification. - - ## Available APIs | API | Description| | ---------------------------------------------------------------------------------------------- | ----------- | diff --git a/en/application-dev/ability/fa-brief.md b/en/application-dev/ability/fa-brief.md deleted file mode 100644 index 598ff0f5a7..0000000000 --- a/en/application-dev/ability/fa-brief.md +++ /dev/null @@ -1,35 +0,0 @@ -# FA Model Overview - -## Overall Architecture -The development of an OpenHarmony application is essentially the development of one or more abilities. By scheduling abilities and managing their lifecycle, OpenHarmony implements application scheduling. - -The Feature Ability (FA) model applies to application development using API version 8 and earlier versions. In this model, there are Page, Service, Data, and Form abilities. -- The Page ability implements the ArkUI and provides the capability of interacting with users. -- The Service ability does not have a UI. It runs in the background and provides custom services for other abilities to invoke. -- The Data ability does not have a UI. It runs in the background and enables other abilities to insert, delete, and query data. -- The Form ability provides a widget, which is a UI display mode. - -## Lifecycle - -Among all abilities, the Page ability has the most complex lifecycle, because it has a UI and acts as a touchpoint for interacting with users. - -**The following figure shows the lifecycle of the Page ability.** - -![fa-pageAbility-lifecycle](figures/fa-pageAbility-lifecycle.png) - -The other abilities do not involve the foreground/background switchover and the **onShow** callback. -You can override the lifecycle callbacks in **app.js/app.ets** to process application logic. - -Currently, the **app.js** file provides only the **onCreate** and **onDestroy** callbacks, and the **app.ets** file provides the full lifecycle callbacks. - - -## Process and Thread Model -An application exclusively uses an independent process, and an ability exclusively uses an independent thread. When an ability is started for the first time, an application process as well as a thread for this ability is created. After the application is started, other abilities in the application are started, and a thread is created for every of these started abilities. Each ability is bound to an independent JSRuntime instance. In this way, abilities are isolated from each other. - -![fa-threading-model](figures/fa-threading-model.png) - -## Application Package Structure - -For details about the project directory structure of the FA model, see [OpenHarmony Project Overview](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-project-overview-0000001218440650#section4154183910141). - -For details about how to configure the application package structure of the FA model, see [Application Package Structure Configuration File](../quick-start/package-structure.md). diff --git a/en/application-dev/ability/fa-serviceability.md b/en/application-dev/ability/fa-serviceability.md deleted file mode 100644 index 3bafb0bc09..0000000000 --- a/en/application-dev/ability/fa-serviceability.md +++ /dev/null @@ -1,400 +0,0 @@ -# Service Ability Development - -## When to Use -A Service ability is used to run tasks in the background, such as playing music or downloading files. It does not provide a UI for user interaction. Service abilities can be started by other applications or abilities and can remain running in the background even after the user switches to another application. - -## Available APIs - -**Table 1** Service ability lifecycle APIs -|API|Description| -|:------|:------| -|onStart?(): void|Called to initialize a Service ability being created. This callback is invoked only once in the entire lifecycle of a Service ability. The **Want** object passed to this callback must be null.| -|onCommand?(want: Want, startId: number): void|Called every time a Service ability is created on a client. You can collect calling statistics and perform initialization operations in this callback.| -|onConnect?(want: Want): rpc.RemoteObject|Called when another ability is connected to the Service ability.| -|onDisconnect?(want: Want): void|Called when another ability is disconnected from the Service ability.| -|onStop?(): void|Called when the Service ability is being destroyed. You should override this callback for your Service ability to clear its resources, such as threads and registered listeners.| - -## How to Develop - -### Creating and Registering a Service Ability - -1. Override the Service ability-related lifecycle callbacks to implement your own logic for processing interaction requests. - - ```javascript - export default { - onStart() { - console.log('ServiceAbility onStart'); - }, - onCommand(want, startId) { - console.log('ServiceAbility onCommand'); - }, - onConnect(want) { - console.log('ServiceAbility OnConnect'); - return new FirstServiceAbilityStub('test'); - }, - onDisconnect(want) { - console.log('ServiceAbility OnDisConnect'); - }, - onStop() { - console.log('ServiceAbility onStop'); - }, - } - ``` - -2. Register a Service ability. - - Declare the Service ability in the **config.json** file by setting its **type** attribute to **service**. - - ```javascript - { - "module": { - "abilities": [ - { - "name": ".ServiceAbility", - "type": "service", - "visible": true - ... - } - ] - ... - } - ... - } - ``` - - - -### Starting a Service Ability - -The **Ability** class provides the **startAbility()** API for you to start another Service ability by passing a **Want** object. - -To set information about the target Service ability, you can first construct a **Want** object with the **bundleName** and **abilityName** parameters specified. The meanings of the parameters are as follows: - -- **bundleName** indicates the name of the bundle to which the target ability belongs. -- **abilityName** indicates the target ability name. - -The following code snippet shows how to start a Service ability running on the local device: - -```javascript -import featureAbility from '@ohos.ability.featureAbility'; -let promise = featureAbility.startAbility( - { - want: - { - bundleName: "com.jstest.service", - abilityName: "com.jstest.service.ServiceAbility", - }, - } -); -``` - -After the preceding code is executed, the **startAbility()** API is called to start the Service ability. -- If the Service ability is not running, the system calls **onStart()** to initialize the Service ability, and then calls **onCommand()** on the Service ability. -- If the Service ability is running, the system directly calls **onCommand()** on the Service ability. - -The following code snippet shows how to start a Service ability running on the remote device. For details about **getRemoteDeviceId()**, see [Connecting to a Remote Service Ability](#connecting-to-a-remote-service-ability). - -```javascript -import featureAbility from '@ohos.ability.featureAbility'; -let promise = featureAbility.startAbility( - { - want: - { - deviceId: getRemoteDeviceId(), // Remote device ID - bundleName: "com.jstest.service", - abilityName: "com.jstest.service.ServiceAbility", - }, - } -); -``` - - -### Stopping a Service Ability - -Once created, the Service ability keeps running in the background. The system does not stop or destroy it unless memory resources must be reclaimed. - -### Connecting to a Local Service Ability - -If you need to connect a Service ability to a Page ability or to a Service ability in another application, you must first implement the **IAbilityConnection** API for the connection. A Service ability allows other abilities to connect to it through **connectAbility()**. - - -You can use either of the following methods to connect to a Service ability: - -1. Using the IDL to automatically generate code - - Use OpenHarmony Interface Definition Language (IDL) to automatically generate the corresponding client, server, and **IRemoteObject** code. For details, see “Development Using TS" in [OpenHarmony IDL Specifications and User Guide](../IDL/idl-guidelines.md). - -2. Writing code in the corresponding file - - When calling **connectAbility()**, you should pass a **Want** object containing information about the target Service ability and an **IAbilityConnection** object to the API. **IAbilityConnection** provides the following callbacks that you should implement: **onConnect()**, **onDisconnect()**, and **onFailed()**. The **onConnect()** callback is invoked when a Service ability is connected, **onDisconnect()** is invoked when a Service ability is unexpectedly disconnected, and **onFailed()** is invoked when a connection to a Service ability fails. - - The following code snippet shows how to implement the callbacks: - - ```javascript - import prompt from '@system.prompt' - - var option = { - onConnect: function onConnectCallback(element, proxy) { - console.log(`onConnectLocalService onConnectDone`) - if (proxy === null) { - prompt.showToast({ - message: "Connect service failed" - }) - return - } - let data = rpc.MessageParcel.create() - let reply = rpc.MessageParcel.create() - let option = new rpc.MessageOption() - data.writeInterfaceToken("connect.test.token") - proxy.sendRequest(0, data, reply, option) - prompt.showToast({ - message: "Connect service success" - }) - }, - onDisconnect: function onDisconnectCallback(element) { - console.log(`onConnectLocalService onDisconnectDone element:${element}`) - prompt.showToast({ - message: "Disconnect service success" - }) - }, - onFailed: function onFailedCallback(code) { - console.log(`onConnectLocalService onFailed errCode:${code}`) - prompt.showToast({ - message: "Connect local service onFailed" - }) - } - } - ``` - - The following code snippet shows how to connect to a local Service ability: - - ```javascript - import featureAbility from '@ohos.ability.featureAbility'; - let connId = featureAbility.connectAbility( - { - bundleName: "com.jstest.service", - abilityName: "com.jstest.service.ServiceAbility", - }, - { - onConnect: onConnectCallback, - onDisconnect: onDisconnectCallback, - onFailed: onFailedCallback, - }, - ); - ``` - - When a Service ability is connected, the **onConnect()** callback is invoked and returns an **IRemoteObject** defining the proxy used for communicating with the Service ability. OpenHarmony provides a default implementation of **IRemoteObject**. You can extend **rpc.RemoteObject** to implement your own class of **IRemoteObject**. - - The following code snippet shows how the Service ability instance returns itself to the calling ability: - - ```javascript - import rpc from "@ohos.rpc"; - - class FirstServiceAbilityStub extends rpc.RemoteObject { - constructor(des: any) { - if (typeof des === 'string') { - super(des) - } else { - return - } - } - - onRemoteRequest(code: number, data: any, reply: any, option: any) { - console.log(printLog + ` onRemoteRequest called`) - if (code === 1) { - let string = data.readString() - console.log(printLog + ` string=${string}`) - let result = Array.from(string).sort().join('') - console.log(printLog + ` result=${result}`) - reply.writeString(result) - } else { - console.log(printLog + ` unknown request code`) - } - return true; - } - ``` - -### Connecting to a Remote Service Ability - ->**NOTE** -> ->This feature applies only to system applications, since the **getTrustedDeviceListSync** API of the **DeviceManager** class is open only to system applications. - -If you need to connect a Service ability to a Page ability or another Service ability on a remote device, you must first implement the **IAbilityConnection** interface for the connection. A Service ability allows abilities on another device to connect to it through **connectAbility()**. - -When calling **connectAbility()**, you should pass a **Want** object containing information about the target Service ability and an **IAbilityConnection** object to the API. **IAbilityConnection** provides the following callbacks that you should implement: **onConnect()**, **onDisconnect()**, and **onFailed()**. The **onConnect()** callback is invoked when a Service ability is connected, **onDisconnect()** is invoked when a Service ability is unexpectedly disconnected, and **onFailed()** is invoked when a connection to a Service ability fails. - -The following code snippet shows how to implement the callbacks: - -```ts -import prompt from '@system.prompt' - -var option = { - onConnect: function onConnectCallback(element, proxy) { - console.log(`onConnectRemoteService onConnectDone`) - if (proxy === null) { - prompt.showToast({ - message: "Connect service failed" - }) - return - } - let data = rpc.MessageParcel.create() - let reply = rpc.MessageParcel.create() - let option = new rpc.MessageOption() - data.writeInterfaceToken("connect.test.token") - proxy.sendRequest(0, data, reply, option) - prompt.showToast({ - message: "Connect service success" - }) - }, - onDisconnect: function onDisconnectCallback(element) { - console.log(`onConnectRemoteService onDisconnectDone element:${element}`) - prompt.showToast({ - message: "Disconnect service success" - }) - }, - onFailed: function onFailedCallback(code) { - console.log(`onConnectRemoteService onFailed errCode:${code}`) - prompt.showToast({ - message: "Connect local service onFailed" - }) - } -} -``` - -The **Want** of the target Service ability must contain the remote **deviceId**, which can be obtained from **DeviceManager**. The sample code is as follows: - -```ts -import deviceManager from '@ohos.distributedHardware.deviceManager'; - -// For details about the implementation of dmClass, see the implementation in Distributed Demo in Samples. -let dmClass; - -function getRemoteDeviceId() { - if (typeof dmClass === 'object' && dmClass != null) { - let list = dmClass.getTrustedDeviceListSync(); - if (typeof (list) == 'undefined' || typeof (list.length) == 'undefined') { - console.log("MainAbility onButtonClick getRemoteDeviceId err: list is null"); - return; - } - console.log("MainAbility onButtonClick getRemoteDeviceId success:" + list[0].deviceId); - return list[0].deviceId; - } else { - console.log("MainAbility onButtonClick getRemoteDeviceId err: dmClass is null"); - } -} -``` - -The following code snippet shows how to connect to a remote Service ability: - -```ts -import featureAbility from '@ohos.ability.featureAbility'; -let connId = featureAbility.connectAbility( - { - deviceId: getRemoteDeviceId(), - bundleName: "ohos.samples.etsDemo", - abilityName: "ohos.samples.etsDemo.ServiceAbility", - }, - { - onConnect: onConnectCallback, - onDisconnect: onDisconnectCallback, - onFailed: onFailedCallback, - }, -); -``` -In the cross-device scenario, the application must also apply for the data synchronization permission from end users. The sample code is as follows: - -```ts -import abilityAccessCtrl from "@ohos.abilityAccessCtrl"; -import bundle from '@ohos.bundle'; -async function RequestPermission() { - console.info('RequestPermission begin'); - let array: Array = ["ohos.permission.DISTRIBUTED_DATASYNC"]; - let bundleFlag = 0; - let tokenID = undefined; - let userID = 100; - let appInfo = await bundle.getApplicationInfo('ohos.samples.etsDemo', bundleFlag, userID); - tokenID = appInfo.accessTokenId; - let atManager = abilityAccessCtrl.createAtManager(); - let requestPermissions: Array = []; - for (let i = 0;i < array.length; i++) { - let result = await atManager.verifyAccessToken(tokenID, array[i]); - console.info("verifyAccessToken result:" + JSON.stringify(result)); - if (result == abilityAccessCtrl.GrantStatus.PERMISSION_GRANTED) { - } else { - requestPermissions.push(array[i]); - } - } - console.info("requestPermissions:" + JSON.stringify(requestPermissions)); - if (requestPermissions.length == 0 || requestPermissions == []) { - return; - } - let context = featureAbility.getContext(); - context.requestPermissionsFromUser(requestPermissions, 1, (data)=>{ - console.info("data:" + JSON.stringify(data)); - }); - console.info('RequestPermission end'); -} -``` - -When a Service ability is connected, the **onConnect()** callback is invoked and returns an **IRemoteObject** defining the proxy used for communicating with the Service ability. OpenHarmony provides a default implementation of **IRemoteObject**. You can extend **rpc.RemoteObject** to implement your own class of **IRemoteObject**. - -The following code snippet shows how the Service ability instance returns itself to the calling ability: - -```ts -import rpc from "@ohos.rpc"; - -class FirstServiceAbilityStub extends rpc.RemoteObject { - constructor(des: any) { - if (typeof des === 'string') { - super(des) - } else { - return - } - } - - onRemoteRequest(code: number, data: any, reply: any, option: any) { - console.log(printLog + ` onRemoteRequest called`) - if (code === 1) { - let string = data.readString() - console.log(printLog + ` string=${string}`) - let result = Array.from(string).sort().join('') - console.log(printLog + ` result=${result}`) - reply.writeString(result) - } else { - console.log(printLog + ` unknown request code`) - } - return true; - } -} - -export default { - onStart() { - console.info('ServiceAbility onStart'); - }, - onStop() { - console.info('ServiceAbility onStop'); - }, - onConnect(want) { - console.log("ServiceAbility onConnect"); - try { - let value = JSON.stringify(want); - console.log("ServiceAbility want:" + value); - } catch(error) { - console.log("ServiceAbility error:" + error); - } - return new FirstServiceAbilityStub("first ts service stub"); - }, - onDisconnect(want) { - console.log("ServiceAbility onDisconnect"); - let value = JSON.stringify(want); - console.log("ServiceAbility want:" + value); - }, - onCommand(want, startId) { - console.info('ServiceAbility onCommand'); - let value = JSON.stringify(want); - console.log("ServiceAbility want:" + value); - console.log("ServiceAbility startId:" + startId); - } -}; -``` diff --git a/en/application-dev/ability/stage-brief.md b/en/application-dev/ability/stage-brief.md deleted file mode 100644 index 427495774a..0000000000 --- a/en/application-dev/ability/stage-brief.md +++ /dev/null @@ -1,105 +0,0 @@ -# Stage Model Overview - -## Design Ideas - -The stage model is designed to make it easier to develop complex applications in the distributed environment. - -The following figure shows the design ideas of the stage model. - -![stagedesign](figures/stagedesign.png) - -The stage model is designed based on the following considerations: - -- **Balance between application capabilities and overall system power consumption** - - On a running device, resources are preferentially guaranteed for foreground applications, on the prerequisites that the overall power consumption requirements of the system are met. The stage model balances the application capabilities and overall system power consumption through ability and UI separation, strict background control, scenario-based service mechanism, and single-process model. - -- **Native support for component continuation and collaboration** - - OpenHarmony natively supports distributed deployment. Therefore, its application framework must be designed for easier component migration and collaboration. The stage model achieves this design objective by providing features such as separation between ability and UI as well as integration of UI display and service capabilities. - -- **Support for multiple device types and window forms** - - To support multiple device types and facilitate the implementation of different window forms, the component manager and window manager must be decoupled at the architecture layer for easier tailoring. To achieve this goal, the stage model redefines the ability lifecycle and implements unidirectional dependency for the component manager and window manager. - - -## Basic Concepts - -The following figure shows the basic concepts in the stage model. - -![stageconcept](figures/stageconcept.png) - -- **HAP**: Harmony Ability Package, also called module, which is the basic unit for building, distributing, and loading OpenHarmony applications. Each HAP has a unique name, which is called **moduleName**, in an application. -- **Bundle**: an OpenHarmony application identified by **appid**. A bundle can contain multiple HAP files. Each application has a **bundleName**. However, **bundleName** must be used together with **appid** and other information to uniquely identify an application. -- **AbilityStage**: runtime class of an HAP. It is created when the HAP is loaded to the process for the first time and is visible to developers in the runtime. -- **Application**: runtime class of a bundle, which is invisible to developers in the runtime. -- **Context**: base class that the context classes of **Ability** and **ExtensionAbility** classes inherit. This class provides various capabilities that can be invoked by developers in the runtime, and various information such as the bundle name, module name, and path. -- **Ability**: class that provides lifecycle callbacks, holds the **AbilityContext** class, and supports component continuation and collaboration. -- **ExtensionAbility**: general name of scenario-based service extension abilities. The system defines multiple scenario-based **ExtensionAbility** classes, each of which has its own **ExtensionContext**. -- **WindowStage**: local window manager. -- **Window**: basic unit managed by the window manager. It has an ArkUI engine instance. -- **ArkUI Page**: ArkUI development framework page. - - -## Lifecycle - -The ability and ability stage lifecycles are the rudiments of the basic process of an application. For details about how these lifecycles differ from those in the FA model, see [Ability Framework Overview](ability-brief.md). This section focuses on the ability lifecycle transition and the scheduling relationships between the ability, ability stage, and window stage. - -![stageabilitylifecyclecallback](figures/stageabilitylifecyclecallback.png) - -To implement device-specific tailoring and multi-window scalability, OpenHarmony decouples the component manager from the window manager. The ability lifecycle defined in the stage model includes only the creation, destruction, foreground, and background states. The gain focus and lose focus states that are closely related to UI content are defined in the window stage. This implements weak coupling between the abilities and windows. On the service side, the window manager notifies the component manager of the foreground and background changes, so the component manager only senses the foreground and background changes but not the focus changes. - -There are two lifecycle states related to **WindowStage** in **Ability**: **onWindowStageCreate** and **onWindowStageDestroy**. They are valid only for devices with the window display capability. **onWindowStageCreate** is invoked when a window stage is created, where you can call **loadContent** to set pages to be loaded for the ability. **onWindowStageDestroy** is invoked when the window stage is destroyed, where you can release resources. - - -## Ability Instances and Missions - -Abilities can be started in any of the following modes: - -+ **Singleton**: For each type of ability, only one instance exists in the application process. **Ability1** in the figure below is started in singleton mode. - -+ **Standard**: Each time **startAbility** is called, an instance of the specified ability type is created in the application process. **Ability2** in the figure below is started in standard mode. - -+ **Specified**: Before creating an **Ability** instance, you can create a key for the instance. Each time **startAbility** is called, the system asks the application which ability instance (corresponding to a key) will be used. **Ability3** in the figure below is started in specified mode. - -Each ability instance corresponds to a mission in **Launcher Recent**. - -The mission corresponding to an ability instance has a snapshot of the ability instance. After the ability instance is destroyed, the ability class information and snapshot are retained in the mission until the user deletes the information or the storage space reaches the upper limit. - - ![AbilityComponentInstanceMission](figures/AbilityComponentInstanceMission.png) - -## ExtensionAbility Mechanism - -Different from the ability used for page display, the extension ability provides a restricted service running environment. It has the following features: - -- Its process runs independently from the main process and shares the same storage sandbox with the main process. There is no inter-process communication (IPC) between the process and the main process. - -- It has an independent context that provides scenario-specific APIs. - -- It is created by the system, rather than by applications. - -- The lifecycles of the extension ability and process are managed by the system. - -The following figure uses the widget scenario as an example. You can inherit from the **FormExtensionAbility** base class to provide the widget details. The lifecycle of the **FormExtensionAbility** instance and that of the extension ability process where the instance is located are managed by **FormManagerService**, which is a system service. - -![ExtensionAbility](figures/ExtensionAbility.png) - -## Process Model - -All OpenHarmony applications are designed to meet the single-process model. In the single-process model, all processes in the application are created and managed by the system. Each application supports a maximum of three types of processes: - -- Main process: runs all ability components, pages, and service logic. - -- Extension process: runs classes derived from **ExtensionAbility** in the application. The lifecycle of this process is managed by a scenario-specific system service. - -- Render process: created for the WebView and used to load the WebView rendering library. - -The following figure shows the process model of an application. - -![stageprocessmodel](figures/stageprocessmodel.png) - -## Application Package Structure - -For details about the project directory structure of the stage model, see [OpenHarmony Project Overview](https://developer.harmonyos.com/en/docs/documentation/doc-guides/ohos-project-overview-0000001218440650#section56487581904). - -For details about how to configure the application package structure of the stage model, see [Application Package Structure Configuration File (Stage Model)](../quick-start/stage-structure.md). diff --git a/en/application-dev/application-models/Readme-EN.md b/en/application-dev/application-models/Readme-EN.md new file mode 100644 index 0000000000..a9473b7f6c --- /dev/null +++ b/en/application-dev/application-models/Readme-EN.md @@ -0,0 +1,2 @@ +# Application Models + -- GitLab