HarmonyOS API:Stage模型能力的接口

joytrian
发布于 2023-3-31 17:45
浏览
0收藏

版本:v3.1 Beta

@ohos.app.ability.UIAbility (UIAbility)

更新时间: 2023-03-30 17:37


Ability模块提供对Ability生命周期、上下文环境等调用管理的能力,包括Ability创建、销毁、转储客户端信息等。


该模块提供以下Ability相关的常用功能:


  • ​Caller​​:通用组件Caller通信客户端调用接口, 用来向通用组件服务端发送约定数据。
  • ​Callee​​:通用组件服务端注册和解除客户端caller通知送信的callback接口。


说明

本模块首批接口从API version 9 开始支持。后续版本的新增接口,采用上角标单独标记接口的起始版本。


本模块接口仅可在Stage模型下使用。

导入模块

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

属性

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

名称

类型

可读

可写

说明

context

​UIAbilityContext​

上下文。

launchWant

​Want​

Ability启动时的参数。

lastRequestWant

​Want​

Ability最后请求时的参数。

callee

​Callee​

调用Stub(桩)服务对象。

Ability.onCreate

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

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

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

参数:

参数名

类型

必填

说明

want

​Want​

当前Ability的Want类型信息,包括ability名称、bundle名称等。

param

AbilityConstant.LaunchParam

创建 ability、上次异常退出的原因信息。

示例:

class myAbility extends Ability {
    onCreate(want, param) {
        console.log('onCreate, want:' + want.abilityName);
    }
}

Ability.onWindowStageCreate

onWindowStageCreate(windowStage: window.WindowStage): void

当WindowStage创建后调用。

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

参数:

参数名

类型

必填

说明

windowStage

window.WindowStage

WindowStage相关信息。

示例:

class myAbility extends Ability {
    onWindowStageCreate(windowStage) {
        console.log('onWindowStageCreate');
    }
}

Ability.onWindowStageDestroy

onWindowStageDestroy(): void

当WindowStage销毁后调用。

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

示例:

class myAbility extends Ability {
    onWindowStageDestroy() {
        console.log('onWindowStageDestroy');
    }
}

Ability.onWindowStageRestore

onWindowStageRestore(windowStage: window.WindowStage): void

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

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

参数:

参数名

类型

必填

说明

windowStage

window.WindowStage

WindowStage相关信息。

示例:

class myAbility extends Ability {
    onWindowStageRestore(windowStage) {
        console.log('onWindowStageRestore');
    }
}

Ability.onDestroy

onDestroy(): void;

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

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

示例:

class myAbility extends Ability {
    onDestroy() {
        console.log('onDestroy');
    }
}

Ability.onForeground

onForeground(): void;

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

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

示例:

class myAbility extends Ability {
    onForeground() {
        console.log('onForeground');
    }
}

Ability.onBackground

onBackground(): void;

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

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

示例:

class myAbility extends Ability {
    onBackground() {
        console.log('onBackground');
    }
}

Ability.onContinue

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

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

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

参数:

参数名

类型

必填

说明

wantParam

{[key: string]: any}

want相关参数。

返回值:

类型

说明

AbilityConstant.OnContinueResult

继续的结果。

示例:

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

Ability.onNewWant

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

当ability的启动模式设置为单例时回调会被调用。

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

参数:

参数名

类型

必填

说明

want

​Want​

Want类型参数,如ability名称,包名等。

launchParams

AbilityConstant.LaunchParam

Ability启动的原因、上次异常退出的原因信息。

示例:

class myAbility extends Ability {
    onNewWant(want) {
        console.log('onNewWant, want:' + want.abilityName);
    }
}

Ability.onDump

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

转储客户端信息时调用。

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

参数:

参数名

类型

必填

说明

params

Array<string>

表示命令形式的参数。

示例:

class myAbility extends Ability {
    onDump(params) {
        console.log('dump, params:' + JSON.stringify(params));
        return ["params"]
    }
}

Caller

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

Caller.call

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

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

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

参数:

参数名

类型

必填

说明

method

string

约定的服务端注册事件字符串。

data

rpc.Sequenceable

由开发者实现的Sequenceable可序列化数据。

返回值:

类型

说明

Promise<void>

Promise形式返回应答。

错误码:

错误码ID

错误信息

401

If the input parameter is not valid parameter.

其他ID见​​元能力子系统错误码​

  

Caller.callWithResult

callWithResult(method: string, data: rpc.Sequenceable): Promise<rpc.MessageParcel>;

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

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

参数:

参数名

类型

必填

说明

method

string

约定的服务端注册事件字符串。

data

rpc.Sequenceable

由开发者实现的Sequenceable可序列化数据。

返回值:

类型

说明

Promise<rpc.MessageParcel>

Promise形式返回通用组件服务端应答数据。

错误码:

错误码ID

错误信息

401

If the input parameter is not valid parameter.

其他ID见​​元能力子系统错误码​

  

Caller.release

release(): void;

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

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

错误码:

错误码ID

错误信息

401

Invalid input parameter.

16200001

Caller released. The caller has been released.

16200002

Callee invalid. The callee does not exist.

16000050

Internal Error.

Caller.onRelease

onRelease(callback: OnReleaseCallBack): void;

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

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

参数:

参数名

类型

必填

说明

callback

OnReleaseCallBack

返回onRelease回调结果。

Caller.on

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

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

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

参数:

参数名

类型

必填

说明

type

string

监听releaseCall事件,固定为'release'。

callback

OnReleaseCallback

返回onRelease回调结果。

错误码:

错误码ID

错误信息

401

If the input parameter is not valid parameter.

其他ID见​​元能力子系统错误码​

  

Callee

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

Callee.on

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

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

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

参数:

参数名

类型

必填

说明

method

string

与客户端约定的通知消息字符串。

callback

CalleeCallback

一个rpc.MessageParcel类型入参的js通知同步回调函数, 回调函数至少要返回一个空的rpc.Sequenceable数据对象, 其他视为函数执行错误。

错误码:

错误码ID

错误信息

401

If the input parameter is not valid parameter.

其他ID见​​元能力子系统错误码​

  

示例:

import Ability from '@ohos.app.ability.UIAbility';
class MyMessageAble{
    name:""
    str:""
    num: 1
    constructor(name, str) {
      this.name = name;
      this.str = str;
    }
    marshalling(messageParcel) {
        messageParcel.writeInt(this.num);
        messageParcel.writeString(this.str);
        console.log('MyMessageAble marshalling num[' + this.num + '] str[' + this.str + ']');
        return true;
    }
    unmarshalling(messageParcel) {
        this.num = messageParcel.readInt();
        this.str = messageParcel.readString();
        console.log('MyMessageAble unmarshalling num[' + this.num + '] str[' + this.str + ']');
        return true;
    }
};
var method = 'call_Function';
function funcCallBack(pdata) {
    console.log('Callee funcCallBack is called ' + pdata);
    let msg = new MyMessageAble("test", "");
    pdata.readSequenceable(msg);
    return new MyMessageAble("test1", "Callee test");
}
export default class MainAbility extends Ability {
  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: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    }
  }
}

Callee.off

off(method: string): void;

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

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

参数:

参数名

类型

必填

说明

method

string

已注册的通知事件字符串。

错误码:

错误码ID

错误信息

401

If the input parameter is not valid parameter.

其他ID见​​元能力子系统错误码​

  

示例:

import Ability from '@ohos.app.ability.UIAbility';
var method = 'call_Function';
export default class MainAbility extends Ability {
  onCreate(want, launchParam) {
    console.log('Callee onCreate is called');
    try {
      this.callee.off(method);
    } catch (error) {
      console.log('Callee.off catch error, error.code: ' + JSON.stringify(error.code) +
        ' error.message: ' + JSON.stringify(error.message));
    }
  }
}

OnReleaseCallback

(msg: string): void;

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

名称

可读

可写

类型

说明

(msg: string)

function

调用者注册的侦听器函数接口的原型。

CalleeCallback

(indata: rpc.MessageParcel): rpc.Sequenceable;

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

名称

可读

可写

类型

说明

(indata: rpc.MessageParcel)

rpc.Sequenceable

被调用方注册的消息侦听器函数接口的原型。


文章转载自:​​https://developer.harmonyos.com/cn/docs/documentation/doc-references-V3/js-apis-app-ability-uiability-0000001427744948-V3?catalogVersion=V3#ZH-CN_TOPIC_0000001427744948__导入模块​

已于2023-3-31 17:45:13修改
收藏
回复
举报
回复