js-apis-application-ability.md

# Ability

- [导入模块](#导入模块)
- [属性](#属性)
- [onCreate](#onCreate)
- [onWindowStageCreate](#onWindowStageCreate)
- [onWindowStageDestroy](#onWindowStageDestroy)
- [onWindowStageRestore](#onWindowStageRestore)
- [onDestroy](#onDestroy)
- [onForeground](#onForeground)
- [onBackground](#onBackground)
- [onContinue](#onContinue)
- [onNewWant](#onNewWant)
- [onConfigurationUpdated](#onConfigurationUpdated)
- [Caller](#Caller)
 - [call](#call)
 - [callWithResult](#callWithResult)
 - [release](#release)
 - [onRelease](#onRelease)
- [Callee](#Callee)
 - [on](#on)
 - [off](#off)


> ![icon-note.gif](public_sys-resources/icon-note.gif) **说明：**
> 从API Version 8 开始支持。


Ability模块，提供对Ability生命周期、上下文环境等调用管理。


## 导入模块

  
```
import Ability from '@ohos.application.Ability';
```


## 属性

  | 名称 | 参数类型 | 可读 | 可写 | 说明 | 
| -------- | -------- | -------- | -------- | -------- |
| context | [AbilityContext](js-apis-ability-context.md) | 是 | 否 | 上下文。 | 
| launchWant | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | 否 | Ability启动时的参数。 | 
| lastRequestWant | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | 否 | Ability最后请求时的参数。 | 


## onCreate

onCreate(want: Want，param：LaunchParam): void

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

- 参数：
    | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
  | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | 当前Ability的Want类型信息，包括ability名称、bundle名称等。 | 
  | param | LaunchParam | 是 | 创建 ability、上次异常退出的原因信息。 | 

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


## onWindowStageCreate

onWindowStageCreate(windowStage: window.WindowStage): void

当WindowStage创建后调用。

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

- 示例：
    
  ```
  class myAbility extends Ability {
      onWindowStageCreate(windowStage) {
          console.log('onWindowStageCreate');
      }
  }
  ```


## onWindowStageDestroy

onWindowStageDestroy(): void

当WindowStage销毁后调用。

- 示例：
    
  ```
  class myAbility extends Ability {
      onWindowStageDestroy() {
          console.log('onWindowStageDestroy');
      }
  }
  ```


## onWindowStageRestore

onWindowStageRestore(windowStage: window.WindowStage): void

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

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

- 示例：
    
  ```
  class myAbility extends Ability {
      onWindowStageRestore(windowStage) {
          console.log('onWindowStageRestore');
      }
  }
  ```


## onDestroy

onDestroy(): void;

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

- 示例：
    
  ```
  class myAbility extends Ability {
      onDestroy() {
          console.log('onDestroy');
      }
  }
  ```


## onForeground

onForeground(): void;

Ability生命周期回调，当应用处于前台时触发。

- 示例：
    
  ```
  class myAbility extends Ability {
      onForeground() {
          console.log('onForeground');
      }
  }
  ```


## onBackground

onBackground(): void;

Ability生命周期回调，当应用处于后台时触发。

- 示例：
    
  ```
  class myAbility extends Ability {
      onBackground() {
          console.log('onBackground');
      }
  }
  ```


## onContinue

onContinue(wantParam : {[key: string]: any}): boolean;

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

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

- 返回值：
    | 类型 | 说明 | 
  | -------- | -------- |
  | boolean | true表示同意迁移，false表示拒绝迁移。 | 

- 示例：
    
  ```
  class myAbility extends Ability {
      onContinue(wantParams) {
          console.log('onContinue');
          wantParams["myData"] = "my1234567";
          return true;
      }
  }
  ```


## onNewWant

onNewWant(want: Want): void;

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

- 参数：
    | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
  | want | [Want](js-apis-featureAbility.md#Want类型说明) | 是 | Want类型参数，如ability名称，包名等。 | 

- 示例：
    
  ```
  class myAbility extends Ability {
      onNewWant(want) {
          console.log('onNewWant, want:' + want.abilityName);
      }
  }
  ```


## onConfigurationUpdated

onConfigurationUpdated(config: Configuration): void;

当系统配置更新时调用。

- 参数：
    | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
  | config | [Configuration](#section188911144124715) | 是 | 表示需要更新的配置信息。 | 

- 示例：
    
  ```
  class myAbility extends Ability {
      onConfigurationUpdated(config) {
          console.log('onConfigurationUpdated, config:' + JSON.stringify(config));
      }
  }
  ```


## Caller

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


### call

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

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

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

- 返回值：
    | 类型 | 说明 | 
  | -------- | -------- |
  | Promise<void> | Promise形式返回应答。 | 

- 示例：
    
  ```
  import Ability from '@ohos.application.Ability';
  class MyMessageAble{ // 自定义的Sequenceable数据结构
      num: 0
      str: ''
      constructor() {}
      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) {
          caller = await this.context.startAbilityByCall({
              bundleName: "com.example.myservice",
              abilityName: "com.example.myservice.MainAbility",
              deviceId: ""
          });
          let msg = new MyMessageAble(1, "world"); // 参考Sequenceable数据定义
          caller.call(method, msg)
          .then(() => {
              console.log('Caller call() called');
          }).catch((e) => {
              console.log('Caller call() catch error ' + e);
          });
      }
  }
  ```


### callWithResult

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

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

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

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

- 示例：
    
  ```
  import Ability from '@ohos.application.Ability';
  class MyMessageAble{
      num: 0
      str: ''
      constructor() {}
      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) {
          caller = await this.context.startAbilityByCall({
              bundleName: "com.example.myservice",
              abilityName: "com.example.myservice.MainAbility",
              deviceId: ""
           });
          let msg = new MyMessageAble(1, "world");
          caller.callWithResult(method, msg)
          .then((data) => {
              console.log('Caller call() called');
              let retmsg = new MyMessageAble(0, "");
              data.readSequenceable(retmsg);
          }).catch((e) => {
              console.log('Caller call() catch error ' + e);
          });
      }
  }
  ```


### release

release(): void;

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

- 示例：
    
  ```
  import Ability from '@ohos.application.Ability';
  var caller;
  export default class MainAbility extends Ability {
      onWindowStageCreate(windowStage) {
          caller = await this.context.startAbilityByCall({
                  bundleName: "com.example.myservice",
                  abilityName: "com.example.myservice.MainAbility",
                  deviceId: ""
              });
          try {
              caller.release();
          } catch (e) {
              console.log('Caller Release error ' + e);
          }
      }
  }
  ```


### onRelease

onRelease(callback: function): void;

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

- 参数：
    | 参数名 | 类型 | 必填 | 说明 | 
  | -------- | -------- | -------- | -------- |
  | callback | function | 是 | 返回onRelease回调结果。 | 

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


## Callee

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


### on

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

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

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

- 示例：
    
  ```
  import Ability from '@ohos.application.Ability';
  class MyMessageAble{
      num: 0
      str: ''
      constructor() {}
      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);
      }
  }
  ```


### off

off(method: string): void;

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

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

- 示例：
    
  ```
  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);
      }
  }
  ```