Ability Development

When to Use

Unlike the FA model, the stage model requires you to declare the application package structure in the module.json and app.json files during application development. For details about the configuration file, see Application Package Structure Configuration File. To develop abilities based on the stage model, implement the following logic:

• Create abilities for an application that involves 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

The ability supports three launch types: singleton, multi-instance, and instance-specific. Each launch type, specified by launchType in the module.json file, specifies the action that can be performed when the ability is started.

By default, the singleton mode is used. The following is an example of the module.json 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 APIs 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.

   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 Ability class.

   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((data) => {
            console.log("MainAbility load content succeed with data: " + JSON.stringify(data))
        }).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("MyAbilityStage config language" + config.language)
    }
}

Requesting Permissions

If an application needs to obtain user privacy information or use system capabilities, for example, obtaining location information or using the camera to take photos or record videos, it must request the permission from consumers. During application development, you need to specify the involved sensitive permissions, declare the required permissions in module.json, and use the requestPermissionsFromUser API to request the permission from consumers in the form of a dialog box. The following uses the permissions for calendar access as an example.

Declare the required permissions in the module.json file.

"requestPermissions": [
    {
    "name": "ohos.permission.READ_CALENDAR"
    }
]

Request the permissions from consumers in the form of a dialog box:

let context = this.context
let permissions: Array<string> = ['ohos.permission.READ_CALENDAR']
context.requestPermissionsFromUser(permissions).then((data) => {
    console.log("Succeed to request permission from user with data: " + JSON.stringify(data))
}).catch((error) => {
    console.log("Failed to request permission from user with error: " + JSON.stringify(error))
})

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 the configuration item in Settings or the icon 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. For details on the configuration, see Configuration.

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 overwrite 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 implement of the onConfigurationUpdated callback in the AbilityStage class. The callback is triggered when the system language and color mode are changed.

import Ability from '@ohos.application.Ability'
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 implement 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 and 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((data) => {
    console.log("Succeed to start ability with data: " + JSON.stringify(data))
}).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((data) => {
    console.log("Succeed to start remote ability with data: " + JSON.stringify(data))
}).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 the permission, see Requesting Permissions.

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) {
    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 '@system.router'

@Entry
@Component
struct Index {
  newWant = undefined

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