鸿蒙三方库 | harmony-utils之AppUtil.init全局初始化

前言在HarmonyOS应用开发中工具类的初始化是整个应用架构的基础环节。pura/harmony-utils是一款专为HarmonyOS打造的高效工具库涵盖了设备信息、网络检测、文件操作、加解密、日期处理等100常用功能而AppUtil.init()是整个库的全局初始化入口必须在应用启动时调用。本文将详细介绍如何使用AppUtil.init()完成harmony-utils的初始化工作并深入解析各种上下文对象的获取方式与使用场景。一、AppUtil.init 核心介绍1.1 方法说明AppUtil.init()是harmony-utils的核心初始化方法需要在UIAbility的onCreate生命周期回调中调用传入AbilityConstant.LaunchParam参数。初始化完成后即可通过AppUtil获取各种上下文对象。方法名参数返回值说明AppUtil.init(launchParam)AbilityConstant.LaunchParamvoid全局初始化仅需调用一次AppUtil.getContext()无Context获取应用上下文AppUtil.getApplicationContext()无ApplicationContext获取应用级上下文AppUtil.getUIAbilityContext()无UIAbilityContext获取Ability上下文AppUtil.getUIContext()无UIContext获取UI上下文1.2 核心特性全局初始化只需调用一次全局可用无需重复初始化上下文统一管理统一管理应用各种上下文对象避免到处传递Context线程安全支持多线程环境下的上下文获取内部做了同步处理懒加载机制UIContext采用懒加载方式页面渲染后才可获取1.3 上下文对象对比上下文类型获取时机适用场景生命周期ApplicationContextinit后即可全局资源访问、系统服务应用级UIAbilityContextinit后即可Ability操作、路由跳转Ability级UIContext页面渲染后UI操作、弹窗、动画页面级二、完整使用步骤2.1 安装依赖在项目根目录执行以下命令安装harmony-utilsohpminstallpura/harmony-utils安装完成后在oh-package.json5中确认依赖已添加{dependencies:{pura/harmony-utils:^1.0.0}}2.2 在UIAbility中初始化在EntryAbility.ets的onCreate回调中调用初始化方法这是最关键的一步import{AppUtil}frompura/harmony-utils;import{AbilityConstant,UIAbility}fromkit.AbilityKit;import{window}fromkit.ArkUI;exportdefaultclassEntryAbilityextendsUIAbility{onCreate(want,launchParam:AbilityConstant.LaunchParam):void{// 全局初始化harmony-utils必须在此处调用AppUtil.init(launchParam);console.info([EntryAbility] harmony-utils initialized);}onWindowStageCreate(windowStage:window.WindowStage):void{// 设置主窗口windowStage.loadContent(pages/Index,(err,data){if(err.code){console.error([EntryAbility] loadContent failed);return;}console.info([EntryAbility] loadContent success);});}}2.3 在页面中获取上下文初始化完成后即可在任意页面中获取各种上下文对象import{AppUtil}frompura/harmony-utils;EntryComponentstruct IndexPage{Stateresult:string;build(){Column({space:12}){Button(获取ApplicationContext).width(100%).onClick((){try{letappCtxAppUtil.getApplicationContext();this.resultApplicationContext获取成功\n应用名称: appCtx.applicationInfo?.name;}catch(e){this.result获取失败: e;}})Button(获取UIAbilityContext).width(100%).onClick((){try{letabilityCtxAppUtil.getUIAbilityContext();this.resultUIAbilityContext获取成功\n当前Ability: abilityCtx.currentAbility?.context?.abilityInfo?.name;}catch(e){this.result获取失败: e;}})Button(获取UIContext).width(100%).onClick((){try{letuiCtxAppUtil.getUIContext();this.resultuiCtx?UIContext获取成功:UIContext为空请确认页面已渲染;}catch(e){this.result获取失败: e;}})Text(this.result).fontSize(14).fontColor(#333333).width(100%).padding(12).backgroundColor(#F5F5F5).borderRadius(8)}.padding(16)}}三、进阶用法3.1 结合其他工具类使用AppUtil.init()初始化完成后harmony-utils中的所有工具类都可以正常使用因为它们内部都依赖AppUtil获取上下文import{AppUtil,DeviceUtil,NetworkUtil,ToastUtil}frompura/harmony-utils;EntryComponentstruct DemoPage{StatedeviceInfo:string;StatenetworkInfo:string;build(){Column({space:12}){Button(获取设备信息).width(100%).onClick(async(){try{letdeviceIdDeviceUtil.getDeviceId();letbrandDeviceUtil.getBrand();this.deviceInfo设备ID:${deviceId}\n品牌:${brand};}catch(e){this.deviceInfo获取失败: e;}})Button(检测网络状态).width(100%).onClick(async(){try{letisConnectedawaitNetworkUtil.isConnected();letnetTypeawaitNetworkUtil.getNetworkType();this.networkInfo网络连接:${isConnected?已连接:未连接}\n类型:${netType};}catch(e){this.networkInfo检测失败: e;}})Button(显示Toast提示).width(100%).onClick((){ToastUtil.showToast(harmony-utils初始化成功);})Text(设备信息:\nthis.deviceInfo).fontSize(13).width(100%).padding(10).backgroundColor(#F0F0F0).borderRadius(6)Text(网络信息:\nthis.networkInfo).fontSize(13).width(100%).padding(10).backgroundColor(#F0F0F0).borderRadius(6)}.padding(16)}}3.2 初始化状态检查在复杂项目中可以通过AppUtil.getContext()是否为空来判断初始化状态import{AppUtil}frompura/harmony-utils;functioncheckInitStatus():boolean{try{letctxAppUtil.getContext();returnctx!nullctx!undefined;}catch(e){returnfalse;}}// 使用示例if(checkInitStatus()){console.info(harmony-utils已正确初始化);}else{console.error(harmony-utils未初始化请检查AppUtil.init()调用);}四、注意事项初始化时机必须在UIAbility.onCreate中调用不能在页面中调用否则会抛出异常单次调用AppUtil.init()只需调用一次重复调用不会产生副作用但也没有必要上下文获取顺序初始化后可立即获取ApplicationContext和UIAbilityContext但UIContext需要页面渲染完成后才能获取多Ability场景如果应用有多个Ability每个Ability的onCreate中都需要调用初始化HSP模块在HSPHarmony Shared Package中使用时需要依赖主应用的初始化五、常见问题Q1: 未初始化就调用AppUtil方法会怎样会抛出异常提示上下文为空。错误信息通常为AppUtil is not initialized。因此务必确保在onCreate中完成初始化后再使用其他工具类。Q2: 能否在Worker线程中使用AppUtil的上下文管理基于主线程不建议在Worker线程中直接使用。如果Worker线程需要上下文信息可以通过MainThread传递必要的数据。Q3: 应用热重载后初始化状态会丢失吗开发阶段的热重载不会重新执行onCreate生命周期因此初始化状态会保持。但如果是冷启动则会重新初始化。Q4: 多个UIAbility如何处理每个UIAbility拥有独立的上下文需要在各自的onCreate中调用AppUtil.init()// SecondAbility.etsimport{AppUtil}frompura/harmony-utils;import{AbilityConstant,UIAbility}fromkit.AbilityKit;exportdefaultclassSecondAbilityextendsUIAbility{onCreate(want,launchParam:AbilityConstant.LaunchParam):void{// 每个Ability都需要独立初始化AppUtil.init(launchParam);}}总结AppUtil.init()是使用harmony-utils的第一步也是最重要的一步。正确完成初始化后才能使用库中所有工具类的功能。本文详细介绍了初始化方法、上下文获取方式、进阶用法以及常见问题的解决方案。建议在项目的EntryAbility中统一初始化确保应用启动时即完成所有准备工作为后续使用DeviceUtil、NetworkUtil、FileUtil等工具类打下基础。本文基于pura/harmony-utils工具库更多功能请参考官方文档与后续系列文章。