鸿蒙三方库 | harmony-utils之AssetUtil关键资产存储详解

SansanDoris

181人浏览 · 2026-07-23 10:09:50

SansanDoris · 2026-07-23 10:09:50 发布

前言

关键资产存储（Asset Store）是HarmonyOS提供的安全存储方案，用于存储密码、Token等敏感数据。数据经过加密存储，只有应用自身可以访问。@pura/harmony-utils 的 AssetUtil 封装了关键资产的增删改查方法。本文将从API说明、代码实战、进阶用法、常见问题等多个维度进行全面讲解，帮助开发者快速掌握并应用到实际项目中。

在这里插入图片描述

一、AssetUtil核心API

AssetUtil 提供了以下关键资产存储方法：

方法	说明	返回类型	使用场景
`add(alias, value)`	添加资产	void	首次存储密码
`query(alias)`	查询资产	string	读取密码
`update(alias, value)`	更新资产	void	修改密码
`remove(alias)`	删除资产	void	清除凭证

1.1 核心特性

简洁易用：封装复杂API为一行调用，降低使用门槛
类型安全：完整的TypeScript类型定义，编译期即可发现错误
异常处理：内置异常捕获机制，避免运行时崩溃
安全加密：数据加密存储，应用独占访问

1.2 安全存储方案对照

方案	安全级别	适用数据	加密
AssetUtil	高	密码、Token	是
Preferences	低	用户设置	否
数据库	中	结构化数据	可选

二、完整使用步骤

2.1 安装依赖

ohpm install @pura/harmony-utils

2.2 存储敏感数据

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

Button('存储密码')
  .width('100%')
  .onClick(async () => {
    try {
      await AssetUtil.add('user_password', 'MySecret123');
      this.result = '密码存储成功 🔒\n数据已加密保存';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.3 查询敏感数据

Button('查询密码')
  .width('100%')
  .onClick(async () => {
    try {
      let password = await AssetUtil.query('user_password');
      this.result = `查询成功 🔓\n密码: ${password}`;
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

2.4 更新和删除

Button('更新密码')
  .width('100%')
  .onClick(async () => {
    try {
      await AssetUtil.update('user_password', 'NewSecret456');
      this.result = '密码更新成功 ✅';
    } catch (e) {
      this.result = '异常: ' + e;
    }
  })

在这里插入图片描述

三、完整页面示例

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

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

  build() {
    Column({ space: 12 }) {
      Button('存储Token').width('100%').onClick(async () => {
        try {
          await AssetUtil.add('auth_token', 'eyJhbGciOiJIUzI1NiJ9...');
          this.result = 'Token存储成功';
        } catch (e) { this.result = '异常: ' + e; }
      });
      Button('查询Token').width('100%').onClick(async () => {
        try {
          let token = await AssetUtil.query('auth_token');
          this.result = `Token: ${token?.substring(0, 20)}...`;
        } catch (e) { this.result = '异常: ' + e; }
      });
      Text(this.result).fontSize(14).fontColor('#333333')
    }
    .padding(16)
  }
}

四、进阶用法

4.1 凭证管理器

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

class CredentialManager {
  static async saveToken(token: string): Promise<void> {
    try { await AssetUtil.update('auth_token', token); }
    catch { await AssetUtil.add('auth_token', token); }
  }

  static async getToken(): Promise<string | null> {
    try { return await AssetUtil.query('auth_token'); }
    catch { return null; }
  }

  static async clearCredentials(): Promise<void> {
    await AssetUtil.remove('auth_token');
  }
}

4.2 自动登录

async function tryAutoLogin(): Promise<boolean> {
  let token = await CredentialManager.getToken();
  if (token) {
    return await validateToken(token);
  }
  return false;
}