鸿蒙5.0开发进阶：ArkTS API-UIAbilityContext

最新推荐文章于 2025-09-16 07:59:19 发布
原创 最新推荐文章于 2025-09-16 07:59:19 发布 · 1.2k 阅读 · 9 ·
CC 4.0 BY-SA版权
版权声明：本文为博主原创文章，遵循 CC 4.0 BY-SA 版权协议，转载请附上原文出处链接和本声明。
文章标签：

#harmonyos #华为 #android #鸿蒙系统 #前端 #ArkTS #ArkUI

往期鸿蒙全套实战文章必看：（文中附带全栈鸿蒙学习资料）

UIAbilityContext

UIAbilityContext是需要保存状态的UIAbility所对应的context，继承自Context，提供UIAbility的相关配置信息以及操作UIAbility和ServiceExtensionAbility的方法，如启动UIAbility，停止当前UIAbilityContext所属的UIAbility，启动、停止、连接、断开连接ServiceExtensionAbility等。

说明

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

导入模块

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

属性

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

名称类型可读可写说明
abilityInfoAbilityInfo是否

UIAbility的相关信息。

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

currentHapModuleInfoHapModuleInfo是否

当前HAP的信息。

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

configConfiguration是否

与UIAbility相关的配置信息，如语言、颜色模式等。

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

windowStage12+window.WindowStage是否

当前WindowStage对象。仅支持在主线程调用。

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

说明

在本文档的示例中，通过this.context来获取UIAbilityContext，其中this代表继承自UIAbility的UIAbility实例。

UIAbilityContext.startAbility

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

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

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

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

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
callbackAsyncCallback<void>是callback形式返回启动结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000018The application is not allow jumping to other applications.
16000019Can not match any component.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.
16000073The app clone index is invalid.

示例：

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

UIAbilityContext.startAbility

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

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

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

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

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
optionsStartOptions是启动Ability所携带的参数。
callbackAsyncCallback<void>是callback形式返回启动结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
801Capability not support.
16000001The specified ability does not exist.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000018The application is not allow jumping to other applications.
16000019Can not match any component.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16000067Start options check failed.
16000068Ability already running.
16200001The caller has been released.
16300003The target application is not self application.
16000073The app clone index is invalid.

示例：

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

UIAbilityContext.startAbility

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

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

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

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

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
optionsStartOptions否启动Ability所携带的参数。

返回值：

类型说明
Promise<void>Promise形式返回启动结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
801Capability not support.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000018The application is not allow jumping to other applications.
16000019Can not match any component.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16000067Start options check failed.
16000068Ability already running.
16200001The caller has been released.
16300003The target application is not self application.
16000073The app clone index is invalid.

示例：

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

UIAbilityContext.startAbilityForResult

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

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

Ability被启动后，有如下情况:

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

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

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

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
callbackAsyncCallback<AbilityResult>是执行结果回调函数。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000018The application is not allow jumping to other applications.
16000019Can not match any component.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.
16000073The app clone index is invalid.

示例：

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

UIAbilityContext.startAbilityForResult

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

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

Ability被启动后，有如下情况:

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

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

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

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
optionsStartOptions是启动Ability所携带的参数。
callbackAsyncCallback<AbilityResult>是执行结果回调函数。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001The specified ability does not exist.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000018The application is not allow jumping to other applications.
16000019Can not match any component.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.
16000073The app clone index is invalid.

示例：

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

UIAbilityContext.startAbilityForResult

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

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

Ability被启动后，有如下情况:

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

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

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

参数：

参数名类型必填说明
wantWant是启动Ability的want信息。
optionsStartOptions否启动Ability所携带的参数。

返回值：

类型说明
Promise<AbilityResult>Promise形式返回执行结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000018The application is not allow jumping to other applications.
16000019Can not match any component.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.
16000073The app clone index is invalid.

示例：

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

UIAbilityContext.terminateSelf

terminateSelf(callback: AsyncCallback<void>): void

停止Ability自身。使用callback异步回调。仅支持在主线程调用。

说明

调用该接口后，任务中心的任务默认不会清理，如需清理，需要配置removeMissionAfterTerminate为true。

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

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

参数：

参数名类型必填说明
callbackAsyncCallback<void>是停止Ability自身的回调函数。

错误码：

以下错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000050Internal error.

示例：

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

UIAbilityContext.terminateSelf

terminateSelf(): Promise<void>

停止Ability自身。使用Promise异步回调。仅支持在主线程调用。

说明

调用该接口后，任务中心的任务默认不会清理，如需清理，需要配置removeMissionAfterTerminate为true。

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

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

返回值：

类型说明
Promise<void>停止Ability自身的回调函数。

错误码：

以下错误码详细介绍。

错误码ID错误信息
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000050Internal error.

示例：

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

UIAbilityContext.terminateSelfWithResult

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

停止当前的Ability。使用callback异步回调。仅支持在主线程调用。

如果该Ability是通过调用startAbilityForResult接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用startAbilityForResult接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者。

说明

调用该接口后，任务中心的任务默认不会清理，如需清理，需要配置removeMissionAfterTerminate为true。

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

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

参数：

参数名类型必填说明
parameterAbilityResult是返回给调用startAbilityForResult 接口调用方的相关信息。
callbackAsyncCallback<void>是callback形式返回停止结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000050Internal error.

示例：


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

UIAbilityContext.terminateSelfWithResult

terminateSelfWithResult(parameter: AbilityResult): Promise<void>

停止当前的Ability。使用Promise异步回调。仅支持在主线程调用。

如果该Ability是通过调用startAbilityForResult接口被拉起的，调用terminateSelfWithResult接口时会将结果返回给调用者，如果该Ability不是通过调用startAbilityForResult接口被拉起的，调用terminateSelfWithResult接口时不会有结果返回给调用者。

说明

调用该接口后，任务中心的任务默认不会清理，如需清理，需要配置removeMissionAfterTerminate为true。

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

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

参数：

参数名类型必填说明
parameterAbilityResult是返回给startAbilityForResult 调用方的信息。

返回值：

类型说明
Promise<void>promise形式返回停止结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000050Internal error.

示例：


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

UIAbilityContext.connectServiceExtensionAbility

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

将当前Ability连接到一个ServiceExtensionAbility。仅支持在主线程调用。

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

参数：

参数名类型必填说明
wantWant是连接ServiceExtensionAbility的want信息。
optionsConnectOptions是与ServiceExtensionAbility建立连接后回调函数的实例。

返回值：

类型说明
number返回Ability连接的结果code。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000011The context does not exist.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.

示例：

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

UIAbilityContext.disconnectServiceExtensionAbility

disconnectServiceExtensionAbility(connection: number): Promise<void>

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

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

参数：

参数名类型必填说明
connectionnumber是连接的ServiceExtensionAbility的数字代码，即connectServiceExtensionAbility返回的connectionId。

返回值：

类型说明
Promise<void>返回执行结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011The context does not exist.
16000050Internal error.

示例：

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

UIAbilityContext.disconnectServiceExtensionAbility

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

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

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

参数：

参数名类型必填说明
connectionnumber是连接的ServiceExtensionAbility的数字代码，即connectServiceExtensionAbility返回的connectionId。
callbackAsyncCallback<void>是callback形式返回断开连接的结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011The context does not exist.
16000050Internal error.

示例：

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

UIAbilityContext.startAbilityByCall

startAbilityByCall(want: Want): Promise<Caller>

跨设备场景下，启动指定Ability至前台或后台，同时获取其Caller通信接口，调用方可使用Caller与被启动的Ability进行通信。使用Promise异步回调。仅支持在主线程调用。

说明

组件启动规则详见：组件启动规则（Stage模型）。

需要权限： ohos.permission.DISTRIBUTED_DATASYNC

说明

API version 11之前的版本，该接口需要申请权限ohos.permission.ABILITY_BACKGROUND_COMMUNICATION（该权限仅系统应用可申请）。从API version 11开始，该接口需要申请的权限变更为ohos.permission.DISTRIBUTED_DATASYNC权限。

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

参数：

参数名类型必填说明
wantWant是传入需要启动的Ability的信息，包含abilityName、moduleName、bundleName、deviceId、parameters(可选)，parameters缺省或为空表示后台启动Ability。

返回值：

类型说明
Promise<Caller>获取要通讯的caller对象。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000018The application is not allow jumping to other applications.
16000050Internal error.
16000073The app clone index is invalid.

示例：

后台启动：

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

export default class EntryAbility extends UIAbility {
  onForeground() {
    let caller: Caller;
    // 后台启动Ability，不配置parameters
    let wantBackground: Want = {
      bundleName: 'com.example.myapplication',
      moduleName: 'entry',
      abilityName: 'EntryAbility',
      deviceId: ''
    };

    try {
      this.context.startAbilityByCall(wantBackground)
        .then((obj: Caller) => {
          // 执行正常业务
          caller = obj;
          console.info('startAbilityByCall succeed');
        }).catch((err: BusinessError) => {
        // 处理业务逻辑错误
        console.error(`startAbilityByCall 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(`startAbilityByCall failed, code is ${code}, message is ${message}`);
    }
  }
}

前台启动：

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

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

    try {
      this.context.startAbilityByCall(wantForeground)
        .then((obj: Caller) => {
          // 执行正常业务
          caller = obj;
          console.info('startAbilityByCall succeed');
        }).catch((err: BusinessError) => {
        // 处理业务逻辑错误
        console.error(`startAbilityByCall 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(`startAbilityByCall failed, code is ${code}, message is ${message}`);
    }
  }
}

UIAbilityContext.setMissionLabel

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

设置UIAbility在任务中显示的名称（callback形式）。

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

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

参数：

参数名类型必填说明
labelstring是显示名称。
callbackAsyncCallback<void>是回调函数，返回接口调用是否成功的结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011The context does not exist.
16000050Internal error.

示例：

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

UIAbilityContext.setMissionLabel

setMissionLabel(label: string): Promise<void>

设置UIAbility在任务中显示的名称（promise形式）。

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

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

参数：

参数名类型必填说明
labelstring是显示名称。

返回值：

类型说明
Promise<void>返回一个Promise，包含接口的结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011The context does not exist.
16000050Internal error.

示例：

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

UIAbilityContext.setMissionContinueState10+

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

设置UIAbility任务中流转状态（callback形式）。

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

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

参数：

参数名类型必填说明
stateAbilityConstant.ContinueState是流转状态。
callbackAsyncCallback<void>是回调函数，返回接口调用是否成功的结果。

错误码：

错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011The context does not exist.
16000050Internal error.

示例：

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

UIAbilityContext.setMissionContinueState10+

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

设置UIAbility任务中流转状态（promise形式）。

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

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

参数：

参数名类型必填说明
stateAbilityConstant.ContinueState是流转状态。

返回值：

类型说明
Promise<void>返回一个Promise，包含接口的结果。

错误码：

错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011The context does not exist.
16000050Internal error.

示例：

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

UIAbilityContext.restoreWindowStage

restoreWindowStage(localStorage: LocalStorage): void

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

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

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

参数：

参数名类型必填说明
localStorageLocalStorage是用于恢复window stage的存储数据。

错误码：

以下错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000011The context does not exist.
16000050Internal error.

示例：

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

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

UIAbilityContext.isTerminating

isTerminating(): boolean

查询UIAbility是否在terminating状态。

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

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

返回值：

类型说明
booleantrue：ability当前处于terminating状态；false：不处于terminating状态。

错误码：

以下错误码详细介绍。

错误码ID错误信息
16000011The context does not exist.

示例：

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

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

UIAbilityContext.requestDialogService

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

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

说明

组件启动规则详见：组件启动规则（Stage模型）。

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

参数：

参数名类型必填说明
wantWant是启动ServiceExtensionAbility的want信息。
resultAsyncCallback<dialogRequest.RequestResult>是执行结果回调函数。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

示例：

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

UIAbilityContext.requestDialogService

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

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

说明

组件启动规则详见：组件启动规则（Stage模型）。

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

参数：

参数名类型必填说明
wantWant是启动ServiceExtensionAbility的want信息。

返回值：

类型说明
Promise<dialogRequest.RequestResult>Promise形式返回执行结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

示例：

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

UIAbilityContext.reportDrawnCompleted10+

reportDrawnCompleted(callback: AsyncCallback<void>): void

当页面加载完成（loadContent成功）时，为开发者提供打点功能（callback形式）。

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

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

参数：

参数名类型必填说明
callbackAsyncCallback<void>是页面加载完成打点的回调函数。

错误码：

以下错误码详细介绍。

错误码ID错误信息
16000011The context does not exist.
16000050Internal error.

示例：


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.log("MainAbility onWindowStageCreate");
}
};

UIAbilityContext.startAbilityByType11+

startAbilityByType(type: string, wantParam: Record<string, Object>,

abilityStartCallback: AbilityStartCallback, callback: AsyncCallback<void>) : void

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

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

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

参数：

参数名类型必填说明
typestring是显示拉起的UIExtensionAbility类型，取值详见通过startAbilityByType接口拉起垂类面板。
wantParamRecord<string, Object>是表示扩展参数。
abilityStartCallbackAbilityStartCallback是执行结果回调函数。
callbackAsyncCallback<void>是回调函数，返回接口调用是否成功的结果。

错误码：

以下错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000050Internal error.

示例：

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.log(`code:` + code + `name:` + name + `message:` + message);
      },
      onResult: (abilityResult: common.AbilityResult) => {
        console.log(`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.log(`success`);
      }
    });
  }
}

UIAbilityContext.startAbilityByType11+

startAbilityByType(type: string, wantParam: Record<string, Object>,

abilityStartCallback: AbilityStartCallback) : Promise<void>

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

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

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

参数：

参数名类型必填说明
typestring是显示拉起的UIExtensionAbility类型，取值详见通过startAbilityByType接口拉起垂类面板。
wantParamRecord<string, Object>是表示扩展参数。
abilityStartCallbackAbilityStartCallback是执行结果回调函数。

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000050Internal error.

示例：

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.log(`code:` + code + `name:` + name + `message:` + message);
      },
      onResult: (abilityResult: common.AbilityResult) => {
        console.log(`resultCode:` + abilityResult.resultCode + `bundleName:` + abilityResult.want?.bundleName);
      }
    };

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

UIAbilityContext.showAbility12+

showAbility(): Promise<void>

显示当前Ability。使用Promise异步回调。仅在2in1设备上生效。仅支持在主线程调用。

调用此接口要求当前Ability必须通过UIAbilityContext.startAbility启动，且启动入参中options.processMode必须设置为NEW_PROCESS_ATTACH_TO_STATUS_BAR_ITEM或者ATTACH_TO_STATUS_BAR_ITEM。

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

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码详细介绍。

错误码ID错误信息
801Capability not support.
16000050Internal error.
16000067Start options check failed.

示例：

// 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 = getContext(this) as common.UIAbilityContext;

            context.showAbility().then(() => {
              console.log(`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
    };

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

UIAbilityContext.hideAbility12+

hideAbility(): Promise<void>

隐藏当前Ability。使用Promise异步回调。仅在2in1设备上生效。仅支持在主线程调用。

调用此接口要求当前Ability必须通过UIAbilityContext.startAbility启动，且启动入参中options.processMode必须设置为NEW_PROCESS_ATTACH_TO_STATUS_BAR_ITEM或者ATTACH_TO_STATUS_BAR_ITEM。

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

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码详细介绍。

错误码ID错误信息
801Capability not support.
16000050Internal error.
16000067Start options check failed.

示例：

// 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 = getContext(this) as common.UIAbilityContext;

context.hideAbility().then(() => {
console.log(`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
    };

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

UIAbilityContext.moveAbilityToBackground12+

moveAbilityToBackground(): Promise<void>

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

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

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

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

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

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

错误码ID错误信息
16000011The context does not exist.
16000050Internal error.
16000061Operation not supported.
16000065The interface can be called only when ability is foreground.
16000066An ability cannot move to foreground or background in Wukong mode.

示例：

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 = getContext(this) as common.UIAbilityContext;

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

UIAbilityContext.openAtomicService12+

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

跳出式启动EmbeddableUIAbility，并返回结果。使用Promise异步回调。仅支持在主线程调用。

分为以下几种情况：

  • 正常情况下可通过调用terminateSelfWithResult接口使之终止并且返回结果给调用方。
  • 异常情况下比如杀死EmbeddableUIAbility会返回异常信息给调用方，异常信息中resultCode为-1。
  • 如果不同应用多次调用该接口启动同一个EmbeddableUIAbility，当这个EmbeddableUIAbility调用terminateSelfWithResult接口使之终止时，只将正常结果返回给最后一个调用方, 其它调用方返回异常信息，异常信息中resultCode为-1。

说明

组件启动规则详见：组件启动规则（Stage模型）。

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

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

参数：

参数名类型必填说明
appIdstring是应用的唯一标识，由云端统一分配。
optionsAtomicServiceOptions否跳出式启动元服务所携带的参数。

返回值：

类型说明
Promise<AbilityResult>Promise对象。返回AbilityResult对象。

错误码：

以下错误码详细介绍。

错误码ID错误信息
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000002Incorrect ability type.
16000003The appId does not exist.
16000004Can not start invisible component.
16000011The context does not exist.
16000012The application is controlled.
16000050Internal error.
16000053The ability is not on the top of the UI.
16000055Installation-free timed out.
16200001The caller has been released.

示例：

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

UIAbilityContext.openLink12+

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

通过AppLinking启动UIAbility，使用Promise异步回调。仅支持在主线程调用。

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

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

如果希望获取被拉起方终止后的结果，可以设置callback参数。

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

说明

组件启动规则详见：组件启动规则（Stage模型）。

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

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

参数：

参数名类型必填说明
linkstring是指示要打开的标准格式URL。
optionsOpenLinkOptions否打开URL的选项参数。
callbackAsyncCallback<AbilityResult>否执行结果回调函数。

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000001The specified ability does not exist.
16000002Incorrect ability type.
16000004Can not start invisible component.
16000005The specified process does not have the permission.
16000006Cross-user operations are not allowed.
16000008The crowdtesting application expires.
16000009An ability cannot be started or stopped in Wukong mode.
16000010The call with the continuation flag is forbidden.
16000011The context does not exist.
16000012The application is controlled.
16000013The application is controlled by EDM.
16000019Can not match any component.
16200001The caller has been released.
16000053The ability is not on the top of the UI.

示例：

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 = getContext(this) 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 occured, errCode ${JSON.stringify(e.code)}`);
          }
        })
    }
    .height('100%')
    .width('100%')
  }
}

UIAbilityContext.backToCallerAbilityWithResult12+

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

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

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

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

参数：

参数名类型必填说明
abilityResultAbilityResult是指示目标方返回给拉起方的结果。
requestCodestring是通过startAbilityForResult或openLink拉起目标方Ability且需要目标方返回结果时，系统生成的用于标识本次调用的requestCode。该值可以通过want中的CALLER_REQUEST_CODE字段获取。

返回值：

类型说明
Promise<void>Promise对象。无返回结果的Promise对象。

错误码：

以下错误码详细介绍。

错误码ID错误信息
201The application does not have permission to call the interface.
401Parameter error. Possible causes: 1.Mandatory parameters are left unspecified. 2.Incorrect parameter types.
16000009An ability cannot be started or stopped in Wukong mode.
16000011The context does not exist.
16000050Internal error.
16000074The caller does not exist.
16000075Not support back to caller.

示例：

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

// 调用方
// index.ets
import { common, Want } from '@kit.AbilityKit';
import { BusinessError } from '@ohos.base';
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 = getContext() 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}`);
}
}
}


                

        

         

    


  



    



                



	

		

			

				
					
【鸿蒙实战开发基于API 13】—— 启动应用内的UIAbility组件

				
			

			

				

					shangkangba的博客
				

				

					11-19
					
					1238
					
				

			

		

		

			
				
一个 UIAbility 可以对应多个页面，在不同的场景下启动该UIAbility时需要展示不同的页面，例如从一个UIAbility的页面中跳转到另外一个UIAbility时，希望启动目标UIAbility的指定页面。UIAbility的启动分为两种情况：UIAbility冷启动和UIAbility热启动。UIAbility冷启动：指的是UIAbility实例处于完全关闭状态下被启动，这需要完整地加载和初始化UIAbility实例的代码、资源等。

			
		

	



                

            
              



	

		

			

				
					
鸿蒙5.0进阶开发：UI开发-组件导航 (Navigation)

				
			

			

				

					AyomQAQ的博客
				

				

					12-19
					
					1058
					
				

			

		

		

			
				
组件导航（Navigation）主要用于实现页面间以及组件内部的页面跳转..........

			
		

	



              


  
              

                


	

		

			

				
					
HarmonyOS实战开发：UIAbilityContext

				
			

			

				

					2401_84194030的博客
				

				

					05-23
					
					2387
					
				

			

		

		

			
				
UIAbilityContext是需要保存状态的UIAbility所对应的context......

			
		

	





	

		

			

				
					
HarmonyOS之UIContext 与 UIAbility、WindowStage 的关系

					
最新发布

				
			

			

				

					无风听海
				

				

					09-16
					
					930
					
				

			

		

		

			
				
UIAbility 是入口，WindowStage 是容器，UIContext 是组件运行时的大脑。它们构建出 ArkUI 应用的核心三层结构，实现了解耦、可组合、可维护的鸿蒙 UI 架构。ArkUI 是 HarmonyOS NEXT 的主推框架，拥有声明式语法、组件化机制、多窗口支持等诸多亮点。理解UIContext与UIAbility的协作机制，是迈向 ArkUI 高阶开发的重要一步。

			
		

	



		

			
		



	

		

			

				
					
鸿蒙Ability Kit（程序框架服务）【应用上下文Context】

				
			

			

				

					鸿蒙的技术博客
				

				

					06-05
					
					1681
					
				

			

		

		

			
				
Context]是应用中对象的上下文，其提供了应用的一些基础信息，例如resourceManager（资源管理）、applicationInfo（当前应用信息）、dir（应用文件路径）、area（文件分区）等，以及应用的一些基本方法，例如createBundleContext()、getApplicationContext()等。UIAbility组件和各种ExtensionAbility派生类组件都有各自不同的Context类。

			
		

	





	

		

			

				
					
鸿蒙5.0开发进阶：ArkTS API UI界面-getContext

				
			

			

				

					Androidbye的博客
				

				

					12-13
					
					934
					
				

			

		

		

			
				
如果需要在页面中获得当前Ability的Context，可调用getContext接口获取当前页面关联的UIAbilityContext或ExtensionContext。

			
		

	





	

		

			

				
					
HarmonyOS之UIAbilityContext详解

				
			

			

				

					无风听海
				

				

					09-10
					
					603
					
				

			

		

		

			
				
功能作用说明代码示例关键字启动 Ability跳转页面或启动后台服务结束 Ability关闭当前能力事件通信事件注册、触发、注销权限申请请求系统权限目录访问获取应用私有目录、缓存目录发送通知给用户发送通知资源管理访问字符串、图片等资源生命周期监听监听前后台切换。

			
		

	





	

		

			

				
					
鸿蒙5.0进阶开发：UI开发-Router切换Navigation

				
			

			

				

					AyomQAQ的博客
				

				

					12-20
					
					1086
					
				

			

		

		

			
				
本文主要从页面跳转、动效和生命周期等方面介绍如何从Router切换到Navigation。

			
		

	





	

		

			

				
					
鸿蒙5.0开发进阶：组件随软键盘弹出避让实现案例

				
			

			

				

					HSMMQAQ的博客
				

				

					11-03
					
					1184
					
				

			

		

		

			
				
本示例介绍使用TextInput组件和LazyForEach实现组件随软键盘弹出避让场景。

			
		

	





	

		

			

				
					
鸿蒙5.0进阶开发：应用文件-应用及文件系统空间统计

				
			

			

				

					AyomQAQ的博客
				

				

					01-21
					
					876
					
				

			

		

		

			
				
在系统中，可能出现系统空间不够或者cacheDir等目录受系统配额限制等情况.............

			
		

	





	

		

			

				
					
鸿蒙5.0开发【录音与音频渲染】

				
			

			

				

					2401_82772199的博客
				

				

					08-07
					
					1444
					
				

			

		

		

			
				
使用AudioCapturer录制音频涉及到AudioCapturer实例的创建、音频采集参数的配置、采集的开始与停止、资源的释放等。建议搭配[AudioCapturer的API说明]阅读。

			
		

	





	

		

			

				
					
鸿蒙开发之context、uicontext、UIAbilityContext的区别

				
			

			

				

					l286935203的专栏
				

				

					12-19
					
					1407
					
				

			

		

		

			
				
本文讲解了鸿蒙开发中context、uicontext、UIAbilityContext的区别

			
		

	





	

		

			

				
					
OpenHarmony—UIAbility组件间交互（设备内）

				
			

			

				

					2401_82546228的博客
				

				

					02-19
					
					1337
					
				

			

		

		

			
				
关注我，同时可以期待后续文章ing，不定期分享原创知识。想要获取更多完整鸿蒙最新VIP学习资料，请点击→《鸿蒙全套学习指南。

			
		

	





	

		

			

				
					
【HarmonyOS】鸿蒙开发之Stage模型-UIAbility的启动模式——第4.4章

				
			

			

				

					我的开源项目:https://gitee.com/derekgo/vue-cms_xg
				

				

					03-03
					
					4027
					
				

			

		

		

			
				
沉默小管 鸿蒙开发之Stage模型-UIAbility的启动模式

			
		

	





	

		

			

				
					
HarmonyOS4.0系统性深入开发03UIAbility组件详解（中）

				
			

			

				

					qq_46189388的博客
				

				

					12-24
					
					1738
					
				

			

		

		

			
				
UIAbility组件的基本用法包括：指定UIAbility的启动页面以及获取UIAbility的上下文。

			
		

	





	

		

			

				
					
HarmonyOS实战开发：UIAbility组件间交互（设备内）

				
			

			

				

					2401_84194030的博客
				

				

					04-23
					
					1461
					
				

			

		

		

			
				
UIAbility是系统调度的最小单元.........

			
		

	





	

		

			

				
					
OpenHarmony开发实战：Stage模型下Ability的创建和使用（ArkTS

				
			

			

				

					m0_60147147的博客
				

				

					04-10
					
					1148
					
				

			

		

		

			
				
这里只是将部分目录大纲截图出来，每个节点里面都包含大厂面经、学习笔记、源码讲义、实战项目、讲解视频，并且会持续更新**

			
		

	





	

		

			

				
					
HarmonyOS开发案例：【UIAbility内和UIAbility间页面的跳转】

				
			

			

				

					鸿蒙的技术博客
				

				

					05-09
					
					1716
					
				

			

		

		

			
				
基于Stage模型下的UIAbility开发，实现UIAbility内和UIAbility间页面的跳转。

			
		

	





	

		

			

				
					
HarmonyOS实战开发-实现UIAbility内和UIAbility间页面的跳转

				
			

			

				

					m0_70749039的博客
				

				

					03-29
					
					1593
					
				

			

		

		

			
				
本篇Codelab基于Stage模型下的UIAbility开发，实现UIAbility内和UIAbility间页面的跳转。包含如下功能：

			
		

	





	

		

			

				
					
鸿蒙5.0版开发：ArkTS组件通用属性（触摸热区设置）

				
			

			

				

					08-21
				

			

		

		

			
				
在 HarmonyOS 5.0 的 ArkTS 组件中，设置触摸热区（Touch Area）属性可以通过组件的 `touchable` 和 `hitTestBehavior` 等属性来实现。这些属性允许开发者定义组件响应触摸事件的区域和行为。

### 配置触摸热区属性

#### 1. `touchable` 属性
`touchable` 属性用于控制组件是否可以响应触摸事件。设置为 `true` 时，组件将可以响应触摸事件；设置为 `false` 时，组件将忽略所有触摸事件。

```ts
@Component
struct MyComponent {
  build() {
    Column() {
      Text('Click Me')
        .fontSize(30)
        .touchable(true)
    }
    .width('100%')
    .height(100)
  }
}
```

#### 2. `hitTestBehavior` 属性
`hitTestBehavior` 属性用于定义组件在命中测试（Hit Test）中的行为。它有以下几种取值：
- `HitTestBehavior.self`: 组件仅在其自身的区域内响应触摸事件。
- `HitTestBehavior.none`: 组件不响应任何触摸事件。
- `HitTestBehavior.default`: 组件按照默认行为响应触摸事件。

```ts
@Component
struct MyComponent {
  build() {
    Column() {
      Text('Click Me')
        .fontSize(30)
        .hitTestBehavior(HitTestBehavior.self)
    }
    .width('100%')
    .height(100)
  }
}
```

#### 3. 自定义触摸热区
如果需要更复杂的触摸热区配置，可以通过自定义组件的 `onTouch` 事件来实现。通过监听触摸事件，开发者可以自定义组件的响应逻辑。

```ts
@Component
struct MyComponent {
  @State message: string = 'Touch Me'

  build() {
    Column() {
      Text(this.message)
        .fontSize(30)
        .onTouch((event: TouchEvent) => {
          if (event.type === TouchType.Down) {
            this.message = 'Touched Down'
          } else if (event.type === TouchType.Up) {
            this.message = 'Touched Up'
          }
        })
    }
    .width('100%')
    .height(100)
  }
}
```

### 注意事项
- **性能优化**：在设置触摸热区时，应避免不必要的复杂逻辑，以确保应用的响应速度和性能。
- **交互设计**：触摸热区的设计应符合用户习惯，避免过于敏感或响应区域过小的问题。

通过以上方法，开发者可以灵活地配置 ArkTS 组件的触摸热区属性，以满足不同的交互需求。



			
		

	



              




          




        



    





    



      

      

        
      

      





	

		评论	
	

  

	
    

      

      

      

        
        

          
          

            

              成就一亿技术人!
            

            

              拼手气红包6.0元
            

          

        

        

          

            还能输入1000个字符
          

          

             
          

          

            

              红包
              添加红包
            

            

              表情包
              插入表情
              

                

              

            

            

              表情包
              代码片
              

                
              

            

            

              
              
              
              
              
              
              
            

          

        

      

    

		

			

			

			

					 条评论被折叠 查看
			

			

				
			

		

	

	




  

    

      添加红包
      
    

    

      

        
        

          
          
        

        
请填写红包祝福语或标题

      

      

        
        

          
          个
        

        
红包个数最小为10个

      

      

        
        

          
          元
        

        
红包金额最低5元

      

      

        
        

          当前余额3.43元
          前往充值 >
        

      

      

        

          需支付：10.00元
        

        
        
      

    

  





  

    
    
  

  

    
    
  








  

    

      

        

          

            
            
成就一亿技术人!

          

          

        

        

          

          

            领取后你会自动成为博主和红包主的粉丝
            规则
          

        

      

      

        

          

            
              
            
            

              
hope_wisdom
 发出的红包
            

          

        

        

          

          

          

        

      

    

    

  



      
      

      
实付元

      
使用余额支付

      

        

          

            
            点击重新获取
          

        

        
扫码支付

      

      

        
          
            
          
          
        
      

      

        
        钱包余额
          0
          

            
            

              

                
抵扣说明：

                
 1.余额是钱包充值的虚拟货币，按照1:1的比例进行支付金额的抵扣。
 2.余额无法直接购买下载，可以购买VIP、付费专栏及课程。

              

            

          

      

      余额充值