UIAbilityContext

导入模块

import { common } from '@kit.AbilityKit';

UIAbilityContext

属性

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

startAbility

startAbility(want: Want, callback: AsyncCallback<void>): void

启动一个UIAbility。使用callback异步回调。仅支持在主线程调用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

    try {
      this.context.startAbility(want, (err: BusinessError) => {
        if (err.code) {
          // 处理业务逻辑错误
          console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // 执行正常业务
        console.info('startAbility succeed');
      });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

startAbility

startAbility(want: Want, options: StartOptions, callback: AsyncCallback<void>): void

启动一个UIAbility。使用callback异步回调。仅支持在主线程调用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0
    };

    try {
      this.context.startAbility(want, options, (err: BusinessError) => {
        if (err.code) {
          // 处理业务逻辑错误
          console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // 执行正常业务
        console.info('startAbility succeed');
      });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

startAbility

startAbility(want: Want, options?: StartOptions): Promise<void>

启动一个UIAbility。使用Promise异步回调。仅支持在主线程调用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0
    };

    try {
      this.context.startAbility(want, options)
        .then(() => {
          // 执行正常业务
          console.info('startAbility succeed');
        })
        .catch((err: BusinessError) => {
          // 处理业务逻辑错误
          console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

startAbilityForResult

startAbilityForResult(want: Want, callback: AsyncCallback<AbilityResult>): void

启动一个UIAbility，并通过回调函数接收被拉起的UIAbility退出时的返回结果。使用callback异步回调。仅支持在主线程调用。

UIAbility被启动后，有如下情况：

• 正常情况下可以通过调用terminateSelfWithResult接口销毁自身，并将结果返回给调用方。
• 异常情况下比如杀死UIAbility会将异常结果返回给调用方，异常结果中resultCode为-1。
• 如果被启动的UIAbility是单实例模式，且这个UIAbility被不同应用多次调用该接口启动，当这个UIAbility调用terminateSelfWithResult接口销毁自身时，只将正常结果返回给最后一个调用方，其它调用方返回异常结果，异常结果中resultCode为-1。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };

    try {
      this.context.startAbilityForResult(want, (err: BusinessError, result: common.AbilityResult) => {
        if (err.code) {
          // 处理业务逻辑错误
          console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // 执行正常业务
        console.info('startAbilityForResult succeed');
      });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`);
    }
  }
}

startAbilityForResult

startAbilityForResult(want: Want, options: StartOptions, callback: AsyncCallback<AbilityResult>): void

启动一个UIAbility，并通过回调函数接收被拉起的UIAbility退出时的返回结果。使用callback异步回调。仅支持在主线程调用。

UIAbility被启动后，有如下情况：

• 正常情况下可以通过调用terminateSelfWithResult接口销毁自身，并将结果返回给调用方。
• 异常情况下比如杀死UIAbility会将异常结果返回给调用方，异常结果中resultCode为-1。
• 如果被启动的UIAbility是单实例模式，且这个UIAbility被不同应用多次调用该接口启动，当这个UIAbility调用terminateSelfWithResult接口销毁自身时，只将正常结果返回给最后一个调用方，其它调用方返回异常结果，异常结果中resultCode为-1。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want, common, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0
    };

    try {
      this.context.startAbilityForResult(want, options, (err: BusinessError, result: common.AbilityResult) => {
        if (err.code) {
          // 处理业务逻辑错误
          console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // 执行正常业务
        console.info('startAbilityForResult succeed');
      });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`);
    }
  }
}

startAbilityForResult

startAbilityForResult(want: Want, options?: StartOptions): Promise<AbilityResult>

启动一个UIAbility，并通过回调函数接收被拉起的UIAbility退出时的返回结果。使用Promise异步回调。仅支持在主线程调用。

UIAbility被启动后，有如下情况：

• 正常情况下可以通过调用terminateSelfWithResult接口销毁自身，并将结果返回给调用方。
• 异常情况下比如杀死UIAbility会将异常结果返回给调用方，异常结果中resultCode为-1。
• 如果被启动的UIAbility是单实例模式，且这个UIAbility被不同应用多次调用该接口启动，当这个UIAbility调用terminateSelfWithResult接口销毁自身时，只将正常结果返回给最后一个调用方，其它调用方返回异常结果，异常结果中resultCode为-1。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want, common, StartOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0
    };

    try {
      this.context.startAbilityForResult(want, options)
        .then((result: common.AbilityResult) => {
          // 执行正常业务
          console.info('startAbilityForResult succeed');
        })
        .catch((err: BusinessError) => {
          // 处理业务逻辑错误
          console.error(`startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbilityForResult failed, code is ${code}, message is ${message}`);
    }
  }
}

terminateSelf

terminateSelf(callback: AsyncCallback<void>): void

销毁UIAbility自身。使用callback异步回调。仅支持在主线程调用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

1. 使用terminateSelf接口停止UIAbility示例代码如下，默认情况下应用会在最近任务列表中保留快照。

   import { UIAbility } from '@kit.AbilityKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   
   export default class EntryAbility extends UIAbility {
     onForeground() {
       try {
         this.context.terminateSelf((err: BusinessError) => {
           if (err.code) {
             // 处理业务逻辑错误
             console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`);
             return;
           }
           // 执行正常业务
           console.info('terminateSelf succeed');
         });
       } catch (err) {
         // 捕获同步的参数错误
         let code = (err as BusinessError).code;
         let message = (err as BusinessError).message;
         console.error(`terminateSelf failed, code is ${code}, message is ${message}`);
       }
     }
   }

2. （可选）如果需要在停止UIAbility时，清理任务中心的相关任务（即不保留最近任务列表中的快照），需要在module.json5配置文件中将removeMissionAfterTerminate字段取值配置为true。

   {
     "module": {
       // ...
       "abilities": [
         {
           // ...
           "removeMissionAfterTerminate": true
         }
       ]
     }
   }

terminateSelf

terminateSelf(): Promise<void>

销毁UIAbility自身。使用Promise异步回调。仅支持在主线程调用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

返回值：

错误码：

以下错误码详细介绍请参考元能力子系统错误码。

示例：

1. 使用terminateSelf接口停止UIAbility示例代码如下，默认情况下应用会在最近任务列表中保留快照。

   import { UIAbility } from '@kit.AbilityKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   
   export default class EntryAbility extends UIAbility {
     onForeground() {
       try {
         this.context.terminateSelf()
           .then(() => {
             // 执行正常业务
             console.info('terminateSelf succeed');
           })
           .catch((err: BusinessError) => {
             // 处理业务逻辑错误
             console.error(`terminateSelf failed, code is ${err.code}, message is ${err.message}`);
           });
       } catch (err) {
         // 捕获同步的参数错误
         let code = (err as BusinessError).code;
         let message = (err as BusinessError).message;
         console.error(`terminateSelf failed, code is ${code}, message is ${message}`);
       }
     }
   }

2. （可选）如果需要在停止UIAbility时，清理任务中心的相关任务（即不保留最近任务列表中的快照），需要在module.json5配置文件中将removeMissionAfterTerminate字段取值配置为true。

   {
     "module": {
       // ...
       "abilities": [
         {
           // ...
           "removeMissionAfterTerminate": true
         }
       ]
     }
   }

terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult, callback: AsyncCallback<void>): void

销毁UIAbility自身。使用callback异步回调。仅支持在主线程调用。

仅当UIAbility通过startAbilityForResult接口拉起时，调用terminateSelfWithResult接口销毁UIAbility，才会返回结果给调用方。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let resultCode = 100;
    // 返回给接口调用方AbilityResult信息
    let abilityResult: common.AbilityResult = {
      want,
      resultCode
    };

    try {
      this.context.terminateSelfWithResult(abilityResult, (err: BusinessError) => {
        if (err.code) {
          // 处理业务逻辑错误
          console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // 执行正常业务
        console.info('terminateSelfWithResult succeed');
      });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`terminateSelfWithResult failed, code is ${code}, message is ${message}`);
    }
  }
}

terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult): Promise<void>

销毁UIAbility自身。使用Promise异步回调。仅支持在主线程调用。

仅当UIAbility通过startAbilityForResult接口拉起时，调用terminateSelfWithResult接口销毁UIAbility，才会返回结果给调用方。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let resultCode = 100;
    // 返回给接口调用方AbilityResult信息
    let abilityResult: common.AbilityResult = {
      want,
      resultCode
    };

    try {
      this.context.terminateSelfWithResult(abilityResult)
        .then(() => {
          // 执行正常业务
          console.info('terminateSelfWithResult succeed');
        })
        .catch((err: BusinessError) => {
          // 处理业务逻辑错误
          console.error(`terminateSelfWithResult failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`terminateSelfWithResult failed, code is ${code}, message is ${message}`);
    }
  }
}

connectServiceExtensionAbility

connectServiceExtensionAbility(want: Want, options: ConnectOptions): number

将当前UIAbility连接到一个ServiceExtensionAbility，通过返回的proxy与ServiceExtensionAbility进行通信，以使用ServiceExtensionAbility对外提供的能力。仅支持在主线程调用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want, common } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'ServiceExtensionAbility'
    };
    let commRemote: rpc.IRemoteObject;
    let options: common.ConnectOptions = {
      onConnect(elementName, remote) {
        commRemote = remote;
        console.info('onConnect...');
      },
      onDisconnect(elementName) {
        console.info('onDisconnect...');
      },
      onFailed(code) {
        console.info('onFailed...');
      }
    };
    let connection: number;

    try {
      connection = this.context.connectServiceExtensionAbility(want, options);
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`connectServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(connection: number): Promise<void>

断开与ServiceExtensionAbility的连接，断开连接之后开发者需要将连接成功时返回的remote对象置空。使用Promise异步回调。仅支持在主线程调用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    // connection为connectServiceExtensionAbility中的返回值
    let connection = 1;
    let commRemote: rpc.IRemoteObject | null;

    try {
      this.context.disconnectServiceExtensionAbility(connection).then(() => {
        commRemote = null;
        // 执行正常业务
        console.info('disconnectServiceExtensionAbility succeed');
      }).catch((err: BusinessError) => {
        // 处理业务逻辑错误
        console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
      });
    } catch (err) {
      commRemote = null;
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`disconnectServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(connection: number, callback: AsyncCallback<void>): void

断开与ServiceExtensionAbility的连接，断开连接之后开发者需要将连接成功时返回的remote对象置空。使用callback异步回调。仅支持在主线程调用。

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    // connection为connectServiceExtensionAbility中的返回值
    let connection = 1;
    let commRemote: rpc.IRemoteObject | null;

    try {
      this.context.disconnectServiceExtensionAbility(connection, (err: BusinessError) => {
        commRemote = null;
        if (err.code) {
          // 处理业务逻辑错误
          console.error(`disconnectServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // 执行正常业务
        console.info('disconnectServiceExtensionAbility succeed');
      });
    } catch (err) {
      commRemote = null;
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`disconnectServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

startAbilityByCall

startAbilityByCall(want: Want): Promise<Caller>

该接口用于获取Caller通信对象，以便于与Callee进行通信。如果指定UIAbility未启动，则会将UIAbility启动至前台或后台。使用Promise异步回调。仅支持在主线程调用。

该接口不支持拉起启动模式为specified模式的UIAbility。

需要权限：ohos.permission.DISTRIBUTED_DATASYNC

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

下面代码展示的是，调用方启动目标方到后台，获取Caller成功后发消息到目标方，然后释放Caller对象。

import { Caller, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { rpc } from '@kit.IPCKit';

const DOMAIN = 0x0000;
const LOG_TAG = 'TEST_TAG';

class TestParcelable implements rpc.Parcelable {
  age: number = 0;
  name: string = '';
  marshalling(dataOut: rpc.MessageSequence): boolean {
    dataOut.writeInt(this.age);
    dataOut.writeString(this.name);
    return true;
  }
  unmarshalling(dataIn: rpc.MessageSequence): boolean {
    this.age = dataIn.readInt();
    this.name = dataIn.readString();
    return true;
  }
}

export default class EntryAbility extends UIAbility {
  async onForeground() {
    let caller: Caller;
    // 后台启动Ability
    let wantBackground: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility',
    };

    try {
      caller = await this.context.startAbilityByCall(wantBackground);
      await caller.call('TEST_CALL', new TestParcelable());
      caller.release();
    } catch (err) {
      // 处理入参错误异常
      hilog.error(DOMAIN, LOG_TAG, `startAbilityByCall failed ${err}`);
    }
  }
}

下面代码展示，目标方启动后注册监听，销毁时取消监听。

import { AbilityConstant, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { rpc } from '@kit.IPCKit';

const DOMAIN = 0x0000;
const LOG_TAG = 'TEST_TAG';

class TestParcelable implements rpc.Parcelable {
  age: number = 0;
  name: string = '';
  marshalling(dataOut: rpc.MessageSequence): boolean {
    dataOut.writeInt(this.age);
    dataOut.writeString(this.name);
    return true;
  }
  unmarshalling(dataIn: rpc.MessageSequence): boolean {
    this.age = dataIn.readInt();
    this.name = dataIn.readString();
    return true;
  }
}

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    hilog.info(DOMAIN, LOG_TAG, '%{public}s', 'Ability onCreate');
    // 注册监听
    this.callee.on('TEST_CALL', (data: rpc.MessageSequence) => {
      let recv = new TestParcelable();
      data.readParcelable(recv);
      recv.age++;
      return recv;
    });
  }

  onDestroy(): void {
    hilog.info(DOMAIN, LOG_TAG, '%{public}s', 'Ability onDestroy');
    // 取消监听
    this.callee.off('TEST_CALL');
  }
}

下面代码展示，调用方启动目标方到前台场景。

import { Caller, UIAbility, Want } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

const DOMAIN = 0x0000;
const LOG_TAG = 'TEST_TAG';

export default class EntryAbility extends UIAbility {
  async onForeground() {
    let caller: Caller;
    // 启动UIAbility到前台，将parameters中的'ohos.aafwk.param.callAbilityToForeground'配置为true
    let wantForeground: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility',
      parameters: {
        'ohos.aafwk.param.callAbilityToForeground': true
      }
    };

    try {
      caller = await this.context.startAbilityByCall(wantForeground);
      caller.release();
    } catch (err) {
      // 处理入参错误异常
      hilog.error(DOMAIN, LOG_TAG, `startAbilityByCall failed ${err}`);
    }
  }
}

setMissionLabel

setMissionLabel(label: string, callback: AsyncCallback<void>): void

设置UIAbility在多任务界面中显示的名称。使用callback异步回调。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    this.context.setMissionLabel('test', (result: BusinessError) => {
      console.info(`setMissionLabel: ${JSON.stringify(result)}`);
    });
  }
}

setMissionLabel

setMissionLabel(label: string): Promise<void>

设置UIAbility在多任务界面中显示的名称。使用Promise异步回调。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    this.context.setMissionLabel('test').then(() => {
      console.info('success');
    }).catch((err: BusinessError) => {
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`setMissionLabel failed, code is ${code}, message is ${message}`);
    });
  }
}

setMissionContinueState¹⁰⁺

setMissionContinueState(state: AbilityConstant.ContinueState, callback: AsyncCallback<void>): void

设置UIAbility任务的流转状态。使用callback异步回调。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

设备行为差异： 该接口在不支持分布式业务的Wearable设备调用不生效。

参数：

错误码：

错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, AbilityConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE, (result: BusinessError) => {
      console.info(`setMissionContinueState: ${JSON.stringify(result)}`);
    });
  }
}

setMissionContinueState¹⁰⁺

setMissionContinueState(state: AbilityConstant.ContinueState): Promise<void>

设置UIAbility任务的流转状态。使用Promise异步回调。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

设备行为差异： 该接口在不支持分布式业务的Wearable设备调用不生效。

参数：

返回值：

错误码：

错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, AbilityConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    this.context.setMissionContinueState(AbilityConstant.ContinueState.INACTIVE).then(() => {
      console.info('success');
    }).catch((err: BusinessError) => {
      console.error(`setMissionContinueState failed, code is ${err.code}, message is ${err.message}`);
    });
  }
}

restoreWindowStage

restoreWindowStage(localStorage: LocalStorage): void

恢复UIAbility中的WindowStage数据。仅支持在主线程调用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let storage = new LocalStorage();
    this.context.restoreWindowStage(storage);
  }
}

isTerminating

isTerminating(): boolean

查询UIAbility是否处于消亡中状态。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

返回值：

错误码：

以下错误码详细介绍请参考元能力子系统错误码。

示例：

import { UIAbility } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let isTerminating: boolean = this.context.isTerminating();
    console.info(`ability state is ${isTerminating}`);
  }
}

requestDialogService

requestDialogService(want: Want, result: AsyncCallback<dialogRequest.RequestResult>): void

启动一个支持模态弹框的ServiceExtensionAbility。ServiceExtensionAbility被启动后，应用弹出模态弹框，通过调用setRequestResult接口返回结果给调用者。使用callback异步回调。仅支持在主线程调用。

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'AuthAccountServiceExtension'
    };

    try {
      this.context.requestDialogService(want, (err: BusinessError, result: dialogRequest.RequestResult) => {
        if (err.code) {
          // 处理业务逻辑错误
          console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // 执行正常业务
        console.info(`requestDialogService succeed, result = ${JSON.stringify(result)}`);
      });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`requestDialogService failed, code is ${code}, message is ${message}`);
    }
  }
}

requestDialogService

requestDialogService(want: Want): Promise<dialogRequest.RequestResult>

启动一个支持模态弹框的ServiceExtensionAbility。ServiceExtensionAbility被启动后，应用弹出模态弹框，通过调用setRequestResult接口返回结果给调用者。使用Promise异步回调。仅支持在主线程调用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want, dialogRequest } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'AuthAccountServiceExtension'
    };

    try {
      this.context.requestDialogService(want)
        .then((result: dialogRequest.RequestResult) => {
          // 执行正常业务
          console.info(`requestDialogService succeed, result = ${JSON.stringify(result)}`);
        })
        .catch((err: BusinessError) => {
          // 处理业务逻辑错误
          console.error(`requestDialogService failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`requestDialogService failed, code is ${code}, message is ${message}`);
    }
  }
}

reportDrawnCompleted¹⁰⁺

reportDrawnCompleted(callback: AsyncCallback<void>): void

用于通知系统UIAbility对应的窗口内容已经绘制完成。使用callback异步回调。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

错误码：

以下错误码详细介绍请参考元能力子系统错误码。

示例：

import { UIAbility } from '@kit.AbilityKit';
import { window } from '@kit.ArkUI';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        return;
      }

      try {
        this.context.reportDrawnCompleted((err) => {
          if (err.code) {
            // 处理业务逻辑错误
            console.error(`reportDrawnCompleted failed, code is ${err.code}, message is ${err.message}`);
            return;
          }
          // 执行正常业务
          console.info('reportDrawnCompleted succeed');
        });
      } catch (err) {
        // 捕获同步的参数错误
        let code = (err as BusinessError).code;
        let message = (err as BusinessError).message;
        console.error(`reportDrawnCompleted failed, code is ${code}, message is ${message}`);
      }
    });
    console.info("MainAbility onWindowStageCreate");
  }
};

startAbilityByType¹¹⁺

startAbilityByType(type: string, wantParam: Record<string, Object>, abilityStartCallback: AbilityStartCallback, callback: AsyncCallback<void>) : void

通过type隐式启动UIExtensionAbility。使用callback异步回调。仅支持在主线程调用，仅支持处于前台的应用调用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, common } from '@kit.AbilityKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let wantParam: Record<string, Object> = {
      'time': '2023-10-23 20:45'
    };
    let abilityStartCallback: common.AbilityStartCallback = {
      onError: (code: number, name: string, message: string) => {
        console.error(`code:` + code + `name:` + name + `message:` + message);
      },
      onResult: (abilityResult: common.AbilityResult) => {
        console.info(`resultCode:` + abilityResult.resultCode + `bundleName:` + abilityResult.want?.bundleName);
      }
    };

    this.context.startAbilityByType("photoEditor", wantParam, abilityStartCallback, (err) => {
      if (err) {
        console.error(`startAbilityByType fail, err: ${JSON.stringify(err)}`);
      } else {
        console.info(`success`);
      }
    });
  }
}

startAbilityByType¹¹⁺

startAbilityByType(type: string, wantParam: Record<string, Object>, abilityStartCallback: AbilityStartCallback) : Promise<void>

通过type隐式启动UIExtensionAbility。使用Promise异步回调。仅支持在主线程调用，仅支持处于前台的应用调用。

元服务API：从API version 11开始，该接口支持在元服务中使用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let wantParam: Record<string, Object> = {
      'time': '2023-10-23 20:45'
    };
    let abilityStartCallback: common.AbilityStartCallback = {
      onError: (code: number, name: string, message: string) => {
        console.error(`code:` + code + `name:` + name + `message:` + message);
      },
      onResult: (abilityResult: common.AbilityResult) => {
        console.info(`resultCode:` + abilityResult.resultCode + `bundleName:` + abilityResult.want?.bundleName);
      }
    };

    this.context.startAbilityByType("photoEditor", wantParam, abilityStartCallback).then(() => {
      console.info(`startAbilityByType success`);
    }).catch((err: BusinessError) => {
      console.error(`startAbilityByType fail, err: ${JSON.stringify(err)}`);
    });
  }
}

showAbility¹²⁺

showAbility(): Promise<void>

显示当前UIAbility。使用Promise异步回调。仅支持在主线程调用。

调用此接口前要求确保应用已添加至状态栏。

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

设备行为差异：该接口仅在PC/2in1和Tablet设备中可正常调用，在其他设备中返回801错误码。

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

// Index.ets
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  @State showAbility: string = 'showAbility'

  build() {
    Row() {
      Column() {
        Text(this.showAbility)
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

            context.showAbility().then(() => {
              console.info(`showAbility success`);
            }).catch((err: BusinessError) => {
              console.error(`showAbility fail, err: ${JSON.stringify(err)}`);
            });
          });
      }
      .width('100%')
    }
    .height('100%')
  }
}

// EntryAbility.ts
import { UIAbility, Want, StartOptions, contextConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0,
      processMode: contextConstant.ProcessMode.NEW_PROCESS_ATTACH_TO_STATUS_BAR_ITEM,
      startupVisibility: contextConstant.StartupVisibility.STARTUP_SHOW
    };

    try {
      this.context.startAbility(want, options, (err: BusinessError) => {
        if (err.code) {
          // 处理业务逻辑错误
          console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // 执行正常业务
        console.info('startAbility succeed');
      });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

hideAbility¹²⁺

hideAbility(): Promise<void>

隐藏当前UIAbility。使用Promise异步回调。仅支持在主线程调用。

调用此接口前要求确保应用已添加至状态栏。

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

设备行为差异：该接口仅在PC/2in1和Tablet设备中可正常调用，在其他设备中返回801错误码。

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

// Index.ets
import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  @State hideAbility: string = 'hideAbility'

  build() {
    Row() {
      Column() {
        Text(this.hideAbility)
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

            context.hideAbility().then(() => {
              console.info(`hideAbility success`);
            }).catch((err: BusinessError) => {
              console.error(`hideAbility fail, err: ${JSON.stringify(err)}`);
            });
          });
      }
      .width('100%')
    }
    .height('100%')
  }
}

// EntryAbility.ts
import { UIAbility, Want, StartOptions, contextConstant } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let options: StartOptions = {
      displayId: 0,
      processMode: contextConstant.ProcessMode.NEW_PROCESS_ATTACH_TO_STATUS_BAR_ITEM,
      startupVisibility: contextConstant.StartupVisibility.STARTUP_HIDE
    };

    try {
      this.context.startAbility(want, options, (err: BusinessError) => {
        if (err.code) {
          // 处理业务逻辑错误
          console.error(`startAbility failed, code is ${err.code}, message is ${err.message}`);
          return;
        }
        // 执行正常业务
        console.info('startAbility succeed');
      });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

moveAbilityToBackground¹²⁺

moveAbilityToBackground(): Promise<void>

将处于前台的UIAbility移动到后台。使用Promise异步回调。仅支持在主线程调用。

该接口仅支持手机和平板设备。

元服务API：从API version 12开始，该接口支持在元服务中使用。

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

设备行为差异：

• 从API version 12开始，该接口仅在Phone设备中可正常调用，在其他设备上返回16000061错误码。
• 从API version 13开始，该接口仅在Phone和Tablet设备中可正常调用，在其他设备上返回16000061错误码。
• 从API version 18开始，该接口仅在Phone、Tablet和Wearable设备中可正常调用，在其他设备上返回16000061错误码。
• 从API version 19开始，该接口仅在Phone、Tablet、Wearable和TV设备中可正常调用，在其他设备上返回16000061错误码。

返回值：

错误码：

以下错误码详细介绍请参考元能力子系统错误码。

示例：

import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  @State moveAbilityToBackground: string = 'Move To Background'

  build() {
    Row() {
      Column() {
        Text(this.moveAbilityToBackground)
          .fontSize(30)
          .fontWeight(FontWeight.Bold)
          .onClick(() => {
            let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

            context.moveAbilityToBackground().then(() => {
              console.info(`moveAbilityToBackground success.`);
            }).catch((err: BusinessError) => {
              console.error(`moveAbilityToBackground error: ${JSON.stringify(err)}.`);
            });
          });
      }
      .width('100%')
    }
    .height('100%')
  }
}

openAtomicService¹²⁺

openAtomicService(appId: string, options?: AtomicServiceOptions): Promise<AbilityResult>

启动一个独立窗口的元服务。使用Promise异步回调。仅支持在主线程调用。

元服务被启动后，有如下情况：

• 正常情况下元服务可以通过terminateSelfWithResult接口销毁自身，并且返回结果给调用方。
• 异常情况下比如杀死元服务会返回异常结果给调用方，异常结果的resultCode为-1。
• 如果不同应用多次调用该接口启动同一个元服务，当这个元服务调用terminateSelfWithResult接口销毁自身时，只将正常结果返回给最后一个调用方，其它调用方返回异常结果，异常结果中resultCode为-1。

元服务API：从API version 12开始，该接口支持在元服务中使用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, common, AtomicServiceOptions } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let appId: string = '6918661953712445909';
    let options: AtomicServiceOptions = {
      displayId: 0
    };

    try {
      this.context.openAtomicService(appId, options)
        .then((result: common.AbilityResult) => {
          // 执行正常业务
          console.info('openAtomicService succeed');
        })
        .catch((err: BusinessError) => {
          // 处理业务逻辑错误
          console.error(`openAtomicService failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`openAtomicService failed, code is ${code}, message is ${message}`);
    }
  }
}

openLink¹²⁺

openLink(link: string, options?: OpenLinkOptions, callback?: AsyncCallback<AbilityResult>): Promise<void>

通过App Linking或Deep Linking方式启动UIAbility，并通过回调函数接收被拉起的UIAbility退出时的返回结果。使用Promise异步回调。仅支持在主线程调用。

通过在link字段中传入标准格式的URL，基于隐式want匹配规则拉起目标UIAbility。目标方必须同时具备以下过滤器特征，才能处理App Linking链接：

• "actions"列表中包含"ohos.want.action.viewData"。
• "entities"列表中包含"entity.system.browsable"。
• "uris"列表中包含"scheme"为"https"且"domainVerify"为true的元素。

如果希望获取被拉起方终止后的结果，可以设置callback参数，此参数的使用可参照startAbilityForResult接口。

传入的参数不合法时，如未设置必选参数或link字符串不是标准格式的URL，接口会直接抛出异常。参数校验通过，拉起目标方时出现的错误通过promise返回错误信息。

元服务API：从API version 12开始，该接口支持在元服务中使用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { common, OpenLinkOptions } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

const DOMAIN = 0xeeee;
const TAG: string = '[openLinkDemo]';

@Entry
@Component
struct Index {
  build() {
    RelativeContainer() {
      Button("Call StartAbilityForResult")
        .onClick(() => {
          let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
          let link: string = 'https://www.example.com';
          let openLinkOptions: OpenLinkOptions = {
            appLinkingOnly: true,
            parameters: { demo_key: 'demo_value' }
          };

          try {
            context.openLink(
              link,
              openLinkOptions,
              (err, result) => {
                hilog.error(DOMAIN, TAG, `openLink callback error.code: ${JSON.stringify(err)}`);
                hilog.info(DOMAIN, TAG, `openLink callback result: ${JSON.stringify(result.resultCode)}`);
                hilog.info(DOMAIN, TAG, `openLink callback result data: ${JSON.stringify(result.want)}`);
              }
            ).then(() => {
              hilog.info(DOMAIN, TAG, `open link success.`);
            }).catch((err: BusinessError) => {
              hilog.error(DOMAIN, TAG, `open link failed, errCode ${JSON.stringify(err.code)}`);
            });
          }
          catch (e) {
            hilog.error(DOMAIN, TAG, `exception occurred, errCode ${JSON.stringify(e.code)}`);
          }
        })
    }
    .height('100%')
    .width('100%')
  }
}

backToCallerAbilityWithResult¹²⁺

backToCallerAbilityWithResult(abilityResult: AbilityResult, requestCode: string): Promise<void>

当通过startAbilityForResult或openLink拉起目标方UIAbility，且需要目标方返回结果时，目标方可以通过该接口将结果返回并拉起调用方。与terminateSelfWithResult不同的是，本接口在返回时不会销毁当前UIAbility。使用Promise异步回调。

元服务API：从API version 12开始，该接口支持在元服务中使用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

调用方通过startAbilityForResult接口拉起目标方，目标方再调用backToCallerAbilityWithResult接口返回到调用方。

// 调用方
// index.ets
import { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

@Entry
@Component
struct Index {
  @State message: string = 'Hello World';

  build() {
    Row() {
      Column() {
        Text(this.message)
          .fontSize(30)
          .fontWeight(FontWeight.Bold)

        Button("Call StartAbilityForResult")
          .onClick(() => {
            let context: common.UIAbilityContext = this.getUIContext().getHostContext() as common.UIAbilityContext;
            let want: Want = {
              bundleName: 'com.example.demo2',
              abilityName: 'EntryAbility'
            };

            try {
              // 通过startAbilityForResult拉起目标应用
              context.startAbilityForResult(want, (err: BusinessError, result: common.AbilityResult) => {
                if (err.code) {
                  // 处理业务逻辑错误
                  hilog.error(0x0000, 'testTag', `startAbilityForResult failed, code is ${err.code}, message is ${err.message}`);
                  this.message = `startAbilityForResult failed: code is ${err.code}, message is ${err.message}`
                  return;
                }
                // 执行正常业务
                hilog.info(0x0000, 'testTag', `startAbilityForResult succeed`);
                hilog.info(0x0000, 'testTag', `AbilityResult is ${JSON.stringify(result)}`);
                this.message = `AbilityResult.resultCode: ${JSON.stringify(result.resultCode)}`
              });
            } catch (err) {
              // 处理入参错误异常
              let code = (err as BusinessError).code;
              let message = (err as BusinessError).message;
              hilog.error(0x0000, 'testTag', `startAbilityForResult failed, code is ${code}, message is ${message}`);
              this.message = `startAbilityForResult failed, code is ${code}, message is ${message}`;
            }
          })
      }
      .width('100%')
    }
    .height('100%')
  }
}

// 目标方
// EntryAbility.ets
import { AbilityConstant, common, UIAbility, Want, wantConstant } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    // 从want中获取调用方的CALLER_REQUEST_CODE，并保存
    let callerRequestCode: string = want?.parameters?.[wantConstant.Params.CALLER_REQUEST_CODE] as string;
    AppStorage.setOrCreate<string>("callerRequestCode", callerRequestCode)
  }

  onNewWant(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    let callerRequestCode: string = want?.parameters?.[wantConstant.Params.CALLER_REQUEST_CODE] as string;
    AppStorage.setOrCreate<string>("callerRequestCode", callerRequestCode)
  }

  onForeground(): void {
    // 获取保存的CALLER_REQUEST_CODE
    let callerRequestCode: string = AppStorage.get<string>("callerRequestCode") as string;
    hilog.info(0x0000, 'testTag', `callerRequestCode is ${callerRequestCode}`);
    let want: Want = {};
    let resultCode = 100;
    let abilityResult: common.AbilityResult = {
      want,
      resultCode
    };
    try {
      // 将结果信息返回给调用方
      this.context.backToCallerAbilityWithResult(abilityResult, callerRequestCode)
        .then(() => {
          // 执行正常业务
          hilog.info(0x0000, 'testTag', 'backToCallerAbilityWithResult succeed');
        })
        .catch((err: BusinessError) => {
          // 处理业务逻辑错误
          hilog.error(0x0000, 'testTag', `backToCallerAbilityWithResult failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // 捕获同步的参数错误
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      hilog.error(0x0000, 'testTag', `backToCallerAbilityWithResult failed, code is ${code}, message is ${message}`);
    }
  }
}

setRestoreEnabled¹⁴⁺

setRestoreEnabled(enabled: boolean): void

设置UIAbility是否启用备份恢复。

元服务API：从API version 14开始，该接口支持在元服务中使用。

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

设备行为差异：UIAbility备份恢复功能仅在Phone、Tablet、Wearable和TV设备中生效，PC/2in1设备不支持备份恢复功能，Tablet设备开启自由多窗后备份恢复功能也不生效。

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, AbilityConstant, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam): void {
    let enabled = true;
    try {
      this.context.setRestoreEnabled(enabled);
    } catch (paramError) {
      let code = (paramError as BusinessError).code;
      let message = (paramError as BusinessError).message;
      console.error(`setRestoreEnabled failed, err code: ${code}, err msg: ${message}`);
    }
  }
}

startUIServiceExtensionAbility¹⁴⁺

startUIServiceExtensionAbility(want: Want): Promise<void>

启动一个UIServiceExtensionAbility。使用Promise异步回调。

元服务API：从API version 14开始，该接口支持在元服务中使用。

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

设备行为差异：该接口仅在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Index {
  build() {
    Column() {
      Row() {
        // 创建启动按钮
        Button('start ability')
          .enabled(true)
          .onClick(() => {
            let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
            let startWant: Want = {
              bundleName: 'com.acts.uiserviceextensionability',
              abilityName: 'UiServiceExtAbility',
            };
            try {
              // 启动UIServiceExtensionAbility
              context.startUIServiceExtensionAbility(startWant).then(() => {
                console.info('startUIServiceExtensionAbility success');
              }).catch((error: BusinessError) => {
                console.error('startUIServiceExtensionAbility error', JSON.stringify(error));
              })
            } catch (err) {
              console.error('startUIServiceExtensionAbility failed', JSON.stringify(err));
            }
          })
      }
    }
  }
}

connectUIServiceExtensionAbility¹⁴⁺

connectUIServiceExtensionAbility(want: Want, callback: UIServiceExtensionConnectCallback) : Promise<UIServiceProxy>

连接一个UIServiceExtensionAbility。使用Promise异步回调。

元服务API：从API version 14开始，该接口支持在元服务中使用。

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

设备行为差异：该接口仅在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

const TAG: string = '[Extension] ';

@Entry
@Component
struct UIServiceExtensionAbility {
  dataCallBack : common.UIServiceExtensionConnectCallback = {
    // 接收数据
    onData: (data: Record<string, Object>) => {
      console.info(`dataCallBack received data`, JSON.stringify(data));
    },
    // 连接断开
    onDisconnect: () => {
      console.info(`dataCallBack onDisconnect`);
    }
  }

  async myConnect() {
    // 获取上下文
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
    let startWant: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'UiServiceExtAbility'
    };

    try {
      // 连接服务
      context.connectUIServiceExtensionAbility(startWant, this.dataCallBack)
        .then((proxy: common.UIServiceProxy) => {
          console.info(TAG + `try to connectUIServiceExtensionAbility`, JSON.stringify(proxy));
        }).catch((err: Error) => {
        let code = (err as BusinessError).code;
        let message = (err as BusinessError).message;
        console.error(TAG + `connectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`);
      });
    } catch (err) {
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(TAG + `connectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    };
  }

  build() {
    RelativeContainer() {
      // 创建连接按钮
      Button('connectServiceExtensionAbility', { type: ButtonType.Capsule, stateEffect: true })
        .alignRules({
          center: { anchor: '__container__', align: VerticalAlign.Center },
          middle: { anchor: '__container__', align: HorizontalAlign.Center }
        })
        .onClick(() => {
          this.myConnect()
        });
    }
    .height('100%')
    .width('100%')
  }
}

disconnectUIServiceExtensionAbility¹⁴⁺

disconnectUIServiceExtensionAbility(proxy: UIServiceProxy): Promise<void>

断开与UIServiceExtensionAbility的连接。使用Promise异步回调。

元服务API：从API version 14开始，该接口支持在元服务中使用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { common } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

const TAG: string = '[Extension] ';

@Entry
@Component
struct UIServiceExtensionAbility {
  comProxy: common.UIServiceProxy | null = null;

  build() {
    Scroll() {
      Column() {
        // 创建断开连接的按钮
        Button('disconnectUIServiceExtensionAbility', { type: ButtonType.Capsule, stateEffect: true })
          .margin({
            top: 5,
            left: 10,
            right: 10,
            bottom: 5
          })
          .alignRules({
            center: { anchor: '__container__', align: VerticalAlign.Center },
            middle: { anchor: '__container__', align: HorizontalAlign.Center }
          })
          .onClick(() => {
            this.myDisconnectUIServiceExtensionAbility()
          });
      }
      .width('100%')
    }
    .height('100%')
  }

  myDisconnectUIServiceExtensionAbility() {
    let context = this.getUIContext().getHostContext() as common.UIAbilityContext;

    try {
      // 断开UIServiceExtension连接
      context.disconnectUIServiceExtensionAbility(this.comProxy)
        .then(() => {
          console.info(TAG + `disconnectUIServiceExtensionAbility succeed ${this.comProxy}`);
        }).catch((err: Error) => {
        let code = (err as BusinessError).code;
        let message = (err as BusinessError).message;
        console.error(TAG + `disconnectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`);
      });
    } catch (err) {
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(TAG + `disconnectUIServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

setAbilityInstanceInfo¹⁵⁺

setAbilityInstanceInfo(label: string, icon: image.PixelMap): Promise<void>

设置当前UIAbility实例的图标和标签信息。图标与标签信息可在任务中心和快捷栏的界面中显示。使用Promise异步回调。

需要权限： ohos.permission.SET_ABILITY_INSTANCE_INFO

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

设备行为差异：该接口仅在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility } from '@kit.AbilityKit';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { window } from '@kit.ArkUI';

export default class EntryAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage): void {
    windowStage.loadContent('pages/Index', async (err, data) => {
      if (err.code) {
        console.error(`loadContent failed, code is ${err.code}`);
        return;
      }

      let newLabel: string = 'instance label';
      let color = new ArrayBuffer(512 * 512 * 4); // 创建一个ArrayBuffer对象，用于存储图像像素。该对象的大小为（height * width * 4）字节。
      let bufferArr = new Uint8Array(color);
      for (let i = 0; i < bufferArr.length; i += 4) {
        bufferArr[i] = 255;
        bufferArr[i+1] = 0;
        bufferArr[i+2] = 122;
        bufferArr[i+3] = 255;
      }
      let opts: image.InitializationOptions = {
        editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 512, width: 512 }
      };
      let imagePixelMap: image.PixelMap = await image.createPixelMap(color, opts);
      // 设置UIAbility实例的图标和标签信息
      try {
        this.context.setAbilityInstanceInfo(newLabel, imagePixelMap)
          .then(() => {
            console.info('setAbilityInstanceInfo success');
          }).catch((err: BusinessError) => {
            console.error(`setAbilityInstanceInfo failed, code is ${err.code}, message is ${err.message}`);
          });
      } catch (paramError) {
        let code = (paramError as BusinessError).code;
        let message = (paramError as BusinessError).message;
        console.error(`setAbilityInstanceInfo failed, code is ${code}, message is ${message}`);
      }
    });
  }
}

revokeDelegator¹⁷⁺

revokeDelegator(): Promise<void>

如果Module下首个UIAbility启动时期望重定向到另一个UIAbility，该重定向的UIAbility被称为“DelegatorAbility”。DelegatorAbility的设置详见当前接口示例的步骤1。

当DelegatorAbility完成特定操作时，可以使用该接口回到首个UIAbility。使用Promise异步回调。

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

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

1. 设置DelegatorAbility。

   在module.json5配置文件标签中配置abilitySrcEntryDelegator和abilityStageSrcEntryDelegator。当Module下首个UIAbility冷启动时，系统优先启动abilitySrcEntryDelegator指向的UIAbility。

   说明

   • 当UIAbility是通过startAbilityByCall启动时，系统会忽略在module.json5配置文件标签中配置的abilitySrcEntryDelegator和abilityStageSrcEntryDelegator。
   • abilityStageSrcEntryDelegator指定的ModuleName不能与当前ModuleName相同。

   {
     "module": {
       // ...
       "abilityStageSrcEntryDelegator": "xxxModuleName",
       "abilitySrcEntryDelegator": "xxxAbilityName",
       // ...
     }
   }

2. 取消DelegatorAbility。

   import { UIAbility } from '@kit.AbilityKit';
   import { BusinessError } from '@kit.BasicServicesKit';
   
   export default class DelegatorAbility extends UIAbility {
     onForeground() {
       // DelegatorAbility完成特定操作后，调用revokeDelegator回到首个UIAbility
       this.context.revokeDelegator().then(() => {
         console.info('revokeDelegator success');
       }).catch((err: BusinessError) => {
         console.error(`revokeDelegator failed, code is ${err.code}, message is ${err.message}`);
       });
     }
   }

setColorMode¹⁸⁺

setColorMode(colorMode: ConfigurationConstant.ColorMode): void

设置UIAbility的深浅色模式。调用该接口前需要保证该UIAbility对应页面已完成加载。仅支持主线程调用。

元服务API：从API version 18开始，该接口支持在元服务中使用。

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

参数：

错误码：

以下错误码详细介绍请参考元能力子系统错误码。

示例：

import { UIAbility, ConfigurationConstant } from '@kit.AbilityKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { window } from '@kit.ArkUI';

export default class MyAbility extends UIAbility {
  onWindowStageCreate(windowStage: window.WindowStage) {
    windowStage.loadContent('pages/Index', (err, data) => {
      if (err.code) {
        hilog.error(0x0000, 'testTag', 'Failed to load the content.');
        return;
      }
      let uiAbilityContext = this.context;
      uiAbilityContext.setColorMode(ConfigurationConstant.ColorMode.COLOR_MODE_DARK);
    });
  }
}

startAppServiceExtensionAbility²⁰⁺

startAppServiceExtensionAbility(want: Want): Promise<void>

启动AppServiceExtensionAbility实例。使用Promise异步回调。

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

设备行为差异：该接口仅在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'AppServiceExtensionAbility'
    };

    try {
      this.context.startAppServiceExtensionAbility(want)
        .then(() => {
          // 执行正常业务
          console.info('startAppServiceExtensionAbility succeed');
        })
        .catch((err: BusinessError) => {
          // 处理业务逻辑错误
          console.error(`startAppServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startAppServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

stopAppServiceExtensionAbility²⁰⁺

stopAppServiceExtensionAbility(want: Want): Promise<void>

停止AppServiceExtensionAbility实例。使用Promise异步回调。

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

设备行为差异：该接口仅在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'AppServiceExtensionAbility'
    };

    try {
      this.context.stopAppServiceExtensionAbility(want)
        .then(() => {
          // 执行正常业务
          console.info('stopAppServiceExtensionAbility succeed');
        })
        .catch((err: BusinessError) => {
          // 处理业务逻辑错误
          console.error(`stopAppServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`stopAppServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

connectAppServiceExtensionAbility²⁰⁺

connectAppServiceExtensionAbility(want: Want, callback: ConnectOptions): number

将当前UIAbility连接到AppServiceExtensionAbility。通过返回的proxy与AppServiceExtensionAbility进行通信，以使用AppServiceExtensionAbility对外提供的能力。仅支持在主线程调用。

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

设备行为差异：该接口仅在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want, common } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'AppServiceExtensionAbility'
    };
    let commRemote: rpc.IRemoteObject;
    let callback: common.ConnectOptions = {
      onConnect(elementName, remote) {
        commRemote = remote;
        console.info('onConnect...');
      },
      onDisconnect(elementName) {
        console.info('onDisconnect...');
      },
      onFailed(code) {
        console.info('onFailed...');
      }
    };
    let connection: number;

    try {
      connection = this.context.connectAppServiceExtensionAbility(want, callback);
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`connectAppServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

disconnectAppServiceExtensionAbility²⁰⁺

disconnectAppServiceExtensionAbility(connection: number): Promise<void>

断开与AppServiceExtensionAbility的连接。仅支持在主线程调用。使用Promise异步回调。

断开连接之后，为了防止使用可能失效的remote对象进行通信，建议将连接成功时返回的remote对象设置为null。

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

设备行为差异：该接口仅在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility } from '@kit.AbilityKit';
import { rpc } from '@kit.IPCKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    // connection为connectAppServiceExtensionAbility中的返回值
    let connection = 1;
    let commRemote: rpc.IRemoteObject | null;

    try {
      this.context.disconnectAppServiceExtensionAbility(connection).then(() => {
        commRemote = null;
        // 执行正常业务
        console.info('disconnectAppServiceExtensionAbility succeed');
      }).catch((err: BusinessError) => {
        // 处理业务逻辑错误
        console.error(`disconnectAppServiceExtensionAbility failed, code is ${err.code}, message is ${err.message}`);
      });
    } catch (err) {
      commRemote = null;
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`disconnectAppServiceExtensionAbility failed, code is ${code}, message is ${message}`);
    }
  }
}

setOnNewWantSkipScenarios²⁰⁺

setOnNewWantSkipScenarios(scenarios: number): Promise<void>

在特定场景下拉起UIAbility时，如果不需要触发onNewWant生命周期回调，可以通过该接口设置。仅支持在主线程调用。使用Promise异步回调。

元服务API：从API version 20开始，该接口支持在元服务中使用。

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

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { AbilityConstant, contextConstant, UIAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate(want: Want, launchParam: AbilityConstant.LaunchParam) {
    let scenarios: number = contextConstant.Scenarios.SCENARIO_MOVE_MISSION_TO_FRONT |
      contextConstant.Scenarios.SCENARIO_SHOW_ABILITY |
      contextConstant.Scenarios.SCENARIO_BACK_TO_CALLER_ABILITY_WITH_RESULT;

    try {
      this.context.setOnNewWantSkipScenarios(scenarios).then(() => {
        // 执行正常业务
        console.info('setOnNewWantSkipScenarios succeed');
      }).catch((err: BusinessError) => {
        // 处理业务逻辑错误
        console.error(`setOnNewWantSkipScenarios failed, code is ${err.code}, message is ${err.message}`);
      });
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`setOnNewWantSkipScenarios failed, code is ${code}, message is ${message}`);
    }
  }
}

startSelfUIAbilityInCurrentProcess²²⁺

startSelfUIAbilityInCurrentProcess(want: Want, specifiedFlag: string, options?: StartOptions): Promise<void>

在当前进程中启动应用程序自己的UIAbility。

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

设备行为差异：

• 从API version 23开始，该接口仅在PC/2in1和Tablet设备中可正常调用，在其他设备中返回801错误码。
• 从API version 22开始，该接口仅在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, StartOptions, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      deviceId: '',
      bundleName: 'com.example.myapplication',
      abilityName: 'EntryAbility'
    };
    let accountId = 100;
    let options: StartOptions = {
      displayId: 0
    };
    
    let instanceFlag = 'instance1';

    try {
      this.context.startSelfUIAbilityInCurrentProcess(want, instanceFlag, options);
    } catch (err) {
      // 处理入参错误异常
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startSelfUIAbilityInCurrentProcess failed, code is ${code}, message is ${message}`);
    }
  }
}

restartApp²²⁺

restartApp(want: Want): Promise<void>

处于获焦状态的UIAbility可以通过该接口，重启当前UIAbility所在的进程，并拉起应用内的指定UIAbility。仅支持主线程调用。使用Promise异步回调。

如果指定UIAbility就是当前UIAbility，则会刷新窗口至初始状态；如果是其他UIAbility，则会跳转并打开新的UIAbility窗口。

元服务API：从API version 22开始，该接口支持在元服务中使用。

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

设备行为差异：该接口仅在Phone设备中可正常调用，在其他设备中返回801错误码。

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { hilog } from '@kit.PerformanceAnalysisKit';
import { common, Want } from '@kit.AbilityKit';

@Entry
@Component
struct Index {
  @State message: string = 'restartApp with window';

  build() {
    RelativeContainer() {
      Text(this.message)
        .id('HelloWorld')
        .fontSize($r('app.float.page_text_font_size'))
        .fontWeight(FontWeight.Bold)
        .alignRules({
          center: { anchor: '__container__', align: VerticalAlign.Center },
          middle: { anchor: '__container__', align: HorizontalAlign.Center }
        })
        .onClick(async () => {
          let want: Want = {
            bundleName: 'com.example.myapplication',
            abilityName: 'EntryAbility'
          };
          let context = this.getUIContext().getHostContext() as common.UIAbilityContext;
          try {
            await context.restartApp(want);
          } catch (err) {
            hilog.error(0x0000, 'testTag', `restart failed: ${err.code}, ${err.message}`);
          }
        })
    }
    .height('100%')
    .width('100%')
  }
}

setMissionWindowIcon²²⁺

setMissionWindowIcon(windowIcon: image.PixelMap): Promise<void>

设置当前UIAbility在应用窗口、任务中心应用卡片、快捷栏窗口快照的图标。使用Promise异步回调。

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

设备行为差异：该接口仅在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

参数：

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility } from '@kit.AbilityKit';
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let imagePixelMap: image.PixelMap;
    let color = new ArrayBuffer(1024 * 1024 * 4); // 创建一个ArrayBuffer对象，用于存储图像像素。该对象的大小为（height * width * 4）字节。
    let bufferArr = new Uint8Array(color);
    for (let i = 0; i < bufferArr.length; i += 4) {
      bufferArr[i] = 255;
      bufferArr[i+1] = 0;
      bufferArr[i+2] = 122;
      bufferArr[i+3] = 255;
    }
    image.createPixelMap(color, {
      editable: true, pixelFormat: image.PixelMapFormat.RGBA_8888, size: { height: 1024, width: 1024 }
    }).then((data) => {
      imagePixelMap = data;
      this.context.setMissionWindowIcon(imagePixelMap)
        .then(() => {
          console.info('setMissionWindowIcon succeed');
        })
        .catch((err: BusinessError) => {
          console.error(`setMissionWindowIcon failed, code is ${err.code}, message is ${err.message}`);
        });
    }).catch((err: BusinessError) => {
      console.error(`createPixelMap failed, code is ${err.code}, message is ${err.message}`);
    });
  }
}

startSelf

startSelf(): Promise<void>

启动当前UIAbility实例，将UIAbility切换至前台，用于将停留在中间阶段的Native UIAbility拉到前台。使用Promise异步回调。

起始版本： 26.0.0

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

设备行为差异：该接口仅在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

返回值：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onCreate() {
    try {
      setTimeout((): void => {
        this.context.startSelf()
          .then((): void => {
            console.info('startSelf succeed');
          })
          .catch((err: BusinessError): void => {
            console.error(`startSelf failed, code is ${err.code}, message is ${err.message}`);
          });
      }, 100);
    } catch (err) {
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startSelf failed, code is ${code}, message is ${message}`);
    }
  }
}

startSelfUIAbilityInChildProcess

startSelfUIAbilityInChildProcess(want: Want, specifiedFlag: string): Promise<void>

在子进程中启动当前应用的UIAbility，子进程中的UIAbility支持加载Native模块。使用Promise异步回调。

起始版本： 26.0.0

模型约束：此接口仅可在Stage模型下使用。

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

设备行为差异：该接口仅在PC/2in1设备中可正常调用，在其他设备中返回801错误码。

参数：

错误码：

以下错误码详细介绍请参考通用错误码和元能力子系统错误码。

示例：

import { UIAbility, Want } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';

export default class EntryAbility extends UIAbility {
  onForeground() {
    let want: Want = {
      bundleName: 'com.example.myapplication',
      abilityName: 'ChildProcessAbility'
    };
    let instanceFlag = 'instance1';
    try {
      this.context.startSelfUIAbilityInChildProcess(want, instanceFlag)
        .then(() => {
          console.info('startSelfUIAbilityInChildProcess succeed');
        })
        .catch((err: BusinessError) => {
          console.error(`startSelfUIAbilityInChildProcess failed, code is ${err.code}, message is ${err.message}`);
        });
    } catch (err) {
      let code = (err as BusinessError).code;
      let message = (err as BusinessError).message;
      console.error(`startSelfUIAbilityInChildProcess failed, code is ${code}, message is ${message}`);
    }
  }
}