General Rules

Synchronous API

A synchronous API directly returns the calling result. The result can be of any type. For details, please refer to the API reference. The following is an example:

console.log(JSON.stringify(app.getInfo()))

Asynchronous API

An asynchronous API does not return the calling result directly. It, however, calls a proper callback function you defined when a task ends. There are two asynchronous call methods available: asynchronous API callback and Promise, where Promise is supported in versions later than 1010. The following table lists the callback functions supported by asynchronous APIs.

The three callback functions success, fail, and cancel are mutually exclusive. One of them will be called based on the execution result. When this callback is complete, the complete function is then executed.

The following is an example:

prompt.showContextMenu({
  itemList: ['item1', 'item2'],
  itemColor: '#ff33ff',
  success: function(data) {
    console.log("handling callback");
  },
  fail: function(data, code) {
    console.log("handling fail, code=" + code);
  },
  cancel: function(data) {
    console.log("handling cancel");
  },
  complete: function() {
    console.log("handling complete");
  },
})

[h2]Promise (1010+)

An asynchronous API supports Promise, which enables asynchronous programming for higher readability and better control.

If no callback function (success, fail, cancel, or complete) is passed during an API call, a Promise object will be returned, based on which you can process the API call result.

The following uses the system.device API as an example:

async function testAsync(){
    try{
    let res = await device.getDeviceId()
        console.debug("get device id " + JSON.stringify(res.data)) 
    }catch(err){
        console.log("get device id error " + e.code )
    }
}

The value returned by the device.getDeviceId() API is a Promise object. You can use await to obtain the successful call result and use catch to obtain the failure result. If an API is successfully called, the res object (res = {data}) is returned. You can use res.data to obtain the result returned by the API and use res.code to obtain the error code returned when the API fails to be called.

If you use the catch method for each API, the code will be cumbersome. You are advised to use one catching function to simplify the code.

function catching(promise){
         return promise.then(res =>res).catch(err =>err)
}
var ret = await catching(device.getDeviceId())

When any callback function is passed during an API call, the API will not return Promise but will return the execution result as defined in the asynchronous callback mode.

Inject @babel/runtime/regenerator into the app.ux file. Sample code:

// This operation is required only if the engine version configured in minPlatformVersion is earlier than 1040.
const injectRef = Object.getPrototypeOf(global) || global;
// injection regeneratorRuntime
injectRef.regeneratorRuntime = require('@babel/runtime/regenerator');

Callback API

Like an asynchronous API, a callback API does not return the execution result directly. It calls a proper callback function you defined instead. Unlike an asynchronous API, a callback API may call callback functions more than once to return the execution results. The following table lists the callback functions supported by callback APIs.

Take the geographical location API (system.geolocation) as an example.

• If geolocation.subscribe is called to listen to geographical location changes, the callback function passed will be called whenever the geographical location changes and the new location will be returned.
• If a user refuses to grant the permission, the fail callback function is called and the API call ends. No more callback function will be called.

geolocation.subscribe({
  callback:function(ret){console.log("handling callback");},
  fail: function(data, code) {
    console.log("handling fail, code=" + code);
  }
})

Asynchronous Callback API

Like an asynchronous API, an asynchronous callback API does not return the execution result directly. It calls a proper callback function you defined instead.

Different from an asynchronous API, an asynchronous callback API accepts only one callback. The API call result will be determined based on the callback result. The callback function is called only once.

The following table lists the callback functions supported by asynchronous callback APIs.

alipay.pay({
  orderInfo:"order1",
  callback:function(ret){console.log("handling callback");}
})

Correctly Implementing Callback Functions

Except for synchronous APIs, the asynchronous, callback, and asynchronous callback APIs do not return execution results directly after being called. Instead, they execute a callback function based on the API execution result. In addition, the page where the API is called may be different from the page where the callback function is executed.

Assume that the page called by the API is A. When the callback function is executed, the actual situation may be one of the following:

1. Page A is still displayed.
2. Page A is switched to the background, and page B is displayed.
3. Page A has been destroyed.

The callback function needs to check the page status based on the following attributes and take the proper action accordingly: $valid and $visible (Boolean data type)

// Indicates whether a page is valid (not destroyed).
this.$valid
// Indicates whether a page is in the background.
this.$visible

For example, to display the list of merchants at the current geographical location of a user, you need to call the geolocation.getLocation() API to obtain the current location information and then call the fetch.fetch() API to obtain the merchants. When implementing the callback function of geolocation.getLocation(), you need to check the status of the current page and take an action accordingly.

• If the page is still displayed, continue to call the fetch API to obtain the merchants.
• If the page has been switched to the background, the current geographical location is cached.
• If the page has been destroyed, no processing is performed.

The sample code is as follows:

geolocation.getLocation({
  success:function(data){
    if (this.$valid && this.$visible) {
      // The page is being displayed.
    }
    else if (this.$valid && !this.$visible) {
      // The page is in the background.
    }
    else {
      // The page is being destroyed.
    }
  }.bind(this),
  fail: function(data, code) {
    console.log("handling fail, code=" + code);
  }
})

The callback function can be called multiple times by the callback API. If the callback function is repeatedly called after the page is switched to the background or destroyed, the app response will become slow and memory leaks may occur. Therefore, you are advised to use either of the following methods to cancel the call:

1. Cancel the call in the onHide or onDestroy function of the page.
2. Check the page status based on the callback function and cancel the call when discovering that the page has been switched to the background or destroyed.

Method 1 is recommended as it can cancel a call promptly and prevent resource waste.

For example, for a page that calls the geolocation.subscribe function to record a user's trajectory:

The logic for canceling the call by using method 1 is as follows:

• Call the geolocation.unsubscribe function in the onDestroy function to cancel the subscription.
• Determine the status of the current page in the callback function and process the page properly.

The sample code is as follows:

export default {
  onDestroy () {
    geolocation.unsubscribe()
  },
  record() {
    geolocation.getLocation({
      success:function(data){
        if (this.$valid && this.$visible) {
          // The page is being displayed, and the trajectory is recorded.
        }
        else if (this.$valid && !this.$visible) {
          // The page is in the background and the trajectory is recorded.
        }
        else {
          // The page is being destroyed and does not need to be processed.
        }
      }.bind(this),
      fail: function(data, code) {
        console.log("handling fail, code=" + code);
      }
    })
  }
}

The logic for canceling the call by using method 2 is as follows:

• Check the page status in the success callback function called by geolocation.subscribe.
• If the page has been destroyed, call the geolocation.unsubscribe API to cancel the subscription.

The sample code is as follows:

geolocation.getLocation({
  success:function(data){
    if (this.$valid && this.$visible) {
      // The page is being displayed, and the trajectory is recorded.
    }
    else if (this.$valid && !this.$visible) {
      // The page is in the background and the trajectory is recorded.
    }
    else {
      // The page is being destroyed.
      geolocation.unsubscribe()
    }
  }.bind(this),
  fail: function(data, code) {
    console.log("handling fail, code=" + code);
  }
})

This method can be used in the lifecycle callback function of an app. It is independent of the page where the API is called. Therefore, it is valid as long as the app is running. However, we strongly recommend that you cancel a callback when confirming that the API needs not be called.

Common Result Codes

Links

[h2]Cases

• Rectifying the Asynchronous Calling Error "regeneratorRuntime is not defined"
• Failed to Obtain the Value Returned by an Asynchronous Callback Method