鸿蒙三方库 | 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获取各种上下文对象。

1.2 核心特性

• 全局初始化：只需调用一次，全局可用，无需重复初始化
• 上下文统一管理：统一管理应用各种上下文对象，避免到处传递Context
• 线程安全：支持多线程环境下的上下文获取，内部做了同步处理
• 懒加载机制：UIContext采用懒加载方式，页面渲染后才可获取

1.3 上下文对象对比

二、完整使用步骤

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()调用');}

四、注意事项

1. 初始化时机：必须在UIAbility.onCreate中调用，不能在页面中调用，否则会抛出异常
2. 单次调用：AppUtil.init()只需调用一次，重复调用不会产生副作用，但也没有必要
3. 上下文获取顺序：初始化后可立即获取ApplicationContext和UIAbilityContext，但UIContext需要页面渲染完成后才能获取
4. 多Ability场景：如果应用有多个Ability，每个Ability的onCreate中都需要调用初始化
5. 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工具库，更多功能请参考官方文档与后续系列文章。