前言
在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.LaunchParam | void | 全局初始化，仅需调用一次 |
AppUtil.getContext() | 无 | Context | 获取应用上下文 |
AppUtil.getApplicationContext() | 无 | ApplicationContext | 获取应用级上下文 |
AppUtil.getUIAbilityContext() | 无 | UIAbilityContext | 获取Ability上下文 |
AppUtil.getUIContext() | 无 | UIContext | 获取UI上下文 |
1.2 核心特性
- 全局初始化：只需调用一次，全局可用，无需重复初始化
- 上下文统一管理：统一管理应用各种上下文对象，避免到处传递Context
- 线程安全：支持多线程环境下的上下文获取，内部做了同步处理
- 懒加载机制：UIContext采用懒加载方式，页面渲染后才可获取
1.3 上下文对象对比
| 上下文类型 | 获取时机 | 适用场景 | 生命周期 |
|---|---|---|---|
ApplicationContext | init后即可 | 全局资源访问、系统服务 | 应用级 |
UIAbilityContext | init后即可 | Ability操作、路由跳转 | Ability级 |
UIContext | 页面渲染后 | UI操作、弹窗、动画 | 页面级 |
二、完整使用步骤
2.1 安装依赖
在项目根目录执行以下命令安装harmony-utils：
ohpminstall@pura/harmony-utils安装完成后，在oh-package.json5中确认依赖已添加：
{"dependencies":{"@pura/harmony-utils":"^1.0.0"}}2.2 在UIAbility中初始化
在EntryAbility.ets的onCreate回调中调用初始化方法，这是最关键的一步：
import{AppUtil}from'@pura/harmony-utils';import{AbilityConstant,UIAbility}from'@kit.AbilityKit';import{window}from'@kit.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}from'@pura/harmony-utils';@Entry@Componentstruct IndexPage{@Stateresult:string='';build(){Column({space:12}){Button('获取ApplicationContext').width('100%').onClick(()=>{try{letappCtx=AppUtil.getApplicationContext();this.result='ApplicationContext获取成功\n'+'应用名称: '+appCtx.applicationInfo?.name;}catch(e){this.result='获取失败: '+e;}})Button('获取UIAbilityContext').width('100%').onClick(()=>{try{letabilityCtx=AppUtil.getUIAbilityContext();this.result='UIAbilityContext获取成功\n'+'当前Ability: '+abilityCtx.currentAbility?.context?.abilityInfo?.name;}catch(e){this.result='获取失败: '+e;}})Button('获取UIContext').width('100%').onClick(()=>{try{letuiCtx=AppUtil.getUIContext();this.result=uiCtx?'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}from'@pura/harmony-utils';@Entry@Componentstruct DemoPage{@StatedeviceInfo:string='';@StatenetworkInfo:string='';build(){Column({space:12}){Button('获取设备信息').width('100%').onClick(async()=>{try{letdeviceId=DeviceUtil.getDeviceId();letbrand=DeviceUtil.getBrand();this.deviceInfo=`设备ID:${deviceId}\n品牌:${brand}`;}catch(e){this.deviceInfo='获取失败: '+e;}})Button('检测网络状态').width('100%').onClick(async()=>{try{letisConnected=awaitNetworkUtil.isConnected();letnetType=awaitNetworkUtil.getNetworkType();this.networkInfo=`网络连接:${isConnected?'已连接':'未连接'}\n类型:${netType}`;}catch(e){this.networkInfo='检测失败: '+e;}})Button('显示Toast提示').width('100%').onClick(()=>{ToastUtil.showToast('harmony-utils初始化成功！');})Text('设备信息:\n'+this.deviceInfo).fontSize(13).width('100%').padding(10).backgroundColor('#F0F0F0').borderRadius(6)Text('网络信息:\n'+this.networkInfo).fontSize(13).width('100%').padding(10).backgroundColor('#F0F0F0').borderRadius(6)}.padding(16)}}3.2 初始化状态检查
在复杂项目中，可以通过AppUtil.getContext()是否为空来判断初始化状态：
import{AppUtil}from'@pura/harmony-utils';functioncheckInitStatus():boolean{try{letctx=AppUtil.getContext();returnctx!==null&&ctx!==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模块：在HSP（Harmony 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}from'@pura/harmony-utils';import{AbilityConstant,UIAbility}from'@kit.AbilityKit';exportdefaultclassSecondAbilityextendsUIAbility{onCreate(want,launchParam:AbilityConstant.LaunchParam):void{// 每个Ability都需要独立初始化AppUtil.init(launchParam);}}总结
AppUtil.init()是使用harmony-utils的第一步，也是最重要的一步。正确完成初始化后，才能使用库中所有工具类的功能。本文详细介绍了初始化方法、上下文获取方式、进阶用法以及常见问题的解决方案。建议在项目的EntryAbility中统一初始化，确保应用启动时即完成所有准备工作，为后续使用DeviceUtil、NetworkUtil、FileUtil等工具类打下基础。
本文基于
@pura/harmony-utils工具库，更多功能请参考官方文档与后续系列文章。
