鸿蒙三方库 | harmony-utils之AppUtil应用包信息查询详解

2301_79533122

152人浏览 · 2026-07-05 00:09:05

2301_79533122 · 2026-07-05 00:09:05 发布

前言

在应用开发中，获取应用包名、版本号、版本名等信息是常见需求，用于版本更新检查、数据统计、日志记录等场景。@pura/harmony-utils 的 AppUtil 封装了便捷的包信息获取方法，无需手动调用 BundleManager，一行代码即可获取所需信息。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握包信息查询功能。

在这里插入图片描述

一、AppUtil包信息核心API

AppUtil 提供了以下包信息查询方法，开发者可以根据实际需求选择调用：

方法	说明	返回类型	使用场景
`getBundleName()`	获取应用包名	string	数据统计、日志标识
`getVersionCode()`	获取版本号	number	版本更新检查
`getVersionName()`	获取版本名	string	关于页面展示
`debug()`	判断是否调试模式	boolean	环境区分

1.1 核心特性

一键获取：无需了解 BundleManager 复杂API，一行代码获取包信息
类型安全：完整的TypeScript类型定义，编译期即可发现错误
缓存优化：内部对包信息做了缓存，避免重复查询系统接口
调试辅助：debug() 方法帮助区分调试和发布环境

1.2 versionCode与versionName对比

属性	类型	示例	用途
versionCode	number	100	版本比较、更新检查
versionName	string	“1.0.0”	用户可见的版本标识

二、完整使用步骤

2.1 安装依赖

在项目根目录执行以下命令安装harmony-utils：

ohpm install @pura/harmony-utils

安装完成后，在 oh-package.json5 中确认依赖已添加：

{
  "dependencies": {
    "@pura/harmony-utils": "^1.0.0"
  }
}

2.2 获取应用包信息

import { AppUtil } from '@pura/harmony-utils';

@Entry
@Component
struct PackageInfoDemo {
  @State result: string = '';

  build() {
    Column({ space: 12 }) {
      Button('获取应用包信息')
        .width('100%')
        .onClick(() => {
          try {
            let bundleName = AppUtil.getBundleName();
            let versionCode = AppUtil.getVersionCode();
            let versionName = AppUtil.getVersionName();
            let debug = AppUtil.debug();
            this.result = `包名: ${bundleName}\n版本号: ${versionCode}\n版本名: ${versionName}\n调试模式: ${debug}`;
          } catch (e) {
            this.result = '异常: ' + e;
          }
        });

      Text(this.result)
        .fontSize(14)
        .fontColor('#333333')
        .width('100%')
        .padding(12)
        .backgroundColor('#F5F5F5')
        .borderRadius(8)
    }
    .padding(16)
  }
}

在这里插入图片描述

2.3 版本更新检查

通过 getVersionCode() 获取当前版本号，与服务器最新版本号比较：

async checkUpdate() {
  let currentVersion = AppUtil.getVersionCode();
  let latestVersion = await this.fetchLatestVersion();
  if (latestVersion > currentVersion) {
    this.showUpdateDialog(AppUtil.getVersionName(), latestVersionName);
  }
}

showUpdateDialog(current: string, latest: string) {
  AlertDialog.show({
    title: '发现新版本',
    message: `当前版本: ${current}\n最新版本: ${latest}`,
    primaryButton: { value: '稍后再说', action: () => {} },
    secondaryButton: { value: '立即更新', action: () => { this.doUpdate(); } }
  });
}

三、进阶用法

3.1 根据调试模式切换环境

通过 debug() 区分调试和发布环境，自动切换服务器地址：

import { AppUtil } from '@pura/harmony-utils';

class ConfigManager {
  private static instance: ConfigManager;
  public baseUrl: string;
  public logLevel: string;

  private constructor() {
    if (AppUtil.debug()) {
      this.baseUrl = 'https://test.api.example.com';
      this.logLevel = 'DEBUG';
    } else {
      this.baseUrl = 'https://api.example.com';
      this.logLevel = 'ERROR';
    }
  }

  static getInstance(): ConfigManager {
    if (!ConfigManager.instance) {
      ConfigManager.instance = new ConfigManager();
    }
    return ConfigManager.instance;
  }
}

3.2 包信息日志工具

将包信息集成到日志系统，方便问题排查：

import { AppUtil, LogUtil } from '@pura/harmony-utils';

function logAppInfo() {
  LogUtil.info('AppInfo', `包名: ${AppUtil.getBundleName()}`);
  LogUtil.info('AppInfo', `版本: ${AppUtil.getVersionName()}(${AppUtil.getVersionCode()})`);
  LogUtil.info('AppInfo', `模式: ${AppUtil.debug() ? 'DEBUG' : 'RELEASE'}`);
}