Ability Development

When to Use

Ability development in the stage model 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. 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.
• Connect to and disconnect from a Service Extension ability. For details, see Service Extension Ability Development.
• Continue the ability on another device. For details, see Ability Continuation Development.

Launch Type

An ability can be launched in the standard, singleton, or specified mode, as configured by launchType in the module.json5 file. Depending on the launch type, the action performed when the ability is started differs, as described below.

By default, the singleton mode is used. The following is an example of the module.json5 file:

{
  "module": {
    "abilities": [
      {
        "launchType": "singleton",
      }
    ]
  }
}

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.

Table 1 AbilityStage APIs

The table below describes the APIs provided by the Ability class. For details about the APIs, see Ability.

Table 2 Ability APIs

Implementing AbilityStage and Ability Lifecycle Callbacks

To create Page abilities for an application in the stage model, you must implement the AbilityStage class and ability lifecycle callbacks, and use the Window class to set the pages. The sample code is as follows:

1. Import the AbilityStage module.

   import AbilityStage from "@ohos.application.AbilityStage"
   

2. Implement the AbilityStage class. The default relative path generated by the APIs is entry\src\main\ets\Application\AbilityStage.ts.

   export default class MyAbilityStage extends AbilityStage {
    onCreate() {
        console.log("MyAbilityStage onCreate")
    }
   }
   

3. Import the Ability module.

   import Ability from '@ohos.application.Ability'
   

4. Implement the lifecycle callbacks of the UIAbility class. The default relative path generated by the APIs is entry\src\main\ets\entryability\EntryAbility.ts.

   In the onWindowStageCreate(windowStage) API, use loadContent to set the application page to be loaded. For details about how to use the Window APIs, see Window Development.

   export default class MainAbility extends Ability {
    onCreate(want, launchParam) {
        console.log("MainAbility onCreate")
    }
   
    onDestroy() {
        console.log("MainAbility onDestroy")
    }
   
    onWindowStageCreate(windowStage) {
        console.log("MainAbility onWindowStageCreate")
   
        windowStage.loadContent("pages/index").then(() => {
            console.log("MainAbility load content succeed")
        }).catch((error) => {
            console.error("MainAbility load content failed with error: " + JSON.stringify(error))
        })
    }
   
    onWindowStageDestroy() {
        console.log("MainAbility onWindowStageDestroy")
    }
   
    onForeground() {
        console.log("MainAbility onForeground")
    }
   
    onBackground() {
        console.log("MainAbility onBackground")
    }
   }
   

Obtaining AbilityStage and Ability Configurations

Both the AbilityStage and Ability classes have the context attribute. An application can obtain the context of an Ability instance through this.context to obtain the configuration details.

The following example shows how an application obtains the bundle code directory, HAP file name, ability name, and system language through the context attribute in the AbilityStage class. The sample code is as follows:

import AbilityStage from "@ohos.application.AbilityStage"

export default class MyAbilityStage extends AbilityStage {
    onCreate() {
        console.log("MyAbilityStage onCreate")
        let context = this.context
        console.log("MyAbilityStage bundleCodeDir" + context.bundleCodeDir)

        let currentHapModuleInfo = context.currentHapModuleInfo
        console.log("MyAbilityStage hap module name" + currentHapModuleInfo.name)
        console.log("MyAbilityStage hap module mainAbilityName" + currentHapModuleInfo.mainAbilityName)

        let config = this.context.config
        console.log("MyAbilityStage config language" + config.language)
    }
}

The following example shows how an application obtains the bundle code directory, HAP file name, ability name, and system language through the context attribute in the Ability class. The sample code is as follows:

import Ability from '@ohos.application.Ability'
export default class MainAbility extends Ability {
    onCreate(want, launchParam) {
        console.log("MainAbility onCreate")
        let context = this.context
        console.log("MainAbility bundleCodeDir" + context.bundleCodeDir)

        let abilityInfo = this.context.abilityInfo;
        console.log("MainAbility ability bundleName" + abilityInfo.bundleName)
        console.log("MainAbility ability name" + abilityInfo.name)

        let config = this.context.config
        console.log("MainAbility config language" + config.language)
    }
}

Notifying of Environment Changes

Environment changes include changes of global configurations and ability configurations. Currently, the global configurations include the system language and color mode. The change of global configurations is generally triggered by configuration items in Settings or icons in Control Panel. The ability configuration is specific to a single Ability instance, including the display ID, screen resolution, and screen orientation. The configuration is related to the display where the ability is located, and the change is generally triggered by the window. Before configuring a project, define the project in the Configuration class.

For an application in the stage model, when the configuration changes, its abilities are not restarted, but the onConfigurationUpdated(config: Configuration) callback is triggered. If the application needs to perform processing based on the change, you can override onConfigurationUpdated. Note that the Configuration object in the callback contains all the configurations of the current ability, not only the changed configurations.

The following example shows the implementation of the onConfigurationUpdated callback in the AbilityStage class. The callback is triggered when the system language and color mode are changed.

import AbilityStage from '@ohos.application.AbilityStage'
import ConfigurationConstant from '@ohos.application.ConfigurationConstant'

export default class MyAbilityStage extends AbilityStage {
    onConfigurationUpdated(config) {
        if (config.colorMode === ConfigurationConstant.ColorMode.COLOR_MODE_DARK) {
            console.log('colorMode changed to dark')
        }
    }
}

The following example shows the implementation of the onConfigurationUpdated callback in the Ability class. The callback is triggered when the system language, color mode, or display parameters (such as the direction and density) change.

import Ability from '@ohos.application.Ability'
import ConfigurationConstant from '@ohos.application.ConfigurationConstant'

export default class MainAbility extends Ability {
    direction : number;

    onCreate(want, launchParam) {
        this.direction = this.context.config.direction
    }

    onConfigurationUpdated(config) {
        if (this.direction !== config.direction) {
            console.log(`direction changed to ${config.direction}`)
        }
    }
}

Starting an Ability

Available APIs

The Ability class has the context attribute, which belongs to the AbilityContext class. The AbilityContext class has the abilityInfo, currentHapModuleInfo, and other attributes as well as the APIs used for starting abilities. For details, see AbilityContext.

Table 3 AbilityContext APIs

Starting an Ability on the Same Device

An application can obtain the context of an Ability instance through this.context and then use the startAbility API in the AbilityContext class to start the ability. The ability can be started by specifying Want, StartOptions, and accountId, and the operation result can be returned using a callback or Promise instance. The sample code is as follows:

let context = this.context
var want = {
    "deviceId": "",
    "bundleName": "com.example.MyApplication",
    "abilityName": "MainAbility"
};
context.startAbility(want).then(() => {
    console.log("Succeed to start ability")
}).catch((error) => {
    console.error("Failed to start ability with error: "+ JSON.stringify(error))
})

Starting an Ability on a Remote Device

This feature applies only to system applications, since the getTrustedDeviceListSync API of the DeviceManager class is open only to system applications. In the cross-device scenario, you must specify the ID of the remote device. The sample code is as follows:

let context = this.context
var want = {
    "deviceId": getRemoteDeviceId(),
    "bundleName": "com.example.MyApplication",
    "abilityName": "MainAbility"
};
context.startAbility(want).then(() => {
    console.log("Succeed to start remote ability")
}).catch((error) => {
    console.error("Failed to start remote ability with error: " + JSON.stringify(error))
})

Obtain the ID of a specified device from DeviceManager. The sample code is as follows:

import deviceManager from '@ohos.distributedHardware.deviceManager';
function getRemoteDeviceId() {
    if (typeof dmClass === 'object' && dmClass != null) {
        var 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");
    }
}

Request the permission ohos.permission.DISTRIBUTED_DATASYNC from consumers. This permission is used for data synchronization. For details about the sample code for requesting permissions, see abilityAccessCtrl.requestPermissionsFromUse.

Starting an Ability with the Specified Page

If the launch type of an ability is set to singleton and the ability has been started, the onNewWant callback is triggered when the ability is started again. You can pass start options through the want. For example, to start an ability with the specified page, use the uri or parameters parameter in the want to pass the page information. Currently, the ability in the stage model cannot directly use the router capability. You must pass the start options to the custom component and invoke the router method to display the specified page during the custom component lifecycle management. The sample code is as follows:

When using startAbility to start an ability again, use the uri parameter in the want to pass the page information.

async function reStartAbility() {
  try {
    await this.context.startAbility({
      bundleName: "com.sample.MyApplication",
      abilityName: "MainAbility",
      uri: "pages/second"
    })
    console.log('start ability succeed')
  } catch (error) {
    console.error(`start ability failed with ${error.code}`)
  }
}

Obtain the want parameter that contains the page information from the onNewWant callback of the ability.

import Ability from '@ohos.application.Ability'

export default class MainAbility extends Ability {
  onNewWant(want, launchParams) {
    globalThis.newWant = want
  }
}

Obtain the want parameter that contains the page information from the custom component and process the route based on the URI.

import router from '@ohos.router'

@Entry
@Component
struct Index {
  newWant = undefined

  onPageShow() {
    console.info('Index onPageShow')
    let newWant = globalThis.newWant
    if (newWant.hasOwnProperty("uri")) {
      router.push({ url: newWant.uri });
      globalThis.newWant = undefined
    }
  }
}