@ohos.app.ability.UIAbility (UIAbility)

UIAbility is an application component that has the UI. The UIAbility module provides lifecycle callbacks such as component creation, destruction, and foreground/background switching. It also provides the following capabilities related to component collaboration:

Caller: an object returned by startAbilityByCall. The CallerAbility (caller) uses this object to communicate with the CalleeAbility (callee).
Callee: an internal object of UIAbility. The CalleeAbility (callee) uses this object to communicate with the CallerAbility (caller).

NOTE

The initial APIs of this module are supported since API version 9. Newly added APIs will be marked with a superscript to indicate their earliest API version. The APIs of this module can be used only in the stage model.

Modules to Import

import UIAbility from '@ohos.app.ability.UIAbility';

Attributes

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Name	Type	Readable	Writable	Description
context	UIAbilityContext	Yes	No	Context of the UIAbility.
launchWant	Want	Yes	No	Parameters for starting the UIAbility.
lastRequestWant	Want	Yes	No	Parameters used when the UIAbility was started last time.
callee	Callee	Yes	No	Object that invokes the stub service.

UIAbility.onCreate

onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void;

Called to initialize the service logic when a UIAbility instance in the completely closed state is created. In other words, a UIAbility instance enters this lifecycle callback from a cold start.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Information related to this UIAbility, including the ability name and bundle name.
param	AbilityConstant.LaunchParam	Yes	Parameters for starting the UIAbility, and the reason for the last abnormal exit.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import Want from '@ohos.app.ability.Want';

class MyUIAbility extends UIAbility {
    onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
        console.log('onCreate, want: ${want.abilityName}');
    }
}

UIAbility.onWindowStageCreate

onWindowStageCreate(windowStage: window.WindowStage): void

Called when a WindowStage is created for this UIAbility.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
windowStage	window.WindowStage	Yes	WindowStage information.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';

class MyUIAbility extends UIAbility {
    onWindowStageCreate(windowStage: window.WindowStage) {
        console.log('onWindowStageCreate');
    }
}

UIAbility.onWindowStageDestroy

onWindowStageDestroy(): void

Called when the WindowStage is destroyed for this UIAbility.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Example

import UIAbility from '@ohos.app.ability.UIAbility';

class MyUIAbility extends UIAbility {
    onWindowStageDestroy() {
        console.log('onWindowStageDestroy');
    }
}

UIAbility.onWindowStageRestore

onWindowStageRestore(windowStage: window.WindowStage): void

Called when the WindowStage is restored during the migration of this UIAbility, which is a multi-instance ability.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
windowStage	window.WindowStage	Yes	WindowStage information.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import window from '@ohos.window';

class MyUIAbility extends UIAbility {
    onWindowStageRestore(windowStage: window.WindowStage) {
        console.log('onWindowStageRestore');
    }
}

UIAbility.onDestroy

onDestroy(): void|Promise<void>;

Called when this UIAbility is destroyed to clear resources.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Example

import UIAbility from '@ohos.app.ability.UIAbility';

class MyUIAbility extends UIAbility {
    onDestroy() {
        console.log('onDestroy');
    }
}

After the onDestroy() lifecycle callback is executed, the application may exit. Consequently, the asynchronous function (for example, asynchronously writing data to the database) in onDestroy() may fail to be executed. You can use the asynchronous lifecycle to ensure that the subsequent lifecycle continues only after the asynchronous function in onDestroy() finishes the execution.

import UIAbility from '@ohos.app.ability.UIAbility';

class MyUIAbility extends UIAbility {
  async onDestroy() {
      console.log('onDestroy');
      // Call the asynchronous function.
  }
}

UIAbility.onForeground

onForeground(): void;

Called when this UIAbility is switched from the background to the foreground.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Example

import UIAbility from '@ohos.app.ability.UIAbility';

class MyUIAbility extends UIAbility {
    onForeground() {
        console.log('onForeground');
    }
}

UIAbility.onBackground

onBackground(): void;

Called when this UIAbility is switched from the foreground to the background.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Example

import UIAbility from '@ohos.app.ability.UIAbility';

class MyUIAbility extends UIAbility {
    onBackground() {
        console.log('onBackground');
    }
}

UIAbility.onContinue

onContinue(wantParam: { [key: string]: Object }): AbilityConstant.OnContinueResult;

Called to save data during the ability migration preparation process.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
wantParam	{[key: string]: Object}	Yes	want parameter.

Return value

Type	Description
AbilityConstant.OnContinueResult	Continuation result.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';

class MyUIAbility extends UIAbility {
    onContinue(wantParams: Record<string, Object>) {
        console.log('onContinue');
        wantParams['myData'] = 'my1234567';
        return AbilityConstant.OnContinueResult.AGREE;
    }
}

UIAbility.onNewWant

onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void;

Called when a UIAbility instance that has undergone the following states is started again: started in the foreground, running in the foreground, and switched to the background In other words, a UIAbility instance enters this lifecycle callback from a hot start.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
want	Want	Yes	Want information, such as the ability name and bundle name.
launchParam	AbilityConstant.LaunchParam	Yes	Reason for the UIAbility startup and the last abnormal exit.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';

class MyUIAbility extends UIAbility {
    onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam) {
        console.log(`onNewWant, want: ${want.abilityName}`);
        console.log(`onNewWant, launchParam: ${JSON.stringify(launchParam)}`);
    }
}

UIAbility.onDump

onDump(params: Array<string>): Array<string>;

Dumps client information.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
params	Array<string>	Yes	Parameters in the form of a command.

Example

import UIAbility from '@ohos.app.ability.UIAbility';

class MyUIAbility extends UIAbility {
    onDump(params: Array<string>) {
        console.log(`dump, params: ${JSON.stringify(params)}`);
        return ['params'];
    }
}

UIAbility.onSaveState

onSaveState(reason: AbilityConstant.StateType, wantParam : {[key: string]: Object}): AbilityConstant.OnSaveResult;

Called when the framework automatically saves the UIAbility state in the case of an application fault. This API is used together with appRecovery. If automatic state saving is enabled, onSaveState is called to save the state of this UIAbility.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
reason	AbilityConstant.StateType	Yes	Reason for triggering the callback to save the UIAbility state.
wantParam	{[key: string]: Object}	Yes	want parameter.

Return value

Type	Description
AbilityConstant.OnSaveResult	Whether the UIAbility state is saved.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';

class MyUIAbility extends UIAbility {
  onSaveState(reason: AbilityConstant.StateType, wantParam: Record<string, Object>) {
      console.log('onSaveState');
      wantParam['myData'] = 'my1234567';
      return AbilityConstant.OnSaveResult.RECOVERY_AGREE;
  }
}

UIAbility.onShare¹⁰⁺

onShare(wantParam:{ [key: string]: Object }): void;

Called by this UIAbility to set data to share in the cross-device sharing scenario.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
wantParam	{[key: string]: Object}	Yes	Data to share.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';

class MyUIAbility extends UIAbility {
  onShare(wantParams: Record<string, Object>) {
      console.log('onShare');
      wantParams['ohos.extra.param.key.shareUrl'] = 'example.com';
  }
}

UIAbility.onPrepareToTerminate¹⁰⁺

onPrepareToTerminate(): boolean;

Triggered when this UIAbility is about to terminate in case that the system parameter persist.sys.prepare_terminate is set to true. You can define an operation in this callback to determine whether to continue terminating the UIAbility. If a confirmation from the user is required, you can define a pre-termination operation in the callback and use it together with terminateSelf, for example, displaying a dialog box to ask the user whether to terminate the UIAbility. The UIAbility termination process is canceled when persist.sys.prepare_terminate is set to true.

Required permissions: ohos.permission.PREPARE_APP_TERMINATE

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Return value

Type	Description
boolean	Whether to terminate the UIAbility. The value true means that the termination process is canceled and the UIAbility is not terminated. The value false means to continue terminating the UIAbility.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import Want from '@ohos.app.ability.Want';
import { BusinessError } from '@ohos.base';

export default class EntryAbility extends UIAbility {
  onPrepareToTerminate() {
    // Define a pre-termination operation,
    // for example, starting another UIAbility and performing asynchronous termination based on the startup result.
    let want: Want = {
      bundleName: "com.example.myapplication",
      moduleName: "entry",
      abilityName: "SecondAbility"
    }
    this.context.startAbilityForResult(want)
      .then((result)=>{
        // Obtain the startup result and terminate the current UIAbility when resultCode in the return value is 0.
        console.log('startAbilityForResult success, resultCode is ' + result.resultCode);
        if (result.resultCode === 0) {
          this.context.terminateSelf();
        }
      }).catch((err: BusinessError)=>{
        // Exception handling.
        console.log('startAbilityForResult failed, err:' + JSON.stringify(err));
        this.context.terminateSelf();
      })

    return true; // The pre-termination operation is defined. The value true means that the UIAbility termination process is canceled.
  }
}

UIAbility.onBackPressed¹⁰⁺

onBackPressed(): boolean;

Called when an operation of going back to a previous page is triggered on this UIAbility. The return value determines whether to destroy the UIAbility instance. By default, the UIAbility instance is destroyed.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Return value

Type	Description
boolean	The value true means that the UIAbility instance will be moved to the background and will not be destroyed, and false means that the UIAbility instance will be destroyed.

Example

import UIAbility from '@ohos.app.ability.UIAbility';

export default class EntryAbility extends UIAbility {
  onBackPressed() {
    return true;
  }
}

Caller

Implements sending of sequenceable data to the target ability when the CallerAbility invokes the target ability (CalleeAbility).

Caller.call

call(method: string, data: rpc.Parcelable): Promise<void>;

Sends sequenceable data to the target ability.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
method	string	Yes	Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.
data	rpc.Parcelable	Yes	Parcelable data. You need to customize the data.

Return value

Type	Description
Promise<void>	Promise used to return a response.

Error codes

ID	Error Message
16200001	Caller released. The caller has been released.
16200002	Callee invalid. The callee does not exist.
16000050	Internal error.

For details about the error codes, see Ability Error Codes.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';
import rpc from '@ohos.rpc';

class MyMessageAble implements rpc.Parcelable { // Custom parcelable data structure.
  name: string
  str: string
  num: number = 1
  constructor(name: string, str: string) {
    this.name = name;
    this.str = str;
  }
  marshalling(messageSequence: rpc.MessageSequence) {
    messageSequence.writeInt(this.num);
    messageSequence.writeString(this.str);
    console.log('MyMessageAble marshalling num[${this.num}] str[${this.str}]');
    return true;
  }
  unmarshalling(messageSequence: rpc.MessageSequence) {
    this.num = messageSequence.readInt();
    this.str = messageSequence.readString();
    console.log('MyMessageAble unmarshalling num[${this.num}] str[${this.str}]');
    return true;
  }
};
let method = 'call_Function'; // Notification message string negotiated by the two UIAbilities.
let caller: Caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
      caller = obj;
      let msg = new MyMessageAble('msg', 'world'); // See the definition of Parcelable.
      caller.call(method, msg)
        .then(() => {
          console.log('Caller call() called');
        })
        .catch((callErr: BusinessError) => {
          console.log('Caller.call catch error, error.code: ${callErr.code}, error.message: ${callErr.message}');
        });
    }).catch((err: BusinessError) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

Caller.callWithResult

callWithResult(method: string, data: rpc.Parcelable): Promise<rpc.MessageSequence>;

Sends sequenceable data to the target ability and obtains the sequenceable data returned by the target ability.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
method	string	Yes	Notification message string negotiated between the two abilities. The message is used to instruct the callee to register a function to receive the sequenceable data.
data	rpc.Parcelable	Yes	Parcelable data. You need to customize the data.

Return value

Type	Description
Promise<rpc.MessageSequence>	Promise used to return the sequenceable data from the target ability.

Error codes

ID	Error Message
16200001	Caller released. The caller has been released.
16200002	Callee invalid. The callee does not exist.
16000050	Internal error.

For details about the error codes, see Ability Error Codes.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';
import rpc from '@ohos.rpc';

class MyMessageAble implements rpc.Parcelable {
  name: string
  str: string
  num: number = 1
  constructor(name: string, str: string) {
    this.name = name;
    this.str = str;
  }
  marshalling(messageSequence: rpc.MessageSequence) {
    messageSequence.writeInt(this.num);
    messageSequence.writeString(this.str);
    console.log('MyMessageAble marshalling num[${this.num}] str[${this.str}]');
    return true;
  }
  unmarshalling(messageSequence: rpc.MessageSequence) {
    this.num = messageSequence.readInt();
    this.str = messageSequence.readString();
    console.log('MyMessageAble unmarshalling num[${this.num] str[${this.str}]');
    return true;
  }
};
let method = 'call_Function';
let caller: Caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
      caller = obj;
      let msg = new MyMessageAble(1, 'world');
      caller.callWithResult(method, msg)
        .then((data) => {
          console.log('Caller callWithResult() called');
          let retmsg = new MyMessageAble(0, '');
          data.readParcelable(retmsg);
        })
        .catch((callErr: BusinessError) => {
          console.log('Caller.callWithResult catch error, error.code: ${callErr.code}, error.message: ${callErr.message}');
        });
    }).catch((err: BusinessError) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

Caller.release

release(): void;

Releases the caller interface of the target ability.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Error codes

ID	Error Message
16200001	Caller released. The caller has been released.
16200002	Callee invalid. The callee does not exist.

For details about the error codes, see Ability Error Codes.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';

let caller: Caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
      caller = obj;
      try {
        caller.release();
      } catch (releaseErr) {
        console.log('Caller.release catch error, error.code: ${releaseErr.code}, error.message: ${releaseErr.message}');
      }
    }).catch((err: BusinessError) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

Caller.onRelease

onRelease(callback: OnReleaseCallback): void;

Registers a callback that is invoked when the stub on the target ability is disconnected.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Error codes

ID	Error Message
16200001	Caller released. The caller has been released.

For details about the error codes, see Ability Error Codes.

Parameters

Name	Type	Mandatory	Description
callback	OnReleaseCallback	Yes	Callback used to return the result.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';

let caller: Caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
        caller = obj;
        try {
          caller.onRelease((str) => {
              console.log(' Caller OnRelease CallBack is called ${str}');
          });
        } catch (error) {
          console.log('Caller.onRelease catch error, error.code: $error.code}, error.message: ${error.message}');
        }
    }).catch((err: BusinessError) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

Caller.onRemoteStateChange¹⁰⁺

onRemoteStateChange(callback: OnRemoteStateChangeCallback): void;

Registers a callback that is invoked when the remote ability state changes in the collaboration scenario.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
callback	OnRemoteStateChangeCallback	Yes	Callback used to return the result.

Error codes

ID	Error Message
16200001	Caller released. The caller has been released.

For details about the error codes, see Ability Error Codes.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';

let caller: Caller;
let dstDeviceId: string;
export default class MainAbility extends UIAbility {
    onWindowStageCreate(windowStage: window.WindowStage) {
        this.context.startAbilityByCall({
            bundleName: 'com.example.myservice',
            abilityName: 'MainUIAbility',
            deviceId: dstDeviceId
        }).then((obj) => {
            caller = obj;
            try {
                caller.onRemoteStateChange((str) => {
                    console.log('Remote state changed ' + str);
                });
            } catch (error) {
                console.log(`Caller.onRemoteStateChange catch error, error.code: ${JSON.stringify(error.code)}, error.message: ${JSON.stringify(error.message)}`);
            }
        }).catch((err: BusinessError) => {
            console.log(`Caller GetCaller error, error.code: ${JSON.stringify(err.code)}, error.message: ${JSON.stringify(err.message)}`);
        })
    }
}

Caller.on

on(type: 'release', callback: OnReleaseCallback): void;

Registers a callback that is invoked when the stub on the target ability is disconnected.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at release.
callback	OnReleaseCallback	Yes	Callback used to return the result.

Error codes

ID	Error Message
401	If the input parameter is not valid parameter.
16200001	Caller released. The caller has been released.

For details about the error codes, see Ability Error Codes.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';

let caller: Caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
        caller = obj;
        try {
          caller.on('release', (str) => {
              console.log(' Caller OnRelease CallBack is called ${str}');
          });
        } catch (error) {
          console.log('Caller.on catch error, error.code: ${error.code}, error.message: ${error.message}');
        }
    }).catch((err: BusinessError) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

Caller.off

off(type: 'release', callback: OnReleaseCallback): void;

Deregisters a callback that is invoked when the stub on the target ability is disconnected. This capability is reserved.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at release.
callback	OnReleaseCallback	Yes	Callback used to return the result.

Error codes

ID	Error Message
401	If the input parameter is not valid parameter.

Example

import UIAbility, { OnReleaseCallback } from '@ohos.app.ability.UIAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';

let caller: Caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
        caller = obj;
        try {
          let onReleaseCallBack: OnReleaseCallback = (str) => {
              console.log(' Caller OnRelease CallBack is called ${str}');
          };
          caller.on('release', onReleaseCallBack);
          caller.off('release', onReleaseCallBack);
        } catch (error) {
          console.log('Caller.on or Caller.off catch error, error.code: ${error.code}, error.message: ${error.message}');
        }
    }).catch((err: BusinessError) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

Caller.off

off(type: 'release'): void;

Deregisters a callback that is invoked when the stub on the target ability is disconnected. This capability is reserved.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
type	string	Yes	Event type. The value is fixed at release.

Example

import UIAbility, { OnReleaseCallback } from '@ohos.app.ability.UIAbility';
import { Caller } from '@ohos.app.ability.UIAbility';
import { BusinessError } from '@ohos.base';
import window from '@ohos.window';

let caller: Caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
        caller = obj;
        try {
          let onReleaseCallBack: OnReleaseCallback = (str) => {
              console.log(' Caller OnRelease CallBack is called ${str}');
          };
          caller.on('release', onReleaseCallBack);
          caller.off('release');
        } catch (error) {
          console.error('Caller.on or Caller.off catch error, error.code: ${error.code}, error.message: ${error.message}');
        }
    }).catch((err: BusinessError) => {
      console.error('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

Callee

Implements callbacks for caller notification registration and deregistration.

Callee.on

on(method: string, callback: CalleeCallback): void;

Registers a caller notification callback, which is invoked when the target ability registers a function.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
method	string	Yes	Notification message string negotiated between the two abilities.
callback	CalleeCallback	Yes	JS notification synchronization callback of the rpc.MessageSequence type. The callback must return at least one empty rpc.Parcelable object. Otherwise, the function execution fails.

Error codes

ID	Error Message
16200004	Method registered. The method has registered.
16000050	Internal error.

For details about the error codes, see Ability Error Codes.

Example

import UIAbility, { CalleeCallback } from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import Want from '@ohos.app.ability.Want';
import rpc from '@ohos.rpc';

class MyMessageAble implements rpc.Parcelable {
    name: string
    str: string
    num: number = 1
    constructor(name: string, str: string) {
      this.name = name;
      this.str = str;
    }
    marshalling(messageSequence: rpc.MessageSequence) {
        messageSequence.writeInt(this.num);
        messageSequence.writeString(this.str);
        console.log('MyMessageAble marshalling num[${this.num}] str[${this.str}]');
        return true;
    }
    unmarshalling(messageSequence: rpc.MessageSequence) {
        this.num = messageSequence.readInt();
        this.str = messageSequence.readString();
        console.log('MyMessageAble unmarshalling num[${this.num}] str[${this.str}]');
        return true;
    }
};
let method = 'call_Function';
function funcCallBack(pdata: rpc.MessageSequence) {
    console.log('Callee funcCallBack is called ${pdata}');
    let msg = new MyMessageAble('test', '');
    pdata.readParcelable(msg);
    return new MyMessageAble('test1', 'Callee test');
}
export default class MainUIAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    console.log('Callee onCreate is called');
    try {
      this.callee.on(method, funcCallBack);
    } catch (error) {
      console.log('Callee.on catch error, error.code: ${error.code}, error.message: ${error.message}');
    }
  }
}

Callee.off

off(method: string): void;

Deregisters a caller notification callback, which is invoked when the target ability registers a function.

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Parameters

Name	Type	Mandatory	Description
method	string	Yes	Registered notification message string.

Error codes

ID	Error Message
16200005	Method not registered. The method has not registered.
16000050	Internal error.

For details about the error codes, see Ability Error Codes.

Example

import UIAbility from '@ohos.app.ability.UIAbility';
import AbilityConstant from '@ohos.app.ability.AbilityConstant';
import Want from '@ohos.app.ability.Want';

let method = 'call_Function';
export default class MainUIAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    console.log('Callee onCreate is called');
    try {
      this.callee.off(method);
    } catch (error) {
      console.log('Callee.off catch error, error.code: ${error.code}, error.message: ${error.message}');
    }
  }
}

OnReleaseCallback

(msg: string): void;

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Name	Readable	Writable	Type	Description
(msg: string)	Yes	No	function	Prototype of the listener function registered by the caller.

OnRemoteStateChangeCallback¹⁰⁺

(msg: string): void;

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Name	Readable	Writable	Type	Description
(msg: string)	Yes	No	function	Prototype of the ability state change listener function registered by the caller in the collaboration scenario.

CalleeCallback

(indata: rpc.MessageSequence): rpc.Parcelable;

System capability: SystemCapability.Ability.AbilityRuntime.AbilityCore

Name	Readable	Writable	Type	Description
(indata: rpc.MessageSequence)	Yes	No	rpc.Parcelable	Prototype of the listener function registered by the callee.

你可能感兴趣的鸿蒙文章

harmony 鸿蒙APIs

harmony 鸿蒙System Common Events (To Be Deprecated Soon)

harmony 鸿蒙System Common Events

harmony 鸿蒙API Reference Document Description

harmony 鸿蒙Enterprise Device Management Overview (for System Applications Only)

harmony 鸿蒙BundleStatusCallback

harmony 鸿蒙@ohos.bundle.innerBundleManager (innerBundleManager)

harmony 鸿蒙@ohos.distributedBundle (Distributed Bundle Management)

harmony 鸿蒙@ohos.bundle (Bundle)

harmony 鸿蒙@ohos.enterprise.EnterpriseAdminExtensionAbility (EnterpriseAdminExtensionAbility)

harmony 鸿蒙@ohos.app.ability.UIAbility (UIAbility)

@ohos.app.ability.UIAbility (UIAbility)

Modules to Import

Attributes

UIAbility.onCreate

UIAbility.onWindowStageCreate

UIAbility.onWindowStageDestroy

UIAbility.onWindowStageRestore

UIAbility.onDestroy

UIAbility.onForeground

UIAbility.onBackground

UIAbility.onContinue

UIAbility.onNewWant

UIAbility.onDump

UIAbility.onSaveState

UIAbility.onShare¹⁰⁺

UIAbility.onPrepareToTerminate¹⁰⁺

UIAbility.onBackPressed¹⁰⁺

Caller

Caller.call

Caller.callWithResult

Caller.release

Caller.onRelease

Caller.onRemoteStateChange¹⁰⁺

Caller.on

Caller.off

Caller.off

Callee

Callee.on

Callee.off

OnReleaseCallback

OnRemoteStateChangeCallback¹⁰⁺

CalleeCallback

你可能感兴趣的鸿蒙文章

最新博客

最热博客

标签云

@ohos.app.ability.UIAbility (UIAbility)

Modules to Import

Attributes

UIAbility.onCreate

UIAbility.onWindowStageCreate

UIAbility.onWindowStageDestroy

UIAbility.onWindowStageRestore

UIAbility.onDestroy

UIAbility.onForeground

UIAbility.onBackground

UIAbility.onContinue

UIAbility.onNewWant

UIAbility.onDump

UIAbility.onSaveState

UIAbility.onShare10+

UIAbility.onPrepareToTerminate10+

UIAbility.onBackPressed10+

Caller

Caller.call

Caller.callWithResult

Caller.release

Caller.onRelease

Caller.onRemoteStateChange10+

Caller.on

Caller.off

Caller.off

Callee

Callee.on

Callee.off

OnReleaseCallback

OnRemoteStateChangeCallback10+

CalleeCallback

你可能感兴趣的鸿蒙文章

最新博客

最热博客

UIAbility.onShare¹⁰⁺

UIAbility.onPrepareToTerminate¹⁰⁺

UIAbility.onBackPressed¹⁰⁺

Caller.onRemoteStateChange¹⁰⁺

OnRemoteStateChangeCallback¹⁰⁺