Ability

Package ohos.aafwk.ability

Class Ability

java.lang.Object

ohos.app.AbilityContext

ohos.aafwk.ability.Ability

public class Ability

extends AbilityContext

implements ILifecycle

An ability is an abstraction of functionalities that a HarmonyOS application can provide. Abilities of HarmonyOS applications are classified into two types: Feature Ability and Particle Ability. A Feature Ability represents an ability with a UI and is designed to interact with users. A Particle Ability represents an ability without a UI and is mainly used to provide support for FAs, for example, providing computing capabilities as a background service or providing data access capabilities as a data repository. The two types of abilities offer different templates for you to implement different functionalities. At present, HarmonyOS provides the following types of ability templates:

Note: In the description below, a Page, Service, or Data ability indicates an ability using the respective template, whereas the ability alone indicates an ability using any type of templates.

Page: An ability that displays a UI. The UI is presented through AbilitySlice. You must override the onStart(ohos.aafwk.content.Intent) method and use the setMainRoute(java.lang.String) and addActionRoute(java.lang.String,java.lang.String) methods to configure the entry of a Page ability.

Service: An ability that runs in the background and has no UI. It is used to develop services that always run in the background or are connected to other abilities. When a Service ability is connected to others, a remote object is returned, and you can use the remote object to call the functionalities provided by the Service ability.

Data: An ability that is used to operate data and has no UI. It provides methods for inserting, deleting, updating, and querying data, and opening files. You must implement these methods.

Ability Profile

Each application has a configuration file: config.json. This file is stored in the root directory of Java code.

 ├── entry

 │   ├── libs

 │   ├── src

 │   │   ├── main

 │   │   │   ├── java

 │   │   │   │   └── com

 │   │   │   │       └── example

 │   │   │   │           └── myapplication

 │   │   │   │               ├── slice

 │   │   │   │               │   └── PageAbilitySlice.java

 │   │   │   │               └── PageAbility.java

 │   │   │   ├── resources

 │   │   │   │     ├── base

 │   │   │   │     │   ├── element

 │   │   │   │     │   │   └── string.json

 │   │   │   │     │   └── media

 │   │   │   │     │       └── icon.png

 │   │   │   │     └── rawfile

 │   │   │   └── config.json

Description of the file structure of an application is as follows:

entry stores the code, resource files, and configuration file of the application. The folder name is editable.

entry/libs stores third-party library files. This directory is automatically generated by the IDE upon project creation.

entry/src/main/java is used for code development. You can change file names in this directory as required. This directory is automatically generated by the IDE upon project creation.

entry/src/main/resources/base/media stores PNG and JPG image files for your application. This directory is automatically generated by the IDE upon project creation.

entry/src/main/resources/base/element stores resource files used for reading text resources. This directory is automatically generated by the IDE upon project creation.

The entry/src/main/config.json file is located in the main root directory. This file contains configuration information about the application. The system runs the application and displays contents on the UI based on the content of this file. This file is automatically generated by the IDE upon project creation.

To develop a new ability, you must register the ability in the config.json file. Example code:

 {

     "module":{

         ...

         "abilities":[

           {

               ...

               "description": "Main ability of hiworld",

               "name": ".MainAbility",

               "label": "main ability",

               "icon": "main-ability.png",

               "type": "page",

               "visible": true,

               "orientation": "unspecified",

               "launch-mode": "standard",

               ...

           }

         ]

         ...

     }

 }

Note: All abilities of an application must be registered in this file and attached to the abilities tag.

The type tag indicates the type of templates used by an ability, and its value page, service, or provider indicates the Page, Service, or Data template, respectively. The type tag must be specified.

The name tag indicates the name of an ability and must be specified.

You can retain the default values for other tags.

Ability Lifecycle

As the fundamental unit of an application, an ability has the following four lifecycle states:

INITIAL: The ability is loaded to the memory but is not running. It is the initial state of all abilities.

INACTIVE: The ability has been loaded and executed but is not interactive. Generally, it is an intermediate state before the ability changes to ACTIVE or BACKGROUND. In this state, the UI may be visible but cannot receive input events.

ACTIVE: The ability is visible and interactive. It is considered that the ability has focus.

BACKGROUND: The ability is invisible. If system memory becomes insufficient, abilities in this state are destroyed first.

The figure below shows a complete ability lifecycle. A specific callback is executed for each state transition. You can override the callback methods.

Note: All Page abilities must implement onStart(ohos.aafwk.content.Intent) to set their UIs. To override a lifecycle callback method, you must first call the callback method corresponding to the parent class, for example, super.onStart(). The state transition is implemented on the main thread. Therefore, you are advised to execute short logic in the lifecycle callback to prevent the main thread of the ability from being blocked.

The following are all lifecycle callback methods of the ability:

 public class MainAbility extends Ability {

      protected void onStart(Intent intent);



      protected void onActive();



      protected void onInactive();



      protected void onForeground(Intent intent);



      protected void onBackground();



      protected void onStop();

  }

For details on lifecycle callback, see AbilitySlice.

Starting Abilities

The startAbility(ohos.aafwk.content.Intent) method is used to start a new ability, which is placed at the top of the ability stack. It uses the parameter Intent to describe the ability. The code below shows how to start an ability:

         Button button = new Button(this);

         button.setClickedListener(listener -> {

             Operation operation = new Intent.OperationBuilder()

                     .withDeviceId("")

                     .withBundleName("com.huawei.hiworld")

                     .withAbilityName("com.huawei.hiworld.MainAbility")

                     .build();



             Intent intent = new Intent();

             intent.setOperation(operation);

             intent.setParam("age", 10);



             startAbility(intent);

         });

Connecting Abilities

The connectAbility(ohos.aafwk.content.Intent,ohos.aafwk.ability.IAbilityConnection) method is used to connect to a Service ability. It has two parameters: Intent and IAbilityConnection. Intent provides information about the target Service ability to connect, and IAbilityConnection is a callback object used to notify you of the connection result (success or failure).

In contrast to connectAbility(ohos.aafwk.content.Intent,ohos.aafwk.ability.IAbilityConnection), the disconnectAbility(ohos.aafwk.ability.IAbilityConnection) method is used to disconnect from a connected Service ability.

For Service abilities, you can override the onConnect(ohos.aafwk.content.Intent) method to provide a RemoteObject for calling. By default, null is returned.

     protected IRemoteObject onConnect(Intent intent) {

         return null;

     }

Since:

1

SystemCapability

SystemCapability.Aafwk#ABILITY

All Implemented Interfaces:

ILifecycle, Context

Direct Known Subclasses:

AccessibleAbility, AceAbility, AVBrowserService, FractionAbility, HostService, InputMethodAbility, IntentAbility, OffHostService, WorkScheduler