@ohos.app.ability.UIAbility (UIAbility)

UIAbility是包含UI界面的应用组件，提供组件创建、销毁、前后台切换等生命周期回调，同时也具备组件协同的能力，组件协同主要提供如下常用功能：

Caller：由startAbilityByCall接口返回，CallerAbility(调用者)可使用Caller与CalleeAbility(被调用者)进行通信。
Callee：UIAbility的内部对象，CalleeAbility(被调用者)可以通过Callee与Caller进行通信。

说明：

本模块首批接口从API version 9 开始支持。后续版本的新增接口，采用上角标单独标记接口的起始版本。
本模块接口仅可在Stage模型下使用。

导入模块

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

属性

系统能力：以下各项对应的系统能力均为SystemCapability.Ability.AbilityRuntime.AbilityCore

名称	类型	可读	可写	说明
context	UIAbilityContext	是	否	上下文。
launchWant	Want	是	否	UIAbility启动时的参数。
lastRequestWant	Want	是	否	UIAbility最后请求时的参数。
callee	Callee	是	否	调用Stub（桩）服务对象。

UIAbility.onCreate

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

UIAbility创建时回调，执行初始化业务逻辑操作。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
want	Want	是	当前UIAbility的Want类型信息，包括ability名称、bundle名称等。
param	AbilityConstant.LaunchParam	是	创建 ability、上次异常退出的原因信息。

示例：

class MyUIAbility extends UIAbility {
    onCreate(want, param) {
        console.log('onCreate, want: ${want.abilityName}');
    }
}

1
2
3
4
5

UIAbility.onWindowStageCreate

onWindowStageCreate(windowStage: window.WindowStage): void

当WindowStage创建后调用。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
windowStage	window.WindowStage	是	WindowStage相关信息。

示例：

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

1
2
3
4
5

UIAbility.onWindowStageDestroy

onWindowStageDestroy(): void

当WindowStage销毁后调用。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

示例：

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

1
2
3
4
5

UIAbility.onWindowStageRestore

onWindowStageRestore(windowStage: window.WindowStage): void

当迁移多实例ability时，恢复WindowStage后调用。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
windowStage	window.WindowStage	是	WindowStage相关信息。

示例：

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

1
2
3
4
5

UIAbility.onDestroy

onDestroy(): void | Promise<void>;

UIAbility生命周期回调，在销毁时回调，执行资源清理等操作。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

示例：

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

1
2
3
4
5

UIAbility.onForeground

onForeground(): void;

UIAbility生命周期回调，当应用从后台转到前台时触发。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

示例：

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

1
2
3
4
5

UIAbility.onBackground

onBackground(): void;

UIAbility生命周期回调，当应用从前台转到后台时触发。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

示例：

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

1
2
3
4
5

UIAbility.onContinue

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

当ability迁移准备迁移时触发，保存数据。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
wantParam	{[key: string]: any}	是	want相关参数。

返回值：

类型	说明
AbilityConstant.OnContinueResult	继续的结果。

示例：

import AbilityConstant from '@ohos.app.ability.AbilityConstant';
class MyUIAbility extends UIAbility {
    onContinue(wantParams) {
        console.log('onContinue');
        wantParams['myData'] = 'my1234567';
        return AbilityConstant.OnContinueResult.AGREE;
    }
}

1
2
3
4
5
6
7
8

UIAbility.onNewWant

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

当传入新的Want，ability再次被拉起时会回调执行该方法。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
want	Want	是	Want类型参数，如ability名称，包名等。
launchParams	AbilityConstant.LaunchParam	是	UIAbility启动的原因、上次异常退出的原因信息。

示例：

class MyUIAbility extends UIAbility {
    onNewWant(want, launchParams) {
        console.log('onNewWant, want: ${want.abilityName}');
        console.log('onNewWant, launchParams: ${JSON.stringify(launchParams)}');
    }
}

1
2
3
4
5
6

UIAbility.onDump

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

转储客户端信息时调用。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
params	Array<string>	是	表示命令形式的参数。

示例：

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

1
2
3
4
5
6

UIAbility.onSaveState

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

该API配合appRecovery使用。在应用故障时，如果使能了自动保存状态，框架将回调onSaveState保存UIAbility状态。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
reason	AbilityConstant.StateType	是	回调保存状态的原因。
wantParam	{[key: string]: any}	是	want相关参数。

返回值：

类型	说明
AbilityConstant.OnSaveResult	是否同意保存当前UIAbility的状态。

示例：

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

class MyUIAbility extends UIAbility {
  onSaveState(reason, wantParam) {
      console.log('onSaveState');
      wantParam['myData'] = 'my1234567';
      return AbilityConstant.OnSaveResult.RECOVERY_AGREE;
  }
}

1
2
3
4
5
6
7
8
9

UIAbility.onShare¹⁰⁺

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

ability分享数据。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
wantParam	{[key: string]: Object}	是	want相关参数。

示例：

import AbilityConstant from '@ohos.app.ability.AbilityConstant';
class MyUIAbility extends UIAbility {
  onShare(wantParams) {
      console.log('onShare');
      wantParams['ohos.extra.param.key.contentTitle'] = {title: "W3"};
      wantParams['ohos.extra.param.key.shareAbstract'] = {abstract: "communication for huawei employee"};
      wantParams['ohos.extra.param.key.shareUrl'] = {url: "w3.huawei.com"};
  }
}

1
2
3
4
5
6
7
8
9

Caller

通用组件Caller通信客户端调用接口, 用来向通用组件服务端发送约定数据。

Caller.call

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

向通用组件服务端发送约定序列化数据。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
method	string	是	约定的服务端注册事件字符串。
data	rpc.Parcelable	是	由开发者实现的Parcelable可序列化数据。

返回值：

类型	说明
Promise<void>	Promise形式返回应答。

错误码：

错误码ID	错误信息
16200001	Caller released. The caller has been released.
16200002	Callee invalid. The callee does not exist.
16000050	Internal Error.

以上错误码详细介绍请参考errcode-ability。

示例：

class MyMessageAble{ // 自定义的Parcelable数据结构
  name:''
  str:''
  num: 1
  constructor(name, str) {
    this.name = name;
    this.str = str;
  }
  marshalling(messageSequence) {
    messageSequence.writeInt(this.num);
    messageSequence.writeString(this.str);
    console.log('MyMessageAble marshalling num[${this.num}] str[${this.str}]');
    return true;
  }
  unmarshalling(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;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
      caller = obj;
      let msg = new MyMessageAble('msg', 'world'); // 参考Parcelable数据定义
      caller.call(method, msg)
        .then(() => {
          console.log('Caller call() called');
        })
        .catch((callErr) => {
          console.log('Caller.call catch error, error.code: ${callErr.code}, error.message: ${callErr.message}');
        });
    }).catch((err) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44

Caller.callWithResult

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

向通用组件服务端发送约定序列化数据, 并将服务端返回的约定序列化数据带回。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
method	string	是	约定的服务端注册事件字符串。
data	rpc.Parcelable	是	由开发者实现的Parcelable可序列化数据。

返回值：

类型	说明
Promise<rpc.MessageSequence>	Promise形式返回通用组件服务端应答数据。

错误码：

错误码ID	错误信息
16200001	Caller released. The caller has been released.
16200002	Callee invalid. The callee does not exist.
16000050	Internal Error.

以上错误码详细介绍请参考errcode-ability。

示例：

class MyMessageAble{
  name:''
  str:''
  num: 1
  constructor(name, str) {
    this.name = name;
    this.str = str;
  }
  marshalling(messageSequence) {
    messageSequence.writeInt(this.num);
    messageSequence.writeString(this.str);
    console.log('MyMessageAble marshalling num[${this.num}] str[${this.str}]');
    return true;
  }
  unmarshalling(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;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(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) => {
          console.log('Caller.callWithResult catch error, error.code: ${callErr.code}, error.message: ${callErr.message}');
        });
    }).catch((err) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46

Caller.release

release(): void;

主动释放通用组件服务端的通信接口。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

错误码：

错误码ID	错误信息
16200001	Caller released. The caller has been released.
16200002	Callee invalid. The callee does not exist.

以上错误码详细介绍请参考errcode-ability。

示例：

let caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(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) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

Caller.onRelease

onRelease(callback: OnReleaseCallback): void;

注册通用组件服务端Stub（桩）断开监听通知。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

错误码：

错误码ID	错误信息
16200001	Caller released. The caller has been released.

以上错误码详细介绍请参考errcode-ability。

参数：

参数名	类型	必填	说明
callback	OnReleaseCallback	是	返回onRelease回调结果。

示例：

let caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(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) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Caller.onRemoteStateChange

onRemoteStateChange(callback: OnRemoteStateChangeCallback): void;

注册协同场景下跨设备组件状态变化监听通知。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
callback	OnRemoteStateChangeCallback	是	返回onRemoteStateChange回调结果。

错误码：

错误码ID	错误信息
16200001	Caller released. The caller has been released.

以上错误码详细介绍请参考errcode-ability。

示例：

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

let 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) => {
            console.log('Caller GetCaller error, error.code: ${JSON.stringify(err.code)}, error.message: ${JSON.stringify(err.message)}');
        })；
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

Caller.on

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

注册通用组件服务端Stub（桩）断开监听通知。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
type	string	是	监听releaseCall事件，固定为'release'。
callback	OnReleaseCallback	是	返回onRelease回调结果。

错误码：

错误码ID	错误信息
16200001	Caller released. The caller has been released.

以上错误码详细介绍请参考errcode-ability。

示例：

let caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(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) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

Caller.off

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

取消注册通用组件服务端Stub（桩）断开监听通知。预留能力，当前暂未支持。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
type	string	是	监听releaseCall事件，固定为'release'。
callback	OnReleaseCallback	是	返回off回调结果。

示例：

let caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
        caller = obj;
        try {
          let 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) => {
      console.log('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Caller.off

off(type: 'release'): void;

取消注册通用组件服务端Stub（桩）断开监听通知。预留能力，当前暂未支持。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
type	string	是	监听releaseCall事件，固定为'release'。

示例：

let caller;
export default class MainUIAbility extends UIAbility {
  onWindowStageCreate(windowStage) {
    this.context.startAbilityByCall({
      bundleName: 'com.example.myservice',
      abilityName: 'MainUIAbility',
      deviceId: ''
    }).then((obj) => {
        caller = obj;
        try {
          let 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) => {
      console.error('Caller GetCaller error, error.code: ${err.code}, error.message: ${err.message}');
    });
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

Callee

通用组件服务端注册和解除客户端caller通知送信的callback接口。

Callee.on

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

通用组件服务端注册消息通知callback。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
method	string	是	与客户端约定的通知消息字符串。
callback	CalleeCallback	是	一个rpc.MessageSequence类型入参的js通知同步回调函数, 回调函数至少要返回一个空的rpc.Parcelable数据对象, 其他视为函数执行错误。

错误码：

错误码ID	错误信息
16200004	Method registered. The method has registered.
16000050	Internal error.

以上错误码详细介绍请参考errcode-ability。

示例：

class MyMessageAble{
    name:''
    str:''
    num: 1
    constructor(name, str) {
      this.name = name;
      this.str = str;
    }
    marshalling(messageSequence) {
        messageSequence.writeInt(this.num);
        messageSequence.writeString(this.str);
        console.log('MyMessageAble marshalling num[${this.num}] str[${this.str}]');
        return true;
    }
    unmarshalling(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) {
    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, 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}');
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38

Callee.off

off(method: string): void;

解除通用组件服务端注册消息通知callback。

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

参数：

参数名	类型	必填	说明
method	string	是	已注册的通知事件字符串。

错误码：

错误码ID	错误信息
16200005	Method not registered. The method has not registered.
16000050	Internal error.

以上错误码详细介绍请参考errcode-ability。

示例：

let method = 'call_Function';
export default class MainUIAbility extends UIAbility {
  onCreate(want, 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}');
    }
  }
}

1
2
3
4
5
6
7
8
9
10
11

OnReleaseCallback

(msg: string): void;

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

名称	可读	可写	类型	说明
(msg: string)	是	否	function	调用者注册的侦听器函数接口的原型。

OnRemoteStateChangeCallback

(msg: string): void;

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

名称	可读	可写	类型	说明
(msg: string)	是	否	function	调用者注册的协同场景下组件状态变化监听函数接口的原型。

CalleeCallback

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

系统能力：SystemCapability.Ability.AbilityRuntime.AbilityCore

名称	可读	可写	类型	说明
(indata: rpc.MessageSequence)	是	否	rpc.Parcelable	被调用方注册的消息侦听器函数接口的原型。

@ohos.app.ability.UIAbility (UIAbility)

@ohos.app.ability.UIAbility (UIAbility)

导入模块

属性

UIAbility.onCreate

UIAbility.onWindowStageCreate

UIAbility.onWindowStageDestroy

UIAbility.onWindowStageRestore

UIAbility.onDestroy

UIAbility.onForeground

UIAbility.onBackground

UIAbility.onContinue

UIAbility.onNewWant

UIAbility.onDump

UIAbility.onSaveState

UIAbility.onShare10+

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

Description

UIAbility.onShare¹⁰⁺