diff --git a/en/readme/ability.md b/en/readme/ability.md new file mode 100644 index 0000000000000000000000000000000000000000..3219acba7084fadc68464d3a9ed9db7b7fd54040 --- /dev/null +++ b/en/readme/ability.md @@ -0,0 +1,135 @@ +# Ability Framework + +## Overview + +The **ability framework** (also called the ability management framework) is used to centrally schedule and manage the running and lifecycle of abilities. An application process can support multiple abilities, and an ability can be called either within a process or across processes. The Ability Manager Service provided in the framework schedules and manages abilities in an application and manages the lifecycle changes of these abilities. + +![](figures/aafwk.png) + +**Architecture Description** + +- **Ability Kit** provides basic running environment for an ability to run. **Ability** is the minimum unit for the system to schedule an application. It is a component that can implement an independent functionality. An application can contain one or more **Ability** instances. There are two types of abilities: Feature Ability (FA) and Particle Ability (PA). FAs use the Page template, and PAs use the Service and Data templates. (The abilities implemented using the Page, Service, or Data template are referred to as the Page, Service, or Data abilities for short, respectively.) + +- **AbilityManagerService** is a system service used to coordinate the running relationships and lifecycle states of **Ability** instances. + - The AbilityStackManager sub-module maintains the presentation sequence of abilities in the stack. + - The AbilityConnectManager sub-module manages connections to Service abilities. + - The DataAbilityManager sub-module manages Data abilities. + - The AppScheduler sub-module schedules and manages the App Manager Service. + - The AbilityScheduler sub-module schedules and manages abilities. + - The LifecycleDeal sub-module schedules and manages ability lifecycle events. + +The **ability lifecycle** is a general term for all states of an ability (either a Page or a Service ability), such as **INACTIVE**, **ACTIVE**, and **BACKGROUND**. + + - The following figure shows the transitions between different states in a Page ability's lifecycle. + +![PageAbility-Lifecycle](figures/page-ability-lifecycle.png) + + + + - The following figure shows the transitions between different states in a Service ability's lifecycle. + +![ServiceAbility-Lifecycle](figures/service-ability-lifecycle.png) + +**Description of ability lifecycle states:** + + - **UNINITIALIZED**: The ability is not initialized. This state is a temporary state. An ability changes directly to the **INITIAL** state upon its creation. + + - **INITIAL**: This state refers to the initial or stopped state. The ability in this state is not running. The ability enters the **INACTIVE** state after it is started. + + - **INACTIVE**: The ability is visible but does not gain focus. This state is the same as the **ACTIVE** state because the concept of window focus is not supported currently. + + - **ACTIVE**: The ability is in the foreground and has focus. The ability changes from the **ACTIVE** state to the **INACTIVE** state before returning to the background. + + - **BACKGROUND**: The ability returns to the background. After being re-activated, the ability enters the **ACTIVE** state. After being destroyed, the ability enters the **INITIAL** state. + +The following figure shows the callbacks to be invoked during the transitions between different lifecycle states of a Page ability. + +![PageAbility-Lifecycle-Callbacks](figures/page-ability-lifecycle-callbacks.png) + + + +The following figure shows the callbacks to be invoked during the transitions between different lifecycle states of a Service ability. + +![Service-Ability-Lifecycle-Callbacks](figures/service-ability-lifecycle-callbacks.jpg) + + + +## Directory Structure + +``` +foundation/ +└──foundation/aafwk/standard + ├── frameworks + │ └── kits + │ └── ability # Core code for AbilityKit + ├── interfaces + │ └── innerkits + │ └── want # External APIs of the information carrier used for interaction between abilities + └── services + ├── abilitymgr # Framework code of the Ability Manager Service + ├── common # Log component + ├── test # Testing + └── tools # aa command code +``` + +## Usage Guidelines + +The application framework does not have the permission management capability. + +In the current version, the JavaScript APIs of the following modules are provided only for the system applications Launcher, Settings, and SystemUI. Significant changes may be provided in later versions. + +- @ohos.feature_ability.d.ts + +- @ohos.napi_ability_manager.d.ts + +- abilityinfo.d.ts + +- abilitymissioninfo.d.ts + +- applicationinfo.d.ts + +- appprocessstate.ts + +- common.d.ts + +- elementname.d.ts + +- moduleinfo.d.ts + +- processinfo.d.ts + +- want.d.ts + +## **aa Commands** + +**aa help** + +| Command | Description | +| ------- | ------------------ | +| aa help | Displays the command help information.| + +**aa start** + +| Command | Description | +| --------------------------------------------------------- | ------------------------ | +| aa start [-d ] -a -b | Starts an ability. The device ID can be empty.| + +Example: +``` +aa start -d 12345 -a com.ohos.app.MainAbility -b com.ohos.app +``` + +**aa dump** + +| Command | Description | +| ---------- | --------------------- | +| aa dump -a | Displays the ability information in the stack.| + +## Repositories Involved +Ability framework + +[ability_base](https://gitee.com/openharmony/ability_ability_base) + +[ability_runtime](https://gitee.com/openharmony/ability_ability_runtime) + +[form_fwk](https://gitee.com/openharmony/ability_form_fwk) diff --git a/en/readme/figures/aafwk.png b/en/readme/figures/aafwk.png new file mode 100644 index 0000000000000000000000000000000000000000..9c984fd666ab4ff18cdfb5e2035f06342249fd4a Binary files /dev/null and b/en/readme/figures/aafwk.png differ diff --git a/en/readme/figures/page-ability-lifecycle-callbacks.png b/en/readme/figures/page-ability-lifecycle-callbacks.png new file mode 100644 index 0000000000000000000000000000000000000000..42cbde8b3f2216141b68a8d12b84889b154af58e Binary files /dev/null and b/en/readme/figures/page-ability-lifecycle-callbacks.png differ diff --git a/en/readme/figures/page-ability-lifecycle.png b/en/readme/figures/page-ability-lifecycle.png new file mode 100644 index 0000000000000000000000000000000000000000..d4fff2a49bf103cb5d8763f271c847fc1b711723 Binary files /dev/null and b/en/readme/figures/page-ability-lifecycle.png differ diff --git a/en/readme/figures/service-ability-lifecycle-callbacks.jpg b/en/readme/figures/service-ability-lifecycle-callbacks.jpg new file mode 100644 index 0000000000000000000000000000000000000000..d24e65e9a1695fe80da4f64e734969ae0e08139a Binary files /dev/null and b/en/readme/figures/service-ability-lifecycle-callbacks.jpg differ diff --git a/en/readme/figures/service-ability-lifecycle.png b/en/readme/figures/service-ability-lifecycle.png new file mode 100644 index 0000000000000000000000000000000000000000..66c11ca4db7900696c064461cb7f774bfcd48d49 Binary files /dev/null and b/en/readme/figures/service-ability-lifecycle.png differ