Ability

Ability模塊提供對(duì)Ability生命周期、上下文環(huán)境等調(diào)用管理的能力，包括Ability創(chuàng)建、銷毀、轉(zhuǎn)儲(chǔ)客戶端信息等。

該模塊提供以下Ability相關(guān)的常用功能：

• [Caller]：通用組件Caller通信客戶端調(diào)用接口, 用來(lái)向通用組件服務(wù)端發(fā)送約定數(shù)據(jù)。
• [Callee]：通用組件服務(wù)端注冊(cè)和解除客戶端caller通知送信的callback接口。

說(shuō)明：

本模塊首批接口從API version 9 開(kāi)始支持。后續(xù)版本的新增接口，采用上角標(biāo)單獨(dú)標(biāo)記接口的起始版本。
本模塊接口僅可在Stage模型下使用。

導(dǎo)入模塊

复制import Ability from '@ohos.application.Ability';

鴻蒙開(kāi)發(fā)指導(dǎo)文檔：[复制qr23.cn/FBD4cY]

屬性

系統(tǒng)能力 ：以下各項(xiàng)對(duì)應(yīng)的系統(tǒng)能力均為SystemCapability.Ability.AbilityRuntime.AbilityCore

Ability.onCreate

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

Ability創(chuàng)建時(shí)回調(diào)，執(zhí)行初始化業(yè)務(wù)邏輯操作。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

示例：

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

Ability.onWindowStageCreate

onWindowStageCreate(windowStage: window.WindowStage): void

當(dāng)WindowStage創(chuàng)建后調(diào)用。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

示例：

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

Ability.onWindowStageDestroy

onWindowStageDestroy(): void

當(dāng)WindowStage銷毀后調(diào)用。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

示例：

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

Ability.onWindowStageRestore

onWindowStageRestore(windowStage: window.WindowStage): void

當(dāng)遷移多實(shí)例ability時(shí)，恢復(fù)WindowStage后調(diào)用。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

示例：

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

Ability.onDestroy

onDestroy(): void;

Ability生命周期回調(diào)，在銷毀時(shí)回調(diào)，執(zhí)行資源清理等操作。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

示例：

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

Ability.onForeground

onForeground(): void;

Ability生命周期回調(diào)，當(dāng)應(yīng)用從后臺(tái)轉(zhuǎn)到前臺(tái)時(shí)觸發(fā)。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

示例：

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

Ability.onBackground

onBackground(): void;

Ability生命周期回調(diào)，當(dāng)應(yīng)用從前臺(tái)轉(zhuǎn)到后臺(tái)時(shí)觸發(fā)。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

示例：

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

Ability.onContinue

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

當(dāng)ability遷移準(zhǔn)備遷移時(shí)觸發(fā)，保存數(shù)據(jù)。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

返回值：

示例：

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

Ability.onNewWant

onNewWant(want: Want): void;

當(dāng)ability的啟動(dòng)模式設(shè)置為單例時(shí)回調(diào)會(huì)被調(diào)用。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

示例：

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

Ability.onConfigurationUpdated

onConfigurationUpdated(config: Configuration): void;

當(dāng)系統(tǒng)配置更新時(shí)調(diào)用。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

示例：

复制class myAbility extends Ability {
    onConfigurationUpdated(config) {
        console.log('onConfigurationUpdated, config:' + JSON.stringify(config));
    }
}

Ability.dump

dump(params: Array): Array;

轉(zhuǎn)儲(chǔ)客戶端信息時(shí)調(diào)用。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

示例：

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

Caller

通用組件Caller通信客戶端調(diào)用接口, 用來(lái)向通用組件服務(wù)端發(fā)送約定數(shù)據(jù)。

Caller.call

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

向通用組件服務(wù)端發(fā)送約定序列化數(shù)據(jù)。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

返回值：

示例：

复制import Ability from '@ohos.application.Ability';
class MyMessageAble{ // 自定義的Sequenceable數(shù)據(jù)結(jié)構(gòu)
    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'; // 約定的通知消息字符串
var caller;
export default class MainAbility extends Ability {
    onWindowStageCreate(windowStage) {
      this.context.startAbilityByCall({
          bundleName: "com.example.myservice",
          abilityName: "MainAbility",
          deviceId: ""
      }).then((obj) = > {
          caller = obj;
          let msg = new MyMessageAble(1, "world"); // 參考Sequenceable數(shù)據(jù)定義
          caller.call(method, msg)
              .then(() = > {
                  console.log('Caller call() called');
              }).catch((e) = > {
              console.log('Caller call() catch error ' + e);
          });
          console.log('Caller GetCaller Get ' + caller);
      }).catch((e) = > {
          console.log('Caller GetCaller error ' + e);
      });
    }
    
}

Caller.callWithResult

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

向通用組件服務(wù)端發(fā)送約定序列化數(shù)據(jù), 并將服務(wù)端返回的約定序列化數(shù)據(jù)帶回。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

返回值：

示例：

复制import Ability from '@ohos.application.Ability';
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';
var caller;
export default class MainAbility extends Ability {
    onWindowStageCreate(windowStage) {
      this.context.startAbilityByCall({
          bundleName: "com.example.myservice",
          abilityName: "MainAbility",
          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.readSequenceable(retmsg);
              }).catch((e) = > {
              console.log('Caller callWithResult() catch error ' + e);
          });
          console.log('Caller GetCaller Get ' + caller);
      }).catch((e) = > {
          console.log('Caller GetCaller error ' + e);
      });
    }
}

Caller.release

release(): void;

主動(dòng)釋放通用組件服務(wù)端的通信接口。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

示例：

复制import Ability from '@ohos.application.Ability';
var caller;
export default class MainAbility extends Ability {
    onWindowStageCreate(windowStage) {
      this.context.startAbilityByCall({
          bundleName: "com.example.myservice",
          abilityName: "MainAbility",
          deviceId: ""
      }).then((obj) = > {
          caller = obj;
          try {
              caller.release();
          } catch (e) {
              console.log('Caller Release error ' + e);
          }
          console.log('Caller GetCaller Get ' + caller);
      }).catch((e) = > {
          console.log('Caller GetCaller error ' + e);
      });
    }
}

Caller.onRelease

onRelease(callback: OnReleaseCallBack): void;

注冊(cè)通用組件服務(wù)端Stub（樁）斷開(kāi)監(jiān)聽(tīng)通知。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

示例：

复制import Ability from '@ohos.application.Ability';
var caller;
export default class MainAbility extends Ability {
    onWindowStageCreate(windowStage) {
      this.context.startAbilityByCall({
          bundleName: "com.example.myservice",
          abilityName: "MainAbility",
          deviceId: ""
      }).then((obj) = > {
          caller = obj;
          try {
              caller.onRelease((str) = > {
                  console.log(' Caller OnRelease CallBack is called ' + str);
              });
          } catch (e) {
              console.log('Caller Release error ' + e);
          }
          console.log('Caller GetCaller Get ' + caller);
      }).catch((e) = > {
          console.log('Caller GetCaller error ' + e);
      });
    }
}

Callee

通用組件服務(wù)端注冊(cè)和解除客戶端caller通知送信的callback接口。

Callee.on

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

通用組件服務(wù)端注冊(cè)消息通知callback。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

示例：

复制import Ability from '@ohos.application.Ability';
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(0, "");
    pdata.readSequenceable(msg);
    return new MyMessageAble(10, "Callee test");
}
export default class MainAbility extends Ability {
    onCreate(want, launchParam) {
        console.log('Callee onCreate is called');
        this.callee.on(method, funcCallBack);
    }
}

Callee.off

off(method: string): void;

解除通用組件服務(wù)端注冊(cè)消息通知callback。

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

參數(shù)：

示例：

复制import Ability from '@ohos.application.Ability';
var method = 'call_Function';
export default class MainAbility extends Ability {
    onCreate(want, launchParam) {
        console.log('Callee onCreate is called');
        this.callee.off(method);
    }
}

OnReleaseCallBack

(msg: string): void;

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

CaleeCallBack

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

系統(tǒng)能力 ：SystemCapability.Ability.AbilityRuntime.AbilityCore

審核編輯 黃宇