鸿蒙开发中的那些工具函数

前言

最近在搞鸿蒙开发，发现 util 这个工具包还挺好用的，里面有不少实用的函数。今天就来分享一下我平时用得比较多的几个，希望能帮到大家。

开发环境

• DevEco Studio 4.0
• HarmonyOS SDK API 14（鸿蒙 5.0）
• 测试设备：华为 Mate 60 Pro

常用工具函数

1. 导入包

import { util } from '@kit.ArkTS';

2. 字符串处理

// 字符串格式化，这个用得最多
let name = '张三';
let age = 25;
let str = util.format('我叫%s，今年%d岁', name, age);
console.info(str);  // 输出: 我叫张三，今年25岁

// 对象转字符串，调试的时候经常用
const person = {
  name: '张三',
  age: 25,
  address: {
    city: '北京',
    country: '中国'
  }
};
console.info(util.format('个人信息: %j', person));
// 输出: 个人信息: {"name":"张三","age":25,"address":{"city":"北京","country":"中国"}}

// 数字格式化，处理小数点的时候挺方便
const pi = 3.141592653;
console.info(util.format('π的值是: %f', pi));  // 输出: π的值是: 3.141592653

3. 错误处理

// 获取错误信息，调试必备
let errnum = -1;
let result = util.errnoToString(errnum);
console.info("错误信息: " + result);  // 输出: 错误信息: operation not permitted

// 常见错误码，建议收藏
const errorCodes = {
  '-1': 'operation not permitted',
  '-2': 'no such file or directory',
  '-3': 'no such process',
  '-4': 'interrupted system call',
  '-5': 'i/o error',
  '-11': 'resource temporarily unavailable',
  '-12': 'not enough memory',
  '-13': 'permission denied',
  '-100': 'network is down'
};

4. 异步处理

// 回调转 Promise，老代码改造必备
async function fetchData() {
  return 'hello world';
}

let cb = util.callbackWrapper(fetchData);
cb((err: Object, ret: string) => {
  if (err) throw new Error;
  console.info(ret);  // 输出: hello world
});

// Promise 化，写起来更爽
const addCall = util.promisify(util.callbackWrapper(fetchData));
(async () => {
  try {
    let res: string = await addCall();
    console.info(res);  // 输出: hello world
  } catch (err) {
    console.info(err);
  }
})();

5. UUID 生成

// 生成 UUID，做唯一标识的时候用
let uuid = util.generateRandomUUID(true);
console.info("UUID: " + uuid);  // 输出类似: 84bdf796-66cc-4655-9b89-d6218d100f9c

// 二进制 UUID，特殊场景用
let binaryUuid = util.generateRandomBinaryUUID(true);
console.info(JSON.stringify(binaryUuid));  // 输出二进制数组

// UUID 转换，偶尔会用到
let parsedUuid = util.parseUUID("84bdf796-66cc-4655-9b89-d6218d100f9c");
console.info("解析后的 UUID: " + parsedUuid);

6. Base64 编解码

// 同步编码，简单场景用
let base64 = new util.Base64();
let array = new Uint8Array([115, 49, 51]);
let encoded = base64.encodeSync(array);
console.info("编码结果: " + encoded);  // 输出: 99,122,69,122

// 同步编码为字符串，最常用
let encodedStr = base64.encodeToStringSync(array);
console.info("编码字符串: " + encodedStr);  // 输出: czEz

// 同步解码，配合上面用
let decoded = base64.decodeSync(encodedStr);
console.info("解码结果: " + decoded);  // 输出: 115,49,51

// 异步编码，大数据量用
base64.encode(array).then((val) => {
  console.info("异步编码结果: " + val.toString());
});

// 异步编码为字符串，图片处理常用
base64.encodeToString(array).then((val) => {
  console.info("异步编码字符串: " + val);
});

// 异步解码，配合上面用
base64.decode(encoded).then((val) => {
  console.info("异步解码结果: " + val.toString());
});

// 图片转 Base64，上传图片的时候经常用
async function imageToBase64(imageData: Uint8Array): Promise<string> {
  try {
    return await base64.encodeToString(imageData);
  } catch (err) {
    console.error('图片转 Base64 失败:', err);
    return '';
  }
}

// Base64 转图片，下载图片的时候用
async function base64ToImage(base64Str: string): Promise<Uint8Array> {
  try {
    return await base64.decode(base64Str);
  } catch (err) {
    console.error('Base64 转图片失败:', err);
    return new Uint8Array();
  }
}

7. 实际应用

下面是一个简单的例子，把这些功能都串起来用：

@Entry
@Component
struct UtilExample {
  @State message: string = '';
  @State uuid: string = '';
  @State base64Result: string = '';

  aboutToAppear() {
    // 字符串处理
    let name = '张三';
    this.message = util.format('欢迎 %s 使用鸿蒙应用', name);

    // 生成 UUID
    this.uuid = util.generateRandomUUID(true);

    // 错误处理
    try {
      let errnum = -1;
      let errorMsg = util.errnoToString(errnum);
      console.info('错误信息:', errorMsg);
    } catch (err) {
      console.error('发生错误:', err);
    }

    // Base64 测试
    let testData = new Uint8Array([72, 101, 108, 108, 111]); // "Hello"
    let base64 = new util.Base64();
    this.base64Result = base64.encodeToStringSync(testData);
    console.info('Base64 编码结果:', this.base64Result);
  }

  build() {
    Column() {
      Text(this.message)
        .fontSize(20)
        .margin({ top: 20 })
      
      Text('UUID: ' + this.uuid)
        .fontSize(16)
        .margin({ top: 10 })
      
      Text('Base64: ' + this.base64Result)
        .fontSize(16)
        .margin({ top: 10 })
      
      Button('测试异步')
        .onClick(async () => {
          async function testAsync() {
            return '测试成功';
          }
          
          const asyncCall = util.promisify(util.callbackWrapper(testAsync));
          try {
            let result = await asyncCall();
            console.info('异步测试结果:', result);
          } catch (err) {
            console.error('异步测试错误:', err);
          }
        })
      
      Button('测试 Base64')
        .onClick(async () => {
          let base64 = new util.Base64();
          let testData = new Uint8Array([72, 101, 108, 108, 111]);
          
          try {
            let encoded = await base64.encodeToString(testData);
            console.info('异步编码结果:', encoded);
            
            let decoded = await base64.decode(encoded);
            console.info('异步解码结果:', decoded);
          } catch (err) {
            console.error('Base64 操作失败:', err);
          }
        })
    }
    .width('100%')
    .height('100%')
    .justifyContent(FlexAlign.Center)
  }
}

踩过的坑

1. 字符串格式化的时候，%s 和 %d 用错了，结果输出不对
2. 异步函数包装的时候，回调函数的参数顺序写反了，调试了半天
3. UUID 生成的时候，缓存没设置好，性能有点问题
4. 错误码和实际错误信息对不上，查了半天文档
5. Base64 编解码的时候，输入数据类型不对，报错
6. Base64 异步操作忘记处理异常，程序崩了

总结

鸿蒙 5.0 的 util 工具函数还是挺好用的，能省不少事。不过用之前最好先看看文档，了解下具体用法，免得踩坑。

参考资料

• 鸿蒙 5.0 Util API 文档
• 鸿蒙开发指南

后记

写这篇文章的时候，发现鸿蒙 5.0 的工具函数比以前好用多了。如果大家有什么问题，欢迎在评论区讨论。