harmony 鸿蒙@ohos.app.ability.errorManager (错误观测管理)

  • 2025-06-12
  • 浏览 (4)

@ohos.app.ability.errorManager (错误观测管理)

ErrorManager模块提供对错误观察器的注册和注销的能力。

说明：

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

导入模块

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

errorManager.on(‘error’)

注意：

在主线程注册errormanager.on接口，当前版本不支持捕获子线程（如：taskpool）中的异常。

使用errormanager.on接口应用不会退出，建议在回调函数执行完后，增加同步退出操作。

on(type: ‘error’, observer: ErrorObserver): number

注册错误观测器。注册后可以捕获到应用产生的js crash，应用崩溃时进程不会退出。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’error’，表示错误观察器。
observer ErrorObserver 是 错误观察器。

返回值：

类型 说明
number 观察器的index值，和观察器一一对应。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16000003 The specified ID does not exist.

示例：

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

let observer: errorManager.ErrorObserver = {
  onUnhandledException(errorMsg) {
    console.info('onUnhandledException, errorMsg: ', errorMsg);
  },
  onException(errorObj) {
    console.info('onException, name: ', errorObj.name);
    console.info('onException, message: ', errorObj.message);
    if (typeof(errorObj.stack) === 'string') {
      console.info('onException, stack: ', errorObj.stack);
    }
  }
};
let observerId = -1;

try {
  observerId = errorManager.on('error', observer);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`error: ${code}, ${message}`);
}

errorManager.on(‘globalErrorOccurred’)18+

on(type: ‘globalErrorOccurred’, observer: GlobalObserver): void

在进程中的任一线程注册errormanager.on接口，支持捕获其他子线程（如：taskpool）中的异常,应用崩溃时进程不会退出，建议在回调函数执行完后，增加同步退出操作。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’globalErrorOccurred’，表示错误观察器。
observer GlobalObserver 是 自定义异常处理回调函数。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16200001 The caller has been released.

示例：

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

function errorFunc(observer: errorManager.GlobalError) {
    console.info("result name :" + observer.name);
    console.info("result message :" + observer.message);
    console.info("result stack :" + observer.stack);
    console.info("result instanceName :" + observer.instanceName);
    console.info("result instaceType :" + observer.instanceType);
}

try {
  errorManager.on('globalErrorOccurred', errorFunc);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`error: ${code}, ${message}`);
}

errorManager.off(‘globalErrorOccurred’)18+

off(type: ‘globalErrorOccurred’, observer?: GlobalObserver): void

注销错误观测器，即取消以前注册的callback监听，取消之后无法实现全局监听。

如果传入的回调不在通过on方法注册的回调队列中，将抛出16300004错误码，因此建议使用try-catch逻辑进行处理。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’globalErrorOccurred’，表示错误观察器。
observer GlobalObserver 否 由on方法注册的callback。建议使用该参数，缺省时默认清除所有通过on注册的相同env的callback，否则删除指定callback。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16200001 The caller has been released.
16300004 The observer does not exist.

示例：

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

function errorFunc(observer: errorManager.GlobalError) {
    console.info("result name :" + observer.name);
    console.info("result message :" + observer.message);
    console.info("result stack :" + observer.stack);
    console.info("result instanceName :" + observer.instanceName);
    console.info("result instaceType :" + observer.instanceType);
}

try {
  errorManager.off('globalErrorOccurred', errorFunc)
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`error: ${code}, ${message}`);
}

errorManager.off(‘error’)

off(type: ‘error’, observerId: number, callback: AsyncCallback<void>): void

注销错误观测器。使用callback异步返回。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’error’，表示错误观察器。
observerId number 是 由on方法返回的观察器的index值。
callback AsyncCallback<void> 是 表示指定的回调方法。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16000003 The specified ID does not exist.

示例：

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

let observerId = 100;

function unregisterErrorObserverCallback(err: BusinessError) {
  if (err) {
    console.error('------------ unregisterErrorObserverCallback ------------', err);
  }
}

try {
  errorManager.off('error', observerId, unregisterErrorObserverCallback);
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`error: ${code}, ${message}`);
}

errorManager.off(‘error’)

off(type: ‘error’, observerId: number): Promise<void>

注销错误观测器。使用Promise异步返回。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’error’，表示错误观察器。
observerId number 是 由on方法返回的观察器的index值。

返回值：

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

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16000003 The specified ID does not exist.

示例：

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

let observerId = 100;

try {
  errorManager.off('error', observerId)
    .then((data) => {
      console.info('----------- unregisterErrorObserver success ----------', data);
    })
    .catch((err: BusinessError) => {
      console.error('----------- unregisterErrorObserver fail ----------', err);
    });
} catch (paramError) {
  let code = (paramError as BusinessError).code;
  let message = (paramError as BusinessError).message;
  console.error(`error: ${code}, ${message}`);
}

errorManager.on(‘loopObserver’)12+

on(type: ‘loopObserver’, timeout: number, observer: LoopObserver): void

注册主线程消息处理耗时监听器。注册后可以捕获到应用主线程处理消息的具体执行时间。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’loopObserver’，表示注册主线程消息处理耗时监听器。
timeout number 是 表示事件执行阈值（单位：毫秒）。 阈值必须大于0。
observer LoopObserver 是 注册主线程消息处理耗时监听器。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.

示例：

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

let observer: errorManager.LoopObserver = {
  onLoopTimeOut(timeout: number) {
    console.info('Duration timeout: ' + timeout);
  }
};

errorManager.on("loopObserver", 1, observer);

errorManager.on(‘globalUnhandledRejectionDetected’)18+

on(type: ‘globalUnhandledRejectionDetected’, observer: GlobalObserver): void

在进程中任一线程注册被拒绝promise监听器，注册后可以捕获到当前进程中未被捕获到的promise rejection。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’globalUnhandledRejectionDetected’，表示注册被拒绝promise监听器。
observer GlobalObserver 是 注册被拒绝promise的callback。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16200001 The caller has been released.

示例：

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

function promiseFunc(observer: errorManager.GlobalError) {
  console.info("result name :" + observer.name);
  console.info("result message :" + observer.message);
  console.info("result stack :" + observer.stack);
  console.info("result instanceName :" + observer.instanceName);
  console.info("result instaceType :" + observer.instanceType);
}

errorManager.on("globalUnhandledRejectionDetected", promiseFunc);
// 建议在抛出promise异常时，使用async抛出异常。
async function throwError() {
  throw new Error("uncaught error");
}

let promise1 = new Promise<void>(() => {}).then(() => {
  throwError();
});

errorManager.on(‘unhandledRejection’)12+

on(type: ‘unhandledRejection’, observer: UnhandledRejectionObserver): void

注册被拒绝promise监听器。注册后可以捕获到当前线程中未被捕获到的promise rejection。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’unhandledRejection’，表示注册被拒绝promise监听器。
observer UnhandledRejectionObserver 是 注册被拒绝promise监听器。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16200001 The caller has been released.

示例：

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

let observer: errorManager.UnhandledRejectionObserver = (reason: Error, promise: Promise<void>) => {
  if (promise === promise1) {
    console.info("promise1 is rejected");
  }
  console.info("reason.name: ", reason.name);
  console.info("reason.message: ", reason.message);
  if (reason.stack) {
    console.info("reason.stack: ", reason.stack);
  }
};

errorManager.on("unhandledRejection", observer);

let promise1 = new Promise<void>(() => {}).then(() => {
  throw new Error("uncaught error");
});

errorManager.on(‘freeze’)18+

on(type: ‘freeze’, observer: FreezeObserver): void

注册应用主线程freeze监听。只能在主线程调用，多次注册后，后一次的注册会覆盖前一次的。

注意：

如果该回调函数执行时间超过1s，可能导致AppRecovery功能不可用。通过解析hilog日志中的begin与Freeze callback execution completed两者的时间差可以计算回调函数执行时长，如果超过1秒，可以尝试采用异步处理、减少阻塞操作、优化数据结构等方法优化回调逻辑，降低执行时长。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’freeze’，表示应用主线程freeze观察器。
observer FreezeObserver 是 由on接口注册的freeze监听的callback。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.

示例：

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

function freezeCallback() {
    console.info("freezecallback");
}
errorManager.on("freeze", freezeCallback);

errorManager.off(‘loopObserver’)12+

off(type: ‘loopObserver’, observer?: LoopObserver): void

注销主线程消息处理监听器。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’loopObserver’，表示应用主线程观察器。
observer LoopObserver 否 应用主线程观察器标志。

错误码：

以下错误码详细介绍请参考通用错误码。

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.

示例：

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

errorManager.off("loopObserver");

errorManager.off(‘globalUnhandledRejectionDetected’)18+

off(type: ‘globalUnhandledRejectionDetected’, observer?: GlobalObserver): void

注销被拒绝promise监听器，注销后无法监听进程中的promise异常。

如果传入的回调不在通过on方法注册的回调队列中，将抛出16300004错误码，因此建议使用try-catch逻辑进行处理。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’globalUnhandledRejectionDetected’，表示注册被拒绝promise监听器。
observer GlobalObserver 否 由on接口注册的被拒绝promise的callback。建议使用该参数，缺省时默认清除所有通过on注册的相同env的callback，否则删除指定callback。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16200001 The caller has been released.
16300004 The observer does not exist.

示例：

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

function promiseFunc(observer: errorManager.GlobalError) {
  console.info("result name :" + observer.name);
  console.info("result message :" + observer.message);
  console.info("result stack :" + observer.stack);
  console.info("result instanceName :" + observer.instanceName);
  console.info("result instaceType :" + observer.instanceType);
}

errorManager.on("globalUnhandledRejectionDetected", promiseFunc);

async function throwError() {
  throw new Error("uncaught error");
}

let promise1 = new Promise<void>(() => {}).then(() => {
  throwError();
});

errorManager.off("globalUnhandledRejectionDetected", promiseFunc);

errorManager.off(‘unhandledRejection’)12+

off(type: ‘unhandledRejection’, observer?: UnhandledRejectionObserver): void

注销被拒绝promise监听器。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’unhandledRejection’，表示注册被拒绝promise监听器。
observer UnhandledRejectionObserver 否 注册了被拒绝promise监听器。建议使用该参数，缺省时默认清除所有通过on注册的相同env的observer，否则删除指定observer。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2.Incorrect parameter types; 3. Parameter verification failed.
16200001 The caller has been released.
16300004 The observer does not exist.

示例：

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

let observer: errorManager.UnhandledRejectionObserver = (reason: Error, promise: Promise<void>) => {
  if (promise === promise1) {
    console.info("promise1 is rejected");
  }
  console.info("reason.name: ", reason.name);
  console.info("reason.message: ", reason.message);
  if (reason.stack) {
    console.info("reason.stack: ", reason.stack);
  }
};

errorManager.on("unhandledRejection", observer);

let promise1 = new Promise<void>(() => {}).then(() => {
  throw new Error("uncaught error")
})

errorManager.off("unhandledRejection");

或者

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

let observer: errorManager.UnhandledRejectionObserver = (reason: Error, promise: Promise<void>) => {
  if (promise === promise1) {
    console.info("promise1 is rejected");
  }
  console.info("reason.name: ", reason.name);
  console.info("reason.message: ", reason.message);
  if (reason.stack) {
    console.info("reason.stack: ", reason.stack);
  }
};

errorManager.on("unhandledRejection", observer);

let promise1 = new Promise<void>(() => {}).then(() => {
  throw new Error("uncaught error")
})

errorManager.off("unhandledRejection", observer);

errorManager.off(‘freeze’)18+

off(type: ‘freeze’, observer?: FreezeObserver): void

取消以前注册的应用主线程freeze监听。只能在主线程调用。

如果传入的回调与通过on方法注册回调不一致，将抛出16300004错误码，因此建议使用try-catch逻辑进行处理。

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

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

参数：

参数名 类型 必填 说明
type string 是 填写’freeze’，表示应用主线程freeze观察器。
observer FreezeObserver 否 由on接口注册的freeze监听的callback。建议使用该参数，如果参数不填会直接清空callback，否则删除指定的callback。

错误码：

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

错误码ID 错误信息
401 Parameter error. Possible causes: 1. Mandatory parameters are left unspecified; 2. Incorrect parameter types; 3. Parameter verification failed.
16300004 The observer does not exist.

示例：

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

function freezeCallback() {
    console.info("freezecallback");
}
errorManager.on("freeze", freezeCallback);
errorManager.off("freeze", freezeCallback);

ErrorObserver

type ErrorObserver = _ErrorObserver.default

ErrorObserver模块。

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

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

类型 说明
_ErrorObserver.default ErrorObserver模块。

LoopObserver12+

type LoopObserver = _LoopObserver

LoopObserver模块。

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

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

类型 说明
_LoopObserver LoopObserver模块。

UnhandledRejectionObserver12+

type UnhandledRejectionObserver = (reason: Error|any, promise: Promise<any>) => void

定义异常监听，用于捕获Promise异步操作失败的原因。

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

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

参数：

参数名 类型 必填 说明
reason Error |any 是 通常是Error类型，表示被拒绝的理由。
promise Promise<any> 是 被拒绝的promise。

FreezeObserver18+

type FreezeObserver = () => void

定义应用主线程freeze回调，用于应用自定义添加freeze信息。

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

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

GlobalObserver18+

type GlobalObserver = (reason: GlobalError) => void

定义异常监听，可以作为errorManager.on(‘globalErrorOccurred’)和errorManager.on(‘globalUnhandledRejectionDetected’)的入参监听当前应用主线程事件处理事件。

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

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

参数：

参数名 类型 必填 说明
reason GlobalError 是 有关异常事件名字、消息、错误堆栈信息、异常线程名称和类型的对象。

GlobalError18+

有关异常事件名字、消息、错误堆栈信息、异常线程名称和类型的对象。

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

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

名称 类型 只读 可选 说明
instanceName string 否 否 表示虚拟机实例名称。
instanceType InstanceType 否 否 表示虚拟机的实例类型。

InstanceType18+

虚拟机的实例类型。

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

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

名称 值 说明
MAIN 0 表示主虚拟机实例。
WORKER 1 表示工作虚拟机实例。
TASKPOOL 2 表示任务池虚拟机实例。
CUSTOM 3 表示用户通过napi_create_ark_runtime从本机代码创建的虚拟机实例。

你可能感兴趣的鸿蒙文章

harmony 鸿蒙Ability Kit（程序框架服务）

harmony 鸿蒙AbilityBase

harmony 鸿蒙AbilityBase_Element

harmony 鸿蒙AbilityRuntime

harmony 鸿蒙bundle

harmony 鸿蒙OH_NativeBundle_ApplicationInfo

harmony 鸿蒙OH_NativeBundle_ElementName

harmony 鸿蒙ability_base_common.h

harmony 鸿蒙ability_runtime_common.h

harmony 鸿蒙application_context.h

0  赞
  • 所属分类： 后端技术
  • 本文标签：
  • 版权声明： 原创文章如转载，请注明本文链接: https://m.seaxiang.com/blog/FJ02iQ
热门推荐
标签云
Linux Java Spring Spring Boot docker 大数据 前端 生活 maven golang 软件 spring cloud fintech mac vscode 其他 区块链 以太坊 V神 开发者 技术 股票 git greenplum 分布式事务 chrome mysql flink kafka 设计模式 原理 鸿蒙 seo
最新文章
本文目录